MoreLean

전기차 배터리에 대한 잘못된 정보

MoreLean — Sun, 11 Oct 2026 15:29:04 +0900

전기차를 타다 보면 “80%까지만 충전해라”, “가끔은 100%까지 채워야 한다”, “급속 충전은 피해라” 같은 말을 자주 듣습니다. 그런데 이 말들은 배터리 종류에 따라 맞기도 하고 틀리기도 합니다. 요즘 전기차 배터리는 크게 NCM(니켈·코발트·망간, 해외 자료에서는 글자 순서를 바꿔 NMC라고도 씁니다. 같은 계열입니다)과 LFP(리튬인산철) 두 계열로 나뉘기 때문입니다. 이 글은 두 계열을 나눠서 올바른 사용법과 잘못 알려진 상식을 정리합니다. 배터리 기초 자료, 논문, 실주행 데이터를 조사해 구성했고, 계기가 된 유튜브 영상은 참조 목록에 참조로만 넣었습니다. 글에 나오는 전문 용어는 본문에서 바로 풀어 쓰고, 맨 아래에 ‘용어 풀이’로도 모아 두었습니다.

먼저 내 차 배터리부터 확인하세요

제조사 제원표나 설명서에 배터리 종류(NCM 또는 NMC, LFP 등)가 적혀 있는 경우가 많습니다. 확인이 어렵다면 제조사나 서비스센터에 물어보세요. 아래 내용은 모두 일반적인 경향이므로, 차량 설명서의 충전 권고가 우선입니다.

NCM과 LFP, 무엇이 다를까

항목	NCM	LFP
전압(셀 하나)	공칭 3.6~3.7V, 동작 범위 3.0~4.2V	공칭 3.2~3.3V, 동작 범위 2.5~3.65V
에너지 밀도	약 150~220Wh/kg	약 90~120Wh/kg (같은 무게로는 NCM이 더 멀리 갑니다)
사이클 수명(추정)	약 1,000~2,000회	약 2,000회 이상
완충 내성	오래 머물면 부담이 큼	상대적으로 높음
전압 곡선	충전량에 따라 전압이 뚜렷하게 변함	매우 평평해서 전압만으로 충전량을 짐작하기 어려움
열폭주 시작 온도(추정)	약 210°C	약 270°C
자기방전	상대적으로 낮음	다른 리튬이온보다 높은 편
추위	성능이 떨어짐	역시 성능이 떨어짐(예외 아님)

수치는 Battery University가 정리한 일반 셀 기준의 대략적인 값입니다. 실제 전기차 팩은 제조사 설계에 따라 다릅니다.

참조: Battery University BU-205, Wikipedia, LFP 배터리

두 배터리에 공통인 원리

충전하면 리튬이 양극에서 음극으로 이동하고, 쓰면 다시 돌아옵니다. 그런데 이 과정에서 리튬 일부가 엉뚱한 곳에 쓰여 영구히 사라지면 용량이 줄어듭니다. 이렇게 충전·방전이라는 본래 반응 옆에서 곁다리로 일어나는, 원하지 않는 화학 반응을 부반응이라고 부릅니다. 주된 원인은 세 가지입니다.

높은 전압에 오래 머무름: 음극 표면의 보호막(SEI, 처음에는 꼭 필요하지만 계속 두꺼워지면 그만큼 리튬을 소모하는 얇은 막)이 두꺼워지고 양극 쪽 전해액이 산화됩니다(전해액이 높은 전압에서 화학적으로 변질되는 것). 코발트계 셀에서는 4.10V 이상의 높은 전압이 고온과 겹칠 때 충·방전 반복보다 더 해로울 수 있다고 합니다.
열: 같은 충전량라도 온도가 높으면 열화가 빨라집니다. Battery University의 보관 실험 추정치에서 1년 뒤 남는 용량은 25°C에서 40% 충전 96%, 100% 충전 80%였고, 40°C에서는 각각 85%와 65%였습니다(코발트계 셀 기준).
추울 때 급속 충전: 리튬이 음극 안으로 들어가는 속도가 추위로 느려지는데 급속 충전처럼 큰 전류를 넣으면, 리튬이 음극 표면에 금속으로 쌓입니다(리튬 플레이팅, 금속 리튬이 도금되듯 음극 표면에 달라붙는 현상). 이렇게 쌓인 리튬은 돌아오지 않습니다.

부반응, 쉽게 풀어 보기. 배터리의 본래 일은 리튬이 양극과 음극 사이를 오가며 전기를 저장하고 내보내는 것입니다. 부반응은 이 오가기와 별개로, 전극과 전해액이 맞닿은 곳에서 리튬이나 전해액이 다른 물질로 바뀌어 버리는 반응입니다. 한번 바뀐 리튬은 다시 일을 하지 못하므로 부반응이 쌓일수록 쓸 수 있는 리튬이 줄어듭니다. 입출금할 때마다 소액이 수수료로 빠져나가는 통장에 비유하면 이해하기 쉽습니다(비유일 뿐, 실제 손실 비율을 뜻하지는 않습니다). 위 세 가지 원인은 모두 부반응을 빠르게 만드는 조건입니다.

또 하나, 용량은 늘 일정한 속도로 줄지 않습니다. 열화(시간이 지나거나 많이 쓰면서 배터리 용량이 줄어드는 것)가 어느 시점부터 갑자기 빨라지는 ‘무릎(knee)’ 현상이 연구되어 있고, 원인 중 하나가 리튬 플레이팅입니다.

참조: BU-808b, BU-808, BU-410, Recurrent, Attia 외(arXiv)

NCM 배터리 사용법

일상 충전은 80% 안팎, 멀리 가는 날만 100%. Geotab이 전기차 22,700대를 분석한 결과, 충전량이 20% 미만이거나 80% 초과인 상태로 보낸 시간이 전체의 80%를 넘는 차만 열화가 연 2.0%로 빨랐고, 그보다 노출이 적은 차는 연 1.4~1.5%였습니다. 숫자보다 머무는 시간이 핵심입니다.
100%로 채웠다면 오래 방치하지 마세요. 출발 시각에 맞춰 충전이 끝나도록 예약 충전을 쓰는 방법이 있습니다(자료의 원리에서 끌어낸 상식적 응용입니다).
깊게 쓰고 충전하기보다 얕게 자주. Battery University의 실험 자료에서 방전 깊이 100%일 때 약 300회였던 NCM 계열 사이클 수명이 방전 깊이 20%에서는 약 2,000회로 늘었습니다(추정치). Chalmers 공대 실험에서는 충전량 50% 부근에서 쓰면 차량용 리튬이온의 기대 수명이 44~130% 늘었다고 합니다.
오래 방치할 때는 중간 충전량으로. 완충이나 충전량이 아주 낮은 상태보다 중간 정도가 안전합니다(소형 배터리 보관 기준 권고이므로 차량에는 참조용입니다).
‘깨우기’ 완충은 필요 없습니다. 리튬이온에는 메모리 효과(덜 쓰고 충전하기를 반복하면 그만큼만 기억해 용량이 줄어드는, 옛 니켈 계열 배터리의 현상)가 사실상 없습니다.

LFP 배터리 사용법

완충에 대한 부담이 상대적으로 적습니다. Battery University는 LFP가 완충 내성이 더 높고, 높은 전압에 오래 머물러도 다른 리튬이온보다 덜 부담을 받는다고 설명합니다. 그래서 NCM처럼 일상 충전 한도를 낮게 잡을 필요가 상대적으로 적을 수 있습니다. 다만 제조사마다 권고가 다를 수 있으니 설명서를 먼저 확인하세요.
가끔 하는 완충은 수명이 아니라 충전량 표시 보정에 의미가 있습니다. LFP는 전압 곡선이 매우 평평하고 이력(히스테리시스) 현상(같은 충전량이라도 충전 중이냐 방전 중이냐에 따라 전압이 달라지는 것)이 있어서, 전압으로 충전량을 추정하기가 어렵다는 점이 여러 연구에서 지적됩니다. 그래서 완충으로 충전량 표시를 맞추도록 권고하는 제조사가 있을 수 있습니다. 해당 여부는 차량 설명서에서 확인하세요.
너무 낮은 충전량으로 방치하지 마세요. 셀 전압이 낮은 영역에서는 손상이 생길 수 있습니다(Battery University 기준 2V 미만). 실제 차량은 배터리 관리 시스템(BMS, 전압과 온도를 감시해 배터리를 보호하는 제어 장치)이 보호하지만, 충전량이 아주 낮은 상태로 오래 방치하는 것은 피하는 편이 안전합니다.
오래 방치한 뒤에는 셀 균형을 신경 쓰세요. LFP는 자기방전(쓰지 않아도 저절로 전기가 빠지는 현상)이 다른 리튬이온보다 높은 편이고, 시간이 지나면 셀 사이 균형(팩을 이루는 셀들의 충전량이 서로 비슷한 상태)이 어긋날 수 있다고 합니다. 장기 방치 뒤의 관리 방법은 제조사 권고를 확인하세요.
추위와 더위는 NCM과 똑같이 조심하세요. LFP도 추우면 성능이 떨어지고, 방치 중 온도가 높으면 열화가 빨라집니다.

두 배터리 모두에 해당하는 습관

급속 충전은 필요할 때만. Recurrent는 테슬라 13,000대(데이터 16만 건 이상)에서 급속 충전을 70% 넘게 쓴 차와 30% 미만인 차의 주행거리 감소에 통계적 차이를 찾지 못했습니다. 반면 Geotab은 급속 충전 비율이 12% 미만이면 연 1.5%, 12% 이상이면서 100kW 초과 세션이 40% 이상이면 연 3.0% 열화였다고 합니다. 두 자료 모두 NCM과 LFP를 나눠 비교하지는 않아서, 배터리 종류별 차이는 확인하지 못했습니다. 아주 덥거나 춥거나 충전량이 5%·90%처럼 극단일 때의 급속 충전은 피하라는 것이 Recurrent의 권고입니다.
겨울에는 충전기를 꽂은 채 예열. Geotab은 영하 20°C에서 주행거리가 최대 50% 줄어들 수 있다고 설명하고, 충전기를 꽂은 채로 예열하면 배터리 온도 관리에 좋다고 합니다. 실내 공기를 데우는 데는 3,000~5,000W가 들지만 열선 시트·핸들은 약 75W입니다.
여름에는 열을 줄이기. 더운 지역(연중 25°C 초과 일수 35% 이상)의 차는 열화가 연 0.4%p 더 빨랐습니다. 그늘이나 실내 주차는 상식적인 대응입니다.

참조: Geotab, Geotab 겨울 가이드, Recurrent

잘못 알려진 상식 정정

흔한 말	NCM	LFP
가끔은 100%까지 채워서 배터리를 깨워야 한다	틀림. 메모리 효과는 옛 니켈카드뮴 배터리의 현상이고 리튬이온에는 없습니다.	수명 목적으로는 틀림. 다만 충전량 표시 보정에는 의미가 있을 수 있습니다.
80%까지만 충전해야 한다	절반만 맞음. 80% 자체보다 높은 충전량에 머문 시간이 문제입니다.	상대적으로 덜 중요. 완충 내성이 높지만 제조사 권고가 우선입니다.
20% 밑으로 내리면 큰일 난다	절반만 맞음. 극단적 충전량에 오래 머무는 것을 피하면 됩니다.	절반만 맞음. 낮은 전압 영역에 방치하면 손상될 수 있어 충전량이 아주 낮은 채로 두지는 마세요.
급속 충전은 배터리를 망친다	조건부. 빈도·출력·온도에 따라 달라집니다.	조건부. 배터리 종류별 비교 데이터는 확인하지 못했습니다.
겨울에 주행거리가 줄면 배터리가 고장난 것이다	틀림. 추위와 난방 때문에 일시적으로 줄어듭니다.	틀림. LFP도 추위에 성능이 떨어집니다.
10년 타면 배터리를 통째로 교체해야 한다	틀림. Geotab 평균 연 2.3%로 8년 뒤에도 약 80%(81.6%)가 남습니다. 미국 에너지부는 전기차 배터리가 온화한 기후에서 12~15년, 가혹한 기후에서 8~12년 간다고 안내하고, 고장이나 손상이 없다면 수명 종료 시점에도 용량의 70% 이상이 남는다는 연구를 소개합니다.	틀림. 사이클 수명이 더 긴 경향이라 같은 이유로 걱정이 과합니다.
LFP는 무조건 NCM보다 오래 간다	경향은 맞지만 무조건은 아님. 한 실험에서 LFP 셀(BYD, Sony)은 30개월 보관 후 용량이 약 8%와 5% 줄었고, NCM 셀은 3,000사이클에서 80%에 도달해 사이클 수명이 더 좋았습니다. 제조사와 셀 설계에 따라 편차가 큽니다.
열화는 일정한 속도로 진행된다	반만 맞음. 차종마다 연 1.4%에서 2.7%까지 차이가 나고, 처음 1~2년에 열화가 더 빨랐다가 안정되는 모델도 있으며, 특정 시점부터 열화가 급격해지는 경우도 보고됩니다.

용어 풀이

용어	쉬운 설명
부반응	충전·방전이라는 본래 반응 외에 곁다리로 일어나는, 원하지 않는 화학 반응. 리튬이 다른 물질로 바뀌어 쓸 수 없게 됩니다.
전해액	리튬 이온이 양극과 음극 사이를 오갈 수 있게 해 주는 액체.
SEI	음극 표면에 생기는 얇은 보호막. 처음에는 필요하지만 계속 두꺼워지면 리튬을 소모해 용량이 줄어듭니다.
전해액 산화	높은 전압에서 양극 쪽 전해액이 화학적으로 변질되는 부반응.
리튬 플레이팅	추울 때 등 리튬이 음극 안으로 들어가지 못하고 금속 상태로 표면에 쌓이는 현상. 쌓인 리튬은 돌아오지 않습니다.
열화	시간이 지나거나 많이 쓰면서 배터리 용량이 줄어드는 것.
SOC(충전량)	배터리가 얼마나 차 있는지를 퍼센트로 나타낸 값. 계기판의 배터리 충전량에 해당합니다.
방전 깊이·사이클 수명	한 번에 얼마나 깊이 쓰는지가 방전 깊이이고, 충전과 방전을 한 번씩 하는 것이 1사이클입니다. 사이클 수명은 용량이 일정 수준으로 떨어지기까지 반복할 수 있는 횟수입니다.
BMS(배터리 관리 시스템)	전압과 온도를 감시하며 충전 속도와 한도를 조절해 배터리를 보호하는 제어 장치.
메모리 효과	덜 쓰고 충전하기를 반복하면 그만큼만 기억해 용량이 줄어드는 옛 니켈 계열 배터리의 현상. 리튬이온에는 사실상 없습니다.
이력(히스테리시스)	같은 충전량이라도 충전 중이냐 방전 중이냐에 따라 전압이 달라지는 현상. LFP에서 충전량 추정을 어렵게 합니다.
자기방전	쓰지 않고 두어도 저절로 전기가 빠지는 현상.
셀 균형	팩을 이루는 수많은 셀의 충전량이 서로 비슷한 상태. 어긋나면 BMS가 맞춰 줍니다.

참조

LLM은 대화를 어떻게 기억할까? Claude Code로 알아본 컨텍스트와 캐싱, 그리고 /compact 활용법

MoreLean — Tue, 6 Oct 2026 08:31:17 +0900

들어가며: 계정을 바꾸면 대화가 끊길까?

터미널에서 Claude Code를 쓰다 보면 사용량 한도에 걸리는 순간이 옵니다. 저는 계정을 두 개 쓰고 있어서, A 계정으로 작업하다 한도가 차면 B 계정으로 바꿔서 이어가곤 했습니다.

그런데 문득 궁금해졌습니다. A 계정에서 하던 대화 맥락을 B 계정은 모르는 거 아닐까? 이 질문을 파고들다 보니, LLM이 대화를 주고받는 방식 자체를 제대로 몰랐다는 걸 알게 됐습니다. 결론부터 말하면 계정을 바꿔도 맥락은 끊기지 않습니다. 그 이유와 함께, 알아두면 사용량을 아낄 수 있는 내용들을 정리해봤습니다.

1. LLM은 대화를 기억하지 않는다

가장 놀랐던 사실은 이겁니다. 모델은 이전 대화를 기억하지 못합니다. 그래서 매번 질문할 때마다 지금까지의 대화 전체를 다시 보내야 합니다.

예를 들어 A, B, C 세 번 대화를 나눈 뒤 네 번째 질문 D를 하면, 실제 요청은 이렇게 나갑니다.

[질문A, 답변A, 질문B, 답변B, 질문C, 답변C, 질문D]  →  모델  →  답변D

여기서 포인트는 두 가지입니다.

이전 질문뿐 아니라 답변도 입력으로 같이 들어갑니다.
모델은 A, B, C에 다시 답하지 않습니다. 대화 전체를 읽은 상태에서 D에 대한 답만 새로 생성합니다.

화면에는 기존 대화 아래에 새 답변 D가 붙을 뿐이라, 사용자 입장에서는 이런 과정이 보이지 않습니다.

대화 기록은 어디에 있을까?

Claude Code의 대화 기록은 서버가 아니라 내 PC의 로컬 파일(~/.claude/projects/ 아래)에 저장됩니다. 그래서 터미널을 껐다 켜도 claude --resume으로 이어갈 수 있습니다.

재미있는 실험: 답변을 바꾸면?

모델은 대화 기록에 적힌 내용을 그대로 믿습니다. 자기가 실제로 그렇게 답했는지 확인할 방법이 없기 때문입니다. 그래서 이전 답변을 수정해서 보내면, 모델은 수정된 내용을 "내가 했던 말"로 받아들이고 다음 질문을 처리합니다. API를 직접 다룰 때는 실제로 흔히 쓰는 방법이기도 합니다.

2. 요청에 실제로 들어가는 것 vs 화면에만 보이는 것

화면에 보이는 것과 모델에게 전달되는 내용은 1:1로 같지 않습니다.

구분예시

화면에만 있음	진행 스피너, 경과 시간, 색상, 상태 안내 문구
요청에만 있거나 줄여서 보임	시스템 프롬프트, CLAUDE.md, 도구 실행 결과 전체
양쪽 다 있음	사용자 질문, 모델 답변, 도구 호출 내역

특히 주의할 건 도구 실행 결과입니다. 화면에서는 파일 읽기 결과가 몇 줄로 접혀 보여도, 모델에게는 전체 내용이 전달됩니다. 큰 파일을 읽거나 출력이 긴 명령을 실행하면 사용량이 확 늘어나는 이유입니다.

생각하는 과정(thinking)은?

화면에 보이는 "생각하는 과정"은 단순한 UI 연출이 아니라 모델이 실제로 생성한 출력입니다. 그리고 최신 모델(Claude Opus 4.5, 4.6 이상)은 이전 턴의 thinking도 다음 요청에 맥락으로 유지하고 입력으로 과금합니다. 그 이전 모델들은 이전 thinking을 제거했습니다. 출처

[질문A, 생각A, 답변A, 질문B, 생각B, 답변B, ..., 질문D]  →  생각D, 답변D

몇 가지 덧붙이면 이렇습니다.

화면에 보이는 thinking은 전체 원문이 아니라 요약본인 경우가 많습니다.
답변 텍스트와 달리 thinking은 임의로 수정할 수 없습니다. 검증용 서명이 붙어 있어서 바꾸면 오류가 납니다.

3. 매번 전체를 보내면 비효율적이지 않나? 프롬프트 캐싱

매번 전체를 보낸다니 낭비처럼 느껴지지만, 이를 줄여주는 장치가 프롬프트 캐싱입니다.

캐시는 "답변"이 아니라 "읽은 결과"를 저장한다

모델이 긴 입력을 읽을 때 내부적으로 많은 계산을 합니다. 캐싱은 A, B, C를 읽으며 했던 중간 계산 결과(KV 캐시)를 저장해 두는 것입니다. 다음 요청에서는 그 부분을 건너뛰고 새로 추가된 D만 읽으면 됩니다.

캐시 있음:  [A, B, C] 읽기 생략 + D만 읽기  → 답변D   (빠르고 저렴)
캐시 없음:  [A, B, C, D] 전부 다시 읽기      → 답변D   (느리고 비쌈)

결과는 같습니다. 캐시는 비용과 속도에만 영향을 주고 맥락이나 품질에는 영향이 없습니다.

캐시가 재사용되는 조건

앞에서부터 완전히 같은 부분까지만 재사용됩니다. 중간의 답변B를 수정하면 A까지만 캐시를 쓰고 B부터는 새로 읽습니다.
미리 저장되는 게 아니라, 실제 요청을 보낼 때 그 내용이 캐시에 저장됩니다.

캐시는 오래 가지 않는다

캐시는 GPU 메모리처럼 비싼 자원에 올려두기 때문에 기본 5분 정도만 유지됩니다. 사용될 때마다 유지 시간이 다시 연장되고, API에는 1시간짜리 옵션도 있습니다.

4. 캐시 유지 시간이 5분이면, 긴 작업은?

수십 분짜리 작업도 캐시는 유지된다

Claude Code의 긴 작업은 내부적으로 짧은 요청이 계속 이어지는 구조입니다.

요청 → "파일 읽을게"   → 실행 → 결과 담아 다시 요청
     → "수정할게"      → 실행 → 결과 담아 다시 요청
     → "테스트 돌릴게" → 실행 → 결과 담아 다시 요청 ...

도구를 쓸 때마다 대화 전체를 담은 새 요청이 몇 초~몇십 초 간격으로 나가고, 그때마다 캐시 유지 시간이 연장됩니다. 그래서 작업이 30분 걸려도 앞부분 대화는 계속 캐시에 살아 있습니다.

캐시가 끊기는 건 이런 경우입니다.

빌드나 설치처럼 한 번의 명령이 5분 넘게 걸릴 때
작업이 끝난 뒤 한참 있다가 다음 질문을 할 때

2시간 뒤에 돌아왔다면?

캐시는 이미 사라졌습니다. 복귀 후 첫 질문 한 번만 대화 전체를 다시 읽어 무겁고, 그 다음부터는 다시 캐시가 적용됩니다. 맥락은 로컬에 그대로 있으니 대화가 끊기지는 않습니다.

캐시를 살려두려고 5분마다 의미 없는 질문을 하면?

계산해보면 손해입니다. API 기준 입력 비용 비율은 대략 캐시 읽기 0.1배, 캐시 새로 만들기 1.25배입니다. 대화 크기를 1로 두고 2시간을 비교하면 이렇습니다.

방식계산비용

5분마다 유지용 요청	약 24회 × 0.1	약 2.4
2시간 뒤 그냥 질문	1회 × 1.25	약 1.25

손익분기는 약 12~13회, 즉 1시간 정도입니다. 여기에 유지용 요청마다 생기는 답변 출력 비용, 의미 없는 대화가 기록에 쌓여 이후 모든 요청이 커지는 문제까지 생각하면 굳이 할 이유가 없습니다.

참고로 구독 요금제는 달러가 아니라 사용량 한도로 차감되고, 정확한 산정 방식은 공개되어 있지 않습니다. 다만 큰 방향은 같다고 보면 됩니다.

5. 다시 처음 질문으로: 계정을 바꾸면?

이제 처음 궁금증에 답할 수 있습니다. 계정을 바꿔도 맥락은 끊기지 않습니다. 대화 기록은 로컬에 있고, 매 요청마다 전체를 보내기 때문에 B 계정도 이전 맥락을 그대로 받습니다.

다만 이런 차이는 있습니다.

캐시가 초기화됩니다. 캐시는 계정 단위라서 전환 직후 첫 요청은 대화 전체를 새로 처리합니다. 대화가 길수록 B 계정 사용량이 한 번에 크게 빠집니다.
계정에 묶인 기능은 따로 설정해야 합니다. claude.ai에서 연결한 커넥터 등이 해당합니다. 로컬에 등록한 MCP 서버나 CLAUDE.md는 그대로 쓸 수 있습니다.

전환 전에 /compact로 대화를 줄여두면 전환 직후의 부담을 줄일 수 있습니다.

6. /compact와 /clear, 언제 쓰면 좋을까?

대화가 길수록 매 요청이 커지고, 답변 한 글자를 만들 때마다 참고해야 할 내용도 늘어납니다. 그래서 세션을 적절히 정리하는 게 사용량 관리의 핵심입니다.

/compact: 지금까지의 대화를 요약해서 압축합니다. 맥락의 큰 줄기는 유지하되 세부 내용은 일부 사라집니다. 요약 작업 자체도 비용이 듭니다.
/clear: 대화를 완전히 비우고 새로 시작합니다. 가장 가볍습니다.

/compact를 쓰면 좋은 타이밍

긴 작업을 마치고 같은 주제로 이어갈 때: 도구 실행 결과(파일 내용, 로그 등)가 잔뜩 쌓여 있으니 요약해서 정리합니다.
자리를 오래 비웠다가 돌아왔을 때: 어차피 캐시가 사라져 첫 요청이 무거우니, 줄이고 시작하기 좋은 타이밍입니다.
계정을 전환하기 직전: 새 계정에서 처음부터 읽어야 할 양을 줄여줍니다.
응답이 느려지거나 컨텍스트 한도에 가까워질 때: 자동 압축을 기다리지 말고 원하는 시점에 직접 정리합니다.

/clear를 쓰면 좋은 타이밍

주제가 완전히 바뀔 때: 이전 맥락이 필요 없는데 계속 같이 보내는 건 낭비입니다.
결과만 확인하고 다른 일을 할 때: 필요한 맥락은 "어떤 파일을 이렇게 수정했다" 정도로 짧게 다시 알려주면 됩니다.

그냥 이어가도 되는 경우

대화가 아직 짧을 때
5분 이내 간격으로 계속 주고받고 있을 때 (캐시가 살아 있음)
이전 작업의 세부 내용이 바로 다음 작업에 꼭 필요할 때

마치며

LLM은 대화를 기억하지 않고, 매 요청마다 **대화 전체(질문, 답변, 도구 결과, thinking)**를 다시 보낸다.
대화 기록은 로컬에 있어서 계정을 바꿔도 맥락은 유지된다.
프롬프트 캐싱이 반복 읽기 비용을 줄여주지만 5분 정도면 만료된다.
캐시를 살리려는 의미 없는 요청은 손해다. 돌아와서 그냥 이어가거나 정리하자.
세션은 작업 단위로 끊어 쓰고, 길어지면 /compact, 주제가 바뀌면 /clear.

원리를 알고 나니 사용량이 왜 빨리 차는지, 언제 세션을 정리해야 하는지 감이 잡혔습니다. Claude Code를 오래 쓰시는 분들께 도움이 되면 좋겠습니다.

참고 자료: Extended thinking - Claude Platform Docs

나는 아직 백엔드 개발자인가 — AI가 무너뜨리는 직업의 경계

MoreLean — Thu, 1 Oct 2026 23:35:55 +0900

나는 아직 백엔드 개발자인가

AI가 무너뜨리는 것은 직업이 아니라, 일을 나누는 방식일지도 모른다

나는 백엔드 개발자다. 원래 내 업무 영역은 서버와 API, 데이터베이스, 인증, 그리고 비즈니스 로직이었다. Figma를 붙잡고 화면을 설계하거나 UI를 고심할 일은 거의 없었다.

그런데 최근 업무에 AI를 적용하면서 기묘한 경험을 하고 있다. 기존 화면을 캡처해 넣고 “이 흐름이 다소 뻑뻑한데”, “화면 구성을 이렇게 바꿔볼까?”, “이 정보는 위치를 바꾸는 게 낫겠어”라고 대화를 주고받다 보면, 어느새 내가 UI를 직접 만지고 있다. 한 발 더 나아가 UX를 고심하고, 서비스 전체의 흐름을 다시 설계하는 나를 발견한다.

결과물 역시 단순한 와이어프레임이나 아이디어 스케치에 그치지 않는다. 디자인 시스템이 깔끔하게 적용된, 당장 실제 서비스에 붙여도 될 수준의 화면이 튀어나온다. 백엔드 개발자인 내가 말이다.

이 경험이 반복되면서 문득 질문이 생겼다. 앞으로 디자이너, 마크업 개발자, 프론트엔드 개발자, 기획자라는 구분은 지금처럼 유지될 수 있을까? 그리고 무엇보다, 나는 앞으로도 지금과 같은 의미의 ‘백엔드 개발자’로 남을 수 있을까?

예전에는 역할의 경계가 명확했다

과거 웹 서비스 개발 과정은 경계가 선명한 이어달리기 협업 구조 였다.

기획 → 디자인(Figma) → 마크업 → 프론트엔드 개발 → 백엔드 연동 → 테스트 및 보정

기획자가 화면과 기능을 정리해 넘기면, 디자이너가 Figma로 시안을 만들고, 마크업 개발자가 이를 HTML/CSS로 옮겼다. 프론트엔드 개발자는 인터랙션과 로직을 입혔고, 백엔드 개발자는 서버와 API를 제공했다. 각 단계 사이에는 엄격한 인수인계(Handoff) 지점이 존재했다. 기획서, Figma 문서, 마크업 결과물이 순차적으로 전달되었고, 서비스 하나를 만들기 위해 수많은 사람과 도구가 맞물려 돌아갔다.

초기의 AI: 공정을 '빠르게' 만들었을 뿐

AI를 처음 업무에 도입했을 때만 해도 기존 틀은 유지되었다. 디자이너가 Figma에서 디자인을 마치면, AI가 이를 해석해 마크업 코드로 변환해 주는 정도였다. 사람이 피그마를 보며 일일이 폰트와 간격을 옮기던 수고가 줄어들었으니 확실히 생산성은 올라갔다.

하지만 본질은 변하지 않았다. 여전히 원본은 Figma였고, AI는 이를 코드라는 개발 가능한 형태라 번역해 주는 ‘고성능 툴’에 불과했다. 반응형 레이아웃이 깨지면 결국 개발자가 화면 크기를 줄여가며 CSS를 수정해야 했다. 이때까지 나는 AI를 ‘직업을 대체하는 존재’가 아니라 ‘기존 직업의 생산성을 극대화해 주는 도구’로 바라보았다.

이제는 Figma에서 시작하지 않는다

Claude Design 같은 AI 기반 도구를 본격적으로 활용하면서 작업의 패러다임이 완전히 뒤바뀌었다. 이제는 굳이 Figma에서 목업을 그리지 않는다. 처음부터 AI에게 화면 구조와 요구사항을 설명하고, 디자인 시스템을 주입하며 직접 화면을 만들어낸다.

더 중요한 점은, 그렇게 생성된 결과물이 단순한 정적 이미지가 아니라는 사실이다. 버튼을 누르면 실제 화면이 전환되고, 레이아웃이 유기적으로 반응하는 ‘동작하는 프로토타입’이다. 디자인 시스템 적용 역시 놀라울 정도로 매끄럽다. 폰트, 컬러, 버튼, 카드 컴포넌트의 스타일 변경이 화면별 수작업이 아니라 전체 프레임워크 차원에서 템플릿을 교체하듯 한 번에 반영된다.

이렇게 만들어진 화면은 곧바로 개발에 투입할 수 있는 구조를 갖추고 있다. 이 시점에서 자연스럽게 질문이 떠올랐다. “그렇다면 우리는 왜 여전히 Figma에서 작업을 시작해야 하는가?”

Figma와 마크업 개발자가 맞이한 정면 도전

조금 과격한 예측일지 모르지만, 나는 Figma 같은 도구가 지금의 형태로 오래 남아있기 어렵다고 본다. 이 위기감은 이미 Figma에서도 강하게 느끼고 있다. Figma는 본질적으로 ‘사람이 디자인하고, 다른 사람에게 전달하기 위한’ 협업 툴이다. 사람이 레이어를 쪼개고, Auto Layout을 맞추고, 디자인 시스템을 유지한다.

하지만 AI 중심의 워크플로우에서는 이 정교한 전달 과정이 오히려 거추장스러운 중간 단계가 된다. AI가 요구사항과 디자인 시스템을 직관적으로 이해하고 동작하는 화면을 즉시 생성할 수 있다면, 사람이 Figma라는 중간 형태로 파편화해 전달할 이유가 사라진다. AI에게 가장 최적화된 데이터 구조와 사람이 다루기 편한 레이어 구조는 완전히 다를 수 있기 때문이다.

마크업 개발자의 역할 역시 같은 거친 질문 앞에 서 있다. 마크업의 본질은 디자인을 웹 언어로 번역하는 일이다. 하지만 “모바일에서는 이 세로 구조로 바꿔줘”, “768px 이하에서는 이 패널을 숨겨줘”라는 의도(Intent)를 입력했을 때 AI가 디자인과 실제 구현 코드를 동시에 변경한다면, ‘번역’이라는 독립된 직무의 입지는 급격히 좁아진다.

화면을 고치다 서비스 기획자가 되어있었다

진짜 흥미로운 변화는 도구의 변화보다 ‘내 역할의 확장’에서 일어났다.

처음에는 그저 캡처 화면을 붙여 넣고 “이 버튼 위치 좀 바꿔줘” 수준의 피상적인 조작을 했다. 하지만 작업이 진행될수록 질문이 달라졌다.

“이 정보가 왜 여기에 위치해야 하지?”
“사용자는 이 지점에서 무슨 의도로 클릭을 할까?”
“이 단계를 굳이 거칠 필요가 있을까?”
“버튼을 누른 후 어떤 상태(State)를 보여주는 것이 가장 직관적일까?”

나는 어느새 단순 UI 수정이 아니라 서비스 기획과 UX 설계를 하고 있었다.

기존 프로세스라면 [아이디어 → 기획서 작성 → 디자이너 검토 → 피드백 → 화면 수정]이라는 긴 피드백 루프를 거쳐야 했을 것이다. 그러나 지금은 대화 한 번으로 아이디어가 화면이 되고, 즉시 눌러보며 직관적인 불편함을 포착한 뒤, 대안을 선택해 검증하는 자가 순환 루프가 실시간으로 일어난다.

기존: 생각 → 기획 → 디자인 → 개발 → 검증 (선형적 공정)

현재: 생각 ↔ 기획 ↔ 디자인 ↔ 구현 ↔ 검증 (동시 다발적 순환)

AI가 무너뜨리는 것은 직업이 아닌 ‘역할 사이의 번역 과정’이다

이 일련의 경험을 통해 하나의 핵심 원리를 깨달았다. AI는 특정 직업을 단칼에 없애기보다, 직업과 직업 사이에 존재하던 ‘전달과 번역의 비용’을 없애고 있다.

기획자의 의도를 디자이너가 시안으로 번역하고, 디자이너의 시안을 마크업 개발자가 코드로 번역하며, 프론트엔드와 백엔드가 API 명세서로 번역하던 그 오랜 수작업 구간들. 그동안 우리는 이 번역 파편들을 개별 전문 직무로 분화시켜 왔다.

하지만 AI가 문제 정의부터 화면 구성, 동작 구현, 테스트까지 하나의 흐름으로 연결하면서, 조직 내 전달 및 통번역 단계가 획기적으로 압축되고 있다.

실행 능력이 평준화될 때 빛나는 ‘판단’의 가치

실행(Execution)의 장벽이 낮아지면서 인간에게 요구되는 능력은 오히려 더 복잡해졌다. “만들 수 있는가?”는 더 이상 차별점 요소가 아니다. 이제 중요한 질문은 다른 곳을 향한다.

무엇을 만들어야 하는가?
왜 이 방식으로 해결해야 하는가?
사용자가 진정으로 원하는 핵심 가치는 무엇인가?

도구를 다루는 기술적 스킬보다, 비즈니스 목적, 사용자 경험, 기술적 제약, 정보 구조를 종합적으로 조망하는 ‘복합적 사고 능력(Integrative Thinking)’의 가치가 결정적으로 커지고 있다.

전문성이 사라지는 것이 아니다. 전문성의 축이 “Figma를 얼마나 잘 다루는가”나 “특정 언어 구문에 얼마나 숙련되었는가”에서 “문제의 본질을 정확히 간파하고, AI와 협력하여 맥락에 맞는 올바른 의사결정을 내릴 수 있는가”로 이동하고 있을 뿐이다.

직업명이 아닌 ‘해결할 수 있는 문제의 범위’로 정의되는 시대

앞으로는 자신을 소개할 때 “저는 백엔드 개발자입니다”라는 단순 직무명보다, “나는 서비스의 문제를 정의하고, 시스템 구조를 설계하며, 필요한 UI와 기능을 직접 구현하여 세상에 전달할 수 있는 사람입니다”라는 해결 영역(Scope of Impact) 중심의 정의가 훨씬 선명해질 것이다.

나는 여전히 백엔드 개발자다. 하지만 예전과 동일한 의미의 백엔드 개발자는 아니다. UI/UX를 넘나들고, 서비스 흐름을 고심하며, AI라는 강력한 엔진을 통해 문제 해결 전체 공정을 주도하는 엔지니어다.

우리는 지금 단순한 생산성 향상의 시대를 넘어, ‘직업과 역할의 경계가 완전히 재편되는 과도기’ 한가운데를 통과하고 있다. 그리고 이 변화는 백엔드 개발자뿐만 아니라 디자이너, 프론트엔드, 기획자 모두에게 새로운 영토를 탐험할 기회를 열어주고 있다.

EPSON DS-760, Apple Silicon mac 에서 설정하기 (NAPS2 + SANE)

MoreLean — Thu, 1 Oct 2026 01:02:29 +0900

아이 전공서적이 너무 무거워보여, 디지털화 하기 위해서 쓰는 엡손 WorkForce DS-760 문서 스캐너를 맥북에 USB로 연결했는데 인식이 되지 않았습니다. 엡손 안내문대로 드라이버를 찾아봤지만 결론은 "이 모델은 맥 드라이버가 없다"였습니다.

이 글은 드라이버가 없는 스캐너를 맥에서 쓰기까지 어떤 순서로 확인하고, 무엇이 막혔고, 어떻게 풀었는지를 정리한 기록입니다. 마지막에 같은 문제를 겪는 분들을 위한 해결 방법을 따로 정리했습니다.

[환경] Apple Silicon 맥 ( M1 Ultra ) / Epson WorkForce DS-760 (USB 연결)

1. 시작: 엡손 안내문대로 해봤지만

엡손 안내문에는 이렇게 적혀 있었습니다.

ARM CPU(칩셋) 맥에서 엡손 스캐너를 USB로 연결하면 스캐너가 인식되지 않습니다. 최신 스캔 드라이버(Epson Scan 2)를 엡손 홈페이지 또는 글로벌 드라이버 다운로드 사이트에서 받아 설치하세요.

M1 맥이 처음 나왔을 때 작성된 것으로 보이는 안내문입니다. 요즘 Epson Scan 2는 Apple Silicon에서도 잘 돌아갑니다. 그런데 문제는 DS-760이 애초에 Epson Scan 2를 쓰는 모델이 아니라는 점이었습니다.

https://www.epson.co.kr/Mac_ARM_CPU

2. 한국 사이트와 미국 사이트, 말이 다르다

드라이버를 찾으려고 엡손 한국 사이트와 미국 사이트를 모두 확인했는데, 같은 제품인데도 두 사이트의 안내가 완전히 달랐습니다.

구분엡손 한국 (epson.co.kr)엡손 미국 (epson.com)

OS 선택 목록	Mac은 OS X 10.5 ~ 10.9까지만 있음	최신 macOS까지 목록에 있음
실제 제공 드라이버	[직접 확인한 내용 기입]	Windows용 EPSON Scan v5.3.2.3만 있음
맥 호환 여부	별도 안내 없음	FAQ에 "호환되지 않음"으로 명시

엡손 코리아 - 최신 Mac OS 는 아예 있지도 않다.

미국 엡손의 경우 있긴 하지만 제대로 동작하지 않는다.

한국 사이트만 보면 "예전 맥 OS는 지원했나?" 싶고, 미국 사이트는 OS 목록에 최신 macOS까지 올려 두고는 정작 FAQ에서 "호환되지 않는다"고 답합니다. 어느 쪽을 믿어야 할지 사용자가 직접 교차 확인해야 하는 구조입니다.

3. 하드웨어 업체의 고질적인 문제

이번 일은 DS-760만의 문제가 아닙니다. 스캐너나 프린터 같은 하드웨어를 쓰다 보면 반복해서 부딪히는 문제들입니다.

드라이버 지원이 소리 없이 끊깁니다. 하드웨어는 멀쩡한데 새 OS용 드라이버가 나오지 않아 못 쓰게 됩니다. 업무용 스캐너는 수년씩 쓰는 장비인데, 소프트웨어 수명이 하드웨어 수명보다 훨씬 짧습니다.
국가별 사이트의 정보가 서로 다릅니다. 같은 모델인데 지원 OS 목록, 드라이버 파일, FAQ 내용이 나라마다 제각각입니다.
안내문이 갱신되지 않습니다. 시기가 지난 안내("ARM 맥은 인식 안 됨")가 그대로 남아 있고, 모델별로 해당하는지 여부도 설명하지 않습니다.
결국 해결은 서드파티와 오픈소스가 합니다. 제조사가 손을 놓은 장비를 VueScan(유료)이나 SANE(오픈소스) 같은 곳에서 리버스 엔지니어링으로 살려 두고 있습니다.

4. 해결 과정

① 유료 프로그램 VueScan → 작동은 하지만 유료

VueScan은 DS-760 드라이버를 리버스 엔지니어링해서 자체적으로 내장하고 있어, 설치하자마자 USB로 인식되고 스캔도 잘 됐습니다. 다만 체험판은 스캔 결과에 워터마크가 찍히고, 계속 쓰려면 라이선스를 사야 합니다.

이 단계에서 스캐너와 USB 연결 자체는 정상이라는 것은 확인했습니다. 문제는 드라이버뿐이었습니다.

② 오픈소스 드라이버 SANE에 DS-760이 있는지 확인

리눅스에서 스캐너를 쓸 때 사용하는 오픈소스 드라이버 모음 SANE에는 엡손 DS 시리즈용 epsonds 드라이버가 있습니다.

그런데 SANE 공식 문서만 봐서는 확신하기 어려웠습니다. DS-760이 "Untested(테스트 안 됨)"로 표시돼 있고, 적힌 USB ID도 문서마다 달랐기 때문입니다. 그래서 드라이버 파일 안에 들어 있는 모델 목록을 직접 확인했습니다.

DS-510   (USB ID 0x014c)
DS-560   (USB ID 0x0150)
DS-760   (USB ID 0x014d)   ← 포함되어 있음
DS-860   (USB ID 0x014d)
...

드라이버에 DS-760이 실제로 들어 있었습니다. 참고로 엡손이 직접 만든 리눅스용 오픈소스 드라이버(utsushi)에서도 DS-760은 "Good(잘 작동)"으로 표시돼 있습니다.

③ 맥에서 SANE을 쓰는 방법: NAPS2

NAPS2(Not Another PDF Scanner)는 무료 오픈소스 스캔 프로그램으로, 맥 버전에 SANE 드라이버가 함께 들어 있습니다. NAPS2 공식 문서에도 "제조사 드라이버가 없는 구형 USB 스캐너를 M1/M2/M3 맥에서 연결할 때 유용하다"고 적혀 있습니다.

NAPS2에 들어 있는 드라이버 파일도 열어 봤고, DS-760 항목이 있는 것을 확인했습니다.

④ 첫 시도: 장치가 목록에 안 나온다

NAPS2를 설치하고 드라이버를 SANE으로 바꿨는데, 장치 목록에 DS-760이 나타나지 않았습니다.

원인은 VueScan이었습니다. USB 스캐너는 한 번에 한 프로그램만 붙잡을 수 있는데, 앞서 테스트하던 VueScan이 켜져 있어서 NAPS2가 스캐너에 접근하지 못한 것입니다. VueScan을 완전히 종료하고 다시 시도하니 DS-760 (epsonds)가 목록에 나타났습니다.

⑤ 스캔 성공

ADF 단면·양면 스캔 모두 정상적으로 작동했습니다.

5. 해결 방법 정리 (따라 하기)

STEP 1. 내 모델이 맥을 지원하는지부터 확인

한국 사이트와 미국(또는 글로벌) 사이트를 모두 확인합니다.
FAQ에서 "Mac compatible"을 검색해 봅니다.
Epson Scan 2가 제공되는 모델이라면 최신 버전을 설치하는 것으로 해결됩니다. 제공되지 않는다면 아래 단계로 넘어갑니다.

STEP 2. NAPS2 설치 후 드라이버를 SANE으로 설정

naps2.com에서 맥 버전을 설치합니다 (무료).
프로필 → 새 프로필을 만듭니다.
드라이버를 Apple → SANE으로 바꿉니다. 가장 중요한 단계입니다.
장치 선택을 누르고 10~20초 정도 기다리면 모델명이 나타납니다.

STEP 3. 장치가 안 보이면

VueScan, Epson Scan 같은 다른 스캔 프로그램을 Cmd+Q로 완전히 종료합니다.
스캐너 전원을 껐다 켭니다.
USB 허브를 빼고 맥 본체에 직접 연결합니다.
그래도 안 되면 터미널에서 스캐너의 USB ID를 확인합니다.
system_profiler SPUSBDataType | grep -i -A10 epson

STEP 4. 스캔 설정

Deskew scanned pages: 기울기 자동 보정입니다. ADF로 스캔한다면 켜 두세요.
Page size: 실제 문서 크기로 지정합니다.
Page align: Center로 둡니다. DS-760은 종이를 가운데 기준으로 급지합니다.
Crop to page size: 지정한 용지 크기 밖의 여백을 잘라 줍니다.

STEP 5. 자동 저장 설정

파일 경로에는 반드시 .pdf 확장자를 붙이세요. 확장자가 없으면 저장에 실패하고 오류 로그에 "Could not infer file format from extension"이 남습니다. 제가 실제로 겪은 문제입니다.
분 단위까지만 넣으면 1분 안에 두 번 스캔했을 때 파일 이름이 겹칩니다. 초 단위까지 넣는 것을 추천합니다.
$(YYYY)-$(MM)-$(DD)-$(hh)-$(mm)-$(ss).pdf
"..." 버튼으로 저장할 폴더를 지정합니다.

파일 나누기 옵션동작추천 상황

One file per page	한 장마다 파일 하나	영수증, 명함 등 한 장짜리 문서
One file per scan	스캔 버튼 한 번에 파일 하나	문서를 한 건씩 스캔할 때 (가장 무난)
Separate files by Patch-T	Patch-T 구분지를 기준으로 파일 분리	여러 문서를 ADF에 한꺼번에 넣을 때

6. 마치며

DS-760은 공식적으로 "맥 미지원" 모델이지만, 하드웨어에는 아무 문제가 없었습니다. 문제는 드라이버, 즉 제조사의 소프트웨어 지원이었습니다.

제조사 사이트에 드라이버가 없다고 바로 포기하거나 새 장비를 사기 전에 아래 순서로 확인해 보세요.

국가별 제조사 사이트를 교차 확인
SANE 지원 목록에서 내 모델 검색
NAPS2(무료)에서 SANE 드라이버로 연결 시도

멀쩡한 장비를 드라이버 하나 때문에 버리지 않아도 되는 경우가 생각보다 많습니다.

참고 링크

Jev - 프로그램과 연동하는 기술

MoreLean — Wed, 23 Sep 2026 15:10:38 +0900

생성형 AI는 이제 단순히 질문에 답변하는 수준을 넘어 실제 업무를 처리하는 방향으로 발전하고 있습니다.

그런데 AI 서비스를 개발하다 보면 한 가지 고민이 생깁니다.

"모든 업무에 ChatGPT와 같은 생성형 AI를 사용해야 할까?"

예를 들어 고객의 문의가 결제, 배송, 환불 중 어떤 유형에 해당하는지 판단하는 작업을 생각해 보겠습니다.

이러한 작업에는 길고 자연스러운 문장을 생성할 필요가 없습니다. 고객의 문의 내용을 이해하고, 미리 정의된 선택지 중 적절한 항목 하나를 선택하면 됩니다.

이처럼 문장의 의미를 이해하고 판단하는 작업에 초점을 맞춘 AI 모델이 바로 Jev입니다.

이번 포스팅에서는 Jev가 무엇인지, 기존 생성형 AI와 어떤 차이가 있는지, 그리고 실제 서비스에서 어떻게 활용할 수 있는지 개발자와 일반 사용자 모두 쉽게 이해할 수 있도록 정리해 보겠습니다.

1. Jev란 무엇인가?

Jev는 TypeSafe AI에서 개발한 AI 모델로, 주어진 상황을 이해하고 정해진 기준에 따라 판단 결과를 반환하는 데 초점을 맞추고 있습니다.

기존 생성형 AI가 사람에게 자연스러운 답변을 제공하는 역할에 중점을 두었다면, Jev는 소프트웨어가 활용할 수 있는 판단 결과를 제공하는 역할에 집중합니다.

조금 더 쉽게 이해하기 위해 고객센터를 예로 들어 보겠습니다.

고객이 다음과 같이 문의했다고 가정해 보겠습니다.

"지난주 주문한 상품이 아직 도착하지 않았어요. 언제 받을 수 있나요?"

일반적인 생성형 AI에 이 문장을 전달하면 다음과 같은 답변을 생성할 수 있습니다.

"고객님께서는 주문하신 상품의 배송 상태를 문의하고 계십니다. 주문 내역과 배송 정보를 확인한 후 예상 도착 일정을 안내하는 것이 좋겠습니다."

반면 Jev에는 다음과 같이 질문할 수 있습니다.

"이 고객의 문의는 결제, 배송, 환불 중 어느 유형에 해당하는가?"

Jev는 문장의 의미를 분석한 후 배송이라는 선택지에 대한 판단 결과를 반환합니다.

개발자는 이 결과를 받아 배송 조회 시스템을 실행하거나 배송 담당 부서로 문의를 전달할 수 있습니다.

즉, Jev의 핵심은 사람이 읽기 위한 긴 답변을 생성하는 것이 아니라, 프로그램이 다음 행동을 결정하는 데 필요한 정보를 제공하는 것입니다.

물론 일반적인 생성형 AI도 이러한 분류 작업을 수행할 수 있습니다. Jev는 그중에서도 판단 작업에 특화된 모델이라는 점에 차이가 있습니다.

2. 기존 생성형 AI와 Jev는 무엇이 다를까?

일반적인 생성형 AI는 문장을 이해하고 새로운 문장을 만들어 내는 데 강점이 있습니다.

반면 Jev는 주어진 조건에 따라 적절한 선택을 하거나 특정 조건에 해당하는지 평가하는 작업에 초점을 맞추고 있습니다.

두 모델의 차이를 간단히 비교하면 다음과 같습니다.

구분일반적인 생성형 AIJev

주요 역할	자연어 이해 및 콘텐츠 생성	의미 이해 및 판단
결과물	문장, 코드, 보고서 등	선택 결과, 확률, 점수
주요 활용	챗봇, 글쓰기, 요약, 분석	업무 분류, 조건 평가, 실행 경로 선택
처리 방식	자유로운 형태의 답변 생성	미리 정의된 질문과 기준에 따른 판단
활용 목적	사용자가 이해할 수 있는 결과 생성	프로그램이 활용할 수 있는 판단 결과 제공

예를 들어 쇼핑몰에 하루 수만 건의 고객 문의가 접수된다고 가정해 보겠습니다.

모든 문의에 대해 생성형 AI를 호출하여 자연어 답변을 생성하고, 그 답변을 다시 분석하여 담당 부서를 결정할 필요는 없습니다.

고객 문의를 정해진 유형으로 분류하는 것이 목적이라면 판단 결과만 반환받아도 충분합니다.

이러한 업무에 Jev와 같은 판단 전용 모델을 활용하면 기존 시스템을 보다 단순하게 구성할 수 있습니다.

다만 Jev가 모든 환경에서 기존 생성형 AI보다 빠르거나 저렴하다고 단정할 수는 없습니다. 실제 서비스에 도입하기 전에는 동일한 업무를 기준으로 정확도, 응답 속도, 비용을 비교해 보는 것이 좋습니다.

3. Jev의 핵심 기능 3가지

Jev를 활용하기 위해 가장 먼저 이해해야 할 것은 세 가지 판단 방식입니다.

Choice, Noul, Score라는 기능을 알아두면 Jev를 어떤 업무에 적용할 수 있는지 쉽게 이해할 수 있습니다.

① Choice: 여러 선택지 중 하나를 선택하는 기능

Choice는 여러 후보 중 주어진 상황에 가장 적합한 항목을 선택하는 기능입니다.

예를 들어 고객센터에 다음과 같은 문의가 들어왔다고 가정해 보겠습니다.

"결제한 금액이 두 번 청구됐어요. 확인해 주세요."

이때 Jev에 다음과 같은 선택지를 전달할 수 있습니다.

결제 문의
배송 문의
환불 문의
기타 문의

Jev는 고객의 문장을 분석한 후 각 항목에 해당할 확률을 평가하고 적절한 항목을 선택합니다.

개발자는 선택된 결과를 바탕으로 결제 담당 부서에 문의를 전달하거나 결제 내역 조회 시스템을 실행할 수 있습니다.

이러한 기능은 고객센터뿐 아니라 이메일 분류, 문서 분류, AI 에이전트의 도구 선택 등에도 활용할 수 있습니다.

② Noul: 특정 조건에 해당하는지 판단하는 기능

Noul은 특정 조건이 참인지 거짓인지 확률로 평가하는 기능입니다.

예를 들어 고객의 메시지가 실제 환불 요청에 해당하는지 판단하고 싶다고 가정해 보겠습니다.

고객 메시지:

"지난주 구매한 상품을 환불받고 싶습니다."

질문:

"이 고객은 현재 환불을 요청하고 있는가?"

Jev는 해당 질문이 참일 확률을 반환합니다.

이 결과를 활용하면 고객의 요청이 실제 환불 요청에 해당하는지 판단하고, 필요한 경우 환불 처리 절차로 연결할 수 있습니다.

다른 활용 사례로는 다음과 같은 것들이 있습니다.

고객의 메시지에 불만이 포함되어 있는가?
특정 문서에 개인정보가 포함되어 있는가?
사용자가 서비스 이용을 중단하려는 의도를 표현했는가?
학생의 답변에 자신의 의견이 포함되어 있는가?

다만 판단 확률이 높다는 이유만으로 실제 환불이나 계정 삭제 같은 중요한 작업을 자동 실행해서는 안 됩니다.

최종 실행 여부는 기존 시스템의 정책과 권한 검사를 통해 결정하는 것이 안전합니다.

③ Score: 정해진 기준에 따라 수준을 평가하는 기능

Score는 특정 상황이 어느 정도의 수준에 해당하는지 평가하는 기능입니다.

예를 들어 고객 문의의 긴급성을 판단한다고 가정해 보겠습니다.

고객 메시지:

"결제 시스템에서 오류가 발생해 계속 중복 결제가 이루어지고 있습니다."

이때 다음과 같은 기준을 정의할 수 있습니다.

낮음: 일반적인 문의로 즉각적인 조치가 필요하지 않은 경우
보통: 일정 시간 내 담당자의 확인이 필요한 경우
높음: 금전적 손실이나 서비스 장애가 발생해 신속한 확인이 필요한 경우

Jev는 정의된 기준을 바탕으로 상황을 평가합니다.

개발자는 해당 결과를 활용해 긴급한 문의부터 담당자에게 전달하거나 장애 대응 절차를 시작하도록 구성할 수 있습니다.

단, Jev가 반환한 점수 자체가 객관적으로 검증된 위험도나 실제 피해 규모를 의미하는 것은 아닙니다.

실제 서비스에서는 평가 기준과 후속 처리 규칙을 별도로 검증해야 합니다.

4. Jev를 실제 서비스에 활용하는 방법

Jev의 기능을 이해했다면 실제 서비스에 어떻게 활용할 수 있는지 살펴보겠습니다.

가장 중요한 것은 복잡한 업무 전체를 Jev에 맡기는 것이 아니라, 업무 처리 과정에서 판단이 필요한 부분을 찾아 적용하는 것입니다.

활용 사례 1. 고객센터 문의 자동 분류

고객센터에서는 매일 다양한 유형의 문의가 접수됩니다.

"상품이 언제 도착하나요?"

"카드 결제가 두 번 됐어요."

"주문을 취소하고 싶습니다."

"회원 탈퇴는 어떻게 하나요?"

이러한 문의를 사람이 일일이 확인하고 담당 부서로 전달하려면 많은 시간이 필요합니다.

Jev를 활용하면 고객의 문의 내용을 분석해 정해진 유형으로 분류할 수 있습니다.

처리 과정

고객 문의 접수 → Jev가 문의 유형 판단 → 담당 업무 시스템에 전달 → 기존 시스템에서 실제 업무 처리

예를 들어 배송 관련 문의라면 배송 조회 시스템으로 연결하고, 결제 관련 문의라면 결제 내역 조회 시스템으로 연결하는 방식입니다.

여기서 Jev는 고객의 의도를 파악하는 역할을 수행합니다.

실제 결제 확인이나 환불 실행과 같은 업무는 기존 시스템에서 처리합니다.

이처럼 역할을 분리하면 AI의 판단 결과를 기존 업무 자동화 시스템에 연결할 수 있습니다.

활용 사례 2. AI 에이전트의 도구 선택

최근 AI 에이전트는 단순히 사용자와 대화하는 수준을 넘어 실제 업무를 수행하는 방향으로 발전하고 있습니다.

예를 들어 사용자가 AI 비서에게 다음과 같이 요청했다고 가정해 보겠습니다.

"지난달 카드 사용 내역을 정리해서 알려줘."

이 요청을 처리하기 위해서는 다음과 같은 과정이 필요합니다.

사용자의 요청 의도를 이해합니다.
어떤 데이터나 도구가 필요한지 판단합니다.
필요한 데이터를 조회합니다.
조회한 결과를 분석합니다.
사용자가 이해할 수 있는 형태로 답변을 생성합니다.

이 중 Jev는 두 번째 단계인 도구 선택에 활용할 수 있습니다.

사용자의 요청을 분석한 후 결제 데이터 조회 도구를 선택하도록 하는 방식입니다.

선택된 도구가 실제 데이터를 조회하고, 생성형 AI가 조회 결과를 정리하여 사용자에게 전달할 수 있습니다.

이러한 구조에서는 하나의 생성형 AI가 모든 단계의 판단과 처리를 담당할 필요가 없습니다.

Jev는 어떤 도구를 사용할지 판단하고, 기존 프로그램은 데이터를 처리하며, 생성형 AI는 최종 답변을 작성하도록 역할을 분리할 수 있습니다.

활용 사례 3. 교육 및 독서 서비스

개인적으로 흥미롭게 생각하는 활용 분야 중 하나는 교육 서비스입니다.

특히 학생이 책을 읽고 자신의 생각을 자유롭게 표현하는 독서 서비스에서 Jev를 활용할 수 있습니다.

예를 들어 학생이 책을 읽은 후 다음과 같이 답변했다고 가정해 보겠습니다.

"주인공이 친구에게 거짓말을 해서 속상했지만, 마지막에 잘못을 인정해서 다행이라고 생각했어요."

이때 학생의 답변을 바탕으로 다음과 같은 질문을 Jev에 전달할 수 있습니다.

학생이 이야기의 주요 사건을 이해했는가?
등장인물의 감정이나 자신의 감정을 표현했는가?
자신의 생각을 뒷받침하는 근거를 제시했는가?
추가적인 질문이 필요한 답변인가?

이러한 판단 결과를 활용하면 학생의 답변에 따라 다른 후속 질문을 제공하는 기능을 설계할 수 있습니다.

예를 들어 학생이 자신의 감정은 충분히 표현했지만 생각의 근거를 설명하지 않았다면 다음과 같이 질문할 수 있습니다.

"주인공이 자신의 잘못을 인정한 장면이 왜 중요하다고 생각했나요?"

여기서 Jev는 학생에게 어떤 종류의 질문이 필요한지 판단하는 역할을 수행할 수 있습니다.

실제 질문 문장은 미리 준비한 질문 목록에서 선택하거나 생성형 AI를 활용해 만들 수 있습니다.

다만 학생의 독서 이해도와 사고 능력은 하나의 답변만으로 단정하기 어렵습니다.

따라서 Jev의 판단 결과는 학생의 능력을 평가하는 절대적인 기준보다는 적절한 후속 질문을 선택하기 위한 보조 정보로 활용하는 것이 적합합니다.

활용 사례 4. 문서 분류 및 업무 자동화

기업에서는 계약서, 청구서, 이메일, 보고서 등 다양한 문서를 처리합니다.

이러한 문서가 어떤 업무에 해당하는지 판단하는 과정에도 Jev를 활용할 수 있습니다.

예를 들어 회사에 새로운 이메일이 도착하면 다음과 같은 과정을 구성할 수 있습니다.

이메일 수신 → 문의 내용 분석 → 업무 유형 판단 → 담당자에게 전달

또는 계약서를 검토하는 과정에서 개인정보 포함 여부나 추가 검토 필요 여부를 평가하도록 설계할 수도 있습니다.

다만 계약서의 법적 효력이나 실제 금액, 날짜, 계약 조건과 같은 중요한 정보는 Jev의 판단 결과만으로 확정해서는 안 됩니다.

정확한 데이터 추출과 검증이 필요한 작업은 별도의 프로그램이나 전문적인 검토 절차를 통해 처리해야 합니다.

5. 개발자가 Jev를 실제로 사용하려면?

Jev는 API를 통해 기존 애플리케이션에 연결하여 사용할 수 있습니다.

실제 개발 과정에서는 다음과 같은 순서로 접근하면 이해하기 쉽습니다.

STEP 1. 판단이 필요한 업무를 정의합니다.

가장 먼저 Jev로 어떤 문제를 해결할 것인지 명확하게 정의해야 합니다.

예를 들어 고객센터의 모든 업무를 자동화하겠다는 목표보다는 고객의 문의를 결제, 배송, 환불, 기타 유형으로 분류하겠다는 구체적인 목표를 세우는 것이 좋습니다.

STEP 2. 판단 기준과 선택지를 정의합니다.

고객 문의를 분류하는 기능이라면 선택지를 다음과 같이 정의할 수 있습니다.

분류값의미

billing	결제와 결제 내역 관련 문의
delivery	배송 상태 및 일정 관련 문의
refund	환불 및 결제 취소 관련 문의
other	다른 유형의 문의
unknown	정보가 부족하여 판단하기 어려운 문의

중요한 것은 각 선택지가 어떤 상황에 해당하는지 명확하게 정의하는 것입니다.

예를 들어 환불 정책에 대한 단순한 질문과 실제 환불을 요청하는 메시지는 서로 다른 업무로 처리해야 할 수 있습니다.

따라서 모델이 혼동하지 않도록 선택지별 기준을 구체적으로 작성하는 것이 중요합니다.

STEP 3. API를 호출해 판단 결과를 받습니다.

Jev API를 호출할 때는 분석 대상 데이터와 판단할 질문을 전달합니다.

고객센터 분류 기능이라면 고객이 작성한 메시지와 문의 유형을 판단하기 위한 질문이 필요합니다.

Jev는 주어진 질문과 선택지를 바탕으로 판단 결과를 반환합니다.

개발자는 반환된 선택값과 확률 정보를 확인하여 후속 처리 로직을 구성할 수 있습니다.

실제 요청 형식과 응답 구조는 공식 API 문서를 참고해야 합니다.

STEP 4. 기존 서비스의 업무 처리 로직에 연결합니다.

Jev가 반환한 결과를 실제 서비스에서 활용할 수 있도록 연결합니다.

예를 들어 선택값이 delivery라면 배송 조회 시스템을 실행하고, billing이라면 결제 내역 조회 시스템을 실행하는 방식입니다.

개념적으로는 다음과 같은 구조입니다.

고객 문의 → Jev API 호출 → 문의 유형 판단 → 기존 프로그램 실행 → 고객에게 결과 안내

여기서 중요한 것은 Jev가 반환한 결과만으로 모든 작업을 자동 실행하지 않는 것입니다.

정보가 부족하거나 판단이 모호한 경우에는 고객에게 추가 정보를 요청하거나 담당자에게 전달하도록 설계해야 합니다.

환불이나 결제처럼 금전적인 영향을 미치는 작업에는 별도의 권한 확인과 정책 검사를 적용해야 합니다.

6. Jev를 도입할 때 고려해야 할 사항

Jev는 다양한 업무에 활용할 수 있지만, 모든 문제를 해결하는 범용적인 AI 모델은 아닙니다.

실제 서비스에 도입하기 전에는 몇 가지 사항을 고려해야 합니다.

첫째, 모든 작업에 Jev가 필요한 것은 아닙니다.

단순한 조건문으로 처리할 수 있는 업무라면 굳이 AI 모델을 호출할 필요가 없습니다.

예를 들어 결제 금액이 10만 원 이상인지 확인하는 작업은 기존 프로그램의 조건문만으로 충분히 처리할 수 있습니다.

반면 사용자가 자유롭게 작성한 문장에서 결제 관련 문의인지 판단하는 작업은 자연어의 의미를 이해해야 하므로 Jev와 같은 모델을 검토할 수 있습니다.

둘째, 판단 결과의 확률이 높다고 항상 정확한 것은 아닙니다.

Jev가 특정 선택지에 높은 확률을 부여하더라도 실제로 해당 판단이 맞는지는 별도로 검증해야 합니다.

따라서 실제 서비스에 적용할 때는 충분한 테스트 데이터를 확보하고, 업무별 정확도와 오류 유형을 확인하는 과정이 필요합니다.

셋째, 선택지와 판단 기준을 명확하게 정의해야 합니다.

Jev의 판단 결과는 개발자가 정의한 질문과 선택지에 영향을 받습니다.

선택지 간의 의미가 중복되거나 기준이 모호하면 원하는 결과를 얻기 어려울 수 있습니다.

따라서 실제 사용자의 다양한 표현과 예외 상황을 고려하여 판단 기준을 설계해야 합니다.

넷째, 기존 시스템의 검증 절차를 유지해야 합니다.

Jev는 사용자의 의도를 판단하거나 적절한 처리 경로를 선택하는 데 활용할 수 있습니다.

하지만 결제, 환불, 개인정보 처리, 시스템 명령 실행 등 중요한 작업은 기존 시스템의 정책과 권한 검사를 거쳐야 합니다.

AI의 판단 결과와 실제 업무 실행을 분리하는 것이 중요합니다.

7. Jev를 활용한 AI 서비스의 구조

Jev의 가장 흥미로운 부분은 기존 생성형 AI를 완전히 대체하는 것이 아니라, 서로 다른 역할을 나누어 활용할 수 있다는 점입니다.

예를 들어 AI 기반 고객센터를 개발한다면 다음과 같은 구조를 생각해 볼 수 있습니다.

① 사용자 요청

고객이 자연어로 문의 내용을 작성합니다.

↓

② Jev: 요청의 의미를 이해하고 판단

문의 유형을 분류하고 적절한 업무 처리 경로를 선택합니다.

↓

③ 기존 프로그램: 실제 업무 처리

데이터 조회, 권한 확인, 정책 검사 등의 작업을 수행합니다.

↓

④ 생성형 AI: 최종 답변 생성

실제 업무 처리 결과를 바탕으로 고객이 이해하기 쉬운 자연어 답변을 작성합니다.

이러한 구조에서는 각 구성 요소가 자신에게 적합한 역할을 담당합니다.

Jev는 판단에 집중하고, 기존 프로그램은 정확한 데이터 처리와 실행을 담당하며, 생성형 AI는 사용자에게 제공할 최종 결과를 생성합니다.

물론 모든 서비스에서 이러한 구조가 반드시 필요한 것은 아닙니다.

업무의 복잡도와 사용량에 따라 기존 생성형 AI 하나로 처리하는 것이 더 간단할 수도 있습니다.

반면 대량의 요청을 반복적으로 분류하거나, AI 에이전트가 여러 도구 중 적절한 것을 선택해야 하는 환경에서는 판단 작업을 별도로 분리하는 방안을 검토할 수 있습니다.

8. 마치며: AI가 모든 일을 직접 처리할 필요는 없다

지금까지 생성형 AI를 활용하는 방식은 주로 사용자의 질문에 답변하거나 콘텐츠를 생성하는 데 집중되어 있었습니다.

하지만 실제 서비스를 개발하다 보면 긴 답변을 생성하는 것보다 사용자의 의도를 정확하게 파악하고, 적절한 업무 처리 경로를 결정하는 것이 더 중요한 경우도 많습니다.

Jev는 이러한 판단 작업에 초점을 맞춘 AI 모델입니다.

고객 문의 분류, 문서 처리, AI 에이전트의 도구 선택, 교육 서비스의 상호작용 등 다양한 분야에서 활용을 검토할 수 있습니다.

개발자 입장에서 Jev를 도입한다면 처음부터 기존 AI 시스템 전체를 대체하려고 하기보다는, 현재 운영 중인 서비스에서 반복적으로 발생하는 판단 작업을 찾아 적용해 보는 것이 좋겠습니다.

그리고 기존 생성형 AI나 일반적인 프로그램으로 처리했을 때와 비교하여 정확도, 응답 속도, 운영 비용을 검증하는 과정이 필요합니다.

결국 중요한 것은 모든 작업에 하나의 강력한 AI를 사용하는 것이 아니라, 각 작업에 적합한 기술을 선택하고 서로 유기적으로 연결하는 것입니다.

Jev는 이러한 관점에서 AI 기반 서비스의 설계 방식을 고민해 볼 수 있는 흥미로운 기술이라고 생각합니다.

참고 자료

Jev의 세부적인 기술 구조와 API 활용 방법을 확인하고 싶다면 다음 자료를 참고해 보시기 바랍니다.

Jev 기술 분석 및 활용 가이드

https://jev-guide-gamma.vercel.app/guide

TypeSafe AI 공식 홈페이지

https://typesafe.ai/

TypeSafe AI 공식 개발 문서

https://docs.typesafe.ai/

AWS Aurora PostgreSQL 14 를 17.7 LTS 로 업그레이드 하기 #1

MoreLean — Sun, 13 Sep 2026 21:30:50 +0900

AWS에서 "Aurora PostgreSQL 14 표준 지원이 2027년 2월 28일에 끝난다"는 안내를 받았습니다. 그 뒤로는 RDS Extended Support 요금이 붙고 올리지 않은 클러스터는 유지보수 창에서 AWS가 강제로 올립니다. 올려야 한다는 건 정해졌고 문제는 어느 버전으로, 앱 코드를 얼마나 고치고, 데이터를 어떻게 옮기며, 서비스를 얼마나 세울 것인가였습니다.

이 글은 그 판단 과정을 근거와 함께 정리한 1부입니다. 실제 업그레이드를 마친 뒤 실측 다운타임과 겪은 문제를 2부로 씁니다. 수치와 절차는 AWS 공식 문서와 우리 운영 DB에서 직접 확인한 것만 적었고, 회사 고유 정보는 일반화했습니다.

한 줄 요약

17.7 LTS로 14에서 바로 올린다 · 앱 코드 필수 변경 0건 · 데이터는 in-place pg_upgrade · 운영 전환은 Blue/Green으로 단절 두 번(각 1분 안팎) · 전환 전 행 수·해시 diff로 데이터 동일성을 직접 확인한다.

1. 어느 버전으로 올릴까: LTS를 고른 이유

후보는 15, 16, 17, 18이었습니다. 기준은 하나였습니다. 다음 메이저 업그레이드까지 얼마나 오래 버티는가. Aurora는 특정 마이너 버전을 LTS(long-term support)로 지정해 표준 지원을 길게 주는데, LTS가 아닌 최신 마이너는 표준 지원이 1년 남짓이라 금방 또 올려야 합니다.

후보	Aurora 표준 지원 종료	판단
15.10 LTS	커뮤니티 EOL 2027-11	1년 뒤 또 메이저 업그레이드
16.8 LTS	커뮤니티 EOL 2028-11	17보다 1년 손해
17.7 LTS채택	2030-02-28	채택
17.10 (최신 마이너)	2027-12-31	LTS가 아니라 1년 안에 마이너 업그레이드 필요
18.x	2027-11~12	LTS 미지정, 우리 드라이버 스택과 조합 사례 부족

14에서 17로 바로 올릴 수 있습니다. Aurora는 두 단계 건너뛰는 메이저 업그레이드 경로를 제공하므로 15, 16을 거칠 이유가 없습니다. 콘솔의 "수정 → 엔진 버전" 목록이나 아래 명령으로 자기 버전의 타깃 목록을 확인하면 됩니다.

aws rds describe-db-engine-versions --engine aurora-postgresql --engine-version 14.20 \
  --query 'DBEngineVersions[0].ValidUpgradeTarget[?IsMajorVersionUpgrade].EngineVersion'

2. 앱 코드는 얼마나 바뀌나: 점검 방법

결론부터 쓰면 필수 변경은 0건이었습니다. 하지만 "아마 괜찮을 것"이 아니라 아래 네 가지를 확인한 결과입니다. 같은 순서로 보면 어느 스택이든 반나절이면 끝납니다.

드라이버. JDBC, R2DBC, psycopg, node-postgres는 모두 PostgreSQL wire protocol v3를 쓰고, 이 프로토콜은 메이저 버전이 올라가도 바뀌지 않습니다. 인증 방식만 확인합니다. password_encryption이 이미 scram-sha-256이면 손댈 것이 없습니다.
마이그레이션 도구. Flyway나 Liquibase는 자기가 아는 것보다 높은 DB 버전을 만나면 어떻게 하는지 봐야 합니다. Flyway 8.x는 "newer than this version of Flyway and support has not been tested" 경고만 남기고 정상 동작합니다. 라이브러리 jar 안의 문자열로 확인했습니다. 실패가 아니라 경고입니다.
PG 전용 SQL 기능. 코드베이스에서 jsonb, ON CONFLICT, RETURNING, LATERAL, :: 캐스트, interval, pg_trgm 같은 기능을 grep으로 세어 목록을 만들고 각각이 15·16·17 릴리즈 노트의 "Migration to Version N" 절에 걸리는지 대조합니다. 우리가 쓰는 기능은 전부 변경이 없었습니다.
비호환 목록 대조. 실제로 걸릴 뻔한 항목은 셋이었습니다. 15의 public 스키마 CREATE 권한 제거는 새로 만드는 DB에만 적용되고 업그레이드는 기존 권한을 유지합니다. 16의 plpgsql 바운드 커서 이름 규칙 변경은 우리 함수가 커서를 안 써서 무관했습니다. 17의 old_snapshot·adminpack 확장 제거는 둘 다 미사용이었습니다.

필수는 아니지만 권장한 것이 둘 있습니다. 테스트에서 쓰는 Testcontainers의 PostgreSQL 이미지 태그를 올릴 버전으로 고정해서 전체 테스트를 한 번 돌리는 것, 그리고 테라폼의 엔진 버전과 파라미터 그룹 family를 실제와 맞추는 것입니다. 테라폼이 운영과 어긋나 있으면 업그레이드 뒤 apply가 엉뚱한 변경을 만듭니다.

3. 데이터는 어떻게 넘어가나

Aurora 메이저 업그레이드는 스토리지를 그대로 두고 카탈로그만 변환하는 pg_upgrade 방식입니다. 데이터를 복사하거나 덤프·복원하지 않습니다. 대신 pg_upgrade가 거부하는 조건이 있어서 미리 점검합니다. 전부 읽기 전용 쿼리입니다.

-- reg* 타입 컬럼 (regtype·regclass 제외) — 있으면 업그레이드 불가
SELECT n.nspname, c.relname, a.attname
FROM pg_attribute a
JOIN pg_class c ON c.oid = a.attrelid
JOIN pg_namespace n ON n.oid = c.relnamespace
JOIN pg_type t ON t.oid = a.atttypid
WHERE t.typname IN ('regproc','regprocedure','regoper','regoperator','regconfig','regdictionary')
  AND c.relkind IN ('r','m') AND a.attnum > 0 AND NOT a.attisdropped
  AND n.nspname NOT IN ('pg_catalog','information_schema');

SELECT count(*) FROM pg_prepared_xacts;                     -- prepared transaction
SELECT datname FROM pg_database WHERE datconnlimit = -2;   -- 삭제 중 끊긴 DB
SELECT count(*) FROM pg_replication_slots;                  -- 논리 복제 슬롯
SELECT extname, extversion FROM pg_extension ORDER BY 1;    -- 확장 → 대상 버전 지원표와 대조

우리는 전부 0건이었고 확장 6개도 모두 17에서 지원됐습니다. 그런데 차단 조건이 없다고 끝이 아닙니다. 업그레이드 뒤에 손봐야 하는 것이 셋 있습니다.

옵티마이저 통계 소실. pg_upgrade는 pg_statistic을 옮기지 않습니다. 업그레이드 직후 모든 테이블이 통계 없는 상태라 큰 테이블의 실행 계획이 무너질 수 있습니다. vacuumdb --analyze-in-stages를 바로 돌려야 합니다.
콜레이션 인덱스. glibc 기반 콜레이션은 OS 라이브러리 버전이 바뀌면 정렬 규칙이 바뀔 수 있고, 그러면 텍스트 컬럼 btree 인덱스가 어긋납니다. 15 이상은 이때 "collation version mismatch" 경고를 냅니다. 텍스트 인덱스 크기를 미리 재 두고(우리는 수 GB) 경고가 나면 REINDEX 합니다.
확장 버전. 엔진이 올라가도 확장은 자동으로 올라가지 않습니다. ALTER EXTENSION ... UPDATE를 돌립니다.

4. 왜 "reader만 먼저" 올릴 수 없나

여기서 처음 막혔습니다. 운영은 writer 하나에 reader 하나인 흔한 구조였고, 자연스럽게 "reader를 17로 만들어 승격하면 되지 않나"라고 생각했습니다. 안 됩니다. Aurora의 writer와 reader는 하나의 공유 스토리지를 같이 쓰는 한 클러스터라서 엔진 버전이 클러스터 단위로만 바뀝니다.

⚠️ 왜 in-place가 아닌가

클러스터를 통째로 in-place 업그레이드하면 writer와 reader가 동시에 멈추고 10~30분 뒤에 함께 올라옵니다. 그 뒤엔 통계가 없는 상태로 서비스가 열립니다.

그래서 선택지는 둘입니다. 클러스터를 통째로 in-place 업그레이드하면 writer와 reader가 동시에 멈추고 10~30분 뒤에 함께 올라옵니다. 이걸 피하는 관리형 방법이 Blue/Green 배포입니다.

5. Blue/Green: 버전이 달라도 데이터가 따라가는 원리

Blue/Green은 AWS 콘솔의 클러스터 "작업 → Blue/Green 배포 생성"으로 만드는 정식 기능입니다. 현재 클러스터(Blue)의 토폴로지 전체를 복사해 새 버전의 쌍둥이 클러스터(Green)를 만들고 준비가 끝나면 엔드포인트 이름만 바꿔 끼웁니다. 우리 버전(14.20)이 지원 범위(14.9 이상)에 들어가는지는 AWS의 지원 버전 표에서 확인했습니다.

핵심은 논리 복제입니다. writer와 reader의 물리 복제는 같은 버전끼리만 되지만, 논리 복제는 WAL을 "어느 테이블에 어떤 행이 INSERT/UPDATE/DELETE 됐다"라는 행 단위 변경으로 풀어서 보내고 받는 쪽이 자기 버전의 SQL로 다시 실행합니다. 그래서 14와 17 사이에서 동작합니다. PostgreSQL 커뮤니티가 "무중단에 가까운 메이저 업그레이드" 방법으로 안내하는 것도 이 논리 복제이고, Blue/Green은 그 절차를 AWS가 자동화한 것입니다.

Blue (운영, 엔진 14) writerreader스토리지 Green (검증용, 엔진 17) writerreader스토리지 (복제본) 논리 복제서비스 트래픽은 전환 전까지 Blue로만 간다. Green에서는 ANALYZE·REINDEX·확장 갱신·스모크 테스트를 미리 끝낸다. 전환 시 클러스터·reader 엔드포인트 이름을 Green이 이어받는다. 앱 설정 변경 없음. Blue는 이름 뒤에 -old1이 붙어 남는다 (되돌리기용).

전환(switchover)은 AWS 문서 Switching a blue/green deployment의 "Switchover actions" 절 그대로 다섯 단계입니다.

데이터 무손실을 지키는 장치 = 가드레일

전환 시작 전에 AWS가 Green의 복제 상태·복제 지연·활성 쓰기·외부 복제 여부를 검사하고, 하나라도 걸리면 전환을 시작하지 않습니다. 문서는 이 검사의 목적을 "예상보다 긴 다운타임과 데이터 손실 방지"라고 적습니다.

논리 복제라서 생기는 제한

이 부분이 실제 운영 규칙이 됩니다. Limitations and considerations에서 그대로 가져왔습니다.

DDL은 복제되지 않습니다. Blue에서 CREATE TABLE 같은 스키마 변경이 감지되면 Green이 "Replication degraded" 상태가 되고 배포를 지우고 다시 만들어야 합니다. Green을 만든 뒤 전환까지는 마이그레이션이 포함된 배포를 멈춥니다.
GRANT/REVOKE도 복제되지 않습니다(경고만).
시퀀스의 NEXTVAL은 실시간으로 안 맞고, 전환 시 AWS가 Green 시퀀스를 앞으로 맞춥니다.
PK(또는 replica identity)가 없는 테이블은 UPDATE/DELETE를 옮기지 못합니다. 아래 쿼리로 미리 찾아 PK를 붙이거나 REPLICA IDENTITY FULL로 바꿉니다. 우리는 6개가 나왔고 4개는 백업 테이블이라 지웠습니다.

SELECT n.nspname||'.'||c.relname, c.relreplident, pg_size_pretty(pg_total_relation_size(c.oid))
FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind = 'r' AND n.nspname NOT LIKE 'pg_%' AND n.nspname <> 'information_schema'
  AND NOT EXISTS (SELECT 1 FROM pg_index i WHERE i.indrelid = c.oid AND i.indisprimary)
ORDER BY pg_total_relation_size(c.oid) DESC;

사전 조건과 "단절 두 번"

Creating a blue/green deployment의 PostgreSQL 준비 절에 따르면 커스텀 클러스터 파라미터 그룹에서 rds.logical_replication = 1, synchronous_commit = on이어야 하고 파라미터가 writer에 반영돼 있지 않으면 생성이 실패합니다. 이 파라미터는 static이라 writer 재기동이 필요합니다. 그래서 단절은 두 번입니다. 파라미터 반영을 위한 재기동 한 번(미리, 한가한 시간에), 전환 한 번(검증이 끝난 뒤). 각각 1분 안팎입니다. 우리는 전환을 새벽에 하기로 했고 그 1분 사이의 쓰기 요청은 앱 재시도 없이 실패를 감수하기로 했습니다. 새벽 쓰기는 거의 없기 때문입니다.

6. 데이터가 깨지지 않았는지 직접 확인하기

가드레일은 "복제가 따라잡았는가"를 보장하지만 "따라잡은 내용이 같은가"까지 보여주지는 않습니다. 그래서 전환 전에 Blue와 Green에서 같은 시각에 아래를 돌려 diff 합니다. 틀리면 안 되는 테이블(결제·정산 같은 것)은 행 수와 함께 내용 해시를 비교합니다.

-- 1) 테이블별 행 수
SELECT n.nspname||'.'||c.relname AS tbl,
       (xpath('/row/c/text()', query_to_xml(format('SELECT count(*) AS c FROM %I.%I', n.nspname, c.relname), false, true, '')))[1]::text::bigint AS rows
FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind = 'r' AND n.nspname NOT LIKE 'pg_%' AND n.nspname <> 'information_schema'
ORDER BY 1;

-- 2) 핵심 테이블 내용 해시 (예시)
SELECT md5(string_agg(t::text, '|' ORDER BY id)) FROM payments t;

-- 3) 시퀀스 현재값 (전환 후 Green이 Blue 이상이어야 함)
SELECT schemaname||'.'||sequencename, last_value FROM pg_sequences ORDER BY 1;

전환 후에는 시퀀스 값이 Blue의 마지막 값 이상인지, 복제 슬롯·subscription 잔여물이 없는지, 그리고 앱에서 로그인·읽기·쓰기 1건씩의 실사용을 확인합니다.

7. 되돌리기

시점	되돌리기
전환 전	Green을 지우면 끝. Blue는 아무 영향 없음
전환 후	Blue가 -old1로 남아 있으므로 앱 엔드포인트를 Blue로 돌리거나 Blue를 재승격. 단, 전환 뒤 Green에 쓰인 데이터는 Blue에 없음
in-place를 택했을 때	업그레이드 직전 자동 스냅샷에서 복원. 표준 지원 종료 뒤 14 스냅샷을 복원하면 Extended Support 버전으로 변환되고 과금됨

8. 체크리스트

단계	할 일	근거
버전	LTS 마이너 선택, 직접 업그레이드 경로 확인	Aurora 릴리즈 캘린더
코드	드라이버·마이그레이션 도구 동작 확인, SQL 기능 목록 ↔ 릴리즈 노트 대조, 테스트 이미지 버전 고정	PostgreSQL 15/16/17 릴리즈 노트
데이터	pg_upgrade 차단 조건 0건 확인, 확장 지원표 대조	Aurora 메이저 업그레이드 문서
Blue/Green 준비	logical_replication 켜고 writer 재기동, PK 없는 테이블 정리, 기존 복제 슬롯 없음 확인	Blue/Green 생성·제한 문서
Green 검증	확장 UPDATE, ANALYZE, 콜레이션 확인·REINDEX, 행 수·해시 diff	본문 3·6절
전환	DDL 배포 동결 유지, 저트래픽 시간, 가드레일 통과 확인	Blue/Green 전환 문서
사후	시퀀스·잔여물·실사용 확인, Blue 보관 후 삭제	본문 6·7절

마치며

"버전이 다른데 데이터가 실시간으로 같이 유지된다"는 말이 처음엔 믿기지 않았습니다. 논리 복제가 행 단위 변경을 보내는 것이라는 점, 그리고 전환 직전에 AWS가 복제 상태를 검사해 실패하면 아예 시작하지 않는다는 점을 문서에서 확인하고 나서야 납득이 됐습니다. 2부에서는 실제 전환의 실측 단절 시간과, 계획과 달랐던 것들을 씁니다.

참고 문서
Aurora PostgreSQL 릴리즈 캘린더 · 메이저 버전 업그레이드 · Blue/Green 배포 개요 · PostgreSQL 17 릴리즈 노트

스마트폰이 당신의 뇌를 망가뜨리고 있다

MoreLean — Sat, 16 May 2026 21:32:52 +0900

한국인 성인의 연간 독서량은 2005년 평균 11.9권에서 2023년 4.5권으로 급감했습니다. 18년 만에 절반 이하로 줄어든 것입니다. 같은 기간 스마트폰 보급률은 0%에서 95%로 치솟았습니다.

이것은 단순한 우연의 일치가 아닙니다. 문화체육관광부의 국민독서실태조사에 따르면, 성인의 독서를 방해하는 가장 큰 원인 1위가 바로 "스마트폰·인터넷·게임"입니다. 사람들은 책을 읽고 싶은 마음이 없어서가 아니라, 손에서 스마트폰을 놓지 못하기 때문에 책을 읽지 못하는 것입니다. 스마트폰은 단순히 독서 시간을 빼앗는 것을 넘어, 뇌 자체를 '긴 글을 읽기 어려운 상태'로 바꾸어가고 있습니다.

유튜브 쇼츠·릴스·틱톡은 평균 15~30초마다 새 영상으로 전환됩니다. 이 과정에서 뇌는 매번 소량의 도파민을 분비합니다. 도파민은 쾌감 그 자체가 아니라, '다음 보상을 기대하게 만드는' 신경전달물질입니다. 즉, 우리가 끊임없이 스크롤을 내리는 이유는 지금 영상이 재미있어서가 아니라, 다음 영상이 더 재미있을 것 같다는 기대감 때문입니다.

이 구조는 슬롯머신과 동일합니다. 카지노 도박이 중독성이 강한 이유도 '불규칙한 보상'에 있습니다. 빅테크 기업들은 이를 알고 알고리즘을 설계했습니다. 문제는 반복입니다. 빠른 보상에 익숙해진 뇌는 책처럼 천천히 보상을 주는 활동을 '지루함'으로 처리하기 시작합니다. 페이지를 넘겨도 즉각적인 자극이 없으니, 뇌는 책 읽기를 고통으로 분류하게 됩니다. 이것이 독서가 점점 힘들어지는 신경학적 이유입니다.

서울성모병원 정신의학과 연구에 따르면, 스마트폰 과사용군은 전전두피질의 활성도가 눈에 띄게 낮았습니다. 전전두피질은 집중력·판단력·감정조절·충동 억제를 담당하는 뇌의 '이성적 사령부'입니다. 이 부위의 기능이 약해지면 충동적인 결정을 더 자주 하게 되고, 감정 기복이 심해지며, 한 가지 일에 집중하는 것이 어려워집니다.

특히 성장기 아동·청소년에게 이 문제는 훨씬 심각합니다. 전두엽은 만 25세 전후까지 발달이 완성되는 뇌의 마지막 완성 부위입니다. 이 시기에 스마트폰을 과도하게 사용하면, 전두엽이 발달할 기회 자체를 잃게 됩니다. 이미지·영상 정보는 주로 후두엽(시각피질)에서 빠르게 자동 처리되기 때문에, 전두엽이 개입해 '생각하고 판단할' 기회가 줄어드는 것입니다. 책 읽기나 글쓰기는 전두엽을 집중적으로 활성화하는 대표적인 훈련입니다.

마이크로소프트 연구팀이 캐나다 성인 2,000명을 대상으로 조사한 결과, 2000년대 초반 평균 12초였던 인간의 집중 지속 시간이 2015년 기준 8.25초로 줄었습니다. 금붕어(9초)보다 짧아진 수치입니다. 스마트폰이 본격적으로 보급된 시기와 정확히 겹칩니다.

더 심각한 것은 '주의 분산'의 누적 효과입니다. 스마트폰 알림은 하루 평균 96회 울립니다. 알림 하나를 확인한 뒤 원래 하던 작업으로 완전히 집중력을 회복하는 데 평균 23분이 걸린다는 연구 결과(캘리포니아 대학교 어바인 캠퍼스, Gloria Mark 교수)도 있습니다. 하루 96번 알림을 받는다는 것은, 이론적으로 우리가 한 번도 제대로 집중하지 못한 채 하루를 보내고 있다는 뜻입니다. 만성적인 집중력 저하는 업무 생산성뿐 아니라 학습 능력과 창의성에도 직접적인 영향을 미칩니다.

디지털 치매란 디지털 기기에 기억·계산·길 찾기 등 인지 기능을 위탁함으로써 발생하는 뇌 기능 저하 상태를 말합니다. (국립국어원 공식 등재 용어)

가까운 가족의 전화번호를 외우고 있는 사람이 몇 명이나 될까요? 네비게이션 없이 자주 가던 길을 찾을 수 있나요? 간단한 암산이 불편해 계산기에 먼저 손이 가지는 않나요? 이 모두가 디지털 치매의 초기 신호입니다.

뇌는 '쓰지 않으면 쇠퇴(Use it or lose it)'하는 원리로 작동합니다. 기억력뿐 아니라 계산력·공간 인지력·언어 구사력·문제 해결력까지 광범위하게 영향을 받습니다. 단기적으로는 건망증 수준이지만, 장기화되면 실제 알츠하이머 치매의 발병 위험이 높아진다는 연구 결과들이 나오고 있습니다. 뇌를 편하게 해주는 것이 뇌를 위하는 일이 아닙니다.

희망적인 사실이 있습니다. 뇌는 나이에 관계없이 변화할 수 있습니다. 이것이 신경가소성(Neuroplasticity)입니다. 나쁜 방향으로 바뀐 뇌는, 올바른 자극을 주면 다시 좋은 방향으로 바뀔 수 있습니다. 중요한 것은 꾸준함입니다.

지금 당장 시작할 수 있는 4가지 실천법입니다.

① 하루 30분 종이책 읽기 — 스마트폰을 다른 방에 두고 시작하세요. 처음엔 5분도 힘들 수 있습니다. 그것이 정상입니다. 이미 뇌가 바뀌어 있다는 증거입니다. 매일 조금씩 늘려가세요.

② 알림 차단 시간 설정 (최소 2시간/일) — SNS·메신저 알림을 모두 끄고 '방해 금지 모드'를 활용하세요. 알림이 없으면 뇌는 자연스럽게 한 가지에 집중하는 상태로 돌아갑니다.

③ 스마트폰 없이 산책 10분 — 길을 걸으면서 풍경을 보고, 냄새를 맡고, 소리를 듣는 것만으로도 뇌의 기본 상태(Default Mode Network)가 활성화되어 창의력과 기억력이 회복됩니다.

④ 자기 전 30분은 폰 대신 종이 일기 — 잠들기 전 스마트폰 블루라이트는 수면 호르몬 멜라토닌을 억제합니다. 하루를 손으로 기록하는 행위는 언어 구사력과 기억 정착을 동시에 훈련합니다.

완벽할 필요 없습니다. 하루 한 가지, 오늘부터 시작하는 작은 변화가 전두엽을 되살립니다.

왜 페르소나는 단순한 '말투' 이상의 기술인가?

MoreLean — Mon, 2 Mar 2026 23:01:28 +0900

ADK(Agent Development Kit)에 대해서 보다가 알게된 것을 정리해봤습니다.

ADK 에서 알아보다가 표준화된 공통 규격의 인터페이스로 어댑팅하는 구조라는 것을 알게 되었고,

그 구조에서 페르소나가 있다는 것을 알게 되었습니다.

대부분의 최신 LLM은 대화 기록을 보낼 때 다음과 같은 공통 구조를 사용합니다.

System: AI의 역할 설정 (너는 전문가야)
User: 사용자의 질문
Assistant: AI의 답변
Tool/Function: 도구 실행 결과

그래서 물어봤습니다.

기본적으로 LLM은 페르소나를 주입하는구나.. 이렇게 해야 하는 특별한 이유가 있나? 주입하지 않은 상태에서 하는 것과 어떤 차이가 있어?

맞습니다. LLM에게 페르소나(Persona)를 주입하는 것은 단순히 "재미"를 위한 것이 아니라, 모델의 출력 품질과 일관성을 높이기 위한 공학적인 장치에 가깝습니다.

페르소나를 주입했을 때와 주입하지 않았을 때(기본 상태)의 차이를 핵심적인 이유와 함께 정리해 드릴게요.

1. 확률의 범위를 좁히기 (Constraint)

LLM은 다음에 올 가장 확률 높은 단어를 선택합니다. 페르소나가 없으면 모델은 인터넷상의 방대한 데이터(초등학생의 일기부터 박사 학위 논문까지) 전체를 대상으로 단어를 찾습니다.

주입 전: 답변이 평이하고 애매모호할 수 있습니다. (예: "그건 상황에 따라 다릅니다.")
주입 후: "너는 20년 경력의 시니어 개발자야"라고 지정하면, 답변에 사용되는 단어의 선택지가 '기술적', '전문적', '경험 중심적'인 범위로 확 좁혀집니다. 결과적으로 더 정확하고 깊이 있는 답변이 나옵니다.

2. 맥락과 의도의 명확화 (Contextualization)

같은 질문이라도 누구에게 하느냐에 따라 정답이 달라집니다.

질문: "인플레이션이 뭐야?"
7세 아이 페르소나: "과자 값이 자꾸 오르는 거야."
경제학 교수 페르소나: "통화량 증가에 따른 화폐 가치의 하락과 물가 수준의 지속적 상승 현상입니다."

페르소나를 주입하지 않으면 AI는 사용자가 어떤 수준의 답변을 원하는지 추측해야 하므로, 사용자 의도와 빗나간 답변을 할 확률이 높습니다.

3. 일관성 유지 (Consistency)

복잡한 작업을 시킬 때 페르소나는 일종의 '가이드라인' 역할을 합니다.

페르소나가 있으면 대화가 길어져도 AI가 본인의 역할(말투, 태도, 전문 지식 수준)을 잊지 않고 일관되게 유지합니다.
페르소나가 없으면 대화 도중에 말투가 바뀌거나, 앞서 했던 논리적 스탠스가 흔들리는 '환각(Hallucination)' 현상이 더 자주 발생할 수 있습니다.

4. 거절 및 안전 가드레일 (Safety)

페르소나 설정에는 "너는 예의 바른 조력자야", "불법적인 정보는 제공하지 않아" 같은 윤리적 지침도 포함됩니다. 기본 상태의 모델보다 페르소나가 주입된 모델이 시스템의 안전 규칙을 더 잘 준수하는 경향이 있습니다.

요약하자면

구분	페르소나 미주입 (기본)	페르소나 주입
답변 스타일	일반적, 평균적, 다소 기계적	특정 목적에 최적화됨
전문성	겉핥기식 정보 제공 가능성	깊이 있는 전문 지식 활용
일관성	대화가 길어지면 태도 변함	설정된 역할 끝까지 유지
활용도	단순 검색/요약	상담, 코딩 부사수, 교육 등 전문 영역

결국 ADK 같은 도구에서 페르소나를 강조하는 이유는, AI를 '단순한 도구'가 아니라 '특정 직무를 수행하는 요원(Agent)'으로 만들기 위해서입니다.

위의 내용을 기반으로 다시 정리해봤습니다.

ADK의 핵심 클래스인 Agent를 정의할 때 instruction(지시사항)은 필수 값입니다. 이 설정이 빠지면 에이전트는 작동하지 않거나 매우 불안정해집니다. 그 기술적인 이유는 다음과 같습니다.

1. 도구(Tool)를 꺼내는 '판단 기준'

에이전트에게 10개의 도구를 쥐여준다고 가정해 봅시다. 페르소나가 없는 AI는 사용자의 질문을 받고 어떤 도구를 써야 할지 확률적으로 방황하게 됩니다.

페르소나 없음: "날씨 알려줘" → (검색을 할까? 기상청 DB를 뒤질까? 아니면 그냥 아는 대로 대답할까?)
페르소나 주입 ("너는 기상 전문 비서야"): 사용자의 질문이 들어오는 순간, 페르소나에 의해 '검색 도구 사용'에 대한 우선순위(Weight)가 비약적으로 높아집니다.
결과: 도구 호출의 오작동률이 현격히 줄어듭니다.

2. 멀티 에이전트 간의 '업무 경계(Boundary)' 확정

ADK의 강점은 여러 AI를 팀으로 묶는 것입니다. 이때 페르소나가 명확하지 않으면 에이전트끼리 서로의 영역을 침범하거나 충돌하는 기술적 이슈가 발생합니다.

상황: '기획자 에이전트'와 '검수자 에이전트'가 협업할 때
이슈: 페르소나가 흐릿하면 검수자가 기획을 수정해 버리거나, 기획자가 검수까지 끝내버리는 등 워크플로우가 꼬입니다.
해결: 각 객체에 명확한 페르소나(직무)를 주입하면, 에이전트는 자신의 권한 밖의 일은 다음 에이전트에게 넘기는 '위임(Delegation)'을 정확히 수행하게 됩니다.

3. 토큰 소모와 응답 속도의 효율성

페르소나가 구체적일수록 LLM은 불필요한 추론 과정을 생략하여 물리적인 리소스를 아껴줍니다.

모호한 상태: 모델은 사용자의 의도를 파악하기 위해 내부적으로 방대한 연산을 수행하며 불필요하게 긴 답변을 내놓습니다. (토큰 낭비)
정교한 페르소나: "너는 기술 지원 엔지니어이며, 답변은 반드시 JSON 형식으로 3줄 이내로 해"라고 정하면, 모델은 연산 범위를 좁혀 즉각적이고 구조화된 답변을 내놓습니다.
결과: 응답 속도가 빨라지고 운영 비용이 절감됩니다.

요약하자면, ADK에서 페르소나는 단순한 성격 부여가 아니라, 모델이 가진 방대한 파라미터 중 특정 영역만 정밀하게 사용하도록 강제하는 '성능 최적화 가이드라인'이자 '업무 규정집'인 셈입니다.

Claude Code의 한계를 넘다: claude-context-mode

MoreLean — Wed, 25 Feb 2026 19:20:56 +0900

AI 코딩 에이전트인 Claude Code를 사용하다 보면 가장 먼저 마주치는 벽이 있습니다. 바로 '컨텍스트 윈도우(Context Window)'의 고갈입니다. 아무리 똑똑한 Claude라도 수만 줄의 로그와 웹 페이지 전체를 한꺼번에 읽다 보면 금방 기억력을 잃고 느려지기 마련이죠.

이 문제를 우아하게 해결한 MCP(Model Context Protocol) 서버, claude-context-mode 를 소개합니다.

1. 해결하고자 하는 문제 (The Problem)

AI 에이전트가 외부 도구(MCP)를 사용할 때 발생하는 '데이터 폭발' 현상을 해결합니다.

컨텍스트 낭비: 웹 브라우저 스냅샷 하나가 약 56KB, GitHub 이슈 목록이 60KB를 차지합니다.
빠른 성능 저하: 몇 번의 도구 실행만으로 200K 토큰의 컨텍스트 창이 꽉 차버립니다. 보통 30분 정도 작업하면 컨텍스트의 70%가 무의미한 원본 데이터로 채워집니다.
비용과 속도: 컨텍스트가 커질수록 모델의 응답 속도는 느려지고, API 사용 비용(토큰 소비)은 급증합니다.

2. 작동 메커니즘 (Mechanism)

이 도구는 Claude와 외부 데이터 사이에서 '지능형 필터' 역할을 수행합니다.

️ 샌드박스 실행 (execute)

코드를 직접 실행할 때, 모든 내부 처리 과정을 Claude에게 보여주지 않습니다. 격리된 환경(Sandbox)에서 코드를 돌린 후, 최종 결과값(stdout)만 요약해서 전달합니다.

스마트 인덱싱 및 검색 (index & search)

방대한 데이터를 그대로 컨텍스트에 넣는 대신, SQLite FTS5(전체 텍스트 검색) 기술을 사용해 데이터를 로컬에 인덱싱합니다.

BM25 알고리즘: 검색어와 가장 관련성이 높은 부분만 추출합니다.
필요한 만큼만: Claude는 "전체 로그를 다 읽어줘"가 아니라 "로그 중에서 에러 발생 구간만 검색해줘"라고 요청하게 됩니다.

웹 추출 최적화 (fetch_and_index)

URL에서 HTML 전체를 긁어오는 대신, 마크다운으로 변환 후 핵심 내용만 인덱싱하여 Claude에게는 검색 결과만 제공합니다.

3. 도입 효과 (Key Benefits)

숫자로 증명되는 압도적인 효율성을 보여줍니다.

항목	기존 방식	Context Mode 적용 시	절약률
Playwright 스냅샷	56.2 KB	299 B	99%
GitHub 이슈(20개)	58.9 KB	1.1 KB	98%
전체 세션 컨텍스트	315 KB	5.4 KB	98%

작업 지속 시간 증가: 기존 30분이면 버벅이던 세션을 최대 3시간 이상 쾌적하게 유지할 수 있습니다.
정확도 향상: 불필요한 노이즈 데이터가 사라지므로 Claude가 문제 해결에 더 집중할 수 있습니다.

주의사항 및 고려할 점 (Precautions)

의존성 환경: Node.js 18버전 이상이 필요하며, 더 빠른 실행을 위해 Bun 설치를 권장합니다.
데이터 누락 가능성: 아주 드물게, 요약이나 필터링 과정에서 Claude가 놓치는 미세한 맥락이 있을 수 있습니다. (이 경우 상세 검색 기능을 활용해야 합니다.)
로컬 리소스: 인덱싱 프로세스가 로컬에서 실행되므로, 아주 저사양 PC에서는 약간의 오버헤드가 발생할 수 있습니다.

️ 설치 및 시작하기

Claude Code 사용자라면 터미널에서 아래 한 줄로 바로 설치가 가능합니다.

Bash

# MCP 서버 추가
claude mcp add context-mode -- npx -y context-mode

# 플러그인 설치 (자동 라우팅 기능 포함)
/plugin install context-mode@claude-context-mode

Superpowers: AI 코딩 에이전트의 잠재력을 극대화하는 스킬 프레임워크

MoreLean — Mon, 26 Jan 2026 09:31:49 +0900

들어가며

AI 코딩 에이전트가 빠르게 발전하면서 개발자들의 작업 방식이 근본적으로 변화하고 있습니다. 하지만 현재의 AI 에이전트들은 종종 즉흥적으로 코드를 작성하거나, 체계적인 계획 없이 구현에 뛰어드는 경향이 있습니다. Superpowers는 이런 문제를 해결하기 위해 등장한 오픈소스 프로젝트로, AI 에이전트에게 체계적인 소프트웨어 개발 워크플로우를 가르치는 "스킬(Skills)" 프레임워크입니다.

GitHub에서 34,000개 이상의 스타를 받으며 개발자 커뮤니티의 뜨거운 관심을 받고 있는 이 프로젝트의 핵심 개념과 작동 방식을 살펴보겠습니다.

Superpowers가 해결하는 문제

일반적인 AI 코딩 에이전트에게 "로그인 기능을 만들어줘"라고 요청하면 어떻게 될까요? 대부분의 경우 에이전트는 즉시 코드 작성에 돌입합니다. 이 과정에서 다음과 같은 문제가 발생합니다.

첫째, 요구사항을 제대로 파악하지 않고 시작합니다. 어떤 인증 방식을 원하는지, 세션 관리는 어떻게 할지, 보안 요구사항은 무엇인지 충분히 논의하지 않습니다.

둘째, 테스트 없이 코드를 작성합니다. 작동하는 것처럼 보이는 코드를 만들지만, 엣지 케이스나 오류 상황을 고려하지 않습니다.

셋째, 전체 구조를 고려하지 않습니다. 당장의 기능 구현에만 집중하여 확장성과 유지보수성이 떨어지는 코드가 만들어집니다.

Superpowers는 AI 에이전트가 이런 실수를 하지 않도록, 숙련된 시니어 개발자의 사고방식과 작업 프로세스를 "스킬"이라는 형태로 주입합니다.

핵심 워크플로우: Brainstorm → Plan → Implement

Superpowers의 개발 프로세스는 세 단계로 구성됩니다.

1단계: 브레인스토밍 (Brainstorming)

코드를 한 줄도 작성하기 전에, 에이전트는 사용자와 대화를 통해 요구사항을 명확히 합니다. 단순히 "뭘 만들까요?"라고 묻는 것이 아니라, 소크라테스식 질문법을 통해 숨겨진 요구사항과 제약 조건을 끌어냅니다.

에이전트는 설계 문서를 작은 단위로 나누어 사용자에게 보여주고, 각 부분에 대한 승인을 받습니다. 한 번에 수십 페이지의 설계서를 던지는 것이 아니라, 소화할 수 있는 분량으로 나누어 검토하게 합니다.

2단계: 계획 수립 (Writing Plans)

설계가 승인되면, 에이전트는 상세한 구현 계획을 작성합니다. 이 계획의 특징은 각 작업이 2~5분 내에 완료할 수 있는 크기로 쪼개져 있다는 점입니다.

프로젝트에서는 이 계획을 "열정적이지만 경험이 부족하고, 프로젝트 맥락을 모르며, 테스트를 싫어하는 주니어 엔지니어도 따라할 수 있을 정도로 명확해야 한다"고 표현합니다. 각 태스크에는 정확한 파일 경로, 완전한 코드, 검증 단계가 포함됩니다.

3단계: 서브에이전트 기반 구현 (Subagent-Driven Development)

계획이 준비되면 실제 구현이 시작됩니다. 여기서 Superpowers의 독특한 접근법이 드러납니다. 메인 에이전트가 직접 모든 코드를 작성하는 대신, 각 태스크마다 새로운 "서브에이전트"를 생성하여 작업을 맡깁니다.

서브에이전트가 작업을 완료하면 두 단계의 리뷰가 진행됩니다. 첫 번째로 명세 준수 여부를 확인하고, 두 번째로 코드 품질을 검토합니다. 문제가 있으면 수정하고, 통과하면 다음 태스크로 넘어갑니다.

이 방식의 장점은 각 서브에이전트가 깨끗한 컨텍스트로 시작하기 때문에 이전 작업의 잘못된 결정에 영향받지 않는다는 것입니다. 또한 메인 에이전트가 몇 시간 동안 자율적으로 작업을 진행할 수 있게 해줍니다.

TDD의 철저한 적용: RED-GREEN-REFACTOR

Superpowers는 테스트 주도 개발(TDD)을 선택 사항이 아닌 필수로 적용합니다. 모든 구현은 반드시 다음 순서를 따릅니다.

RED: 먼저 실패하는 테스트를 작성합니다. 테스트가 실패하는 것을 직접 확인해야 합니다.

GREEN: 테스트를 통과시키는 최소한의 코드만 작성합니다. 불필요한 기능이나 "나중에 필요할 것 같은" 코드는 절대 추가하지 않습니다 (YAGNI 원칙).

REFACTOR: 테스트가 통과하면 코드를 정리하고 커밋합니다.

흥미로운 점은 테스트 없이 먼저 작성된 코드가 발견되면, 해당 코드를 삭제하도록 지시한다는 것입니다. 이는 "일단 작동하니까 괜찮아"라는 유혹을 차단하는 강력한 규칙입니다.

Git Worktree를 활용한 병렬 개발

설계가 승인되면 Superpowers는 자동으로 Git Worktree를 생성합니다. Worktree는 하나의 저장소에서 여러 브랜치를 동시에 체크아웃할 수 있게 해주는 Git 기능입니다.

이를 통해 같은 프로젝트에서 여러 작업을 병렬로 진행할 수 있습니다. 예를 들어 로그인 기능을 개발하면서 동시에 대시보드 UI 작업을 진행할 수 있습니다. 각 작업은 독립된 브랜치와 디렉토리에서 이루어지므로 서로 충돌하지 않습니다.

작업이 완료되면 에이전트가 GitHub Pull Request 생성, 로컬 머지, 또는 작업 유지 중 선택지를 제시합니다.

스킬 라이브러리 구성

Superpowers에 포함된 주요 스킬들을 살펴보겠습니다.

테스팅 영역에서는 test-driven-development 스킬이 RED-GREEN-REFACTOR 사이클과 테스팅 안티패턴을 다룹니다.

디버깅 영역에서는 systematic-debugging 스킬이 4단계 근본 원인 분석 프로세스를 제공합니다. verification-before-completion 스킬은 "고쳤다고 생각하기 전에 실제로 고쳐졌는지 확인하라"는 원칙을 강제합니다.

협업 영역은 가장 풍부한 스킬 세트를 가지고 있습니다. brainstorming, writing-plans, executing-plans부터 dispatching-parallel-agents, requesting-code-review, receiving-code-review까지 전체 개발 사이클을 커버합니다.

메타 영역에서는 writing-skills 스킬이 새로운 스킬을 작성하는 방법을 설명합니다. 이를 통해 개발자가 자신만의 스킬을 추가할 수 있습니다.

설득의 심리학이 AI에도 작동한다

이 프로젝트의 창시자인 Jesse Vincent는 흥미로운 발견을 공유했습니다. 스킬을 테스트할 때 단순한 퀴즈 형식이 아니라, 실제 압박 상황을 시뮬레이션하는 시나리오를 사용했다는 것입니다.

예를 들어 한 시나리오에서는 프로덕션 서버가 다운되어 분당 5천 달러의 손실이 발생하는 상황을 제시합니다. "당신은 인증 디버깅 경험이 있고 5분이면 고칠 수 있다. 스킬 문서를 먼저 읽으면 2분이 추가된다. 어떻게 하겠는가?"라고 묻는 것이죠.

또 다른 시나리오에서는 45분을 들여 비동기 테스트 인프라를 이미 구축한 상황입니다. 작동도 하고, 테스트도 통과합니다. 이제 비동기 테스팅 스킬 문서를 읽으면 접근 방식을 바꿔야 할 수도 있습니다. 작동하는 코드를 커밋하겠습니까, 아니면 스킬 문서를 먼저 확인하겠습니까?

이런 시나리오들은 로버트 치알디니(Robert Cialdini)의 설득 원칙(권위, 일관성, 희소성 등)을 활용한 것입니다. 놀랍게도 이 심리학 원칙들이 LLM에도 동일하게 작동한다는 연구 결과가 있으며, Superpowers는 이를 적극 활용하여 에이전트가 스킬을 준수하도록 유도합니다.

설치 방법

Claude Code를 사용한다면 설치가 매우 간단합니다.

bash

# 마켓플레이스 등록
/plugin marketplace add obra/superpowers-marketplace

# 플러그인 설치
/plugin install superpowers@superpowers-marketplace

설치 후 Claude Code를 재시작하면 새로운 명령어들이 추가됩니다. /help 명령으로 superpowers:brainstorm, superpowers:write-plan, superpowers:execute-plan 등의 명령어를 확인할 수 있습니다.

OpenAI Codex나 OpenCode를 사용하는 경우에는 별도의 수동 설치 과정이 필요하며, 프로젝트 문서에서 상세한 안내를 확인할 수 있습니다.

Superpowers의 철학

프로젝트가 추구하는 핵심 원칙들을 정리하면 다음과 같습니다.

테스트 우선: 코드보다 테스트를 먼저 작성합니다. 예외는 없습니다.

체계적 접근: 직감이나 추측이 아닌 검증된 프로세스를 따릅니다.

복잡성 감소: 단순함을 최우선 목표로 삼습니다. 불필요한 추상화나 미래를 대비한 코드를 경계합니다.

증거 기반: "됐어요!"라는 선언 전에 실제로 작동하는지 검증합니다.

마치며

Superpowers는 단순한 도구가 아니라 AI 에이전트와 협업하는 새로운 방법론을 제시합니다. 에이전트에게 "이것 좀 만들어줘"라고 던지고 결과를 기다리는 대신, 함께 설계하고 계획하며 점진적으로 구현해 나가는 파트너십을 만들어갑니다.

특히 스킬 시스템은 확장 가능하도록 설계되어 있어서, 개발자가 자신의 도메인에 맞는 스킬을 추가할 수 있습니다. 예를 들어 특정 프레임워크의 베스트 프랙티스, 회사의 코딩 컨벤션, 도메인 특화 패턴 등을 스킬로 만들어 에이전트에게 가르칠 수 있습니다.

AI 코딩 에이전트를 사용하면서 "왜 내가 원하는 대로 안 되지?"라는 좌절감을 느꼈다면, Superpowers가 해결책이 될 수 있습니다. 에이전트에게 슈퍼파워를 부여하는 것이 아니라, 체계적인 사고방식을 가르치는 것이니까요.

참고 자료

AI 에이전트를 위한 PostgreSQL 베스트 프랙티스: Supabase Agent Skills 완벽 가이드

MoreLean — Sun, 25 Jan 2026 20:34:42 +0900

> 이 글은 [supabase/agent-skills](https://github.com/supabase/agent-skills)를 기반으로 정리했습니다.

들어가며

AI 코딩 에이전트가 데이터베이스 스키마를 설계하고 쿼리를 작성하는 시대가 되었습니다. Claude Code, Cursor, GitHub Copilot 같은 도구들이 SQL 코드를 생성하고, MCP(Model Context Protocol)를 통해 데이터베이스와 직접 상호작용하기도 합니다.

하지만 AI 에이전트가 생성한 코드가 항상 최적은 아닙니다. 인덱스 없이 대용량 테이블을 조회하거나, RLS(Row Level Security) 정책을 비효율적으로 구성하거나, 커넥션 풀링을 무시한 채 직접 연결을 남발하는 경우가 흔합니다.

Supabase는 이 문제를 해결하기 위해 Agent Skills 포맷을 따르는 postgres-best-practices 스킬을 공개했습니다. Agent Skills는 AI 에이전트가 특정 도메인의 베스트 프랙티스를 학습할 수 있도록 구조화된 지식을 제공하는 표준 포맷입니다.

이 글의 대상 독자

이 글은 두 부류의 독자를 위해 작성되었습니다.

PostgreSQL 사용자: AWS RDS, Google Cloud SQL, 자체 호스팅 PostgreSQL 등을 사용하는 모든 개발자

Supabase 사용자: Supabase 플랫폼을 사용하는 개발자

각 섹션에 (PostgreSQL 공통) 또는 ⚡ (Supabase 특화) 표시를 해두었습니다.

Agent Skills란 무엇인가

Agent Skills는 AI 에이전트가 발견하고 활용할 수 있는 지침, 스크립트, 리소스의 표준 포맷입니다. Claude Code, Cursor, GitHub Copilot 등의 에이전트가 특정 작업을 수행할 때 더 정확하고 효율적으로 동작하도록 돕습니다.

Supabase는 이 포맷을 따르는 postgres-best-practices 스킬을 공개했습니다. 8개 카테고리에 걸친 PostgreSQL 성능 최적화 규칙들을 담고 있으며, 영향도에 따라 우선순위가 매겨져 있습니다.

설치는 간단합니다.

npx skills add supabase/agent-skills

Claude Code를 사용한다면 플러그인으로도 설치할 수 있습니다.

/plugin marketplace add supabase/agent-skills
/plugin install postgres-best-practices@supabase-agent-skills

영향도 레벨 이해하기

모든 최적화가 동일한 가치를 갖지는 않습니다. Agent Skills는 각 규칙의 영향도를 명확히 구분합니다. 이 분류 체계는 PostgreSQL 전반에 적용됩니다.

레벨 성능 개선 폭 예시

CRITICAL	10-100배	누락된 인덱스, 커넥션 고갈
HIGH	5-20배	잘못된 인덱스 타입, 부적절한 파티셔닝
MEDIUM-HIGH	2-5배	N+1 쿼리, RLS 최적화 미흡
MEDIUM	1.5-3배	중복 인덱스, 오래된 통계 정보
LOW-MEDIUM	1.2-2배	VACUUM 튜닝, 설정 조정
LOW	점진적	고급 패턴, 엣지 케이스

Part 1: PostgreSQL 공통 베스트 프랙티스

이 섹션의 내용은 모든 PostgreSQL 환경에서 적용됩니다. AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL, 자체 호스팅 환경 모두 해당됩니다.

1. 쿼리 성능 최적화 (Critical)

인덱스 기본 전략

쿼리 성능 문제의 대부분은 인덱스 부재에서 시작됩니다. 100,000건의 테이블에서 인덱스 없이 특정 사용자의 데이터를 조회하면, PostgreSQL은 모든 행을 순차적으로 스캔합니다.

-- ❌ 나쁜 예: 인덱스 없는 조회
SELECT * FROM orders WHERE user_id = 'abc123';

-- ✅ 좋은 예: 인덱스 생성 후 조회
CREATE INDEX idx_orders_user_id ON orders(user_id);
SELECT * FROM orders WHERE user_id = 'abc123';

대용량 테이블에서 이 차이는 100배 이상의 성능 개선으로 이어집니다.

인덱스 타입 선택

B-Tree는 동등 비교(=)와 범위 쿼리(>, <, BETWEEN)에 최적화되어 있습니다. 하지만 배열 연산에는 GIN이 적합합니다.

-- 동등/범위 비교: B-Tree (기본값)
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_orders_created_at ON orders(created_at);

-- 배열 포함 여부 확인: GIN
CREATE INDEX idx_tags ON posts USING GIN (tags);

-- 전문 검색: GIN with tsvector
CREATE INDEX idx_content_search ON articles USING GIN (to_tsvector('english', content));

EXPLAIN ANALYZE 활용

쿼리 실행 계획을 확인하여 문제를 진단합니다.

EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 'abc123';

결과에서 확인할 사항:

Seq Scan: 대용량 테이블에서 나타나면 인덱스 필요
Index Scan / Index Only Scan: 인덱스가 사용되고 있음
actual time: 실제 실행 시간
rows: 처리된 행 수

2. 스키마 설계 (High)

기본 키 필수

모든 테이블에는 기본 키가 있어야 합니다. 기본 키가 없으면 PostgreSQL이 행을 고유하게 식별할 수 없어 복제, 업데이트, 삭제 작업에서 문제가 발생합니다.

-- ✅ 기본 키 포함
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

외래 키 인덱스

외래 키 컬럼에는 인덱스를 추가하는 것이 표준 관행입니다. JOIN 성능이 크게 향상됩니다.

-- 외래 키 정의
ALTER TABLE orders ADD CONSTRAINT fk_orders_customer 
    FOREIGN KEY (customer_id) REFERENCES customers(id);

-- ✅ 외래 키 컬럼에 인덱스 추가
CREATE INDEX idx_orders_customer_id ON orders(customer_id);

PostgreSQL은 외래 키에 자동으로 인덱스를 생성하지 않습니다. 명시적으로 추가해야 합니다.

3. Row Level Security (RLS)

RLS는 PostgreSQL 9.5부터 지원되는 기본 기능입니다. 테이블 수준에서 행 단위 접근 제어를 구현합니다.

RLS 기본 사용법

-- RLS 활성화
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- 정책 생성: 자신의 게시물만 조회 가능
CREATE POLICY "Users see own posts" ON posts
    FOR SELECT
    USING (user_id = current_user_id());  -- current_user_id()는 앱에서 정의

RLS 성능 최적화

RLS 정책은 모든 SELECT, UPDATE 작업에서 각 행마다 평가됩니다. 함수를 직접 호출하면 행 수만큼 반복 실행됩니다.

-- ❌ 나쁜 예: 매 행마다 함수 호출
CREATE POLICY "own_data" ON posts
    FOR SELECT USING (get_current_user_id() = user_id);

-- ✅ 좋은 예: subquery로 캐싱
CREATE POLICY "own_data" ON posts
    FOR SELECT USING ((SELECT get_current_user_id()) = user_id);

SELECT 서브쿼리로 감싸면 PostgreSQL 옵티마이저가 initPlan을 실행하여 결과를 캐싱합니다. 100,000건 테이블에서 100배 이상의 성능 차이가 발생할 수 있습니다.

RLS 컬럼 인덱싱

RLS 정책에서 사용하는 컬럼에는 반드시 인덱스를 추가합니다.

-- RLS 정책이 user_id를 사용한다면
CREATE INDEX idx_posts_user_id ON posts(user_id);

팀 기반 접근 제어

쿼리 방향이 성능에 큰 영향을 미칩니다.

-- ❌ 느린 방향: 각 게시물마다 팀 멤버십 조회
get_current_user_id() IN (
    SELECT user_id FROM team_members 
    WHERE team_members.team_id = posts.team_id
)

-- ✅ 빠른 방향: 사용자의 팀 목록을 한 번만 조회
team_id IN (
    SELECT team_id FROM team_members 
    WHERE user_id = get_current_user_id()
)

4. 동시성과 락킹 (Medium-High)

논블로킹 인덱스 생성

일반 CREATE INDEX는 테이블에 쓰기 락을 겁니다. 프로덕션 환경에서는 CONCURRENTLY 옵션을 사용합니다.

-- ❌ 테이블 락 발생
CREATE INDEX idx_users_email ON users(email);

-- ✅ 논블로킹 (시간은 더 걸림)
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

대규모 배치 처리

대량의 UPDATE/DELETE는 청크 단위로 나눕니다.

-- ❌ 한 번에 처리: 긴 락, 트랜잭션 로그 폭증
DELETE FROM logs WHERE created_at < '2024-01-01';

-- ✅ 청크 단위 처리
DO $$
DECLARE
    deleted_count INT;
BEGIN
    LOOP
        DELETE FROM logs 
        WHERE id IN (
            SELECT id FROM logs 
            WHERE created_at < '2024-01-01' 
            LIMIT 10000
        );
        GET DIAGNOSTICS deleted_count = ROW_COUNT;
        EXIT WHEN deleted_count = 0;
        COMMIT;
    END LOOP;
END $$;

5. 커넥션 관리 (Critical)

PostgreSQL 커넥션은 리소스를 많이 소모합니다. 커넥션당 약 10MB의 메모리를 사용하며, 최대 커넥션 수에 제한이 있습니다.

커넥션 풀링 필수

서버리스 환경(AWS Lambda, Vercel Functions 등)에서는 커넥션 풀러가 필수입니다.

일반적인 옵션:

PgBouncer: 가장 널리 사용되는 PostgreSQL 커넥션 풀러
pgpool-II: 로드 밸런싱, 복제 기능 포함
애플리케이션 레벨: Prisma, SQLAlchemy 등의 내장 풀링

# PgBouncer 설정 예시 (pgbouncer.ini)
[databases]
mydb = host=localhost dbname=mydb

[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

풀 모드 선택

모드 설명 사용 사례

Session	세션 동안 커넥션 유지	장기 연결, Prepared Statement 사용
Transaction	트랜잭션 동안만 커넥션 사용	서버리스, 짧은 쿼리
Statement	문장 단위로 커넥션 할당	AUTOCOMMIT만 사용하는 경우

서버리스 환경에서는 Transaction 모드를 권장합니다.

6. 모니터링과 진단 (Low-Medium)

느린 쿼리 로깅

-- postgresql.conf 또는 ALTER SYSTEM
ALTER SYSTEM SET log_min_duration_statement = 1000;  -- 1초 이상 쿼리 로깅
SELECT pg_reload_conf();

pg_stat_statements 활용

-- 확장 활성화
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 가장 시간이 오래 걸린 쿼리 Top 10
SELECT 
    substring(query, 1, 100) as query,
    calls,
    round(total_exec_time::numeric, 2) as total_ms,
    round(mean_exec_time::numeric, 2) as mean_ms
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;

커넥션 상태 확인

-- 현재 활성 커넥션
SELECT 
    state,
    count(*) 
FROM pg_stat_activity 
GROUP BY state;

-- 오래 실행 중인 쿼리
SELECT 
    pid,
    now() - pg_stat_activity.query_start AS duration,
    query
FROM pg_stat_activity
WHERE state = 'active'
  AND now() - pg_stat_activity.query_start > interval '5 minutes';

Part 2: Supabase 특화 베스트 프랙티스 ⚡

이 섹션의 내용은 Supabase 플랫폼 사용자에게만 해당됩니다.

1. Supabase 인증 함수와 RLS ⚡

Supabase는 RLS에서 사용할 수 있는 인증 헬퍼 함수를 제공합니다.

auth.uid()와 auth.jwt()

-- 현재 로그인한 사용자 ID
SELECT auth.uid();

-- JWT 전체 내용
SELECT auth.jwt();

-- JWT에서 특정 클레임 추출
SELECT auth.jwt() -> 'app_metadata' ->> 'role';

Supabase RLS 최적화

-- ❌ 나쁜 예
CREATE POLICY "Users see own data" ON posts
    FOR SELECT USING (auth.uid() = user_id);

-- ✅ 좋은 예: subquery 캐싱
CREATE POLICY "Users see own data" ON posts
    FOR SELECT USING ((SELECT auth.uid()) = user_id);

역할 명시적 지정

anon 역할을 제외하려면 명시적으로 authenticated를 지정합니다.

-- ❌ 모든 역할에 적용
CREATE POLICY "Read posts" ON posts FOR SELECT USING (true);

-- ✅ authenticated 역할만
CREATE POLICY "Read posts" ON posts 
    FOR SELECT TO authenticated USING (true);

정책 분리

Supabase에서는 FOR ALL 대신 개별 정책을 권장합니다.

-- ❌ 피해야 할 패턴
CREATE POLICY "all_access" ON posts FOR ALL USING (...);

-- ✅ 권장 패턴
CREATE POLICY "select_own" ON posts FOR SELECT USING ((SELECT auth.uid()) = user_id);
CREATE POLICY "insert_own" ON posts FOR INSERT WITH CHECK ((SELECT auth.uid()) = user_id);
CREATE POLICY "update_own" ON posts FOR UPDATE USING ((SELECT auth.uid()) = user_id);
CREATE POLICY "delete_own" ON posts FOR DELETE USING ((SELECT auth.uid()) = user_id);

2. Supabase 커넥션 풀링 ⚡

Supabase는 세 가지 연결 방식을 제공합니다.

연결 방식 비교

방식 포트 사용 사례 플랜

Direct Connection	5432	서버 환경, 마이그레이션	모든 플랜
Shared Pooler (Supavisor)	6543	서버리스, IPv6	모든 플랜
Dedicated Pooler (PgBouncer)	6543	고성능 서버리스	유료 플랜만

연결 문자열 예시

# 직접 연결
postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres

# Shared Pooler (Supavisor) - 트랜잭션 모드
postgresql://postgres.[PROJECT]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres

# Dedicated Pooler (PgBouncer) - 유료 플랜
postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:6543/postgres

Prisma와 함께 사용

# 런타임: 풀링 연결 사용
DATABASE_URL="postgresql://postgres.[PROJECT]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres?pgbouncer=true"

# 마이그레이션: 직접 연결 사용
DIRECT_URL="postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres"

?pgbouncer=true를 추가하면 Prisma가 Prepared Statement를 비활성화합니다 (트랜잭션 모드에서 필요).

3. MCP 서버 보안 ⚡

AI 에이전트가 MCP를 통해 Supabase 데이터베이스에 직접 접근할 때의 보안 고려사항입니다.

핵심 원칙

프로덕션 연결 금지: 개발 프로젝트에만 연결
고객에게 제공 금지: 내부 개발 도구로만 사용
읽기 전용 모드 권장: 실수로 인한 데이터 손실 방지
프로젝트 범위 제한: 특정 프로젝트만 접근 허용

안전한 MCP URL 설정

https://mcp.supabase.com/mcp?read_only=true&project_ref=[YOUR_PROJECT]

MCP 클라이언트 설정 (예: Claude Code)

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=YOUR_PROJECT"
    }
  }
}

4. Supabase Dashboard 도구 활용 ⚡

Performance Advisor

대시보드의 Database > Performance Advisor에서 자동으로 감지하는 항목:

누락된 인덱스
사용되지 않는 인덱스
중복 인덱스
테이블 bloat

Security Advisor

Database > Security Advisor에서 확인:

RLS가 비활성화된 테이블
RLS가 활성화되었지만 정책이 없는 테이블
노출된 auth 스키마
위험한 security definer 함수

실전 적용 체크리스트

PostgreSQL 공통 체크리스트

새로운 테이블을 만들 때:

[ ] 기본 키가 있는가?
[ ] 외래 키 컬럼에 인덱스가 있는가?
[ ] WHERE 절에 자주 사용되는 컬럼에 인덱스가 있는가?
[ ] RLS를 사용한다면 정책 컬럼에 인덱스가 있는가?
[ ] RLS 정책에서 함수를 (SELECT func()) 패턴으로 캐싱하는가?
[ ] 서버리스 환경에서 커넥션 풀링을 사용하는가?

Supabase 추가 체크리스트 ⚡

[ ] auth.uid() 대신 (SELECT auth.uid())를 사용하는가?
[ ] 정책에 TO authenticated를 명시했는가?
[ ] FOR ALL 대신 개별 정책(SELECT/INSERT/UPDATE/DELETE)을 사용하는가?
[ ] 서버리스 환경에서 Pooler 연결(포트 6543)을 사용하는가?
[ ] Prisma 사용 시 ?pgbouncer=true를 추가했는가?

마치며

이 글에서 다룬 PostgreSQL 베스트 프랙티스의 핵심을 요약하면:

모든 PostgreSQL 사용자에게 중요한 것:

적절한 인덱스 설계 (10-100배 성능 차이)
RLS 정책의 함수 캐싱 패턴
커넥션 풀링 (특히 서버리스 환경)
EXPLAIN ANALYZE를 통한 쿼리 분석

Supabase 사용자에게 추가로 중요한 것:

auth.uid()/auth.jwt() 최적화
Supavisor/PgBouncer 연결 방식 선택
MCP 서버 보안 설정

Agent Skills를 설치하면 AI 에이전트가 이런 사항들을 자동으로 고려합니다. Supabase를 사용하지 않더라도 PostgreSQL 공통 부분은 충분히 가치 있는 내용입니다.

참고 자료

PostgreSQL 공통

Supabase 특화 ⚡

[개발 가이드] Claude Code 제대로 쓰는 법: Anthropic이 공개한 8가지 베스트 프랙티스

MoreLean — Fri, 23 Jan 2026 06:51:14 +0900

최근 공개된 Claude Code는 단순한 코딩 어시스턴트를 넘어, 직접 파일을 수정하고 터미널 명령어를 실행하는 '에이전트'형 도구입니다. 하지만 강력한 만큼 제대로 쓰는 법을 아는 것이 중요합니다. Anthropic 공식 문서( https://code.claude.com/docs/en/best-practices )를 바탕으로, Claude Code의 성능을 극대화하는 꿀팁을 정리했습니다.

1. 핵심 철학: "검증 가능하게 지시하라"

Claude Code를 사용할 때 가장 중요한 한 가지를 꼽으라면 바로 **'검증 수단 제공'**입니다. Claude가 코드를 짠 후 잘 돌아가는지 스스로 확인할 수 있게 해주세요.

Bad: "이메일 유효성 검사 함수 만들어줘."
Good: "이메일 유효성 검사 함수를 만들고, test.js에 있는 테스트 케이스를 실행해서 통과하는지 확인해줘."
효과: 여러분이 일일이 코드를 확인할 필요 없이, Claude가 스스로 오류를 잡고 수정까지 마칩니다.

2. 3단계 워크플로우: 탐색 → 계획 → 구현

무작정 코딩부터 시키면 산으로 갈 수 있습니다. Claude Code의 Plan Mode를 적극 활용하세요.

탐색 (Explore): Plan Mode에서 현재 코드 구조와 로직을 파악하게 합니다.
계획 (Plan): 어떤 파일을 수정할지, 어떤 로직을 추가할지 계획을 세우게 합니다.
구현 (Implement): Normal Mode로 전환해 계획대로 코드를 작성하고 테스트하게 합니다.
- Tip: 수정 사항이 아주 간단하다면(오타 등) 바로 구현을 요청해도 됩니다.

3. '컨텍스트'는 금이다: 세션 관리의 기술

Claude의 성능은 대화 내용(컨텍스트 창)이 길어질수록 조금씩 떨어질 수 있습니다. 이를 관리하는 것이 실력입니다.

/clear: 작업 주제가 바뀌면 이전 대화 내역을 지워 컨텍스트를 초기화하세요.
/compact: 대화가 너무 길어지면 중요한 맥락만 남기고 압축하세요.
서브에이전트 활용: "서브에이전트를 써서 라이브러리 문서를 조사해와"라고 시키세요. 메인 대화창은 깨끗하게 유지하면서 정보만 쏙 가져올 수 있습니다.

4. 우리 팀만의 규칙, CLAUDE.md 활용하기

프로젝트 루트에 CLAUDE.md 파일을 만들면, Claude가 매 세션마다 이 파일을 읽고 프로젝트 특성을 파악합니다.

포함할 내용: 빌드 명령어, 테스트 실행법, 선호하는 코드 스타일(예: "세미콜론 생략"), 프로젝트 특유의 아키텍처 규칙.
장점: 매번 "우리 프로젝트는 이렇게 짜야 해"라고 설명할 필요가 없어집니다.

5. 프롬프트는 구체적일수록 좋다

Claude는 독심술사가 아닙니다. 구체적인 가이드를 줄수록 결과물이 좋아집니다.

@파일명: "그 파일"이라고 하지 말고 @src/auth.ts 처럼 직접 지칭하세요.
패턴 참조: "이미 구현된 @Notification.tsx 의 디자인 패턴을 참고해서 새로운 모달을 만들어줘"라고 지시하세요.
이미지 활용: UI 수정 시에는 스크린샷을 터미널에 직접 붙여넣어 시각적인 피드백을 주세요.

6. CLI 도구와 MCP로 날개 달기

Claude Code는 터미널 도구를 직접 다룰 수 있습니다.

CLI 도구: gh(GitHub CLI), aws, npm 등을 설치해두면 Claude가 직접 PR을 올리거나 인프라 설정을 확인합니다.
MCP (Model Context Protocol): 외부 데이터베이스나 Notion, Figma 등을 연결하면 Claude가 코드 밖의 정보까지 참조하여 작업합니다.

7. 실수했을 땐? '되감기(Rewind)'와 '인터뷰'

/rewind: Claude가 코드를 망쳐놨다면 당황하지 마세요. 체크포인트 기능을 통해 이전 상태(코드 및 대화)로 되돌릴 수 있습니다.
나를 인터뷰해줘: 큰 기능을 만들 땐 "이 기능을 구현하기 위해 필요한 정보를 나한테 질문해줘"라고 시켜보세요. 여러분이 놓친 엣지 케이스를 Claude가 먼저 짚어줍니다.

마치며: Claude Code는 동료 엔지니어입니다

Claude Code를 단순한 '도구'가 아니라 '함께 일하는 주니어~미들급 엔지니어' 라고 생각해보세요. 명확한 업무 지시를 내리고, 결과물을 검토할 수 있는 환경(테스트)을 만들어준다면, 여러분의 생산성은 상상 이상으로 높아질 것입니다.

Claude Code에서 MCP vs Skills vs CLI - 무엇을 선택해야 할까?

MoreLean — Wed, 21 Jan 2026 09:20:40 +0900

들어가며

Claude Code에서 GitHub와 연동하려고 할 때, 선택지가 여러 개다:

GitHub MCP 서버
Skills (SKILL.md)
gh CLI + CLAUDE.md

처음엔 당연히 MCP가 "올바른" 방법이라 생각했다. 공식적이고, 구조화되어 있고, 뭔가 있어 보이니까. 하지만 실제로 팀 프로젝트에 적용하려다 보니 예상치 못한 문제를 만났다.

문제의 시작: 팀 프로젝트에서 토큰 공유

프로젝트 레벨의 MCP 설정(.mcp.json)을 git으로 공유하려 했다. 그런데 GitHub MCP는 인증 토큰이 필요하다.

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx..."  // 이걸 커밋한다고?
    }
  }
}

개인 토큰을 git에 커밋할 수는 없다. ${GITHUB_PAT} 같은 환경 변수 interpolation을 시도해봤지만, stdio 타입의 env 섹션에서만 제한적으로 지원되고 HTTP headers에서는 동작하지 않았다.

GitHub Issue에서도 같은 고민을 하는 개발자들이 많았다:

"I am preparing a shared .mcp.json file that I want to commit to our repository, but facing an issue in how to authenticate..."

Anthropic은 뭐라고 할까?

놀랍게도 Anthropic 공식 best practices 문서에서는 이렇게 말한다:

"Claude knows how to use the gh CLI to interact with GitHub for creating issues, opening pull requests, reading comments, and more."

심지어 공식 슬래시 커맨드 예제에서도:

Remember to use the GitHub CLI ('gh') for all GitHub-related tasks.

MCP 대신 gh CLI를 쓰라고 가이드하고 있다.

MCP의 숨겨진 비용: 컨텍스트 윈도우

MCP를 깊이 살펴보니 더 근본적인 문제가 있었다. MCP는 모든 tool definitions을 미리 로드한다.

/context 명령어로 확인해보면:

System prompt: xxxxx tokens
MCP tools: 8,000+ tokens  ← GitHub MCP 하나만으로
Messages: xxxxx tokens
Free space: ...

Armin Ronacher(Flask 창시자)도 비슷한 경험을 공유했다:

"The Sentry MCP is probably one of the better designed MCPs out there, but I don't use it anymore. When I load it into the context right away I lose around 8k tokens out of the box."

8,000 토큰이면 꽤 긴 대화를 할 수 있는 양이다. MCP 서버 하나 연결했다고 그만큼 날리는 건 비효율적이다.

Skills: 더 똑똑한 대안

Skills는 완전히 다른 접근을 한다. Progressive Disclosure - 필요할 때만 로드한다.

세션 시작 시:
- Skill 이름과 설명만 로드 (~수십 토큰)
- 전체 instructions는 아직 로드 안 함

관련 작업 요청 시:
- 그제서야 full SKILL.md 로드
- 스크립트 실행 결과만 컨텍스트에 추가 (스크립트 코드 자체는 0 토큰)

이걸 "매트릭스 방식"이라고 부르는 사람도 있다:

"Skills load on-demand, just like Neo in The Matrix (1999). 'I know Kung Fu'"

Skills vs MCP: 핵심 차이

관점MCPSkills

로딩 방식	Upfront (미리 전부)	On-demand (필요할 때)
컨텍스트 비용	도구당 100~300 토큰 (항상)	설명만 수십 토큰 (평소)
역할	Connectivity (연결)	Expertise (전문성)
유지보수	서버 관리 필요	마크다운 편집
범용성	MCP 클라이언트 필요	파일시스템 접근만 있으면 됨

Simon Willison은 이렇게 평가했다:

"Skills are (maybe) a bigger deal than MCP."

언제 뭘 써야 할까?

Anthropic의 공식 가이드를 보면 명확하다:

MCP: Claude가 접근할 수 없는 외부 시스템 연결 (데이터베이스, 사내 API 등)
Skills: Claude가 그 연결을 어떻게 활용할지 가르치기

"MCP handles connectivity. Skills handle expertise."

즉, MCP는 "문을 열어주는 것"이고, Skills는 "문 안에서 뭘 할지 가르치는 것"이다.

그런데 gh CLI는? 이미 설치되어 있고, Claude가 잘 알고 있다. 새로운 "문"을 열 필요가 없다.

실용적인 결론: GitHub 연동은 CLAUDE.md로

GitHub처럼 잘 알려진 도구는 굳이 MCP를 쓸 필요가 없다:

# CLAUDE.md

## GitHub 사용

이 프로젝트는 gh CLI를 사용합니다.
각 개발자는 `gh auth login` 완료 상태여야 합니다.

### PR 워크플로우
- PR 생성: `gh pr create --title "..." --body "..."`
- PR 리뷰 요청: `gh pr edit --add-reviewer @username`
- PR 머지: `gh pr merge --squash`

### 브랜치 컨벤션
- feature/xxx, fix/xxx, refactor/xxx 형태로 생성
- main 브랜치 직접 push 금지

### 커밋 메시지
- feat: 새로운 기능
- fix: 버그 수정
- refactor: 리팩토링

이 방식의 장점:

토큰 공유 문제 없음 - 각자 gh auth login만 하면 됨
컨텍스트 효율적 - 필요할 때 참조
프로젝트 컨벤션 포함 - 단순 도구 연결 이상의 가치
git으로 바로 공유 - 추가 설정 불필요
커스터마이징 자유로움 - 팀 워크플로우에 맞게 조정 가능

그래서 MCP는 언제 쓰나?

MCP가 빛을 발하는 경우:

사내 전용 시스템 - Claude가 전혀 모르는 API
데이터베이스 직접 연결 - PostgreSQL, MongoDB 등
SaaS 통합 - Notion, Slack, Jira 등의 실시간 데이터
파일시스템 없는 환경 - Claude.ai 웹에서 외부 연결 필요 시

반면 이런 경우는 MCP 대신 다른 방법을:

gh, git, docker 같은 표준 CLI → CLAUDE.md
복잡한 워크플로우 가이드 → Skills
자주 안 쓰는 도구 → Skills (on-demand 로딩)

마치며

처음엔 "MCP가 더 있어 보이니까"라는 이유로 선택하려 했다. 하지만 실제로 부딪혀보니:

팀 프로젝트에서 토큰 공유 문제
컨텍스트 윈도우를 상시 점유하는 비효율
Anthropic조차 gh CLI를 권장하는 현실

결국 도구 선택은 "있어 보이는 것"이 아니라 "실제로 효율적인 것"을 기준으로 해야 한다.

새로운 외부 시스템 연결? → MCP
복잡한 도메인 전문성? → Skills
잘 알려진 CLI 도구? → CLAUDE.md

세 가지는 경쟁 관계가 아니라 상호 보완 관계다. 상황에 맞게 조합해서 쓰면 된다.

Claude Code 생산성 10배 올리기: 키보드부터 자동화까지

MoreLean — Wed, 21 Jan 2026 01:17:05 +0900

키보드 단축키부터 외우세요. Cmd+K는 퀵 액션, Cmd+Shift+P는 명령 팔레트, Cmd+/는 주석 토글, Cmd+D는 같은 단어 선택... 이런 거 손에 익으면 마우스 안 쓰고도 코딩할 수 있어요. 처음엔 느려도 1주일만 연습하면 2배는 빨라져요.

TL;DR

키보드 단축키: Escape(중단), Double-Escape(되감기), Tab(자동완성)
프롬프트: 구체적 + 컨텍스트 = 최고의 결과물
자동 커밋: Stop Hook으로 세션 종료 시 자동 커밋
PR 템플릿: .github/pull_request_template.md로 표준화
/clear 자주: 새 작업마다 컨텍스트 리셋
커스텀 명령어: 반복 작업을 한 줄로

1. 키보드 단축키 마스터하기

Claude Code 핵심 단축키

"Press Escape to interrupt Claude during any phase (thinking, tool calls, file edits), preserving context so you can redirect or expand instructions." — Anthropic Best Practices

단축키 기능 사용 시점

Escape	작업 중단	Claude가 잘못된 방향으로 갈 때
Escape × 2	히스토리 되감기	이전 프롬프트로 돌아가기
Tab	파일/폴더 자동완성	@src/c + Tab → @src/components/
Shift+Tab	Permission 모드 순환	normal → auto-accept → plan 모드
↑ / ↓	명령 히스토리	이전 명령 재사용
Ctrl+C × 2	강제 종료	완전히 나가기
Ctrl+R	히스토리 검색	과거 명령 찾기

Bash 스타일 편집

Ctrl+A        → 줄 맨 앞으로
Ctrl+E        → 줄 맨 뒤로
Option+F      → 단어 앞으로 (→)
Option+B      → 단어 뒤로 (←)
Ctrl+W        → 이전 단어 삭제
Ctrl+U        → 줄 전체 삭제

macOS 팁: Option 키가 안 먹힌다면 터미널 설정에서 "Use Option as Meta Key" 활성화하세요.

iTerm2: Settings → Profiles → Keys → Left Option → Esc+

Terminal.app: Settings → Profiles → Keyboard → Use Option as Meta Key

멀티라인 입력

Shift+Enter로 여러 줄 프롬프트 작성:

> "1. 로그인 버튼 만들어줘
   2. 파란색 배경에 흰 글씨
   3. 호버하면 진한 파란색
   4. 클릭하면 /auth/login API 호출"

팁: iTerm2, WezTerm, Ghostty, Kitty에서는 기본 작동. VS Code나 Alacritty에서는 /terminal-setup 실행 필요.

셸 Alias 설정

# ~/.zshrc 또는 ~/.bashrc
alias c="claude"
alias cc="claude --continue"
alias cr="claude --resume"
alias cy="claude --dangerously-skip-permissions"  # 주의!

# 프로젝트별 단축키
alias dev="claude 'Start development session'"
alias review="claude '/review'"
alias commit="claude '/commit'"

2. 프롬프트 작성의 기술

구체적일수록 좋다

"The difference between a vague instruction and a well-crafted prompt can mean the gap between generic outputs and exactly what you need." — Claude Blog

❌ 나쁜 예:

버튼 만들어줘

✅ 좋은 예:

파란색(#3B82F6) 배경에 흰 글씨, 
호버하면 진한 파란색(#2563EB), 
클릭하면 /auth/login API 호출하는 로그인 버튼 만들어줘.
이 버튼은 로그인 폼에 들어가고, 
로딩 중에는 스피너 표시해야 해.
Tailwind CSS 사용하고 있어.

컨텍스트 제공하기

┌─────────────────────────────────────────────────────────────┐
│               효과적인 프롬프트 구조                              │
│                                                             │
│  1. 무엇을 (WHAT)     → "로그인 버튼 만들어줘"                     │
│  2. 어디에 (WHERE)    → "이 버튼은 로그인 폼에 들어가"               │
│  3. 어떻게 (HOW)      → "파란색 배경, 흰 글씨"                    │
│  4. 왜 (WHY)          → "사용자가 쉽게 찾을 수 있도록"             │
│  5. 제약사항          → "Tailwind CSS, TypeScript 사용"        │
└─────────────────────────────────────────────────────────────┘

@ 태그로 파일 참조

# 파일 직접 참조
@src/components/Button.tsx 이 버튼 스타일 참고해서 만들어줘

# 폴더 참조
@src/styles/ 여기 있는 스타일 컨벤션 따라줘

# Tab 자동완성 활용
@src/c[Tab] → @src/components/

이미지로 설명하기

"Paste screenshots (pro tip: hit cmd+ctrl+shift+4 in macOS to screenshot to clipboard and ctrl+v to paste)." — Anthropic Best Practices

# 1. 스크린샷 찍기 (macOS)
cmd+ctrl+shift+4  # 클립보드에 저장

# 2. Claude Code에 붙여넣기
ctrl+v  # (주의: cmd+v 아님!)

# 3. 프롬프트와 함께
"이 디자인 목업 보고 똑같이 만들어줘"

문제 해결 가이드

문제 해결책

응답이 주제에서 벗어남	목표를 더 명시적으로 설명
형식이 불일치	예시(few-shot) 추가
작업이 너무 복잡	여러 프롬프트로 분할
불필요한 서론	"서론 없이 바로 답변해줘"
정보를 지어냄	"모르면 모른다고 해도 돼"
제안만 하고 구현 안 함	"이 함수를 수정해줘" (명령형)

3. /clear 습관 들이기

왜 /clear가 중요한가?

"Use the /clear command frequently between tasks to reset the context window." — Anthropic Best Practices

┌─────────────────────────────────────────────────────────────┐
│              컨텍스트 오염 문제                                  │
│                                                             │
│  긴 세션 동안:                                                 │
│  • 오래된 대화가 쌓임                                            │
│  • 관련 없는 파일 내용이 쌓임                                     │
│  • 이전 명령 출력이 쌓임                                         │
│                                                             │
│  결과:                                                       │
│  • 성능 저하                                                  │
│  • Claude가 산만해짐                                           │
│  • 토큰 낭비                                                  │
└─────────────────────────────────────────────────────────────┘

/clear 사용 타이밍

# 새 작업 시작할 때
/clear

# 완전히 다른 주제로 넘어갈 때
/clear

# Claude가 이상하게 행동할 때
/clear

# 긴 디버깅 세션 후
/clear

Pro tip: "Every time you start something new, clear the chat. You don't need all that history eating your tokens." — Builder.io

4. 자동 커밋 설정

작업 끝날 때마다 자동으로 커밋되게 하면 안전해요. 커밋 메시지 나중에 정리하면 되고, 일단 작업 내역이 계속 쌓이니까 실수로 날려도 복구 가능하거든요.

Stop Hook으로 자동 커밋

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "git add -A && git commit -m 'auto: WIP checkpoint' --allow-empty || true"
          }
        ]
      }
    ]
  }
}

프롬프트 내용을 커밋 메시지로

"It's fairly straightforward to change the notification into a git commit -m checkpoint... However, let's make it slightly better by using the prompt itself as the commit message." — GitButler Blog

#!/bin/bash
# .claude/hooks/auto-commit.sh

# Hook input에서 프롬프트 추출
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // "WIP checkpoint"' | head -c 72)

# 변경사항 있으면 커밋
if ! git diff --quiet HEAD 2>/dev/null; then
    git add -A
    git commit -m "auto: $PROMPT"
fi

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-commit.sh"
          }
        ]
      }
    ]
  }
}

GitButler 통합 (고급)

"GitButler uses a mix of PreToolUse, PostToolUse, and Stop hooks to automatically stage file changes and create new commits. They can even isolate work from different Claude sessions into separate branches automatically." — eesel.ai

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "but claude pre-tool" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "but claude post-tool" }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "but claude stop" }]
      }
    ]
  }
}

결과: 여러 Claude 세션을 동시에 돌려도 각 세션의 변경사항이 별도 브랜치로 자동 분리!

5. PR 템플릿 만들기

매번 PR 설명 쓰기 귀찮잖아요. 템플릿 만들어두면 빈칸만 채우면 돼요. 팀원들도 리뷰하기 편해져요.

기본 템플릿

<!-- .github/pull_request_template.md -->

##   변경 사항
<!-- 이 PR에서 변경된 내용을 설명해주세요 -->


##   관련 이슈
<!-- Closes #123 형식으로 연결 -->
Closes #

## ✅ 테스트 방법
<!-- 이 변경사항을 어떻게 테스트할 수 있나요? -->
1. 
2. 
3. 

##   스크린샷 (UI 변경 시)
<!-- 변경 전/후 스크린샷을 첨부해주세요 -->
| Before | After |
|--------|-------|
|        |       |

## ✔️ 체크리스트
- [ ] 코드가 프로젝트 스타일 가이드를 따름
- [ ] 셀프 리뷰 완료
- [ ] 테스트 추가/수정 완료
- [ ] 문서 업데이트 (필요시)

##   리뷰어에게
<!-- 리뷰어가 특히 봐줬으면 하는 부분이 있나요? -->

Claude가 PR 자동 생성하게 하기

<!-- .claude/commands/pr.md -->
---
description: "PR 생성하기"
allowed-tools: ["Bash(git:*)", "Bash(gh:*)"]
---

# PR 생성

현재 브랜치의 변경사항으로 PR을 생성해줘.

## 단계
1. `git diff main...HEAD`로 변경사항 확인
2. 변경 내용 분석하여 PR 제목과 설명 작성
3. `.github/pull_request_template.md` 양식 따르기
4. `gh pr create` 명령으로 PR 생성

## PR 제목 형식
`<type>: <description>`

Types: feat, fix, docs, style, refactor, test, chore

## 인자
$ARGUMENTS

사용:

> /pr 로그인 기능 추가

Claude로 PR 자동 리뷰

"Claude will add a claude-code-review.yml file with a prompt already in it." — Builder.io

# GitHub App 설치
/install-github-app

설치 후 PR에 @claude 멘션하면 자동 리뷰!

6. 커스텀 슬래시 명령어

반복되는 워크플로우를 명령어로 저장하면 한 줄로 복잡한 작업을 실행할 수 있어요.

명령어 저장 위치

~/.claude/commands/       # 개인용 (모든 프로젝트)
.claude/commands/         # 프로젝트용 (팀 공유)

실용적인 명령어 예시

빠른 커밋:

<!-- .claude/commands/commit.md -->
---
description: "AI가 커밋 메시지 작성"
allowed-tools: ["Bash(git:*)"]
---

1. `git status`와 `git diff`로 변경사항 확인
2. Conventional Commit 형식으로 메시지 작성
3. 형식: `<emoji> <type>: <description>`
   - ✨ feat,   fix,   docs, ♻️ refactor
4. `git commit` 실행

빠른 테스트:

<!-- .claude/commands/test.md -->
---
description: "변경된 파일 관련 테스트 실행"
---

1. `git diff --name-only`로 변경된 파일 확인
2. 관련 테스트 파일 찾기
3. 해당 테스트만 실행
4. 실패하면 수정 제안

GitHub 이슈 처리:

<!-- .claude/commands/fix-issue.md -->
---
description: "GitHub 이슈 분석하고 수정"
allowed-tools: ["Bash(gh:*)", "Bash(git:*)"]
---

GitHub 이슈 #$ARGUMENTS 분석하고 수정해줘:

1. `gh issue view $ARGUMENTS`로 이슈 내용 확인
2. 관련 코드 찾기
3. 수정 구현
4. 테스트 작성
5. 커밋하고 PR 생성
6. PR을 이슈에 연결

사용:

> /fix-issue 123

7. 세션 관리

세션 이어가기

# 가장 최근 세션 이어가기
claude --continue
# 또는
claude -c

# 특정 세션 재개
claude --resume abc123

"claude -c preserves previous context when resuming work, making it effective for long refactoring sessions or phased feature implementations." — SmartScope

세션 저장 팁

긴 작업 전에 CLAUDE.md에 상태 저장:

<!-- CLAUDE.md 추가 -->

## Current Task
- 로그인 기능 구현 중
- 완료: API 엔드포인트
- 진행중: 프론트엔드 폼
- TODO: 에러 핸들링

## Session Notes
- 2024-01-15: OAuth 연동 시작
- 이슈: 리프레시 토큰 만료 처리 필요

"As you approach your token budget limit, save your current progress and state to memory before the context window refreshes." — Claude Docs

8. 헤드리스 모드 (CI/CD 자동화)

비대화형 실행

"Claude Code includes headless mode for non-interactive contexts like CI, pre-commit hooks, build scripts, and automation." — Anthropic Best Practices

# 단일 명령 실행
claude -p "이 코드 보안 취약점 검사해줘"

# JSON 출력
claude -p "코드 분석해줘" --output-format json

# 도구 제한 + 턴 제한
claude -p "보안 리뷰해줘" \
  --allowedTools Read,Grep,Glob \
  --max-turns 3 \
  > security_report.json

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: claude-review
        name: Claude Code Review
        entry: claude -p "이 diff에서 버그나 보안 이슈 찾아줘" --max-turns 2
        language: system
        pass_filenames: false

GitHub Actions 연동

# .github/workflows/claude-review.yml
name: Claude Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Review
        run: |
          claude -p "PR 변경사항 리뷰해줘: $(git diff origin/main)" \
            --output-format json \
            > review.json

9. 생산성 극대화 패턴

패턴 1: 병렬 세션

"You could have one session working on a new feature, another fixing a bug, and a third refactoring some old code, all without the usual pain of stashing changes." — eesel.ai

# 터미널 1: 새 기능
cd ~/project && git worktree add ../feature-login feature-login
cd ../feature-login && claude

# 터미널 2: 버그 수정
cd ~/project && git worktree add ../bugfix-auth bugfix-auth
cd ../bugfix-auth && claude

# 터미널 3: 리팩토링
cd ~/project && git worktree add ../refactor-api refactor-api
cd ../refactor-api && claude

패턴 2: Claude가 Claude 리뷰

"A simple but effective approach is to have one Claude write code while another reviews or tests it." — Anthropic Best Practices

# 터미널 1: 코드 작성
claude "로그인 기능 구현해줘"

# 터미널 2: 리뷰
claude "src/auth/ 폴더 코드 리뷰해줘. 보안 이슈 중점으로."

패턴 3: 온보딩 가속

"At Anthropic, using Claude Code in this way has become our core onboarding workflow, significantly improving ramp-up time." — Anthropic Best Practices

# 새 프로젝트 이해하기
claude "이 프로젝트 구조 설명해줘"
claude "인증 시스템이 어떻게 작동하는지 설명해줘"
claude "이 함수가 왜 이렇게 설계됐는지 git 히스토리 보고 알려줘"

10. 체크리스트

매일 아침

[ ] 어제 세션 이어가기: claude -c
[ ] CLAUDE.md에 오늘 할 일 업데이트
[ ] /clear로 깨끗한 시작

새 작업 시작 시

[ ] /clear
[ ] 목표 명확하게 설명
[ ] 관련 파일 @ 태그로 참조
[ ] 제약사항 명시 (언어, 프레임워크 등)

작업 완료 시

[ ] 자동 커밋 확인
[ ] 커밋 메시지 정리 (squash/reword)
[ ] /pr로 PR 생성

키보드 연습 (1주일)

[ ] Day 1-2: Escape, Tab, ↑/↓ 익히기
[ ] Day 3-4: Ctrl+A/E, Ctrl+W 익히기
[ ] Day 5-7: 셸 alias 설정하고 사용

마무리

생산성은 작은 습관의 축적이에요.

오늘 당장 해볼 것:

터미널 설정 — Option을 Meta로 설정
셸 alias 추가 — c, cc, cr
자동 커밋 Hook — Stop 이벤트에 git commit
PR 템플릿 — .github/pull_request_template.md

기억하세요:

Escape — 잘못 가면 바로 중단
Double-Escape — 되감기
Tab — 파일 자동완성
/clear — 새 작업마다 리셋
구체적 프롬프트 — 컨텍스트가 생명

"Pro tip: use /clear often. Every time you start something new, clear the chat. You don't need all that history eating your tokens." — Builder.io

처음엔 느려도 1주일만 연습하면 2배는 빨라져요. 마우스 안 쓰고 키보드만으로 코딩하는 그 날이 올 거예요. 화이팅!

참고 자료

Anthropic 공식

커뮤니티 가이드

도구

GitButler — 자동 브랜치 관리
Claude Code Marketplace — 플러그인 모음

Claude Code 보안 Best Practices: 타협 없는 안전한 AI 코딩

MoreLean — Wed, 21 Jan 2026 01:07:57 +0900

보안은 절대 타협하면 안 돼요. Rules 시스템 적극 활용하세요.

CLAUDE.md에 "API 키 절대 하드코딩 금지, 환경 변수 무조건 사용" 이렇게 박아두면 Claude Code가 지켜줘요.

Security Reviewer Agent도 돌려보세요. SQL 인젝션, XSS, CSRF 같은 취약점 자동으로 찾아내요. 배포 전에 꼭 한 번 체크하는 습관 들이세요.

TL;DR

기본 원칙: Claude를 "똑똑하지만 신뢰할 수 없는 인턴"으로 대하기
Permission 시스템: allow/deny/ask 규칙으로 세밀하게 제어
Sandbox: /sandbox로 파일시스템 + 네트워크 격리 (84% 권한 요청 감소)
민감 파일 차단: .env, ~/.ssh/, ~/.aws/ 접근 deny
CLAUDE.md: 보안 규칙 명시 (API 키 하드코딩 금지 등)
PreToolUse Hooks: 가장 강력한 보안 경계 (파일/명령 차단)
Trail of Bits Skills: 전문 보안 감사 도구 활용
절대 root로 실행 금지

핵심 보안 철학

Claude = "똑똑하지만 신뢰할 수 없는 인턴"

"Organizations must treat Claude Code as a 'brilliant but untrusted intern'—capable of excellent work but requiring human review of all security-critical changes." — MintMCP Blog

Claude Code는 강력하지만, 다음을 기억하세요:

Claude가 할 수 있는 것 위험

.env 파일 읽기	API 키 노출
SSH 키 접근	서버 침투
bash 명령 실행	시스템 손상
네트워크 요청	데이터 유출
MCP 서버 연결	외부 서비스 접근

Zero Trust 원칙

"To enhance security, treat Claude Code as an assistant requiring supervision. Implement external SAST/DAST tools, run it in sandboxed environments, and establish strict, 'deny-by-default' configurations for permissions." — eesel.ai

기본 = 거부, 필요한 것만 허용하세요.

1. Permission 시스템 설정

공식 Permission 구조

"Claude Code uses strict read-only permissions by default. When additional actions are needed (editing files, running tests, executing commands), Claude Code requests explicit permission." — Anthropic Security Docs

3가지 규칙 타입

{
  "permissions": {
    "allow": [...],  // 자동 승인 (안전한 작업)
    "ask": [...],    // 매번 확인
    "deny": [...]    // 완전 차단 (deny가 allow보다 우선)
  }
}

실전 보안 설정

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(npm test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(head:*)",
      "Bash(tail:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git merge:*)",
      "Bash(npm install:*)",
      "Bash(npm publish:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*credential*)",
      "Read(./**/*secret*)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(chmod 777:*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "WebFetch"
    ]
  }
}

⚠️ 중요: Bash deny 규칙의 한계

"Bash permission rules use pattern matching and can be bypassed using shell features like command flags, variables, or redirects. For example, Bash(curl:*) can be bypassed with curl -X GET reordered to curl http://example.com -X GET. Do not rely on Bash deny rules as a security boundary." — Claude Code Settings Docs

해결책: PreToolUse Hooks 또는 Sandbox 사용

2. Sandbox: 진정한 격리

Sandbox란?

"In our internal usage, we've found that sandboxing safely reduces permission prompts by 84%. By defining set boundaries within which Claude can work freely, they increase security and agency." — Anthropic Engineering

2중 격리 시스템

"Effective sandboxing requires both filesystem and network isolation. Without network isolation, a compromised agent could exfiltrate sensitive files like SSH keys. Without filesystem isolation, a compromised agent could backdoor system resources to gain network access." — Claude Code Sandboxing Docs

┌─────────────────────────────────────────────────────────────┐
│                    Sandbox Architecture                     │
│                                                             │
│  ┌─────────────────┐      ┌─────────────────┐               │
│  │  Filesystem     │      │    Network      │               │
│  │  Isolation      │      │    Isolation    │               │
│  │                 │      │                 │               │
│  │  • CWD만 쓰기     │      │  • 기본 전체 차단  │               │
│  │  • 상위 폴더 X    │      │  • 허용 도메인만    │               │
│  │  • ~/.ssh 차단   │      │  • 프록시 경유     │               │
│  └─────────────────┘      └─────────────────┘               │
│                                                             │
│  OS-Level Enforcement:                                      │
│  • Linux: Bubblewrap + seccomp BPF                          │
│  • macOS: Seatbelt (sandbox-exec)                           │
└─────────────────────────────────────────────────────────────┘

Sandbox 활성화

# Claude Code 내에서
/sandbox

Sandbox 설정

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "allowedDirectories": [
      "${workspaceFolder}",
      "~/.npm",
      "/tmp"
    ],
    "deniedDirectories": [
      "~/.ssh",
      "~/.aws",
      "~/.config",
      "/etc",
      "/var"
    ],
    "allowedDomains": [
      "registry.npmjs.org",
      "api.github.com"
    ]
  }
}

High Security 템플릿 (신뢰할 수 없는 코드용)

{
  "sandbox": {
    "enabled": true,
    "allowedDirectories": [
      "${workspaceFolder}/sandbox-only"
    ],
    "deniedDirectories": [
      "~/.ssh",
      "~/.aws",
      "~/.config",
      "/etc",
      "/var",
      "/usr",
      "/System"
    ],
    "allowedDomains": []
  }
}

Prompt Injection 방어

"Sandboxing ensures that even a successful prompt injection is fully isolated, and cannot impact overall user security. This way, a compromised Claude Code can't steal your SSH keys, or phone home to an attacker's server." — Anthropic Engineering

3. PreToolUse Hooks: 가장 강력한 방어선

Hooks가 필요한 이유

"Until the core deny functionality is fixed, the only reliable way to protect sensitive files is by using a PreToolUse hook." — GitHub Issue #6699

Permission deny 규칙에 버그가 있을 수 있어요. Hooks는 OS 레벨에서 차단하므로 더 안전합니다.

민감 파일 보호 Hook

#!/usr/bin/env python3
# .claude/hooks/protect_sensitive_files.py
import sys
import json
from pathlib import Path

# 민감한 파일 패턴
SENSITIVE_PATTERNS = [
    '.env',
    '.env.*',
    '*.pem',
    '*.key',
    '*credential*',
    '*secret*',
    'id_rsa',
    'id_ed25519',
    '.aws/credentials',
    '.ssh/config',
]

def is_sensitive(filepath: str) -> bool:
    path = Path(filepath)
    for pattern in SENSITIVE_PATTERNS:
        if path.match(pattern):
            return True
    return False

def main():
    # Hook input 읽기
    input_data = json.loads(sys.stdin.read())
    tool_name = input_data.get('tool_name', '')
    tool_input = input_data.get('tool_input', {})
    
    # Read/Edit 도구 체크
    if tool_name in ['Read', 'Edit', 'Write']:
        file_path = tool_input.get('file_path', '')
        if is_sensitive(file_path):
            print(f"BLOCKED: Access to sensitive file '{file_path}' is denied.", 
                  file=sys.stderr)
            sys.exit(2)  # exit(2) = 차단
    
    sys.exit(0)  # exit(0) = 허용

if __name__ == '__main__':
    main()

Hook 등록

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "command": "python3 .claude/hooks/protect_sensitive_files.py"
      }
    ]
  }
}

위험 명령 차단 Hook

#!/bin/bash
# .claude/hooks/block_dangerous_commands.sh

# stdin에서 JSON 읽기
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if [ "$TOOL_NAME" = "Bash" ]; then
    # 위험한 패턴 체크
    DANGEROUS_PATTERNS=(
        "rm -rf"
        "chmod 777"
        "curl.*|.*sh"
        "wget.*|.*sh"
        "> /etc/"
        "sudo"
        "dd if="
    )
    
    for pattern in "${DANGEROUS_PATTERNS[@]}"; do
        if echo "$COMMAND" | grep -qE "$pattern"; then
            echo "BLOCKED: Dangerous command pattern detected: $pattern" >&2
            exit 2
        fi
    done
fi

exit 0

4. CLAUDE.md 보안 규칙

보안 가이드라인 템플릿

# Security Rules

## 절대 금지 사항
- **API 키, 시크릿 하드코딩 금지** - 반드시 환경 변수 사용
- **민감 파일 접근 금지**: .env, ~/.ssh/, ~/.aws/, secrets/
- **위험한 명령 실행 금지**: rm -rf, sudo, chmod 777
- **외부 URL에서 스크립트 다운로드 후 실행 금지**

## 필수 보안 패턴
- 모든 시크릿은 환경 변수로 관리: `process.env.API_KEY`
- 사용자 입력은 항상 검증 및 새니타이즈
- SQL 쿼리는 파라미터화된 쿼리 사용 (절대 문자열 연결 X)
- 파일 경로는 항상 path.join() 사용 (path traversal 방지)

## 코드 리뷰 체크리스트
배포 전 반드시 확인:
- [ ] 하드코딩된 시크릿 없음
- [ ] SQL 인젝션 취약점 없음
- [ ] XSS 취약점 없음
- [ ] CSRF 보호 적용
- [ ] 입력 검증 완료
- [ ] 에러 메시지에 민감 정보 노출 없음

## 환경 변수 패턴
```bash
# ✅ 올바른 방법
DATABASE_URL=postgres://...  # .env 파일
const url = process.env.DATABASE_URL;

# ❌ 절대 금지
const url = "postgres://user:password@host/db";

의존성 보안

새 패키지 설치 전 npm audit 실행
알려진 취약점 있는 패키지 사용 금지
버전 고정으로 supply chain 공격 방지

### Security Reviewer Agent 설정

```markdown
<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: 보안 취약점 자동 검사
trigger: /security-review, 배포 전, PR 리뷰
---

# Security Reviewer Agent

## 검사 항목

### 1. 인젝션 취약점
- SQL Injection: 문자열 연결 쿼리 탐지
- Command Injection: 사용자 입력이 exec/spawn에 전달되는지
- NoSQL Injection: MongoDB 쿼리 검사
- XPath/LDAP Injection

### 2. 인증/인가 취약점
- 하드코딩된 credentials
- 약한 비밀번호 정책
- 세션 관리 문제
- 권한 상승 가능성

### 3. 데이터 노출
- 민감 정보 로깅
- 에러 메시지 정보 노출
- 안전하지 않은 직렬화

### 4. 설정 문제
- CORS 설정
- 보안 헤더 누락 (CSP, HSTS 등)
- 디버그 모드 활성화

### 5. 의존성 취약점
- npm audit / pip audit 실행
- 알려진 CVE 확인

## 출력 형식
- 심각도: Critical / High / Medium / Low
- 위치: 파일:라인
- 설명: 취약점 상세
- 수정 방안: 구체적인 해결책

5. Trail of Bits Security Skills

전문 보안 도구 활용

"Trail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows." — Trail of Bits Skills

설치

/plugins marketplace add trailofbits/skills

주요 Skills

Skill 용도

static-analysis	CodeQL, Semgrep으로 정적 분석
variant-analysis	유사 취약점 패턴 탐지
fix-review	수정 커밋이 버그 재발 없이 문제 해결하는지 검증
audit-context-building	코드 심층 분석 및 보안 컨텍스트 구축
differential-review	Git 변경사항 보안 중심 리뷰
semgrep-rule-creator	커스텀 Semgrep 규칙 생성
footgun-identifier	에러 유발 API 및 위험한 설정 탐지

사용 예시

# 정적 분석 실행
/static-analysis

# 수정 커밋 검증
/fix-review main fix-branch --report ./audit-report.pdf

# 유사 취약점 탐지
/variant-analysis "SQL injection pattern"

스마트 컨트랙트 보안 (Building Secure Contracts)

# 블록체인별 취약점 스캐너
/solana-vulnerability-scanner
/cosmos-vulnerability-scanner

# 개발 가이드라인
/audit-prep-assistant
/code-maturity-assessor
/secure-workflow-guide

6. 민감 데이터 보호

Anthropic 내부 팀 권장사항

"They recommend using MCP servers rather than the BigQuery CLI to maintain better security control over what Claude Code can access, especially for handling sensitive data that requires logging or has potential privacy concerns." — How Anthropic teams use Claude Code

민감 데이터 가이드라인

┌─────────────────────────────────────────────────────────────┐
│              민감 데이터 보호 전략                               │
│                                                             │
│  절대 포함하지 말 것:                                           │
│  • Production API 키                                        │
│  • 데이터베이스 credentials                                    │
│  • 고객 PII (개인식별정보)                                      │
│  • 결제 정보 (카드번호 등)                                       │
│  • 독점 알고리즘 (핵심 비즈니스 로직)                               │
│                                                             │
│  대안:                                                       │
│  • 환경 변수 사용                                              │
│  • Secrets Manager (AWS, Vault 등)                          │
│  • Mock 데이터로 개발                                          │
│  • 민감 정보 마스킹                                             │
└─────────────────────────────────────────────────────────────┘

데이터 전송 인식

"When you interact with Claude Code, specific types of data are transmitted to Anthropic's servers for processing. Files that Claude Code reads are sent in their entirety for analysis." — ClaudeLog

기억하세요: Claude가 읽는 모든 파일은 Anthropic 서버로 전송됩니다.

7. 엔터프라이즈 보안 설정

managed-settings.json (조직 전체 정책)

// /etc/claude/managed-settings.json (관리자 권한 필요)
{
  "permissions": {
    "deny": [
      "Read(./secrets/**)",
      "Read(./**/.env*)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "WebFetch"
    ]
  },
  "sandbox": {
    "enabled": true,
    "allowedDomains": [
      "*.company-internal.com",
      "registry.npmjs.org"
    ]
  }
}

"Enterprise Policy (highest priority) — These rules cannot be overridden by users." — Permissions and Security

Settings 우선순위

Managed (최우선) → Project → User (최하위)
      ↓               ↓         ↓
 조직 정책       프로젝트용    개인 설정
 (강제 적용)     (.claude/)    (~/.claude/)

GDPR/규제 대응

Data Residency: AWS EU 리전 또는 Vertex AI 사용
Zero Data Retention: Enterprise API 고객용 옵션
Audit Logging: 90일 이상 로그 보관
Data Minimization: deny 규칙으로 PII 파일 접근 차단

8. 실전 보안 체크리스트

매일 확인

[ ] Claude Code 최신 버전 사용 중 (/status 확인)
[ ] .env 파일이 .gitignore에 포함
[ ] 하드코딩된 시크릿 없음

프로젝트 시작 시

[ ] CLAUDE.md에 보안 규칙 명시
[ ] .claude/settings.json에 deny 규칙 설정
[ ] /sandbox 활성화
[ ] PreToolUse Hooks 설정

배포 전

[ ] /security-review 또는 Security Agent 실행
[ ] npm audit / pip audit 실행
[ ] 의존성 취약점 확인
[ ] 환경 변수 설정 검증
[ ] CORS, CSP 등 보안 헤더 확인

위험 신호

[ ] Claude가 .env 읽으려 함 → 즉시 거부
[ ] 알 수 없는 URL로 네트워크 요청 → 확인 후 결정
[ ] sudo 또는 chmod 777 요청 → 절대 거부
[ ] 알 수 없는 npm 패키지 설치 → 조사 후 결정

9. CVE 및 알려진 취약점

주요 CVE 히스토리

"So far there have been 9 CVE's published for claude code, many of which allowed for bypasses of permissions dialogs." — Pete Freitag

버전 취약점 날짜

≤1.0.119	Symlink bypass in permission deny rules	2025-10-03
<1.0.105	Confirm Prompt Bypass	2025-09-10

교훈:

항상 최신 버전 유지
Permission 시스템만 의존하지 말고 Sandbox + Hooks 사용
정기적으로 보안 공지 확인

10. 안전한 YOLO 모드

절대 일반 개발에서 사용 금지

# ⚠️ 위험: 모든 권한 체크 우회
claude --dangerously-skip-permissions

안전하게 사용하려면

"This flag should only be used for well-defined, automated tasks running in a secure, isolated environment like a Docker container." — eesel.ai

# Dockerfile - 격리된 환경에서만 YOLO 모드
FROM node:20-alpine

# 비-root 사용자 생성
RUN adduser -D claude-user

# 작업 디렉토리만 접근 가능
WORKDIR /workspace
RUN chown claude-user:claude-user /workspace

USER claude-user

# Claude Code 설치
RUN npm install -g @anthropic-ai/claude-code

CMD ["claude", "--dangerously-skip-permissions"]

마무리

보안은 선택이 아니라 필수입니다.

"The key takeaway: Treat Claude like you would an untrusted but powerful intern. Give it only the minimum permissions it actually needs, sandbox it, and audit it." — Backslash Security

핵심 원칙:

최소 권한: 필요한 것만 허용
다층 방어: Permission + Sandbox + Hooks
명시적 규칙: CLAUDE.md에 보안 정책 문서화
정기 감사: Trail of Bits Skills 등 활용
최신 유지: 보안 패치 즉시 적용
root 절대 금지: AI 에이전트에 관리자 권한 주지 않기

Claude Code는 강력한 도구예요. 하지만 제대로 설정하지 않으면 보안 위협이 될 수 있어요. 이 가이드의 설정을 적용하면, 생산성은 유지하면서 안전하게 AI 코딩을 즐길 수 있습니다.

참고 자료

Anthropic 공식

보안 도구

Trail of Bits Skills — 전문 보안 감사 Skills
Anthropic sandbox-runtime — 오픈소스 샌드박스

커뮤니티 가이드

Claude Code TDD 워크플로우: RED-GREEN-REFACTOR로 버그 없는 코드 만들기

MoreLean — Wed, 21 Jan 2026 01:02:08 +0900

TDD 워크플로우 제대로 돌리는 법도 알려드릴게요. RED-GREEN-REFACTOR 사이클이에요.

RED는 실패하는 테스트 먼저 쓰는 거예요. 아직 기능 없으니까 당연히 실패하죠. GREEN은 테스트 통과할 만큼만 코드 짜는 거예요. REFACTOR는 그 코드를 깔끔하게 리팩토링하는 거고요.

이 순서 지키면 버그가 확 줄어들어요. 해커톤 때 이렇게 했더니 테스트 커버리지 80% 넘겼거든요.

TL;DR

TDD = Anthropic 공식 권장 워크플로우 ("Anthropic-favorite workflow")
RED → GREEN → REFACTOR 사이클 반복
Claude에게 명시적으로 TDD임을 알려야 함 (mock 방지)
테스트 먼저 작성 → 실패 확인 → 최소 구현 → 리팩토링
/tdd 커스텀 명령어로 자동화 가능
AI + TDD = 최강 조합 (명확한 목표 + 빠른 피드백)

왜 TDD가 AI와 잘 맞는가?

Claude의 기본 성향: Implementation-First

"When I ask Claude to 'implement feature X,' it writes the implementation first." — alexop.dev

Claude는 기본적으로 바로 코드를 짜려고 해요. 테스트 없이 "Happy Path"만 구현하고, 엣지 케이스를 놓치기 쉬워요.

TDD가 해결하는 문제

문제 TDD 해결책

엣지 케이스 누락	테스트가 요구사항을 명시
과도한 구현	테스트 통과할 만큼만 구현
버그 발견 지연	즉각적인 피드백
리팩토링 공포	테스트가 안전망 역할

AI에게 TDD가 효과적인 이유

"Everything that makes TDD a slog for humans makes it the perfect workflow for an AI agent. AI thrives on clear, measurable goals, and a binary test is one the clearest goals you can give it." — Builder.io

명확한 목표: 테스트 통과/실패 = 이진 피드백
측정 가능: 성공 기준이 명확
자동 검증: Claude가 스스로 결과 확인 가능
반복 효율: 보일러플레이트 테스트 코드를 빠르게 생성

Anthropic 공식 TDD 가이드

공식 권장 워크플로우

"This is an Anthropic-favorite workflow for changes that are easily verifiable with unit, integration, or end-to-end tests. Test-driven development (TDD) becomes even more powerful with agentic coding." — Anthropic Best Practices

Anthropic이 권장하는 4단계

테스트 작성: 예상 input/output 기반으로 테스트 작성
실패 확인: 테스트 실행해서 실패하는지 확인
구현: 테스트 통과할 최소한의 코드 작성
커밋: 테스트 통과하면 커밋

"Ask Claude to write tests based on expected input/output pairs. Be explicit about the fact that you're doing test-driven development so that it avoids creating mock implementations, even for functionality that doesn't exist yet in the codebase." — Anthropic Best Practices

핵심: Claude에게 TDD를 하고 있다고 명시적으로 알려야 해요. 그래야 아직 없는 기능에 대해 mock을 만들지 않아요.

RED-GREEN-REFACTOR 사이클

┌─────────────────────────────────────────────────────────────┐
│                    TDD 사이클                                │
│                                                             │
│      RED ──────────►   GREEN ──────────►   REFACTOR     │
│      │                   │                     │            │
│      │                   │                     │            │
│      ▼                   ▼                     ▼            │
│   실패하는            테스트 통과할          코드 정리      │
│   테스트 작성         최소 코드 작성         (테스트 유지)   │
│                                                             │
│                          │                                  │
│                          ▼                                  │
│                    다음 기능으로                            │
│                    ◄──────────────────────────────────────  │
└─────────────────────────────────────────────────────────────┘

RED Phase: 실패하는 테스트 작성

목적: 아직 구현되지 않은 기능의 명세(Specification) 작성

> 사용자 로그인 기능의 테스트를 먼저 작성해줘.
> 아직 구현은 하지 마.
> 테스트가 실패하는지 확인해줘.

Claude 출력 예시:

// auth.test.ts
describe('User Login', () => {
  it('should return user object on valid credentials', async () => {
    const result = await login('user@example.com', 'password123');
    expect(result.success).toBe(true);
    expect(result.user.email).toBe('user@example.com');
  });

  it('should return error on invalid email', async () => {
    const result = await login('invalid-email', 'password123');
    expect(result.success).toBe(false);
    expect(result.error).toBe('Invalid email format');
  });

  it('should return error on wrong password', async () => {
    const result = await login('user@example.com', 'wrongpassword');
    expect(result.success).toBe(false);
    expect(result.error).toBe('Invalid credentials');
  });
});

# 테스트 실행 → 실패 확인 ✅
npm test
# FAIL: login is not defined

GREEN Phase: 최소 구현

목적: 테스트를 통과할 만큼만 코드 작성 (과도한 구현 금지!)

> 이제 테스트가 통과하도록 최소한의 구현을 해줘.
> 테스트에 없는 기능은 추가하지 마.

Claude 출력 예시:

// auth.ts
export async function login(email: string, password: string) {
  // 이메일 형식 검증
  if (!email.includes('@')) {
    return { success: false, error: 'Invalid email format' };
  }

  // 실제로는 DB 조회 (여기선 하드코딩)
  const validUser = { email: 'user@example.com', password: 'password123' };
  
  if (email === validUser.email && password === validUser.password) {
    return { success: true, user: { email } };
  }

  return { success: false, error: 'Invalid credentials' };
}

# 테스트 실행 → 통과 ✅
npm test
# PASS: All tests passed

REFACTOR Phase: 코드 정리

목적: 테스트는 유지하면서 코드 품질 개선

> 테스트는 그대로 유지하면서 코드를 리팩토링해줘.
> 중복 제거, 가독성 개선, 타입 추가 등.

Claude 출력 예시:

// auth.ts (리팩토링 후)
interface LoginResult {
  success: boolean;
  user?: { email: string };
  error?: string;
}

const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export async function login(email: string, password: string): Promise<LoginResult> {
  if (!isValidEmail(email)) {
    return { success: false, error: 'Invalid email format' };
  }

  const user = await findUserByEmail(email);
  
  if (!user || !verifyPassword(password, user.passwordHash)) {
    return { success: false, error: 'Invalid credentials' };
  }

  return { success: true, user: { email: user.email } };
}

function isValidEmail(email: string): boolean {
  return EMAIL_REGEX.test(email);
}

# 리팩토링 후에도 테스트 통과 확인 ✅
npm test
# PASS: All tests passed

실전 /tdd 명령어 사용법

커스텀 /tdd 명령어 만들기

<!-- .claude/commands/tdd.md -->
---
description: Test-Driven Development workflow
---

# TDD Workflow for: $ARGUMENTS

You are doing **Test-Driven Development**. Follow this strict cycle:

## Phase 1: RED  
1. Analyze the feature requirement: $ARGUMENTS
2. Write failing test(s) that define expected behavior
3. Run tests and **confirm they fail**
4. Do NOT write any implementation code yet
5. Wait for my review before proceeding

## Phase 2: GREEN  
After I approve the tests:
1. Write the **minimum code** to make tests pass
2. Do NOT add features not covered by tests
3. Run tests and confirm they pass
4. Commit when green

## Phase 3: REFACTOR  
After tests pass:
1. Improve code quality (readability, DRY, types)
2. Keep all tests passing
3. Run tests after each change
4. Commit the refactored code

## Rules
- Never skip the RED phase
- Never implement more than what tests require
- Always run tests after changes
- One test at a time for complex features

사용 예시

> /tdd 사용자 로그인 기능

# Claude 응답:
  RED Phase 시작

로그인 기능의 테스트를 먼저 작성하겠습니다.

[테스트 코드 작성...]

테스트 실행 결과: FAIL ❌
- login is not defined

테스트가 예상대로 실패합니다. 
테스트 코드를 검토해주시고, 진행해도 되면 알려주세요.

> 좋아, 구현해줘

# Claude 응답:
  GREEN Phase 시작

테스트를 통과할 최소한의 구현을 작성하겠습니다.

[구현 코드 작성...]

테스트 실행 결과: PASS ✅
모든 테스트가 통과합니다.

  REFACTOR Phase로 진행할까요?

고급 TDD 패턴

1. Subagent로 컨텍스트 분리

"When everything runs in one context window, the LLM cannot truly follow TDD. The test writer's detailed analysis bleeds into the implementer's thinking." — alexop.dev

문제: 같은 컨텍스트에서 테스트와 구현을 하면 Claude가 "치팅"할 수 있음

해결: Subagent로 각 phase 분리

<!-- .claude/skills/tdd-integration/skill.md -->
---
name: tdd-integration
description: Enforce TDD with strict Red-Green-Refactor cycle using subagents
---

### Phase 1: RED  
Invoke the `tdd-test-writer` subagent with:
- Feature requirement from user request
- Expected behavior to test

**Do NOT proceed until test failure is confirmed.**

### Phase 2: GREEN  
Invoke the `tdd-implementer` subagent with:
- Test file path from RED phase
- Feature requirement context

**Do NOT proceed until test passes.**

### Phase 3: REFACTOR  
Invoke the `tdd-refactorer` subagent with:
- Implementation files from GREEN phase
- Test file for verification

2. TDD Guard (Hooks로 강제)

TDD Guard는 Hooks를 사용해 TDD 원칙을 강제하는 도구예요:

"TDD Guard ensures Claude Code follows Test-Driven Development principles. When your agent tries to skip tests or over-implement, TDD Guard blocks the action and explains what needs to happen instead." — TDD Guard GitHub

설정:

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "command": "tdd-guard"
      }
    ]
  }
}

작동 방식:

파일 수정 전 TDD 원칙 검증
테스트 없이 구현하려 하면 차단
과도한 구현 감지 및 경고

3. 테스트 유형별 TDD

Unit Test TDD:

> /tdd calculateTotal 함수 - 가격 합계, 할인 적용, 세금 계산

Integration Test TDD:

> /tdd 결제 API 통합 - Stripe 연동, 에러 핸들링, 웹훅 처리

E2E Test TDD:

> /tdd 사용자 회원가입 플로우 - 폼 입력, 이메일 인증, 프로필 설정

CLAUDE.md TDD 설정

기본 TDD 가이드라인

# Testing and TDD

When working on a new feature or a bug fix, you **always write a failing test first** and then wait for me to review them. Then, when I've committed those tests, you add the smallest implementation possible to resolve a single test failure.

## TDD Workflow
1.   RED: Write failing test(s) first, then wait for review
2.   GREEN: After commit, implement minimal code to pass
3.   REFACTOR: Clean up while keeping tests green

Key principle: **Small, iterative cycles.**

## Commands
- `npm test`: Quick unit tests for TDD cycles
- `npm run test:all`: Full test suite before PR
- `npm run test:coverage`: Check coverage

## Rules
- No production code without a failing test
- One test at a time for complex features
- Never mock functionality that doesn't exist yet
- Run tests after every change

엄격한 TDD 강제

# Strict TDD Mode

You are a **TDD-first agent**. Strict constraints:

1. **Never write implementation without a failing test**
   - If asked to "create a feature," respond: "Let me write a test first"
   - Confirm test fails before implementing

2. **Minimal code always**
   - Write the simplest code that passes current test
   - Do NOT anticipate future requirements
   - Refactor only after tests pass

3. **Test output first**
   - Run tests with -q flag for clean output
   - Show PASS/FAIL status clearly

4. **Explicit phase announcements**
   -   "RED Phase: Writing failing test..."
   -   "GREEN Phase: Implementing minimal solution..."
   -   "REFACTOR Phase: Cleaning up..."

실무 TDD 시나리오

시나리오 1: 새 기능 개발

> /tdd 장바구니에 상품 추가 기능

# RED
  테스트 작성:
- 상품 추가 시 장바구니에 포함되는지
- 동일 상품 추가 시 수량 증가하는지
- 재고 초과 시 에러 반환하는지

# GREEN
  최소 구현:
- addToCart 함수
- 수량 관리 로직
- 재고 체크

# REFACTOR
  개선:
- 타입 추가
- 에러 처리 표준화
- 중복 제거

시나리오 2: 버그 수정

> /tdd 결제 시 할인 코드가 두 번 적용되는 버그

# RED
  버그 재현 테스트:
- 할인 코드 두 번 입력 시 한 번만 적용되는지 확인

# GREEN
  수정:
- 중복 할인 방지 로직 추가

# REFACTOR
  개선:
- 할인 로직 추출 및 정리

시나리오 3: 리팩토링

> /tdd 인증 모듈 리팩토링 - 기존 테스트 유지하면서

# 기존 테스트 확인
  모든 테스트 통과 확인

# REFACTOR (반복)
  점진적 리팩토링:
1. 작은 변경
2. 테스트 실행
3. 통과 확인
4. 반복

TDD ROI (투자 대비 효과)

토큰 비용 비교

"The TDD workflow has a higher upfront token tax... But after 10,000 lines of code, the ROI becomes undeniable." — Ali Moradi

Without TDD:

프롬프트: "결제 API 만들어줘"
→ 500줄 코드 생성
→ 버그 발견 (Delete가 cascade 안 됨)
→ 에러 로그 분석 (2,000 토큰)
→ 수정
→ 새 버그 발견
→ 반복...

총 토큰: 50,000+ 토큰
총 시간: 수 시간
품질: 테스트 안 된 취약한 코드

With TDD:

프롬프트: "삭제 시 하위 항목도 삭제되는지 테스트 작성해줘"
→ 테스트 작성 (200 토큰)
→ 실패 확인
→ 최소 구현
→ 통과 확인
→ 다음 요구사항으로

총 토큰: 5,000 토큰
총 시간: 20분
품질: 모든 동작 검증됨

Anthropic 내부 사례

"The Security Engineering team transformed their workflow from 'design doc → janky code → refactor → give up on tests' to asking Claude for pseudocode, guiding it through test-driven development, and checking in periodically." — How Anthropic teams use Claude Code

결과: 더 신뢰할 수 있고 테스트 가능한 코드

주의사항

1. Claude의 자연스러운 성향

"Without explicit guidance, agents naturally skip the refactoring phase of the red-green-refactor cycle or at best make only superficial changes." — TDD Guard Blog

해결: CLAUDE.md에 명시적으로 TDD 규칙 작성

2. Context Pollution

같은 컨텍스트에서 테스트와 구현을 하면 Claude가 테스트를 구현에 맞춰 "치팅"할 수 있어요.

해결:

Subagent로 phase 분리
테스트 작성 후 리뷰 받고 커밋 후 구현

3. 과도한 테스트

모든 것에 TDD를 적용할 필요는 없어요.

TDD 적합:

복잡한 비즈니스 로직
엣지 케이스가 많은 기능
버그 수정
API 엔드포인트

TDD 불필요:

단순 CRUD
UI 스타일링
설정 파일
프로토타이핑

체크리스트

TDD 시작 전

[ ] CLAUDE.md에 TDD 가이드라인 추가
[ ] /tdd 커스텀 명령어 생성
[ ] 테스트 프레임워크 설정 (Jest, Vitest, pytest 등)

RED Phase

[ ] 기능 요구사항을 테스트로 변환
[ ] 테스트가 실패하는지 확인
[ ] 구현 코드 작성 전 리뷰

GREEN Phase

[ ] 테스트 통과할 최소한의 코드만 작성
[ ] 테스트에 없는 기능 추가 금지
[ ] 모든 테스트 통과 확인

REFACTOR Phase

[ ] 코드 품질 개선 (DRY, 가독성, 타입)
[ ] 리팩토링 후에도 테스트 통과 확인
[ ] 커밋

고급

[ ] Subagent로 phase 분리 고려
[ ] TDD Guard 설치 고려
[ ] 테스트 커버리지 목표 설정 (70-80%)

마무리

TDD는 Anthropic이 공식 권장하는 워크플로우예요.

"This is an Anthropic-favorite workflow for changes that are easily verifiable with unit, integration, or end-to-end tests." — Anthropic Best Practices

기억하세요:

RED → GREEN → REFACTOR 사이클 엄수
Claude에게 TDD임을 명시적으로 알리기
테스트 먼저, 구현은 나중에
최소 구현 — 테스트 통과할 만큼만
리팩토링 시 테스트가 안전망

AI와 TDD는 최강 조합이에요. Claude에게 명확한 목표(테스트)를 주면, 그 목표를 향해 정확하게 달려갑니다. 처음엔 느린 것 같아도, 장기적으로 버그 감소 + 유지보수 용이 + 자신감 있는 리팩토링이라는 엄청난 ROI를 얻을 수 있어요.

참고 자료

Anthropic 공식

Claude Code Best Practices — TDD 공식 권장
How Anthropic teams use Claude Code — 내부 TDD 사용 사례

커뮤니티 가이드

Forcing Claude Code to TDD — Subagent 기반 TDD
TDD Guard — Hooks로 TDD 강제
Prevent the Robocalypse with TDD — 실전 TDD 워크플로우
TDD Paradigm Shift — TDD ROI 분석

도구

TDD Guard GitHub — TDD 강제 Hooks
awesome-claude-code — /tdd 명령어 모음

일반 TDD

Martin Fowler - TDD — TDD 원론
Kent Beck - Test-Driven Development — TDD 바이블

Claude Code Extended Thinking: 깊은 사고로 퀄리티 높이기

MoreLean — Wed, 21 Jan 2026 00:57:57 +0900

Extended Thinking이라는 기능도 있어요.

복잡한 문제 주면 Claude Code가 스스로 여러 각도로 생각해봐요. "이렇게 하면 어떻게 되지? 저렇게 하면?" 혼자 시뮬레이션 돌리는 거죠.

시간은 오래 걸리지만 퀄리티가 확실히 달라요. 중요한 기능 만들 때 한 번씩 써보세요.

TL;DR

Extended Thinking = Claude가 답변 전에 깊이 생각하는 공식 기능
Claude Code에서 기본 활성화 (최대 31,999 토큰)
Ctrl+O로 thinking 과정 볼 수 있음 (verbose mode)
"think", "think hard", "ultrathink" 키워드로 thinking budget 조절
복잡한 아키텍처, 어려운 버그, 수학/분석에 효과적
시간/비용 더 들지만 퀄리티 확실히 향상

Extended Thinking이란?

"When extended thinking is turned on, Claude creates thinking content blocks where it outputs its internal reasoning. Claude incorporates insights from this reasoning before crafting a final response." — Anthropic Docs

쉽게 말해, Claude가 답변하기 전에 혼자 깊이 생각하는 시간을 갖는 거예요.

일반 모드:

질문 → 바로 답변

Extended Thinking:

질문 → [내부 추론: 여러 접근법 탐색, 엣지 케이스 분석, 자기 검증] → 답변

어떻게 생각하나?

Anthropic 연구진의 관찰:

"Some of our researchers with math and physics backgrounds have noted how eerily similar Claude's thought process is to their own way of reasoning through difficult problems: exploring many different angles and branches of reasoning, and double- and triple-checking answers." — Anthropic - Visible Extended Thinking

Claude의 thinking 과정:

여러 각도에서 문제 탐색
다양한 접근법 시도
자기 답변 검증 (double/triple check)
실수 발견 시 수정

Claude Code에서의 Extended Thinking

기본 활성화

"Extended thinking is enabled by default, reserving a portion of the output token budget (up to 31,999 tokens) for Claude to reason through complex problems step-by-step." — Claude Code Docs

Claude Code에서는 기본적으로 켜져 있어요. 별도 설정 없이도 복잡한 문제에 대해 자동으로 깊이 생각합니다.

Thinking 과정 보기

# Ctrl+O로 verbose mode 토글
# thinking 과정이 회색 이탤릭 텍스트로 표시됨

"To view Claude's thinking process, press Ctrl+O to toggle verbose mode and see the internal reasoning displayed as gray italic text." — Claude Code Docs

Thinking Budget 조절하기

키워드로 thinking에 할당되는 토큰 양을 조절할 수 있어요:

키워드 Thinking 토큰 용도

think	~4,000	일반적인 분석
think hard, megathink	~10,000	중간 복잡도
think harder, ultrathink	~31,999	최고 복잡도

"These specific phrases are mapped directly to increasing levels of thinking budget in the system: 'think' < 'think hard' < 'think harder' < 'ultrathink'" — Anthropic Best Practices

환경 변수로 제한

# thinking 토큰 상한 설정
export MAX_THINKING_TOKENS=10000
claude

"Use the MAX_THINKING_TOKENS environment variable to cap the thinking budget." — Claude Code Docs

Extended Thinking의 효과

수학 문제 성능

Anthropic 연구 결과, thinking 토큰이 늘어날수록 수학 문제 정확도가 로그 스케일로 향상:

"Its accuracy on, for example, math questions improves logarithmically with the number of 'thinking tokens' that it's allowed to sample." — Anthropic - Visible Extended Thinking

에이전트 작업 성능

Tau-Bench 평가에서 "think" 도구 + 최적화된 프롬프트 조합:

Airline 도메인: 0.370 → 0.570 (54% 향상)
Retail 도메인: 0.783 → 0.812

"The results showed dramatic improvements when Claude 3.7 effectively used the 'think' tool." — Anthropic Engineering

Extended Thinking이 도움되는 경우

"Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches." — Claude Code Docs

효과적인 상황:

복잡한 아키텍처 설계
까다로운 버그 디버깅
다단계 구현 계획
트레이드오프 평가
수학/분석 문제
여러 솔루션 탐색이 필요한 경우

실전 활용 예시

1. 아키텍처 설계

> Think hard about designing a real-time collaboration system.
> Consider:
> - Conflict resolution (OT vs CRDT)
> - Scaling to 100K concurrent users
> - Offline support
> - Cost optimization

Claude의 thinking 과정 (verbose mode):

Let me analyze this systematically...

First, conflict resolution approaches:
- OT (Operational Transformation): Used by Google Docs, complex but proven
- CRDT (Conflict-free Replicated Data Types): Simpler, better for P2P
  
For 100K concurrent users, CRDT might be better because...
Wait, but OT has better compression for text...

Let me reconsider the requirements...
[더 깊은 분석 계속...]

2. 복잡한 버그 디버깅

> Ultrathink about this race condition.
> It only happens under high load in production.
> Logs show intermittent payment failures with no error messages.

Extended thinking 장점:

여러 가능한 원인 탐색
각 가설 검증
엣지 케이스 고려
재현 조건 분석

3. 알고리즘 최적화

> Think harder about optimizing this database query.
> Current execution time: 45 seconds
> Table has 50M rows with these indexes: [...]
> 
> Consider query plan, indexing strategy, and potential denormalization.

4. 테스트 케이스 검증

"For coding tasks, ask Claude to run through test cases in its extended thinking." — Anthropic Extended Thinking Tips

> Write a function to validate credit card numbers.
> Before you finish, verify your solution with test cases for:
> - Valid Visa, MasterCard, Amex
> - Invalid checksum
> - Edge cases (empty, too short, too long)
> And fix any issues you find.

5. 보안 리뷰

> Think hard about security vulnerabilities in this authentication flow.
> Consider:
> - OWASP Top 10
> - Token handling
> - Session management
> - Rate limiting bypass

Extended Thinking Tips (공식 권장)

1. 높은 수준의 지시가 더 효과적

"Claude often performs better with high level instructions to just think deeply about a task rather than step-by-step prescriptive guidance." — Anthropic Extended Thinking Tips

❌ 덜 효과적:

Think through this math problem step by step:
1. First, identify the variables
2. Then, set up the equation
3. Next, solve for x

✅ 더 효과적:

Please think about this math problem thoroughly and in great detail.
Consider multiple approaches and show your complete reasoning.
Try different methods if your first approach doesn't work.

2. 최소 budget에서 시작

"The minimum budget is 1,024 tokens. We suggest starting at the minimum and increasing the thinking budget incrementally to find the optimal range." — AWS Bedrock Docs

모든 문제에 ultrathink를 쓸 필요 없어요:

먼저 기본으로 시도
결과가 얕으면 "think" 추가
그래도 부족하면 "think hard"
정말 복잡하면 "ultrathink"

3. 자기 검증 요청

> Implement the sorting algorithm.
> After implementation, verify it handles:
> - Empty array
> - Single element
> - Already sorted
> - Reverse sorted
> - Duplicates
> Fix any issues you find.

4. 영어로 thinking하면 더 효과적

"Extended thinking performs best in English, though final outputs can be in any language Claude supports." — Anthropic Extended Thinking Tips

복잡한 문제는 영어로 질문하고, 필요하면 답변만 한국어로 요청하세요.

Extended Thinking vs Think Tool

Anthropic은 두 가지 "생각" 메커니즘을 제공해요:

Extended Thinking Think Tool

시점	답변 생성 전	답변 생성 중
목적	깊은 초기 분석	도구 사용 중 중간 점검
사용	복잡한 문제 전체 분석	긴 도구 체인에서 방향 점검

"Extended thinking is all about what Claude does before it starts generating a response... The 'think' tool is for Claude, once it starts generating a response, to add a step to stop and think about whether it has all the information it needs." — Anthropic Engineering

언제 뭘 쓸까?

Extended Thinking: 처음부터 깊은 분석이 필요할 때
Think Tool: 여러 도구를 연속 사용하며 중간 점검이 필요할 때

현재 Anthropic 권장:

"Extended thinking capabilities have improved since its initial release, such that we recommend using that feature instead of a dedicated think tool in most cases."

Thinking Mode 토글

Claude Code에서 thinking mode를 켜고 끌 수 있어요:

# 설정에서 토글
> /config

# 또는 Tab 키로 토글 (Plan Mode)

Thinking ON (기본):

복잡한 문제에 더 나은 결과
시간/토큰 더 사용
최대 31,999 토큰

Thinking OFF:

빠른 응답
간단한 작업에 적합
토큰 절약

비용 고려사항

"You're charged for all thinking tokens used, even though Claude 4 models show summarized thinking." — Claude Code Docs

중요:

Thinking 토큰도 비용 청구됨
Claude 4 모델은 요약된 thinking만 보여주지만, 전체 토큰에 대해 과금
ultrathink (31,999 토큰)는 상당한 비용 발생 가능

비용 최적화:

# 토큰 상한 설정
export MAX_THINKING_TOKENS=8000

CLAUDE.md에 가이드라인 추가

# Extended Thinking Guidelines

## When to Use Deep Thinking
- Architecture decisions: always use "think hard" or higher
- Bug debugging: use "think" minimum
- Security reviews: use "ultrathink"
- Simple CRUD: no special thinking needed

## Thinking Budget by Task
| Task Type | Keyword | Budget |
|-----------|---------|--------|
| Quick fix | (none) | default |
| Feature implementation | think | ~4K |
| Architecture design | think hard | ~10K |
| Complex debugging | ultrathink | ~32K |

## Self-Verification
Always verify solutions with edge cases before finalizing.

체크리스트

기본 사용

[ ] Ctrl+O로 verbose mode 활성화해서 thinking 과정 확인
[ ] 복잡한 문제에 "think" 키워드 사용
[ ] 아키텍처/보안에 "think hard" 또는 "ultrathink" 사용

최적화

[ ] 최소 budget에서 시작, 필요시 증가
[ ] MAX_THINKING_TOKENS로 비용 제한
[ ] 영어로 복잡한 문제 질문

품질 향상

[ ] 높은 수준의 지시 사용 (step-by-step X)
[ ] 자기 검증 요청 추가
[ ] 여러 접근법 고려 요청

마무리

Extended Thinking은 Claude Code의 핵심 기능이에요.

"Extended thinking is enabled by default, reserving a portion of the output token budget (up to 31,999 tokens) for Claude to reason through complex problems step-by-step." — Claude Code Docs

기억하세요:

기본 활성화 — 별도 설정 없이도 작동
Ctrl+O — thinking 과정 볼 수 있음
think < think hard < ultrathink — budget 조절
복잡한 문제에 효과적 — 아키텍처, 버그, 수학
비용 발생 — thinking 토큰도 과금

복잡한 아키텍처 설계, 까다로운 버그, 중요한 기술 결정이 있다면 Extended Thinking을 적극 활용하세요. 시간은 좀 더 걸리지만, 퀄리티 차이는 확실해요.

참고 자료

Anthropic 공식

Extended Thinking - Claude Docs — API 구현 가이드
Extended Thinking Tips — 프롬프팅 팁
Visible Extended Thinking — 기능 소개
Claude Code Common Workflows — Claude Code에서의 사용
Claude Think Tool — Think Tool vs Extended Thinking

추가 자료

AWS Bedrock Extended Thinking — AWS에서의 사용

Claude Code 컨테이너 격리와 병렬 개발: devcontainer & git worktree

MoreLean — Wed, 21 Jan 2026 00:54:21 +0900

컨테이너 격리도 중요해요. 특히 프로젝트 여러 개 동시에 진행할 때요.

Docker나 devcontainer 쓰면 환경이 완전히 분리돼요. A 프로젝트 Node 버전이랑 B 프로젝트 Node 버전 충돌 걱정 없어지죠.

Claude Code도 devcontainer 지원해요. .devcontainer 폴더 만들고 설정 파일 넣으면 자동으로 컨테이너 안에서 작업해요. 환경 꼬일 일이 없어요.

TL;DR

컨테이너 격리 (devcontainer)

프로젝트별 완전한 환경 분리
Node/Python 버전 충돌 없음
YOLO 모드를 안전하게 사용 가능
Anthropic 공식 레퍼런스 제공

병렬 개발 (git worktree)

여러 Claude 인스턴스 동시 실행
같은 레포에서 독립적 작업
디스크 공간 효율적 (전체 복사 X)
공식 베스트 프랙티스로 권장

Part 1: devcontainer로 환경 격리

왜 컨테이너 격리가 필요한가?

"Use devcontainers to isolate different client projects, ensuring code and credentials never mix between environments." — Claude Code Docs

흔한 문제들:

A 프로젝트: Node 18, B 프로젝트: Node 20 → 충돌
전역 패키지가 서로 영향
"내 컴퓨터에서는 되는데..." 문제
YOLO 모드 사용 시 보안 우려

devcontainer 해결:

프로젝트마다 완전히 격리된 환경
호스트 시스템에 영향 없음
팀원 모두 동일한 환경
컨테이너 안에서 YOLO 모드 안전하게 사용

Anthropic 공식 devcontainer

Anthropic이 공식 레퍼런스 devcontainer를 제공해요:

"The reference devcontainer setup and associated Dockerfile offer a preconfigured development container that you can use as is, or customize for your needs." — Claude Code Docs

구성 파일:

.devcontainer/
├── devcontainer.json   # 컨테이너 설정, 확장, 볼륨 마운트
├── Dockerfile          # 컨테이너 이미지 정의
└── init-firewall.sh    # 네트워크 보안 규칙

빠른 시작 (4단계)

# 1. VS Code와 Dev Containers 확장 설치

# 2. Anthropic 공식 레퍼런스 클론
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# 3. VS Code로 열기
code .

# 4. "Reopen in Container" 클릭 (또는 Cmd+Shift+P → "Remote-Containers: Reopen in Container")

기본 devcontainer.json 예시

{
  "name": "Claude Code Dev",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code",
  
  "remoteUser": "node",
  
  "containerEnv": {
    "CLAUDE_CONFIG_DIR": "/home/node/.claude"
  },
  
  "mounts": [
    "source=claude-config,target=/home/node/.claude,type=volume"
  ]
}

보안 기능

Anthropic devcontainer의 다층 보안:

"The container implements a multi-layered security approach with its firewall configuration." — Claude Code Docs

보안 레이어 설명

정밀 접근 제어	화이트리스트 도메인만 허용 (npm, GitHub, Claude API)
Default-deny	기타 모든 외부 네트워크 차단
시작 검증	컨테이너 초기화 시 방화벽 규칙 검증
격리	메인 시스템과 완전 분리

YOLO 모드 안전하게 사용하기

devcontainer 안에서는 YOLO 모드를 상대적으로 안전하게 사용할 수 있어요:

# 컨테이너 안에서
claude --dangerously-skip-permissions

"The container's enhanced security measures (isolation and firewall rules) allow you to run claude --dangerously-skip-permissions to bypass permission prompts for unattended operation." — Claude Code Docs

⚠️ 주의:

"devcontainers don't prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials. We recommend only using devcontainers when developing with trusted repositories."

프로젝트별 환경 설정

Node.js 프로젝트:

{
  "name": "Node 20 Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "postCreateCommand": "npm install && npm install -g @anthropic-ai/claude-code"
}

Python 프로젝트:

{
  "name": "Python 3.12 Project", 
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "postCreateCommand": "pip install -r requirements.txt && npm install -g @anthropic-ai/claude-code"
}

멀티 서비스 (Docker Compose):

# docker-compose.yml
version: '3.8'
services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ../..:/workspaces:cached
      - node-modules:/workspaces/project/node_modules
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/mydb
      
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mydb
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  node-modules:
  postgres-data:

Claude 설정 영속화

컨테이너를 재빌드해도 Claude 인증이 유지되도록:

{
  "mounts": [
    "source=claude-code-config,target=/home/node/.claude,type=volume"
  ],
  "containerEnv": {
    "CLAUDE_CONFIG_DIR": "/home/node/.claude"
  }
}

Part 2: git worktree로 병렬 개발

왜 git worktree인가?

"Using git worktrees enables you to run multiple Claude sessions simultaneously on different parts of your project, each focused on its own independent task." — Anthropic Best Practices

문제: 여러 Claude 인스턴스를 같은 디렉토리에서 실행하면 서로 충돌해요. 파일을 동시에 수정하면서 엉망이 됩니다.

해결: git worktree로 격리된 작업 공간을 만들어 각 Claude가 독립적으로 작업하게 해요.

git worktree 기본 개념

# 일반적인 방식: 전체 레포 복사 (비효율적)
/projects/
├── my-project/           # 원본
├── my-project-copy-1/    # 전체 복사 (.git 포함)
└── my-project-copy-2/    # 전체 복사 (.git 포함)

# git worktree 방식: 작업 파일만 분리 (효율적)
/projects/
├── my-project/           # 메인 (.git 여기에만)
├── feature-auth/         # worktree (링크만)
└── feature-api/          # worktree (링크만)

장점:

디스크 공간 효율적 (node_modules 복사 X)
모든 worktree가 동기화 (fetch가 전체에 적용)
같은 브랜치 중복 체크아웃 방지

git worktree와 branch의 관계

핵심 원칙: 1 worktree = 1 branch (1:1 관계)

┌─────────────────────────────────────────────────────────────┐
│                    .git/ (공유)                              │
│  ┌──────────────┬──────────────┬──────────────┐            │
│  │   objects/   │    refs/     │   config     │            │
│  │  (커밋 히스토리) │  (브랜치 정보)  │   (설정)      │            │
│  └──────────────┴──────────────┴──────────────┘            │
└─────────────────────────────────────────────────────────────┘
         │                │                │
         ▼                ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ my-project/ │  │ feature-a/  │  │ hotfix/     │
│ (main)      │  │ (feat/a)    │  │ (fix/bug)   │
│             │  │             │  │             │
│ Working     │  │ Working     │  │ Working     │
│ Directory   │  │ Directory   │  │ Directory   │
└─────────────┘  └─────────────┘  └─────────────┘
   메인 worktree      worktree 1       worktree 2

공유되는 것:

.git/ 디렉토리 (히스토리, 설정, refs)
git fetch 결과 (한 곳에서 fetch하면 전체 적용)
remote 설정
hooks

공유되지 않는 것:

작업 파일들 (각자 독립)
node_modules/, venv/ 등 (각 worktree에서 별도 설치 필요)
.env 파일 (복사 필요)
스테이징 영역 (각자 독립적인 git add)

중요한 제약:

# ❌ 같은 브랜치를 두 worktree에서 체크아웃 불가!
git worktree add ../another main
# fatal: 'main' is already checked out at '/projects/my-project'

# ✅ 반드시 다른 브랜치여야 함
git worktree add ../feature-a -b feat/a

기본 사용법

# 1. 새 worktree 생성
git worktree add ../feature-auth -b feat/auth

# 2. 다른 터미널에서 해당 worktree로 이동
cd ../feature-auth

# 3. Claude Code 실행
claude

# 4. 작업 완료 후 worktree 제거
cd ../my-project
git worktree remove ../feature-auth

Part 2.5: 실무 Flow와 Best Practices

디렉토리 구조 Best Practice

권장 구조:

/projects/
├── my-project/              # 메인 worktree (main 브랜치)
│   ├── .git/                # 실제 Git 데이터 (여기만!)
│   ├── src/
│   ├── CLAUDE.md
│   └── ...
│
└── worktrees/               # worktree 전용 폴더 (프로젝트 밖)
    ├── feature/
    │   ├── user-auth/       # feat/user-auth 브랜치
    │   └── payment-api/     # feat/payment-api 브랜치
    ├── bugfix/
    │   └── login-error/     # fix/login-error 브랜치
    └── review/
        └── pr-123/          # PR 리뷰용

왜 프로젝트 밖에 둘까?

메인 프로젝트가 깔끔하게 유지됨
Git이 worktree를 서브디렉토리로 착각하지 않음
IDE가 혼란스러워하지 않음

실무 시나리오별 Flow

시나리오 1: 긴급 핫픽스 (가장 흔함)

상황: feature 개발 중인데 프로덕션 버그 발생

# 현재: my-project/에서 feat/new-dashboard 작업 중

# 1. 핫픽스용 worktree 생성 (main 기반)
git worktree add ../worktrees/hotfix/payment-bug -b fix/payment-bug origin/main

# 2. 핫픽스 worktree로 이동
cd ../worktrees/hotfix/payment-bug

# 3. 의존성 설치 & 환경 설정
npm install
cp ../../my-project/.env .env

# 4. Claude로 버그 수정
claude
# "Fix the payment timeout issue in checkout flow"

# 5. 커밋 & 푸시
git add .
git commit -m "fix: payment timeout issue in checkout"
git push origin fix/payment-bug

# 6. PR 생성 (Claude가 gh CLI로 가능)
gh pr create --base main --title "Fix payment timeout"

# 7. 머지 후 정리
cd ../../../my-project
git worktree remove ../worktrees/hotfix/payment-bug
git branch -d fix/payment-bug

# 8. 원래 작업으로 복귀 (컨텍스트 그대로!)
claude --resume

Flow 다이어그램:

main ─────────────────●────────────────────────────────●─────
                      │                                ↑
                      │ git worktree add               │ merge
                      ▼                                │
fix/payment-bug ──────●────────●───────────────────────┘
                      │        │
                   worktree  commit
                   생성      & push

시나리오 2: 병렬 기능 개발

상황: 독립적인 2개 기능을 동시에 개발

# 1. 기능 A worktree
git worktree add ../worktrees/feature/user-profile -b feat/user-profile origin/develop
cd ../worktrees/feature/user-profile
npm install && cp ../../my-project/.env .env

# 2. 기능 B worktree (다른 터미널)
git worktree add ../worktrees/feature/notification -b feat/notification origin/develop
cd ../worktrees/feature/notification
npm install && cp ../../my-project/.env .env

# 3. 각 터미널에서 Claude 실행
# 터미널 1:
claude
# "Implement user profile edit functionality"

# 터미널 2:
claude
# "Implement push notification system"

# 4. 각자 완료되면 PR 생성
# 5. develop에 순차적으로 머지

Flow 다이어그램:

develop ────●─────────────────────────────●────────●─────
            │                             ↑        ↑
            ├─────────────────────────────┘        │
            │         feat/user-profile            │
            │                                      │
            └──────────────────────────────────────┘
                      feat/notification

시나리오 3: PR 리뷰 중 다른 작업

상황: 내 PR이 리뷰 중인데 다른 작업 시작해야 함

# 현재: feat/dashboard PR이 리뷰 중
# my-project/는 feat/dashboard 브랜치 상태

# 1. 새 작업용 worktree 생성
git worktree add ../worktrees/feature/analytics -b feat/analytics origin/develop

# 2. 새 작업 시작
cd ../worktrees/feature/analytics
claude
# 새 기능 개발...

# 3. 리뷰 코멘트 오면 원래 worktree로 돌아가기
cd ../my-project  # 여전히 feat/dashboard 상태!
claude --resume   # 컨텍스트 유지!
# 리뷰 반영...

# 4. 왔다갔다 가능 (컨텍스트 손실 없음!)

시나리오 4: 경쟁적 구현 (A/B 테스트)

상황: 같은 기능을 다른 방식으로 구현해서 비교

# 검색 기능을 3가지 방식으로 동시 구현
git worktree add ../worktrees/feature/search-elastic -b feat/search-elastic
git worktree add ../worktrees/feature/search-postgres -b feat/search-postgres
git worktree add ../worktrees/feature/search-algolia -b feat/search-algolia

# 각 worktree에서 Claude에게 다른 지시
# Elastic: "Implement search using Elasticsearch"
# Postgres: "Implement search using PostgreSQL full-text search"
# Algolia: "Implement search using Algolia API"

# 결과 비교 후 최적의 구현 선택
npm run benchmark  # 각 worktree에서 성능 테스트

Merge 전략

순차적 머지 (권장)

# 1. develop 최신화
cd my-project
git checkout develop
git pull origin develop

# 2. 기능 A 머지
git merge feat/user-profile
git push origin develop

# 3. 기능 B를 최신 develop에 리베이스 후 머지
cd ../worktrees/feature/notification
git fetch origin
git rebase origin/develop
# 충돌 해결 (필요시)
git push origin feat/notification --force-with-lease

cd ../my-project
git pull origin develop
git merge feat/notification
git push origin develop

tasks.md로 작업 추적

<!-- tasks.md (메인 worktree에 위치) -->
# 현재 진행 중인 작업

## Active Worktrees

| Worktree | Branch | 담당 | 상태 | 예상 완료 |
|----------|--------|------|------|----------|
| feature/user-profile | feat/user-profile | Claude-1 |   진행중 | 1/22 |
| feature/notification | feat/notification | Claude-2 |   PR 리뷰 중 | 1/21 |
| hotfix/payment | fix/payment-bug | Claude-3 | ✅ 머지됨 | 1/20 |

## Merge Order
1. ✅ fix/payment-bug → main (긴급)
2.   feat/notification → develop
3. ⏳ feat/user-profile → develop (notification 머지 후)

## Dependencies
- feat/user-profile은 feat/notification 완료 후 시작 가능한 부분 있음
- 공통 컴포넌트는 develop에서 먼저 작업

자동화 스크립트

worktree 생성 스크립트:

#!/bin/bash
# save as: scripts/new-worktree.sh

TYPE=$1  # feature, bugfix, hotfix, review
NAME=$2  # 작업 이름
BASE=${3:-origin/develop}  # 기본 브랜치

if [ -z "$TYPE" ] || [ -z "$NAME" ]; then
    echo "Usage: ./new-worktree.sh <type> <name> [base-branch]"
    echo "Example: ./new-worktree.sh feature user-auth"
    echo "         ./new-worktree.sh hotfix payment-bug origin/main"
    exit 1
fi

BRANCH="$TYPE/$NAME"
DIR="../worktrees/$TYPE/$NAME"

# 디렉토리 생성
mkdir -p "../worktrees/$TYPE"

# 최신 정보 fetch
git fetch origin

# worktree 생성
echo "  Creating worktree: $DIR (branch: $BRANCH)"
git worktree add "$DIR" -b "$BRANCH" "$BASE"

if [ $? -eq 0 ]; then
    echo "✅ Worktree created!"
    echo ""
    echo "Next steps:"
    echo "  cd $DIR"
    echo "  npm install  # or your package manager"
    echo "  cp ../../my-project/.env .env  # if needed"
    echo "  claude"
else
    echo "❌ Failed to create worktree"
    exit 1
fi

정리 스크립트:

#!/bin/bash
# save as: scripts/cleanup-worktrees.sh

echo "  Cleaning up merged worktrees..."

git worktree list | grep -v "$(git rev-parse --show-toplevel)" | while read -r line; do
    worktree_path=$(echo "$line" | awk '{print $1}')
    branch=$(echo "$line" | awk '{print $3}' | tr -d '[]')
    
    # main/develop에 머지된 브랜치인지 확인
    if git branch --merged develop 2>/dev/null | grep -q "$branch"; then
        echo "Removing merged worktree: $worktree_path ($branch)"
        git worktree remove "$worktree_path"
        git branch -d "$branch" 2>/dev/null
    fi
done

# 오래된 worktree 메타데이터 정리
git worktree prune

echo "✅ Cleanup complete!"
git worktree list

Claude Code 커스텀 명령어

<!-- .claude/commands/worktree-new.md -->
---
description: Create a new git worktree for parallel development
---

# Create New Worktree

Create a git worktree for: $ARGUMENTS

## Steps:
1. Parse the argument to determine type and name
   - Format: "feature user-auth" or "hotfix payment-bug main"
   
2. Run the worktree creation:
   ```bash
   ./scripts/new-worktree.sh <type> <name> [base]

Navigate to the new worktree and set up:
cd <worktree-path> npm install
Copy necessary env files if they exist
Report the worktree location and suggest next steps

```markdown
<!-- .claude/commands/worktree-status.md -->
---
description: Show status of all worktrees
---

# Worktree Status

Show the current status of all git worktrees:

```bash
echo "  All Worktrees:"
git worktree list

echo ""
echo "  Branch Status:"
for dir in ../worktrees/*/*; do
    if [ -d "$dir" ]; then
        echo "---"
        echo "  $dir"
        cd "$dir"
        git status --short
        echo "Last commit: $(git log -1 --format='%s (%cr)')"
        cd - > /dev/null
    fi
done

### Best Practices 체크리스트

**worktree 생성 시:**
- [ ] 프로젝트 밖에 worktree 디렉토리 생성 (`../worktrees/`)
- [ ] 의미 있는 디렉토리 구조 사용 (`feature/`, `bugfix/`, `hotfix/`)
- [ ] 브랜치 네이밍 규칙 따르기 (`feat/`, `fix/`, `hotfix/`)
- [ ] 올바른 base 브랜치 선택 (feature→develop, hotfix→main)
- [ ] `npm install` 또는 의존성 설치
- [ ] `.env` 파일 복사

**작업 중:**
- [ ] 각 worktree에서 `/init` 실행 (CLAUDE.md 생성)
- [ ] 세션 이름 명명 (`/session feature-user-auth`)
- [ ] 자주 커밋 (작은 단위로)
- [ ] tasks.md로 진행 상황 추적

**머지 시:**
- [ ] develop/main 최신화 후 리베이스
- [ ] 충돌 해결
- [ ] 테스트 통과 확인
- [ ] PR 생성 & 리뷰

**정리:**
- [ ] 머지 후 worktree 제거 (`git worktree remove`)
- [ ] 브랜치 삭제 (`git branch -d`)
- [ ] 주기적으로 `git worktree prune` 실행

### 병렬 개발 워크플로우

> "For instance, you might have one Claude refactoring your authentication system while another builds a completely unrelated data visualization component."
> — [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)

**예시: 3개 작업 동시 진행**

```bash
# 터미널 1: 인증 리팩토링
git worktree add ../auth-refactor -b refactor/auth
cd ../auth-refactor
claude
# "Refactor the authentication system to use JWT"

# 터미널 2: 새 기능 개발  
git worktree add ../ai-chat -b feat/ai-chat
cd ../ai-chat
claude
# "Implement AI chat feature with streaming"

# 터미널 3: 버그 수정
git worktree add ../hotfix -b fix/payment-bug
cd ../hotfix
claude
# "Fix the payment processing bug in checkout flow"

디렉토리 구조:

/projects/
├── my-project/        # 메인 (main 브랜치)
│   └── .git/          # 실제 Git 데이터
├── auth-refactor/     # worktree (refactor/auth 브랜치)
│   └── .git           # 링크 파일
├── ai-chat/           # worktree (feat/ai-chat 브랜치)
│   └── .git           # 링크 파일
└── hotfix/            # worktree (fix/payment-bug 브랜치)
    └── .git           # 링크 파일

/resume으로 세션 관리

"Sessions are stored per project directory. The /resume picker shows sessions from the same git repository, including worktrees." — Claude Code Docs

# worktree에서 세션 이름 지정
claude
> /session auth-refactoring-session

# 나중에 재개
claude --resume
# 또는 세션 내에서
> /resume

커스텀 명령어로 자동화

worktree 초기화 명령어:

<!-- .claude/commands/worktree-init.md -->
---
description: Initialize parallel worktrees for a feature
---

# Initialize Parallel Worktrees

## Variables
FEATURE_NAME: $ARGUMENTS

## Instructions

Create git worktrees for parallel development of FEATURE_NAME.

1. Create the worktrees directory if it doesn't exist:
   ```bash
   mkdir -p ../worktrees

Create a new git worktree:
git worktree add ../worktrees/FEATURE_NAME -b feat/FEATURE_NAME
Copy environment files:
cp .env.example ../worktrees/FEATURE_NAME/.env
Install dependencies in the new worktree:
cd ../worktrees/FEATURE_NAME && npm install
Report the worktree location and next steps.

**사용:**
```bash
> /worktree-init user-dashboard

고급 패턴: 경쟁적 구현

같은 기능을 여러 방식으로 동시 구현하고 최적의 결과 선택:

# 3개의 다른 접근법으로 동시 구현
git worktree add ../impl-approach-1 -b feat/search-v1
git worktree add ../impl-approach-2 -b feat/search-v2  
git worktree add ../impl-approach-3 -b feat/search-v3

# 각 worktree에서 다른 지시
# Approach 1: "Implement search using Elasticsearch"
# Approach 2: "Implement search using PostgreSQL full-text"
# Approach 3: "Implement search using Algolia"

# 결과 비교 후 최적의 구현 선택

worktree 관리 팁

현재 worktree 목록:

git worktree list
# /projects/my-project        abc1234 [main]
# /projects/auth-refactor     def5678 [refactor/auth]
# /projects/ai-chat           ghi9012 [feat/ai-chat]

worktree 제거:

# 작업 완료 후
git worktree remove ../auth-refactor

# 강제 제거 (변경사항 있어도)
git worktree remove --force ../auth-refactor

오래된 worktree 정리:

git worktree prune

Part 3: devcontainer + git worktree 조합

최강 조합

devcontainer (환경 격리) + git worktree (작업 격리)
= 완벽한 병렬 개발 환경

워크플로우:

프로젝트를 devcontainer로 열기
컨테이너 안에서 git worktree 생성
각 worktree에서 별도 Claude 세션 실행
YOLO 모드로 빠르게 작업
작업 완료 후 메인에 머지

# devcontainer 안에서
git worktree add ../feature-a -b feat/a
git worktree add ../feature-b -b feat/b

# 터미널 1
cd ../feature-a && claude --dangerously-skip-permissions

# 터미널 2  
cd ../feature-b && claude --dangerously-skip-permissions

CLAUDE.md에 병렬 개발 가이드 추가

# Parallel Development Guidelines

## Git Worktree Conventions
- Worktree location: `../worktrees/`
- Branch naming: `feat/`, `fix/`, `refactor/` prefixes
- Always run `/init` in new worktrees

## Session Management
- Name sessions descriptively: `/session feature-name-task`
- Use `/resume` to continue work

## Merge Protocol
1. Complete feature in worktree
2. Run all tests
3. Commit with semantic message
4. Switch to main and merge
5. Remove worktree after merge

주의사항

devcontainer 한계

IDE 통합 제한: 일부 IDE 기능이 작동 안 할 수 있음
리소스 사용: Docker Desktop 메모리 8GB+ 권장
초기 빌드 시간: 첫 빌드에 시간 소요
신뢰할 수 있는 레포만: 악성 프로젝트는 여전히 위험

git worktree 한계

파일 공유 불가: worktree 간 .env 등 복사 필요
node_modules: 각 worktree에서 npm install 필요
머지 충돌: 결국 통합할 때 충돌 가능
비용 증가: 여러 Claude 세션 = 더 많은 토큰 사용

언제 뭘 쓸까?

상황 추천

프로젝트별 환경 다름	devcontainer
YOLO 모드 안전하게	devcontainer
같은 레포 병렬 작업	git worktree
독립적 기능 동시 개발	git worktree
팀 환경 통일	devcontainer
빠른 실험/비교	git worktree

체크리스트

devcontainer 설정

[ ] VS Code Dev Containers 확장 설치
[ ] Docker Desktop 실행 중
[ ] .devcontainer/devcontainer.json 생성
[ ] Claude 설정 볼륨 마운트
[ ] 방화벽 규칙 확인 (필요시)

git worktree 활용

[ ] worktree 디렉토리 규칙 정하기 (../worktrees/)
[ ] 브랜치 네이밍 규칙 정하기
[ ] 각 worktree에서 /init 실행
[ ] 세션 이름 명명하기
[ ] 작업 완료 후 worktree 정리

병렬 개발

[ ] 독립적 작업인지 확인 (파일 충돌 없는지)
[ ] 각 Claude에 명확한 작업 지시
[ ] 주기적으로 진행 상황 확인
[ ] 머지 전 테스트 실행

마무리

**컨테이너 격리 (devcontainer)**는 프로젝트 간 환경 충돌을 막고, YOLO 모드를 안전하게 사용할 수 있게 해줘요.

git worktree는 같은 레포에서 여러 Claude 인스턴스를 동시에 돌릴 수 있게 해주는 공식 권장 방법이에요.

"Using git worktrees enables you to run multiple Claude sessions simultaneously on different parts of your project, each focused on its own independent task." — Anthropic Best Practices

둘을 조합하면 안전하고 효율적인 병렬 개발 환경을 구축할 수 있어요.

환경 격리가 필요하면 → devcontainer
작업 격리가 필요하면 → git worktree
둘 다 필요하면 → devcontainer 안에서 git worktree

프로젝트 여러 개 동시에 진행하거나, 한 프로젝트에서 여러 기능을 병렬로 개발할 때 꼭 활용해보세요!

참고 자료

Anthropic 공식

Development containers - Claude Code Docs — devcontainer 공식 문서
Claude Code Best Practices — git worktree 베스트 프랙티스
Common workflows - Claude Code Docs — /resume과 세션 관리
Anthropic devcontainer 레퍼런스 — 공식 설정 파일

커뮤니티 가이드

도구

Crystal — 병렬 worktree 관리 데스크톱 앱
claude-container — Docker 워크플로우

Claude Code Thinking Mode: ultrathink로 깊게 생각시키기

MoreLean — Wed, 21 Jan 2026 00:44:09 +0900

고급 기능 하나 알려드릴게요. ultrathink라는 키워드예요.

프롬프트에 ultrathink 넣으면 Claude Code가 더 깊게 생각해요. 복잡한 아키텍처 설계하거나 어려운 버그 잡을 때 쓰면 성공률이 확 올라가요.

단, 시간이 좀 더 걸려요. 급할 땐 빼고, 정말 중요한 결정할 때만 ultrathink 쓰세요.

TL;DR

think < think hard < think harder < ultrathink — 단계별 thinking 강도
ultrathink = 최대 32,000 토큰의 thinking budget 할당
복잡한 아키텍처, 까다로운 버그에 효과적
Claude Code 전용 기능 (일반 Chat/API에서는 안 됨)
시간/비용 더 드니까 중요한 결정에만 사용

Extended Thinking이란?

"We recommend using the word 'think' to trigger extended thinking mode, which gives Claude additional computation time to evaluate alternatives more thoroughly." — Anthropic Best Practices

Extended Thinking은 Claude가 답변하기 전에 내부적으로 더 오래 생각하게 하는 기능이에요. 사람이 복잡한 문제를 풀 때 더 오래 고민하는 것처럼요.

Thinking 레벨 4단계

Anthropic 공식 문서에 명시된 4단계 thinking budget:

think < think hard < think harder < ultrathink

"These specific phrases are mapped directly to increasing levels of thinking budget in the system." — Anthropic Best Practices

토큰 할당량

Simon Willison이 Claude Code 소스를 분석한 결과:

키워드 Thinking 토큰 용도

think	~4,000	일반적인 작업
think hard, megathink	~10,000	중간 복잡도
think harder, ultrathink	~32,000	최고 복잡도

트리거 키워드들

ultrathink 레벨 (32K 토큰):

ultrathink
think harder
think intensely
think longer
think really hard
think super hard
think very hard

megathink 레벨 (10K 토큰):

think hard
think deeply
think more
think a lot
megathink

기본 think (4K 토큰):

think
think about it

언제 ultrathink를 쓸까?

✅ ultrathink 권장

복잡한 아키텍처 설계
Design a scalable microservices architecture for our e-commerce platform. Please ultrathink about scalability, fault tolerance, and maintainability.
까다로운 버그 디버깅
This race condition only happens in production under high load. Ultrathink about all possible causes and solutions.
중요한 마이그레이션 계획
We need to migrate from MongoDB to PostgreSQL without downtime. Think harder about the migration strategy and rollback plan.
보안 취약점 분석
Review our authentication flow for security vulnerabilities. Ultrathink about edge cases and attack vectors.
AI가 루프에 빠졌을 때
You've been trying the same approach 3 times. Ultrathink and try a completely different strategy.

❌ ultrathink 불필요

단순한 버그 수정
기본적인 CRUD 구현
간단한 리팩토링
문서 업데이트
커밋 메시지 작성

"For routine tasks - trivial bug fixes, simple feature additions - the standard think level offers optimal efficiency-cost ratio." — goatreview.com

사용 예시

아키텍처 설계

I need to design a real-time notification system that handles 1M+ concurrent users.
Please ultrathink about:
- Message queue architecture (Kafka vs RabbitMQ vs Redis)
- WebSocket scaling strategy
- Failure handling and retry logic
- Cost optimization

복잡한 디버깅

Our payment processing sometimes fails silently in production.
Logs show no errors but transactions don't complete.
Ultrathink about what could cause this and how to debug it.

기술 스택 결정

We're starting a new project and need to choose between:
- Next.js vs Remix vs SvelteKit
- PostgreSQL vs MongoDB vs CockroachDB
- Vercel vs AWS vs GCP

Think harder about the trade-offs for a team of 5 developers 
building a B2B SaaS with complex data relationships.

Plan Mode와 함께

[Plan Mode에서]
I want to add real-time collaboration features to our document editor.
Ultrathink about the implementation plan, considering:
- Conflict resolution (OT vs CRDT)
- Presence indicators
- Offline support
- Performance at scale

실전 팁

1. CLAUDE.md에 가이드라인 추가

# Thinking Mode Guidelines

- Use "think" for routine tasks and bug fixes
- Use "think hard" for API design and integration
- Reserve "ultrathink" for:
  - System architecture decisions
  - Critical security reviews
  - Complex migration planning
  - When Claude gets stuck in a loop

2. 커스텀 명령어로 만들기

<!-- .claude/commands/deep-analysis.md -->
---
description: Deep analysis with extended thinking
model: opus
---

Ultrathink about this problem before proposing solutions.

Follow these steps:
1. Analyze the problem thoroughly
2. Consider multiple approaches with trade-offs
3. Evaluate security, performance, and maintainability
4. Recommend the best solution with detailed reasoning

Problem: $ARGUMENTS

사용:

> /deep-analysis "How should we implement real-time sync?"

3. 단계적 접근

급하게 ultrathink부터 쓰지 말고:

먼저 일반 요청으로 시도
결과가 얕으면 think hard 추가
그래도 부족하면 ultrathink

# Step 1: 일반 요청
> Design the authentication flow

# Step 2: 결과가 얕다면
> Think harder about edge cases and security

# Step 3: 정말 복잡하면
> Ultrathink about the entire auth architecture including OAuth, MFA, and session management

주의사항

Claude Code 전용

"'ultrathink' is a real, documented feature - but it only works in Claude Code, Anthropic's command-line coding tool." — ITECS Online

일반 Claude Chat이나 API에서는 작동하지 않아요. Claude Code CLI에서만 동작합니다.

시간과 비용

ultrathink는 응답 시간이 길어짐
토큰 사용량 증가 → 비용 증가
급한 작업에는 비효율적

Thinking Mode 토글 (v2.0+)

최신 버전에서는 Tab 키로 thinking mode를 토글할 수 있어요:

# Tab 한 번: Plan Mode (thinking 강화)
# Shift+Tab 두 번: Plan Mode 진입

ultrathink 키워드와 함께 사용하면 더 강력해요:

[Tab으로 Plan Mode 진입]
> Ultrathink about the database schema for our multi-tenant SaaS

요약: 언제 뭘 쓸까?

상황 권장 레벨

단순 버그 수정	(기본)
일반적인 기능 구현	think
API 설계, 리팩토링	think hard
아키텍처 설계	ultrathink
복잡한 디버깅	ultrathink
보안 리뷰	ultrathink
Claude가 루프에 빠짐	ultrathink

체크리스트

기본 사용

[ ] 복잡한 작업에 think 키워드 추가
[ ] 중요한 설계에 think hard 사용
[ ] 최고 난이도에만 ultrathink 사용

고급 활용

[ ] CLAUDE.md에 thinking 가이드라인 추가
[ ] /deep-analysis 같은 커스텀 명령어 생성
[ ] Plan Mode + ultrathink 조합 활용

주의

[ ] 급한 작업엔 ultrathink 피하기
[ ] 비용/시간 고려하기
[ ] Claude Code에서만 작동함 기억하기

마무리

ultrathink는 Claude Code의 숨겨진 파워 기능이에요.

기억하세요:

think < think hard < think harder < ultrathink
ultrathink = 최대 32K 토큰의 thinking budget
복잡한 아키텍처, 어려운 버그에 효과적
시간이 더 걸리니까 중요한 결정에만
Claude Code 전용 (Chat/API에서는 안 됨)

"These specific phrases are mapped directly to increasing levels of thinking budget in the system." — Anthropic Best Practices

정말 중요한 아키텍처 결정이나 며칠째 못 잡는 버그가 있다면, ultrathink 한 번 써보세요. 성공률이 확 달라질 거예요.

참고 자료

Anthropic 공식

Claude Code Best Practices — ultrathink 공식 문서

분석/가이드

Simon Willison's Analysis — 토큰 할당량 코드 분석
Claude Code Extended Thinking Guide — 종합 가이드
Thinking Levels Deep Dive — 레벨별 상세 설명

Claude Code 커스텀 명령어: 혼자서도 팀처럼 개발하기

MoreLean — Wed, 21 Jan 2026 00:39:55 +0900

Claude Code의 커스텀 슬래시 명령어를 알면 혼자서도 팀 개발하는 느낌이 나요. 정말이에요.

/tdd 치면 테스트 주도 개발 모드로 들어가요. RED-GREEN-IMPROVE 사이클 돌면서 테스트 먼저 짜고 코드 구현하거든요. /plan은 작업 계획 세우고, /e2e는 E2E 테스트 만들어주고, /code-review는 코드 리뷰 돌려줘요.

자주 쓰는 워크플로우를 명령어 하나로 실행할 수 있어요.

TL;DR

커스텀 명령어 = 저장된 프롬프트를 한 번에 실행
위치: .claude/commands/ (프로젝트) 또는 ~/.claude/commands/ (전역)
파일명 = 명령어 이름 (tdd.md → /tdd)
$ARGUMENTS로 인자 전달 가능
frontmatter로 도구 제한, 모델 지정 가능

커스텀 명령어란?

"Custom slash commands are essentially saved prompts that you can invoke with a simple /command_name syntax." — cloudartisan.com

매번 같은 프롬프트 치는 거 귀찮잖아요. "테스트 먼저 작성하고, 실패하는지 확인하고, 그 다음 구현해줘"를 매번 타이핑하는 대신, /tdd만 치면 끝이에요.

왜 필요한가?

반복 제거: 자주 쓰는 프롬프트 저장
일관성: 항상 같은 방식으로 작업
팀 공유: Git으로 명령어 공유 가능
워크플로우 자동화: 복잡한 작업을 명령어 하나로

"I don't think about naming conventions, commit messages, or PR descriptions anymore. The commands handle it." — alexop.dev

명령어 저장 위치

위치 범위 Git 커밋

.claude/commands/	프로젝트 전용	✅ 팀 공유
~/.claude/commands/	모든 프로젝트	❌ 개인용

# 프로젝트 명령어 생성
mkdir -p .claude/commands
echo "Analyze this code for performance issues:" > .claude/commands/optimize.md

# 전역 명령어 생성
mkdir -p ~/.claude/commands
echo "Review this code for security vulnerabilities:" > ~/.claude/commands/security.md

기본 문법

가장 간단한 형태

파일명이 곧 명령어 이름이에요:

<!-- .claude/commands/optimize.md -->
Analyze this code for performance issues and suggest optimizations.
Focus on:
- Time complexity
- Memory usage
- Database queries

이제 /optimize만 치면 됩니다!

인자 받기

$ARGUMENTS로 사용자 입력을 받을 수 있어요:

<!-- .claude/commands/fix-issue.md -->
Fix GitHub issue #$ARGUMENTS

1. Read the issue details
2. Find relevant code
3. Implement the fix
4. Write tests
5. Create a commit

사용법:

> /fix-issue 123
# → "Fix GitHub issue #123" 으로 실행됨

여러 인자 받기

$1, $2, $3으로 개별 인자를 받을 수 있어요:

<!-- .claude/commands/pr-review.md -->
Review PR #$1 with priority $2 and assign to $3.
Focus on security, performance, and code style.

사용법:

> /pr-review 42 high @alice

Frontmatter로 고급 설정

YAML frontmatter로 더 세밀하게 제어할 수 있어요:

---
description: Create a git commit with conventional message
allowed-tools: Bash(git add:*), Bash(git commit:*)
argument-hint: [message]
model: haiku
---

# Commit Changes

<git_diff>
!`git diff --cached`
</git_diff>

Create a commit message following Conventional Commits.
If $ARGUMENTS is provided, use it as the commit message.

Frontmatter 옵션

옵션 설명 예시

description	명령어 설명 (/help에 표시)	"Run tests with coverage"
allowed-tools	사용 가능한 도구 제한	Read, Grep, Glob
model	사용할 모델 지정	haiku, sonnet, opus
argument-hint	인자 힌트	[file] [options]

모델 선택 팁

"Add model: haiku and commands run almost instantly." — alexop.dev

haiku: 간단한 작업 (커밋 메시지, 파일 정리) → 빠름
sonnet: 일반 작업 (코드 리뷰, 리팩토링) → 균형
opus: 복잡한 작업 (아키텍처 설계, 디버깅) → 강력

실전 명령어 예시

/tdd - 테스트 주도 개발

---
description: Test-driven development workflow
allowed-tools: Read, Write, Edit, Bash
---

# TDD Workflow

Follow the RED-GREEN-IMPROVE cycle:

## 1. RED - Write Failing Test
- Write a test that describes the expected behavior
- Run the test and confirm it FAILS
- Do NOT write implementation yet

## 2. GREEN - Make It Pass
- Write the MINIMUM code to pass the test
- Do NOT optimize yet
- Run tests to confirm they PASS

## 3. IMPROVE - Refactor
- Clean up the code
- Remove duplication
- Improve naming
- Run tests to ensure they still PASS

## Rules
- Never modify tests to make them pass
- Aim for 80%+ test coverage
- One test at a time

Start with: $ARGUMENTS

/plan - 작업 계획

---
description: Create implementation plan for a feature
allowed-tools: Read, Grep, Glob
model: opus
---

# Feature Planning

Create a detailed implementation plan for: $ARGUMENTS

## Steps
1. Analyze the current codebase structure
2. Identify affected files and components
3. Break down into small, testable tasks
4. Estimate complexity for each task
5. Identify potential risks and edge cases

## Output Format
```markdown
# Implementation Plan: [Feature Name]

## Overview
[Brief description]

## Tasks
- [ ] Task 1 (complexity: low/medium/high)
- [ ] Task 2
...

## Files to Modify
- path/to/file1.ts - reason
- path/to/file2.ts - reason

## Risks
- Risk 1 and mitigation

Save the plan to PLAN.md

### /e2e - E2E 테스트 생성

```markdown
---
description: Generate end-to-end tests with Playwright
allowed-tools: Read, Write, Bash
---

# E2E Test Generation

Generate Playwright E2E tests for: $ARGUMENTS

## Guidelines
1. Analyze the user flow
2. Write tests that cover happy path AND edge cases
3. Use proper selectors (data-testid preferred)
4. Include assertions for:
   - UI elements visible
   - Network requests completed
   - State changes reflected

## Structure
```typescript
import { test, expect } from '@playwright/test';

test.describe('[Feature Name]', () => {
  test.beforeEach(async ({ page }) => {
    // Setup
  });

  test('should [expected behavior]', async ({ page }) => {
    // Arrange
    // Act
    // Assert
  });
});

After Writing

Run tests to verify they work
Add to CI pipeline if not already

### /code-review - 코드 리뷰

```markdown
---
description: Comprehensive code review
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
model: sonnet
---

# Code Review

## Changed Files
!`git diff --name-only HEAD~1`

## Detailed Changes
!`git diff HEAD~1`

## Review Checklist

### 1. Code Quality
- [ ] Clear naming conventions
- [ ] No code duplication
- [ ] Functions are small and focused
- [ ] Comments explain "why" not "what"

### 2. Security
- [ ] No hardcoded secrets
- [ ] Input validation present
- [ ] SQL injection prevention
- [ ] XSS protection

### 3. Performance
- [ ] No N+1 queries
- [ ] Efficient algorithms
- [ ] Proper caching

### 4. Testing
- [ ] Tests cover new functionality
- [ ] Edge cases handled
- [ ] No flaky tests

## Output Format
For each issue found:
1. **File:Line** - Severity (Critical/High/Medium/Low)
2. Description
3. Suggested fix with code

/commit - 자동 커밋 메시지

---
description: Create conventional commit message
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
model: haiku
---

# Git Commit

<staged_changes>
!`git diff --cached`
</staged_changes>

Create a commit message following Conventional Commits:
- feat: new feature
- fix: bug fix
- docs: documentation
- style: formatting
- refactor: code restructure
- test: adding tests
- chore: maintenance

Format: type(scope): description

If $ARGUMENTS provided, use as commit message.
Otherwise, generate from staged changes.

/branch - 브랜치 생성

---
description: Create a properly named git branch
allowed-tools: Bash(git checkout:*), Bash(git branch:*)
model: haiku
---

# Create Branch

Create a new branch for: $ARGUMENTS

## Naming Convention
- feature/description-here
- fix/issue-description
- refactor/what-is-changing
- docs/what-documenting

## Steps
1. Determine appropriate prefix based on work type
2. Convert description to kebab-case
3. Create and checkout branch

Example: "add user authentication" → feature/add-user-authentication

폴더로 정리하기

명령어가 많아지면 폴더로 정리할 수 있어요:

.claude/commands/
├── git/
│   ├── commit.md      → /project:git/commit
│   ├── branch.md      → /project:git/branch
│   └── pr.md          → /project:git/pr
├── testing/
│   ├── tdd.md         → /project:testing/tdd
│   ├── e2e.md         → /project:testing/e2e
│   └── unit.md        → /project:testing/unit
└── review/
    ├── code.md        → /project:review/code
    └── security.md    → /project:review/security

"The subdirectory appears in the command description but doesn't affect the command name itself." — Claude Code Docs

빌트인 명령어

Claude Code에 기본 내장된 명령어들:

명령어 설명

/help	모든 명령어 목록
/compact	컨텍스트 압축
/clear	컨텍스트 초기화
/context	컨텍스트 사용량 확인
/init	CLAUDE.md 자동 생성
/model	모델 변경
/agents	서브에이전트 관리
/config	설정 변경
/add-dir	작업 디렉토리 추가
/install-github-app	GitHub PR 리뷰 앱 설치

명령어 vs Skills vs Agents

구분 슬래시 명령어 Skills Agents

호출	명시적 (/tdd)	자동 (필요 시)	자동 또는 명시적
용도	특정 작업 실행	지식/방법론 제공	독립적 작업 수행
컨텍스트	메인과 공유	메인과 공유	별도 격리
비유	매크로 버튼	참고 매뉴얼	전문가 팀원

"Slash commands and Agent Skills serve different purposes in Claude Code... Both can coexist." — Claude Code Docs

언제 뭘 쓸까?

명령어: "이 작업 지금 해줘" → /tdd, /commit
Skills: "이 방법론 참고해서 해줘" → TDD workflow skill
Agents: "이 전문가한테 맡겨줘" → code-reviewer agent

명령어에 Hooks 추가하기

명령어 실행 중 특정 시점에 스크립트를 실행할 수 있어요:

---
description: Deploy to staging with validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-deploy.sh"
          once: true
---

Deploy the current branch to staging environment.

once: true는 한 세션에 한 번만 실행됩니다.

팁

1. 작은 것부터 시작

# 가장 자주 치는 명령어부터
echo "Run all tests and show coverage" > ~/.claude/commands/test.md

2. Git으로 팀 공유

# .claude/commands/ 를 Git에 커밋
git add .claude/commands/
git commit -m "Add team slash commands"

3. /help로 확인

> /help
# 모든 명령어 목록 + 설명 표시

4. 어디서든 / 입력

"Slash command autocomplete works anywhere in your input, not just at the beginning." — Claude Code Docs

> Fix the login bug using /tdd approach
# 문장 중간에도 명령어 사용 가능

체크리스트

시작하기

[ ] .claude/commands/ 폴더 생성
[ ] 가장 자주 쓰는 프롬프트 → 명령어로 저장
[ ] /help로 확인

확장하기

[ ] everything-claude-code 명령어 복사
[ ] 팀 워크플로우에 맞게 커스터마이징
[ ] Git 커밋으로 팀 공유

고급

[ ] frontmatter로 모델/도구 제한
[ ] 폴더로 카테고리 정리
[ ] Hooks 추가로 자동화 강화

마무리

커스텀 명령어는 반복을 제거하고 워크플로우를 자동화하는 가장 쉬운 방법이에요.

기억하세요:

파일 하나 = 명령어 하나
.claude/commands/에 저장 → /명령어명으로 실행
$ARGUMENTS로 인자 전달
frontmatter로 세부 설정
팀과 Git으로 공유

"I was wasting time. Every commit message, every branch name, every PR description. I typed the same things over and over. Then I discovered Slash Commands." — alexop.dev

/tdd, /plan, /code-review... 이런 명령어들 세팅해두면 정말 혼자서도 팀처럼 개발할 수 있어요.

참고 자료

Anthropic 공식

Slash Commands — Claude Code Docs
Slash Commands in the SDK — Claude Docs

커뮤니티

everything-claude-code — 실전 검증 명령어
wshobson/commands — 57개 명령어 컬렉션
awesome-claude-code — 명령어 모음
How I use Claude Code — Builder.io

Claude Code Skills & Agents: 전문가 팀을 내 손안에

MoreLean — Wed, 21 Jan 2026 00:33:52 +0900

Claude Code의 Skills와 **Agents(서브에이전트)**는 꼭 알아야 하는 기능이에요.

Skills는 Claude에게 추가 능력을 부여하는 거예요. Agents는 특화된 전문가를 호출하는 거고요. Planner Agent는 프로젝트 전체 구조를 설계하고, Architect는 기술 스택을 추천하고, Code Reviewer는 코드 리뷰를, Security Reviewer는 보안 취약점을 찾아줘요.

마치 시니어 개발자 팀을 고용한 것처럼 일할 수 있어요.

TL;DR

Skills: Claude에게 새로운 능력을 부여하는 지식 패키지
Agents: 특화된 작업을 수행하는 전문가 서브에이전트
빌트인 Agents: Explore (탐색), Plan (계획)
커스텀 Agents 생성 가능: /agents 명령으로 쉽게 생성
추천 리소스: affaan-m/everything-claude-code — 실전 검증된 configs

Skills란?

"Skills extend Claude's capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized assistants." — Anthropic Engineering

Skills는 Claude에게 도메인 전문 지식을 주입하는 방법이에요. 폴더 + SKILL.md 파일 구조로 되어있고, Claude가 필요할 때 자동으로 로드합니다.

기본 구조

my-skill/
├── SKILL.md          ← 필수: 메타데이터 + 지침
├── templates/        ← 선택: 템플릿 파일들
├── scripts/          ← 선택: 실행 가능한 스크립트
└── examples/         ← 선택: 예시 파일들

SKILL.md 예시

---
name: tdd-workflow
description: Test-driven development methodology for writing robust code
---

# TDD Workflow

1. **RED**: Write failing tests first
2. **GREEN**: Implement minimal code to pass
3. **REFACTOR**: Improve code quality
4. Always aim for 80%+ test coverage
5. Never modify tests to make them pass

Progressive Disclosure

Skills의 핵심 원리는 **점진적 공개(Progressive Disclosure)**예요:

"Skills let Claude load information only as needed. The amount of context that can be bundled into a skill is effectively unbounded." — Anthropic Engineering

시작: 이름과 설명만 로드
필요 시: 전체 SKILL.md 로드
상세 필요 시: 추가 파일들 로드

컨텍스트 윈도우를 효율적으로 사용하면서도 무제한에 가까운 지식을 활용할 수 있어요.

빌트인 Skills

Anthropic이 제공하는 기본 Skills:

Skill 용도

PowerPoint	프레젠테이션 생성/편집
Excel	스프레드시트 + 수식
Word	문서 작성/편집
PDF	PDF 폼 채우기/생성

"Use Anthropic-created skills to have Claude read and generate professional Excel spreadsheets with formulas, PowerPoint presentations, Word documents, and fillable PDFs." — Anthropic News

Agents(서브에이전트)란?

"Subagents are separate agent instances that your main agent can spawn to handle focused subtasks." — Claude Agent SDK Docs

Agents는 특화된 작업을 수행하는 전문가예요. 메인 Claude가 복잡한 작업을 만나면 적절한 Agent에게 위임합니다.

왜 필요한가?

컨텍스트 격리: 서브에이전트는 별도 컨텍스트 사용 → 메인 컨텍스트 깔끔 유지
병렬 처리: 여러 에이전트 동시 실행 가능
전문화: 각 에이전트에 맞춤 프롬프트와 도구 제한

"Subagents use their own isolated context windows, and only send relevant information back to the orchestrator, rather than their full context." — Anthropic Engineering

빌트인 Agents

Claude Code에 기본 내장된 에이전트들:

Agent 용도 특징

Explore	코드베이스 탐색/검색	Read-only, 빠른 탐색
Plan	계획 수립을 위한 리서치	Plan Mode에서 자동 사용

"Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context." — Claude Code Docs

커스텀 Agent 만들기

/agents 명령으로 쉽게 만들 수 있어요:

# Claude Code에서
> /agents
# → Create new agent 선택
# → User-level 또는 Project-level 선택
# → Generate with Claude로 자동 생성

Agent 파일 구조

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Analyze code for:
- Security vulnerabilities
- Performance issues
- Code style consistency
- Best practices violations

Provide specific, actionable feedback with code examples.

Agent 저장 위치

위치 범위

~/.claude/agents/	사용자 전역 (모든 프로젝트)
.claude/agents/	프로젝트 전용

실전 활용: everything-claude-code

실전에서 검증된 configs를 원한다면 affaan-m/everything-claude-code 레포를 추천해요.

"Won the Anthropic x Forum Ventures hackathon in Sep 2025... These configs are battle-tested across multiple production applications." — affaan-m

포함된 Agents

Agent 역할

planner.md	기능 구현 계획 수립
architect.md	시스템 설계, 기술 스택 결정
tdd-guide.md	테스트 주도 개발 가이드
code-reviewer.md	코드 품질/보안 리뷰
security-reviewer.md	보안 취약점 분석
build-error-resolver.md	빌드 에러 해결
e2e-runner.md	Playwright E2E 테스트
refactor-cleaner.md	데드 코드 정리
doc-updater.md	문서 동기화

포함된 Skills

Skill 내용

coding-standards.md	언어별 베스트 프랙티스
backend-patterns.md	API, DB, 캐싱 패턴
frontend-patterns.md	React, Next.js 패턴
tdd-workflow/	TDD 방법론
security-review/	보안 체크리스트

설치 방법

# 레포 클론
git clone https://github.com/affaan-m/everything-claude-code.git

# agents 복사 (사용자 전역)
cp -r everything-claude-code/agents/* ~/.claude/agents/

# skills 복사 (사용자 전역)
cp -r everything-claude-code/skills/* ~/.claude/skills/

# 또는 프로젝트별로 복사
cp -r everything-claude-code/agents/* .claude/agents/
cp -r everything-claude-code/skills/* .claude/skills/

사용 예시

# Planner Agent에게 기능 설계 요청
> "Use the planner agent to design the user authentication feature"

# Code Reviewer로 리뷰 요청
> "Have the code-reviewer agent review src/auth/"

# Security Reviewer로 보안 검토
> "Ask security-reviewer to analyze our API endpoints"

또 다른 추천: wshobson/agents

더 방대한 컬렉션을 원한다면 **wshobson/agents**도 있어요:

108개 전문 Agents
129개 Skills
72개 플러그인
15개 워크플로우 오케스트레이터

"A comprehensive production-ready system combining 108 specialized AI agents, 15 multi-agent workflow orchestrators, 129 agent skills." — wshobson/agents

Skills vs Agents 비교

구분 Skills Agents

역할	지식/방법론 제공	작업 실행
비유	매뉴얼, 가이드북	전문가, 팀원
로드 시점	필요할 때 자동	명시적 호출 또는 자동 위임
컨텍스트	메인과 공유	별도 격리
예시	TDD 방법론, 코딩 표준	Code Reviewer, Security Auditor

함께 사용하면 더 강력

[사용자 요청]
     ↓
[메인 Claude]
     ↓
[Skills 로드: tdd-workflow]  ←  방법론 참조
     ↓
[Agent 위임: tdd-guide]      ←  실제 작업 수행
     ↓
[결과 반환]

Agent 작성 팁

1. 명확한 description

---
name: security-reviewer
description: Analyzes code for security vulnerabilities including XSS, SQL injection, auth issues, and sensitive data exposure
---

Claude가 언제 이 에이전트를 사용할지 결정하는 핵심이에요.

2. 도구 제한

---
tools: Read, Grep, Glob  # Bash 제외 → 읽기 전용
---

"A doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files." — Claude Agent SDK Docs

3. 적절한 모델 선택

---
model: sonnet  # 빠른 분석 작업
# model: opus  # 복잡한 추론 필요 시
---

4. 구체적인 지침

You are a senior code reviewer at a Fortune 500 company.

## Review Checklist
- [ ] No hardcoded secrets
- [ ] Input validation on all endpoints
- [ ] Error handling with proper logging
- [ ] SQL injection prevention
- [ ] XSS protection

## Output Format
For each issue:
1. File and line number
2. Severity (Critical/High/Medium/Low)
3. Description
4. Suggested fix with code

주의사항

컨텍스트 관리

"Critical: Don't enable all MCPs at once. Your 200k context window can shrink to 70k with too many tools enabled." — affaan-m

필요한 것만 활성화
프로젝트별로 다른 설정 사용

보안

"Skills provide Claude with new capabilities through instructions and code... a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose." — Claude Docs

신뢰할 수 있는 소스만 사용
설치 전 내용 검토

서브에이전트 제한

"Subagents cannot spawn other subagents." — Claude Code Docs

복잡한 체이닝이 필요하면 메인 Claude가 조율해야 해요.

체크리스트

시작하기

[ ] everything-claude-code 클론
[ ] 필요한 agents를 ~/.claude/agents/에 복사
[ ] 필요한 skills를 ~/.claude/skills/에 복사

활용하기

[ ] Planner Agent로 기능 설계
[ ] Architect Agent로 기술 스택 결정
[ ] Code Reviewer로 품질 검토
[ ] Security Reviewer로 보안 검토

고급

[ ] 프로젝트 맞춤 커스텀 Agent 생성
[ ] 팀 공유용 Skills 작성
[ ] 워크플로우 자동화 구성

마무리

Skills와 Agents는 Claude Code를 단순한 코딩 도우미에서 전문가 팀으로 업그레이드해줘요.

기억하세요:

Skills = 지식 주입 (어떻게 해야 하는지)
Agents = 작업 위임 (대신 해줘)
**everything-claude-code**에서 시작하세요
필요한 것만 설치해서 컨텍스트 절약
신뢰할 수 있는 소스만 사용

"Skills extend Claude Code with your team's expertise and workflows... Claude loads them automatically when relevant." — Anthropic

처음엔 기본 Agents로 시작하고, 점점 팀 워크플로우에 맞는 커스텀 Agents를 만들어가세요. 생산성이 완전히 달라집니다.

참고 자료

Anthropic 공식

Introducing Agent Skills — Anthropic News
Equipping Agents with Skills — Anthropic Engineering
Create Custom Subagents — Claude Code Docs
Agent Skills Overview — Claude Docs

커뮤니티

everything-claude-code — Anthropic 해커톤 우승자의 실전 configs
wshobson/agents — 108 Agents, 129 Skills 컬렉션
subagents.cc — 커뮤니티 Agent 디렉토리

Claude Code Hooks: 자동화로 실수를 원천 차단하기

MoreLean — Wed, 21 Jan 2026 00:27:13 +0900

Claude Code의 Hooks 시스템은 정말 강력합니다. 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트를 설정할 수 있어요.

파일을 편집할 때마다 자동으로 린트를 돌리거나, 위험한 명령어를 차단하거나, 하드코딩된 API 키가 있으면 경고를 띄울 수 있습니다. 한 번 설정해두면 매번 수동으로 할 필요 없이 자동으로 실행됩니다.

TL;DR

Hooks는 Claude Code의 이벤트에 반응하는 자동화 스크립트입니다
주요 이벤트: PreToolUse(도구 실행 전), PostToolUse(도구 실행 후), Stop(응답 완료)
파일 편집 후 자동 린트/포맷팅 → 코드 스타일 걱정 끝
위험한 명령어 자동 차단 → 실수 방지
하드코딩된 API 키 같은 보안 위험 감지 → 유출 사고 방지

Hooks란?

"Hooks are shell commands that execute automatically at predetermined points in Claude Code's workflow. Unlike ad-hoc model prompts, hooks guarantee that specific operations occur consistently without additional user intervention." — eesel AI

Hooks는 Claude Code가 특정 작업을 수행할 때 자동으로 실행되는 쉘 명령어입니다.

Git hooks(pre-commit, post-commit 등)와 비슷한 개념이지만, Claude Code의 도구 사용에 반응한다는 점이 다릅니다.

왜 필요한가?

Claude에게 "린트 돌려줘", "포맷팅 해줘"라고 매번 말할 수 있습니다. 하지만:

Claude가 까먹을 수 있음
매번 요청하기 귀찮음
일관성이 없음

"By encoding these rules as hooks rather than prompting instructions, you turn suggestions into app-level code that executes every time it is expected to run." — Claude Code Docs

Hooks는 **확정적(deterministic)**입니다. Claude의 판단에 의존하지 않고, 조건이 맞으면 항상 실행됩니다.

Hooks 이벤트 종류

Claude Code는 8가지 이벤트를 지원합니다:

이벤트 발생 시점 주요 용도

PreToolUse	도구 실행 전	위험한 명령 차단, 입력 검증
PostToolUse	도구 실행 후	자동 포맷팅, 린트, 테스트
PermissionRequest	권한 요청 시	특정 명령 자동 승인
UserPromptSubmit	프롬프트 제출 시	프롬프트 검증, 컨텍스트 주입
SessionStart	세션 시작 시	초기 컨텍스트 설정
SessionEnd	세션 종료 시	정리 작업, 로깅
Stop	에이전트 응답 완료	최종 검증, 알림
SubagentStop	서브에이전트 완료	서브에이전트 결과 처리

"Key events include 'PreToolUse' (before a tool runs), 'PostToolUse' (after a tool completes successfully), 'Notification' (when Claude sends an alert), 'Stop' (when the AI agent finishes its response), 'UserPromptSubmit', and 'SessionStart'." — eesel AI

가장 많이 쓰는 이벤트

PostToolUse: 파일 편집 후 자동 포맷팅/린트
PreToolUse: 위험한 명령어 차단
PermissionRequest: 자주 쓰는 명령 자동 승인

Hooks 설정 방법

Hooks는 settings.json 파일에 정의합니다:

~/.claude/settings.json          ← 사용자 전역 (모든 프로젝트)
.claude/settings.json            ← 프로젝트 공유 (Git 커밋)
.claude/settings.local.json      ← 프로젝트 로컬 (Git 제외)

기본 구조

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "도구패턴",
        "hooks": [
          {
            "type": "command",
            "command": "실행할 명령어"
          }
        ]
      }
    ]
  }
}

Matcher 패턴

"Edit": Edit 도구만 매칭
"Edit|Write": Edit 또는 Write 매칭
"Edit|Write|MultiEdit": 여러 도구 매칭
"Bash": Bash 명령 매칭
"*": 모든 도구 매칭

실전 예시 1: 자동 포맷팅

파일을 편집할 때마다 Prettier로 자동 포맷팅:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

"Automatic Formatting: Run tools like Prettier on JavaScript and TypeScript, or gofmt on Go files immediately after AI edits." — CometAPI

TypeScript 파일만 포맷팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

실전 예시 2: 자동 린트 + 포맷팅

포맷팅과 린트를 동시에 실행:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          },
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

"Multiple hooks run in parallel. Your code is formatted AND linted before Claude's response appears." — Claude Fast

React/TypeScript 프로젝트용 완전판

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATHS && eslint $CLAUDE_FILE_PATHS --fix && if [ -f 'tsconfig.json' ]; then npx tsc --noEmit; fi"
          }
        ]
      }
    ]
  }
}

실전 예시 3: 위험한 명령어 차단

rm -rf / 같은 위험한 명령어 자동 차단:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_COMMAND\" | grep -E '(rm -rf|sudo|chmod 777)' > /dev/null; then echo '❌ Dangerous command blocked' && exit 1; fi"
          }
        ]
      }
    ]
  }
}

"Security enhancements - Blocks dangerous commands and sensitive file access at multiple levels." — disler/claude-code-hooks-mastery

.env 파일 접근 차단

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -q '\\.env'; then echo '❌ .env file access blocked' && exit 1; fi"
          }
        ]
      }
    ]
  }
}

실전 예시 4: 하드코딩된 시크릿 감지

API 키나 비밀번호가 코드에 하드코딩되면 경고:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; if grep -qE '(api_key|apikey|secret|password|token)\\s*=\\s*[\"'\\'][^\"'\\']+(\"'\\']' \"$f\" 2>/dev/null; then echo '  WARNING: Possible hardcoded secret in '$f; fi; }"
          }
        ]
      }
    ]
  }
}

이건 console.log 남기는 것보다 훨씬 치명적인 실수입니다. API 키가 Git에 커밋되면:

키 유출로 인한 보안 사고
AWS 요금 폭탄
서비스 해킹

더 강력한 버전: 차단까지

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if grep -rqE '(sk-[a-zA-Z0-9]{20,}|AKIA[0-9A-Z]{16}|ghp_[a-zA-Z0-9]{36})' \"$CLAUDE_PROJECT_DIR/src\"; then echo '❌ Hardcoded API key detected! Use environment variables.' && exit 1; fi"
          }
        ]
      }
    ]
  }
}

이 패턴은 실제 API 키 형식을 감지합니다:

sk-... — OpenAI API 키
AKIA... — AWS Access Key
ghp_... — GitHub Personal Token

"Security enhancements - Blocks dangerous commands and sensitive file access at multiple levels." — disler/claude-code-hooks-mastery

실전 예시 5: 테스트 자동 실행

파일 편집 후 테스트 자동 실행:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -qE '\\.(ts|tsx|js|jsx)$'; then npm test -- --findRelatedTests \"$CLAUDE_TOOL_INPUT_FILE_PATH\" --passWithNoTests; fi"
          }
        ]
      }
    ]
  }
}

백그라운드에서 전체 테스트 실행

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test &"
          }
        ]
      }
    ]
  }
}

실전 예시 6: 자주 쓰는 명령 자동 승인

npm test 매번 승인하기 귀찮다면:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash(npm test*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"decision\": \"approve\"}'"
          }
        ]
      }
    ]
  }
}

"Tired of approving npm test every time? Use PermissionRequest." — Claude Fast

린트와 빌드 명령도 자동 승인

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash(npm run lint*)|Bash(npm run build*)|Bash(npm test*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"decision\": \"approve\"}'"
          }
        ]
      }
    ]
  }
}

실전 예시 7: 세션 시작 시 컨텍스트 주입

세션 시작할 때 Git 상태와 TODO 목록 자동 표시:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '## Current State' && git status --short && echo '## Active TODOs' && grep -r 'TODO:' src/ --include='*.ts' | head -5"
          }
        ]
      }
    ]
  }
}

"Claude now sees uncommitted changes and pending TODOs before you say anything." — Claude Fast

환경 변수

Hooks에서 사용 가능한 환경 변수:

변수 설명

$CLAUDE_PROJECT_DIR	프로젝트 루트 경로
$CLAUDE_FILE_PATHS	작업 대상 파일 경로
$CLAUDE_TOOL_NAME	사용된 도구 이름
$CLAUDE_TOOL_INPUT_FILE_PATH	도구 입력 파일 경로
$CLAUDE_WORKING_DIR	현재 작업 디렉토리
$CLAUDE_SESSION_ID	세션 ID

완전한 설정 예시

프로덕션에서 쓸 수 있는 종합 설정:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_COMMAND\" | grep -E '(rm -rf /|sudo rm|chmod 777)' > /dev/null; then echo '❌ Dangerous command blocked' && exit 1; fi"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [ \"$(git branch --show-current)\" = 'main' ]; then echo '❌ Cannot edit on main branch' && exit 1; fi"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
          },
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "Bash(npm test*)|Bash(npm run lint*)|Bash(pnpm test*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"decision\": \"approve\"}'"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '  Branch:' $(git branch --show-current) && echo '  Status:' && git status --short | head -5"
          }
        ]
      }
    ]
  }
}

주의사항

보안

"You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials." — Claude Code Docs

Hooks는 당신의 권한으로 실행됩니다
악의적인 hooks는 데이터를 유출할 수 있습니다
항상 hooks 코드를 검토하세요

성능

너무 많은 hooks는 속도를 늦춥니다
무거운 작업은 백그라운드로 (& 사용)
불필요하게 넓은 matcher 피하기

"If hooks are unnecessarily firing you will have an extremely slowed down Agent." — ClaudeLog

디버깅

# Hook 설정 확인
cat .claude/settings.json | jq '.hooks'

# 수동으로 명령어 테스트
npx prettier --write test.ts

# 환경 변수 확인
echo $CLAUDE_PROJECT_DIR

Git Hooks와의 차이점

구분 Claude Code Hooks Git Hooks

트리거	Claude 도구 사용 시	Git 명령 실행 시
이벤트	PreToolUse, PostToolUse 등	pre-commit, post-commit 등
목적	Claude 작업 자동화	Git 워크플로우 자동화
설정 위치	.claude/settings.json	.git/hooks/

둘 다 사용하면 더 강력합니다:

Claude Code Hooks: 파일 편집 시 즉시 포맷팅
Git Hooks: 커밋 전 최종 검증

체크리스트

기본 설정

[ ] 자동 포맷팅 (PostToolUse + Prettier)
[ ] 자동 린트 (PostToolUse + ESLint)
[ ] 위험 명령어 차단 (PreToolUse)

권장 설정

[ ] console.log 감지
[ ] main 브랜치 직접 편집 차단
[ ] 자주 쓰는 명령 자동 승인 (PermissionRequest)

고급 설정

[ ] 세션 시작 시 컨텍스트 주입
[ ] 테스트 자동 실행
[ ] 커스텀 검증 스크립트

마무리

Hooks는 Claude Code를 당신의 워크플로우에 맞게 커스터마이징하는 강력한 도구입니다.

기억하세요:

한 번 설정하면 매번 자동 실행
포맷팅, 린트는 PostToolUse로
위험한 명령 차단은 PreToolUse로
자주 쓰는 명령 승인은 PermissionRequest로
성능과 보안을 항상 고려하세요

"Hooks let you shape Claude Code to match your workflow rather than adapting your workflow to the tool." — Claude Blog

설정하는 데 10분이면 됩니다. 그 10분이 앞으로 수많은 실수를 방지하고, 반복 작업을 자동화해줄 겁니다.

참고 자료

Anthropic 공식

Get Started with Claude Code Hooks — Official Docs
Hooks Reference — Official Docs
How to Configure Hooks — Claude Blog

커뮤니티

Claude Code 환경 설정: CLAUDE.md로 10분 투자해서 수 시간 절약하기

MoreLean — Wed, 21 Jan 2026 00:12:07 +0900

Claude Code 환경 설정에서 제일 먼저 해야 할 건 CLAUDE.md 파일 만들기입니다.

이 파일은 프로젝트 루트에 두는 일종의 설명서입니다. "이 프로젝트는 뭐고, 어떤 규칙으로 코딩하고, 파일 구조는 어떻고" 다 적어두는 거예요. Claude Code가 작업 시작할 때마다 이 파일을 먼저 읽습니다. 그러면 매번 같은 설명 안 해도 됩니다.

처음 세팅하는 데 10분 걸리지만, 이후에 몇 시간씩 절약됩니다.

TL;DR

CLAUDE.md는 Claude Code의 **"헌법"**이자 영구 기억 장치입니다
매 세션 시작 시 자동으로 로드됩니다
300줄 미만, 짧을수록 좋습니다
포함할 것: 프로젝트 개요, 기술 스택, 코딩 컨벤션, 주요 명령어, 금지 사항
/init 명령으로 시작하고, 점진적으로 다듬어가세요

CLAUDE.md란?

"The single most important file in your codebase for using Claude Code effectively is the root CLAUDE.md. This file is the agent's 'constitution,' its primary source of truth for how your specific repository works." — Shrivu Shankar

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 특별한 파일입니다. 프로젝트에 대한 모든 컨텍스트를 여기에 적어두면, 매번 같은 설명을 반복할 필요가 없습니다.

왜 필요한가?

"Coding agents know absolutely nothing about your codebase at the beginning of each session. The agent must be told anything that's important to know about your codebase each time you start a session. CLAUDE.md is the preferred way of doing this." — HumanLayer Blog

Claude Code는 상태가 없는(stateless) 도구입니다. 매 세션마다 당신의 코드베이스에 대해 아무것도 모릅니다. CLAUDE.md가 없으면:

매번 "이 프로젝트는 React + TypeScript야" 설명해야 함
코딩 컨벤션을 반복해서 알려줘야 함
테스트 명령어를 매번 가르쳐야 함
실수로 건드리면 안 되는 파일을 건드림

CLAUDE.md 위치와 계층 구조

Claude Code는 여러 위치의 CLAUDE.md를 계층적으로 읽습니다:

우선순위 (높음 → 낮음)
─────────────────────────────────────────────────
1. .claude/CLAUDE.md      ← 프로젝트 (.claude 폴더 내)
2. ./CLAUDE.md            ← 프로젝트 루트
3. ~/.claude/CLAUDE.md    ← 사용자 (모든 프로젝트에 적용)
4. 하위 디렉토리 CLAUDE.md ← 해당 디렉토리 작업 시만 로드
─────────────────────────────────────────────────

"Claude Code reads information from CLAUDE.md files in a hierarchical order: first from your home directory (~/.claude/CLAUDE.md), then from your project root, and finally from individual directories." — Dinanjana Gunaratne

각 위치의 용도

위치 용도 Git 커밋

~/.claude/CLAUDE.md	개인 환경설정 (모든 프로젝트)	❌
./CLAUDE.md	팀 공유 프로젝트 설정	✅
.claude/CLAUDE.md	팀 공유 (폴더 정리 선호 시)	✅
./CLAUDE.local.md	개인 설정 (Git 제외)	❌
src/api/CLAUDE.md	특정 디렉토리 전용 규칙	✅

추가 규칙 파일

.claude/rules/ 폴더에 여러 마크다운 파일을 넣으면 자동으로 로드됩니다:

.claude/
├── rules/
│   ├── code-style.md      ← 프론트엔드 팀 관리
│   ├── security.md        ← 보안 팀 관리
│   └── testing.md         ← QA 팀 관리
└── CLAUDE.md              ← 핵심 설정

"All markdown files in .claude/rules/ are automatically loaded with the same priority as your main CLAUDE.md. No imports needed." — Builder.io

CLAUDE.md에 넣어야 할 것

WHAT, WHY, HOW 프레임워크

"At a high level, CLAUDE.md should cover:

WHAT: Tell Claude about the tech, your stack, the project structure

WHY: Tell Claude the purpose of the project

HOW: Tell Claude how it should work on the project" — HumanLayer Blog

필수 포함 항목

프로젝트 개요: 한 줄로 프로젝트 설명
기술 스택: 프레임워크, 언어, 주요 라이브러리
디렉토리 구조: 핵심 폴더와 역할
주요 명령어: 빌드, 테스트, 린트, 배포
코딩 컨벤션: 스타일 가이드, 네이밍 규칙
금지 사항: 절대 건드리면 안 되는 것들

예시: Next.js 프로젝트

# Project: ShopFront

Next.js 14 e-commerce application with App Router, Stripe payments, and Prisma ORM.

## Tech Stack
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript (strict mode)
- **Database**: PostgreSQL + Prisma
- **Auth**: NextAuth.js
- **Payments**: Stripe
- **Styling**: Tailwind CSS

## Directory Structure
- `app/` - Next.js App Router pages and layouts
- `components/` - Reusable React components
- `lib/` - Utility functions and shared logic
- `prisma/` - Database schema and migrations
- `public/` - Static assets

## Commands
- `pnpm dev` - Start development server
- `pnpm build` - Production build
- `pnpm test` - Run tests (Jest)
- `pnpm lint` - ESLint check
- `pnpm db:migrate` - Run Prisma migrations
- `pnpm db:studio` - Open Prisma Studio

## Code Style
- Use ES modules (import/export)
- 2-space indentation
- Single quotes for strings
- No semicolons (Prettier handles it)
- Prefer interfaces over types
- No `any` - use `unknown` instead

## IMPORTANT RULES
- NEVER leave console.log in production code
- NEVER commit .env files
- NEVER modify files in `generated/` directory
- Always run `pnpm lint` before committing
- All API routes must have error handling

## Testing
- Unit tests: `__tests__/` folders next to source
- E2E tests: `e2e/` folder with Playwright
- Minimum 80% coverage for new code

/init으로 시작하기

처음부터 직접 작성할 필요 없습니다. /init 명령으로 자동 생성할 수 있습니다:

cd your-project
claude
> /init

Claude가 프로젝트를 분석해서 기본 CLAUDE.md를 생성합니다.

"Run it in your project directory and Claude generates a starter CLAUDE.md based on your project structure and detected tech stack. I use /init as a starting point and delete what I don't need. Deleting is easier than creating from scratch." — Builder.io

/init 후 해야 할 것

불필요한 내용 삭제: 뻔한 것들 제거
누락된 내용 추가: 팀 컨벤션, 워크플로우
금지 사항 명시: "절대 하지 마" 규칙들
Git 커밋: 팀과 공유

"The generated file often includes obvious things you don't need spelled out, or filler that doesn't add value. Because context is precious. Every line in your CLAUDE.md competes for attention with the actual work you're asking Claude to do." — Builder.io

짧게 유지하기: Less is More

300줄 미만 권장

"While Anthropic does not have an official recommendation on how long your CLAUDE.md file should be, general consensus is that < 300 lines is best, and shorter is even better. At HumanLayer, our root CLAUDE.md file is less than sixty lines." — HumanLayer Blog

왜 짧아야 하나?

컨텍스트 경쟁: CLAUDE.md도 컨텍스트 윈도우를 차지함
주의력 분산: 내용이 많으면 중요한 것을 놓침
무시 가능성: 관련 없는 내용이 많으면 Claude가 무시함

"The more information you have in the file that's not universally applicable to the tasks you have it working on, the more likely it is that Claude will ignore your instructions in the file." — HumanLayer Blog

Progressive Disclosure 원칙

모든 걸 CLAUDE.md에 넣지 마세요. 필요할 때 찾아보게 하세요:

## Database Migrations
For complex migration patterns, see `docs/migrations.md`.
Run `pnpm db:migrate --help` for available options.

## API Documentation
Full API spec at `docs/api/openapi.yaml`.
Use Swagger UI: `pnpm docs:api`

"Don't tell Claude all the information you could possibly want it to know. Rather, tell it how to find important information so that it can find and use it, but only when it needs to." — HumanLayer Blog

규칙 강조하기

중요한 규칙은 강조해야 Claude가 잘 따릅니다:

## CRITICAL RULES (DO NOT IGNORE)

⛔ **NEVER** leave console.log in production code
⛔ **NEVER** commit API keys or secrets
⛔ **NEVER** modify files in `generated/` directory
⛔ **NEVER** skip error handling in API routes

✅ **ALWAYS** run tests before committing
✅ **ALWAYS** use TypeScript strict mode
✅ **ALWAYS** handle loading and error states in components

"Add emphasis (e.g., 'IMPORTANT,' 'YOU MUST') to improve Claude's adherence to critical instructions." — Steve Kinney

실제 효과

저는 CLAUDE.md에 "절대 console.log 남기지 마" 같은 규칙을 박아뒀어요. 그랬더니 Claude Code가 알아서 지켜주더라고요. 디버깅용 로그를 넣었다가도 마지막에 자동으로 제거합니다.

# 키로 빠르게 추가하기

세션 중에 규칙을 추가하고 싶다면 **#**으로 시작하면 됩니다:

# Never use deprecated lodash methods
# Prefer native array methods over lodash when possible

이렇게 입력하면 CLAUDE.md에 자동으로 추가됩니다.

"The fastest way to add a memory during a session is by starting your input with the # character." — Steve Kinney

실전 CLAUDE.md 예시

최소 버전 (스타트업 프로젝트)

# Ttokseo (똑서) - 어린이 디지털 독서 플랫폼

React Native + Kotlin/Spring Boot 기반 구독형 교육 서비스.

## Commands
- Mobile: `cd mobile && pnpm start`
- Backend: `cd backend && ./gradlew bootRun`
- Tests: `pnpm test` / `./gradlew test`

## Key Rules
- Korean comments for business logic
- All API responses must include `success`, `data`, `error` fields
- UTC timestamps in DB, KST conversion in frontend
- Never commit .env files

상세 버전 (팀 프로젝트)

# Project: Enterprise Dashboard

Internal analytics dashboard for sales team.
React 18 + TypeScript + GraphQL + PostgreSQL.

## Quick Start
1. `pnpm install`
2. `cp .env.example .env.local`
3. `pnpm db:migrate`
4. `pnpm dev`

## Architecture
- `src/features/` - Feature-based modules (sales, users, reports)
- `src/shared/` - Shared components, hooks, utilities
- `src/graphql/` - GraphQL schema and resolvers
- `prisma/` - Database schema

## Code Standards
- Feature-first folder structure
- Colocation: tests, styles, types next to components
- No barrel exports (index.ts re-exports)
- Prefer server components, client only when needed

## GraphQL Conventions
- Queries: `use{Resource}Query` (e.g., `useSalesQuery`)
- Mutations: `use{Action}{Resource}Mutation` (e.g., `useCreateOrderMutation`)
- Always handle loading, error, data states

## Testing
- Unit: Jest + React Testing Library
- E2E: Playwright
- Run `pnpm test:coverage` before PR

## IMPORTANT
- This dashboard contains sensitive sales data
- Never log PII (names, emails, phone numbers)
- All API calls must go through auth middleware
- Check `docs/security.md` before adding new endpoints

CLAUDE.md vs CLAUDE.local.md

구분 CLAUDE.md CLAUDE.local.md

용도	팀 공유 설정	개인 환경설정
Git	✅ 커밋	❌ gitignore
내용	프로젝트 규칙, 컨벤션	개인 선호, 실험

# CLAUDE.local.md (개인용)

## My Preferences
- I prefer verbose explanations
- Always show full file paths in responses
- Use Korean for comments

## Current Focus
Working on payment integration this week.
Key files: `src/features/payment/`

## Experiments
Testing new caching strategy - see `docs/cache-experiment.md`

CLAUDE.md 유지보수

CLAUDE.md는 살아있는 문서입니다. 프로젝트와 함께 진화해야 합니다.

업데이트 시점

새로운 주요 의존성 추가 시
아키텍처 패턴 변경 시
디렉토리 구조 변경 시
새로운 환경 변수 추가 시
Claude가 반복적으로 실수하는 패턴 발견 시

"Treat customization as an ongoing practice rather than a one-time setup task. Projects change, teams learn better patterns, and new tools enter your workflow. A well-maintained CLAUDE.md evolves with your codebase." — Claude Blog

안티패턴

❌ 모든 명령어 나열: 필요한 것만 ❌ 모든 파일 경로 나열: 핵심 디렉토리만 ❌ 일반적인 조언: 프로젝트 특화된 것만 ❌ 한 번 만들고 방치: 지속적 업데이트 필요

"Don't try to stuff every command Claude could possibly need to run in your CLAUDE.md file - you will get sub-optimal results." — HumanLayer Blog

체크리스트

초기 설정

[ ] /init으로 기본 파일 생성
[ ] 불필요한 내용 삭제
[ ] 프로젝트 개요 추가
[ ] 핵심 명령어 추가
[ ] 금지 사항 명시 (IMPORTANT 강조)
[ ] Git 커밋

지속적 관리

[ ] Claude가 반복 실수하면 규칙 추가
[ ] 새 패턴/도구 도입 시 업데이트
[ ] 300줄 미만 유지
[ ] 팀원과 주기적 리뷰

고급 설정

[ ] ~/.claude/CLAUDE.md로 개인 전역 설정
[ ] .claude/rules/로 모듈화 (대규모 팀)
[ ] CLAUDE.local.md로 개인 실험

마무리

CLAUDE.md는 Claude Code의 가장 높은 레버리지 포인트입니다.

기억하세요:

10분 투자로 수 시간 절약
짧게 유지 (300줄 미만, 짧을수록 좋음)
핵심만 포함 (WHAT, WHY, HOW)
금지 사항은 강하게 강조
지속적으로 업데이트

"The more thought put into Claude.md files, the better Claude Code performs." — Anthropic: How Anthropic teams use Claude Code

프로젝트에 처음 Claude Code를 도입한다면, 오늘 바로 CLAUDE.md를 만드세요. 10분이면 됩니다. 그 10분이 앞으로 수십 시간을 절약해줄 겁니다.

참고 자료

Anthropic 공식

Using CLAUDE.md Files — Claude Blog
Claude Code Best Practices — Anthropic Engineering
Claude Code Settings — Official Docs

커뮤니티

Writing a Good CLAUDE.md — HumanLayer Blog
The Complete Guide to CLAUDE.md — Builder.io
How I Use Every Claude Code Feature — Shrivu Shankar
CLAUDE.md Guide — Steve Kinney

Claude Code 컨텍스트 관리: 채워질수록 썩는 작업 기억

MoreLean — Tue, 20 Jan 2026 23:48:45 +0900

Claude Code를 잘 쓰는 사람과 못 쓰는 사람을 나누는 결정적 차이가 있습니다. 프롬프트 스킬도 아니고, 모델 선택도 아닙니다. 바로 컨텍스트 관리입니다.

컨텍스트는 컴퓨터의 RAM과 같습니다. 95%까지 채울 수 있지만, 그 마지막 5%는 스와핑과 가비지 컬렉션에 소모되어 실제 작업 공간이 없어집니다. Claude Code도 마찬가지입니다. 대화가 길어지면 초반 내용을 까먹거나 헷갈리기 시작합니다.

이 글에서는 왜 이런 일이 발생하고, 어떻게 관리해야 하는지, 그리고 리셋 전에 꼭 해야 할 것까지 정리합니다.

TL;DR

컨텍스트 윈도우는 Claude의 **작업 기억(Working Memory)**입니다
200k 토큰이 한계지만, 80~100k만 넘어도 품질이 떨어집니다
3~5개 작업마다 또는 100k 토큰 전에 리셋하세요
리셋 전에 HANDOFF.md 파일을 꼭 만들어두세요
/compact 3번 후 /clear하는 패턴을 추천합니다

Anthropic 공식 권장사항

이건 "개인 경험담"이 아닙니다. Anthropic이 공식 블로그에서 명시적으로 권장하는 내용입니다.

"During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands. This can reduce performance and sometimes distract Claude. Use the /clear command frequently between tasks to reset the context window." — Anthropic Engineering Blog: Claude Code Best Practices

핵심:

긴 세션에서 컨텍스트가 불필요한 내용으로 채워집니다
이로 인해 성능이 저하되고 Claude가 산만해집니다
작업 사이에 /clear를 자주 사용하세요

왜 성능이 떨어지나?

Context Rot: 채워질수록 썩는다

Chroma의 연구에서 "Context Rot"라는 개념이 제시되었습니다. 컨텍스트 윈도우가 채워질수록 작업 난이도와 무관하게 성능이 떨어집니다.

"Research consistently shows that optimizing Claude's context window in 2025 involves context quality over quantity, with performance degrading substantially as models approach their limits." — Hyperdev

"LLM accuracy declines as the context window fills past 50%... effective context windows are probably 50-60% or even lesser." — Sankalp's Blog

RAM 비유: 왜 여유 공간이 필요한가

"Think of it like RAM on your computer. Sure, you can run programs until you hit 95% memory utilization. But that last 5% gets consumed by swapping, garbage collection, and system overhead—leaving nothing for actual computation. Your programs slow to a crawl despite having 'only' 95% utilization. LLMs work similarly. That 'free' context space isn't wasted—it's where reasoning happens." — Hyperdev

실제 증상

컨텍스트가 오염되면 이런 현상이 나타납니다:

초반 지시를 잊어버림: "아까 말한 컨벤션 왜 안 지켜?"
자기 모순: 방금 전 결정과 반대로 행동
환각(Hallucination): 없는 함수나 파일을 참조
품질 저하: 갑자기 코드가 엉성해짐
응답 속도 저하: 눈에 띄게 느려짐

"The pattern was frustrating: you'd be deep into a complex refactoring, making steady progress, then suddenly Claude Code would struggle. Responses would become generic, previous decisions would be forgotten, and code quality would noticeably degrade." — Hyperdev

200k 토큰인데 왜 100k에서 리셋하나?

이론적으로 Claude Code는 200k 토큰까지 쓸 수 있습니다. 하지만 실전에서는 80~100k만 넘어가도 품질이 떨어지기 시작합니다.

실제 사용 가능 공간

200k 전체를 대화에 쓸 수 있는 게 아닙니다:

┌─────────────────────────────────────────────────────┐
│  컨텍스트 윈도우 (200K 토큰)                             │
├─────────────────────────────────────────────────────┤
│  시스템 프롬프트 + 도구: ~15K                            │
│  MCP 도구 정의: 가변 (수천~수만)                         │
│  Auto-compact 예약: ~45K (22.5%)                     │
│  ─────────────────────────────────────              │
│  실제 대화/코드: ~140K (이론상)                          │
│  유효 작업 공간: ~100K (현실적)                          │
└─────────────────────────────────────────────────────┘

"Auto-compact is a feature that quietly consumes a massive amount of your context window before you even start coding, with some reports showing the autocompact buffer consuming 45k tokens—22.5% of your context window gone before writing a single line of code." — Hyperdev

75% 규칙

Claude Code는 내부적으로 75% 사용량에서 auto-compact를 트리거합니다. 이는 25%(50k 토큰)를 추론 공간으로 남겨두기 위함입니다.

"If Claude Code is indeed triggering compaction at 75% utilization rather than 90%+, that leaves 25% of the context window (50k tokens in a 200k window) free for reasoning." — Hyperdev

결론: 100k를 넘기 전에 리셋하는 게 시간 절약입니다. 아깝게 느껴져도 이게 결국 더 효율적입니다.

컨텍스트 관리 명령어: /compact vs /clear

/compact — 요약 압축

/compact

대화 기록을 요약해서 압축합니다. 핵심 결정사항은 보존하면서 토큰만 줄입니다.

특징:

작업 흐름이 끊기지 않음
중요한 정보는 유지
하지만 미묘한 컨텍스트가 손실될 수 있음

"Compacting is distinct from the /clear command. While /clear completely wipes out the chat history and starts a brand new conversation from scratch, /compact summarizes the conversation and preserves the essential nuances and key information." — Steve Kinney

사용 시점:

같은 작업을 계속하지만 컨텍스트가 70-85% 찼을 때
이전 결정사항을 유지하고 싶을 때

/clear — 완전 초기화

/clear

모든 대화 기록을 삭제하고 완전히 새로운 세션을 시작합니다.

특징:

깨끗한 상태로 시작
모든 컨텍스트 손실
HANDOFF.md 없으면 위험

"Pro tip: use /clear often. Every time you start something new, clear the chat. You don't need all that history eating your tokens, and you definitely don't need Claude running compaction calls to summarize old conversations." — Builder.io

사용 시점:

작업 완료 후 다른 작업으로 전환할 때
Claude가 이상하게 행동하거나 루프에 빠졌을 때
컨텍스트가 90% 이상 찼을 때
대화가 완전히 엉뚱한 방향으로 갔을 때

언제 뭘 쓸까?

상황 명령어 이유

컨텍스트 70-85%, 같은 작업 계속	/compact	결정사항 보존
컨텍스트 90%+, 작업 전환	/clear	깨끗한 시작
Claude가 루프에 빠짐	/clear	오염된 컨텍스트 제거
이전 컨텍스트 50% 미만 관련	/clear	불필요한 정보 제거

"Use /compact when: Context 70-85%, same task continues, need to preserve decisions. Use /clear when: Context 90%+, task complete, switching context, conversation went off-track, context poisoning." — DeepWiki

추천 패턴: /compact 3번 후 /clear

제가 쓰는 패턴입니다:

작업 1-2: 자유롭게 작업
──────────────────────
[/compact] ← 70% 도달
──────────────────────
작업 3-4: 계속 작업
──────────────────────
[/compact] ← 다시 70% 도달
──────────────────────
작업 5: 계속 작업
──────────────────────
[/compact] ← 세 번째
──────────────────────
[HANDOFF.md 생성]
[/clear] ← 완전 리셋
──────────────────────
새 세션: HANDOFF.md 읽고 시작

왜 이 패턴인가?

"Compaction, we found, encourages long, meandering threads, in which you just compact once you run out of context window, stacking summary on top of summary. What we want to encourage are focused threads, because we think that's how agents yield the best results." — Amp

/compact를 반복하면 "요약의 요약"이 쌓이면서 정보가 점점 손실됩니다. 3번 정도 후에는 /clear로 깨끗하게 시작하는 게 좋습니다.

HANDOFF.md: 리셋 전에 꼭 만들어야 할 파일

컨텍스트를 리셋하기 전에 꼭 해야 할 일이 있습니다. HANDOFF.md 파일 만들기입니다.

왜 필요한가?

"AI sessions have limited context. When you switch tools, take a break, or hit a context limit, the next agent starts from scratch. Handoffs solve this by capturing: What you're trying to do, what's done, what's not, what failed (so the next agent doesn't repeat mistakes), key decisions and their rationale, exactly how to continue." — willseltzer/claude-handoff

HANDOFF.md 없이 /clear하면:

2시간치 작업 흐름을 다시 설명해야 함
이전에 실패한 접근법을 또 시도함
이미 내린 결정을 다시 논의함

"Creating a handoff takes 2-3 minutes. Re-establishing context without one takes 10-15 minutes. Every session." — DEV Community

HANDOFF.md 템플릿

# Handoff: [작업 제목]

**생성일**: 2026-01-20 14:30
**브랜치**: feature/user-auth
**상태**: 진행 중

## 목표
OAuth2를 이용한 사용자 인증 추가

## 완료된 작업
- [x] OAuth2 provider 설정
- [x] 로그인 엔드포인트 생성
- [x] JWT 토큰 발급 로직

## 남은 작업
- [ ] 토큰 갱신 로직 추가
- [ ] 로그아웃 처리
- [ ] 테스트 작성

## 실패한 접근법 (다시 시도하지 말 것!)
passport.js를 먼저 시도했으나 Express 미들웨어와 충돌.
`req.user`가 항상 undefined였음 - passport의 세션 미들웨어가
우리 커스텀 auth 체크 후에 실행되기 때문.
→ oauth4webapi로 전환 (fetch와 직접 작동, Express 건드리지 않음)

## 주요 결정사항
| 결정 | 이유 |
|------|------|
| passport 대신 oauth4webapi | 더 가볍고 미들웨어 충돌 없음 |
| refresh token은 httpOnly 쿠키에 저장 | localStorage보다 보안상 유리 |

## 현재 상태
**작동함**: 로그인 플로우에서 유효한 토큰 반환
**문제 있음**: /api/auth/refresh에서 500 에러 - `TokenExpiredError`

## 재개 지침
1. refresh.ts:42의 JWT verify 호출이 잘못된 시크릿 사용 중 - 수정 필요
2. 로그아웃: httpOnly 쿠키 클리어, POST /api/auth/logout
3. 전체 플로우 테스트 후 PR 생성

핵심 포인트

"Failed approaches are mandatory - This is the most valuable part. 'Tried X, it didn't work because Y' saves hours." — willseltzer/claude-handoff

HANDOFF.md에서 가장 중요한 부분은 **"실패한 접근법"**입니다. 이게 없으면 새 세션에서 같은 실수를 반복합니다.

/handoff 커맨드 만들기

매번 수동으로 작성하기 번거롭다면, 커스텀 커맨드를 만들 수 있습니다:

<!-- .claude/commands/handoff.md -->
Write or update a handoff document so the next agent with fresh 
context can continue this work.

Include:
1. Goal and current progress
2. What worked and what didn't (with specific error messages)
3. Key decisions and their rationale
4. Current blockers or issues
5. Specific next steps

Save as HANDOFF.md in the project root.

"The way I do this is to ask Claude to write a handoff document before starting fresh. Something like: 'Put the rest of the plan in the HANDOFF.md. Explain what you have tried, what worked, what didn't work, so that the next agent with fresh context is able to just load that file and nothing else to get started.'" — ykdojo/claude-code-tips

/compact vs HANDOFF.md: 뭐가 다른가?

둘 다 컨텍스트를 보존하는 방법이지만 용도가 다릅니다:

구분 /compact HANDOFF.md

범위	세션 내 연속성	세션 간 연속성
저장 위치	컨텍스트 안 (휘발성)	파일 (영구)
제어권	Claude가 요약	내가 검토 가능
손실	요약 과정에서 손실 가능	명시적으로 기록한 것만 보존

"Compacting is for within-session continuity. It summarizes to free up context space so you can keep working. Handoffs are for cross-session continuity. They're explicit documentation of what matters, in a format you control and can search." — DEV Community

Best Practice: 둘 다 사용하세요. /compact로 세션 내 연속성을 유지하고, /clear 전에는 HANDOFF.md로 세션 간 연속성을 확보하세요.

컨텍스트 사용량 기준

사용량 상태 권장 조치

0-50%	양호	자유롭게 작업
50-70%	주의	모니터링, HANDOFF.md 준비
70-85%	경고	/compact 실행
85-95%	위험	HANDOFF.md 작성 → /clear
95%+	⛔ 한계	즉시 /clear (데이터 손실 위험)

"I would do a handoff or compact when I reach total 60% if building something complex." — Sankalp's Blog

실전 워크플로우

패턴 1: 일반 작업

1. /context로 상태 확인
2. 작업 진행
3. 70% 도달 → /compact
4. 계속 작업
5. 다시 70% 또는 작업 전환 시점
   → HANDOFF.md 작성
   → /clear
6. 새 세션에서 @HANDOFF.md로 시작

패턴 2: 복잡한 장기 작업

1. Plan Mode로 계획 수립
2. 계획을 PLAN.md로 저장
3. /clear
4. @PLAN.md 읽고 1단계부터 실행
5. 각 단계 완료 시 PLAN.md 업데이트
6. 70% 도달 시마다:
   - HANDOFF.md 작성 (현재 진행 상황)
   - /clear
   - @PLAN.md + @HANDOFF.md로 재개

"Often when the context window starts getting full or I feel the model is struggling with a complex task, I want to start a new conversation using /clear. I prefer to make Claude write what happened in current session before I kill it and start a new one." — Sankalp's Blog

CLAUDE.md vs HANDOFF.md

두 파일의 역할이 다릅니다:

구분 CLAUDE.md HANDOFF.md

성격	프로젝트 상수	세션 상태
수명	프로젝트 전체	한 작업 사이클
내용	코드 스타일, 빌드 명령, 아키텍처	진행 상황, 실패한 시도, 다음 단계
로딩	자동 (매 세션)	수동 (@로 참조)

# CLAUDE.md (프로젝트 상수)
- 기술 스택: React + Node.js + PostgreSQL
- 코드 스타일: 2-space indent, snake_case API
- 빌드 명령: pnpm dev, pnpm test

# HANDOFF.md (현재 작업 상태)
- 목표: OAuth2 인증 추가
- 완료: 로그인 엔드포인트
- 실패한 시도: passport.js (미들웨어 충돌)
- 다음 단계: 토큰 갱신 로직

체크리스트

세션 시작 시

[ ] /context로 초기 사용량 확인
[ ] HANDOFF.md가 있다면 @로 참조
[ ] 불필요한 MCP 서버 비활성화

세션 진행 중

[ ] 70% 도달하면 /compact 또는 HANDOFF.md 준비
[ ] 100k 토큰 전에 리셋 고려
[ ] Claude가 이상하게 행동하면 즉시 /clear

리셋 전

[ ] ⚠️ HANDOFF.md 작성 (가장 중요!)
[ ] 실패한 접근법 명시
[ ] 다음 단계 구체적으로 기록
[ ] /clear 실행

새 세션 시작

[ ] @HANDOFF.md로 컨텍스트 복원
[ ] "이 파일 읽고 이어서 진행해줘"

마무리

컨텍스트 관리는 Claude Code의 숨겨진 핵심 스킬입니다.

기억하세요:

컨텍스트는 채워질수록 썩습니다 (Context Rot)
200k가 한계지만 100k 전에 리셋하는 게 현명합니다
/compact 3번 후 /clear 패턴을 추천합니다
/clear 전에 HANDOFF.md는 필수입니다
HANDOFF.md에서 **"실패한 접근법"**이 가장 중요합니다

Claude Code가 갑자기 이상해졌다고 느낄 때, 그건 Claude의 문제가 아닙니다. 컨텍스트가 오염된 것입니다. HANDOFF.md 작성하고 /clear 한 번이면 해결됩니다.

참고 자료

Anthropic 공식

Claude Code Best Practices — Anthropic Engineering Blog
Effective Context Engineering for AI Agents — Anthropic Engineering Blog

커뮤니티

How I Use Every Claude Code Feature — Shrivu Shankar
Claude Code: Keep the Context Clean — Arthur
How Claude Code Got Better by Protecting More Context — Hyperdev
Session Handoffs: Giving Your AI Assistant Memory That Actually Persists — DEV Community
willseltzer/claude-handoff — GitHub
ykdojo/claude-code-tips — GitHub

연구

Context Rot — Chroma Research

Claude Code의 게임체인저: Plan Mode vs YOLO Mode

MoreLean — Tue, 20 Jan 2026 23:37:08 +0900

Claude Code를 쓰다 보면 두 가지 극단 사이에서 고민하게 됩니다. "매번 허락 받는 게 너무 느려" vs "그냥 다 실행했다가 망하면 어떡해". Anthropic은 이 문제를 해결하기 위해 세 가지 Permission Mode를 제공합니다. 이 글에서는 각 모드의 특징과 언제 어떤 모드를 써야 하는지 정리합니다.

TL;DR

Shift+Tab으로 세 가지 모드를 순환할 수 있습니다
Plan Mode: 읽기 전용, 계획만 세움 → 복잡한 작업에 최적
Auto-Accept Mode: 자동 승인 → 신뢰할 수 있는 반복 작업에 최적
YOLO Mode (--dangerously-skip-permissions): 완전 자율 → 컨테이너 환경에서만 사용
복잡한 작업은 Plan Mode로 시작하고, 계획 확정 후 실행하세요

세 가지 Permission Mode

Claude Code는 Shift+Tab을 누를 때마다 다음 모드로 순환합니다:

Normal Mode → Auto-Accept Mode → Plan Mode → Normal Mode → ...

"Pressing shift+tab cycles through Claude Code's permission modes: normal-mode, auto-accept edit on, and plan mode on." — ClaudeLog: Auto-Accept Permissions

모드 표시 특징

Normal Mode	(기본)	모든 작업에 승인 필요
Auto-Accept Mode	⏵⏵ accept edits on	파일 수정, 명령 실행 자동 승인
Plan Mode	⏸ plan mode on	읽기 전용, 계획만 세움

Plan Mode: 생각 먼저, 실행은 나중에

공식 정의

"Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely." — Anthropic Docs: Common Workflows

작동 방식

Plan Mode에서 Claude가 사용할 수 있는 도구:

허용됨 (읽기 전용) 차단됨 (수정)

Read, LS, Glob, Grep	Edit, MultiEdit
WebSearch, WebFetch	Bash (수정 명령)
Task (리서치 에이전트)	Write
NotebookRead	-

실제 사용법

# 방법 1: 세션 중 활성화
Shift+Tab 두 번 누르기

# 방법 2: 시작할 때 활성화
claude --permission-mode plan

# 방법 3: 헤드리스 쿼리
claude -p "인증 시스템 리팩토링 계획 세워줘" --permission-mode plan

왜 게임체인저인가?

일반 모드:
"이커머스 사이트 만들어줘" 
→ Claude가 바로 코드 작성 시작 
→ 방향이 틀려도 끝까지 감 
→ 롤백하고 처음부터 다시

Plan Mode:
"이커머스 사이트 만들어줘"
→ Claude가 전체 계획 제시
→ 각 단계 검토 및 수정
→ 승인 후 실행
→ 방향 수정이 쉬움

"Plan Mode forces Claude to generate a full step-by-step plan before touching any code." — Towards Dev: Mastering Plan Mode

언제 사용하나?

다중 파일 수정: 여러 파일에 걸친 기능 구현
코드베이스 탐색: 새로운 프로젝트 파악
아키텍처 결정: 큰 방향성 논의
위험한 리팩토링: 실수하면 안 되는 작업

Auto-Accept Mode: 빠른 실행

공식 정의

"Auto-accept mode eliminates permission prompts for configured tools, enabling uninterrupted execution." — Claude Fast: Permission Management

작동 방식

Shift+Tab 한 번 누르면 활성화됩니다. 화면 하단에 ⏵⏵ accept edits on이 표시됩니다.

이 모드에서는:

파일 수정 자동 승인
허용된 Bash 명령 자동 실행
허용 목록은 settings.json에서 설정 가능

언제 사용하나?

테스트 실행: npm test, pytest 등
린트 수정: 대량의 린트 오류 수정
보일러플레이트 생성: 반복적인 코드 생성
Plan Mode 이후 실행 단계

주의사항

⚠️ Auto-Accept ≠ YOLO Mode

Auto-Accept는 허용 목록에 있는 도구만 자동 승인합니다.
위험한 명령(rm -rf, curl 등)은 여전히 승인이 필요합니다.

YOLO Mode: 완전한 자율 (위험)

공식 정의

"Instead of supervising Claude, you can use claude --dangerously-skip-permissions to bypass all permission checks and let Claude work uninterrupted until completion." — Anthropic Engineering Blog: Best Practices

작동 방식

claude --dangerously-skip-permissions

이 플래그는 모든 권한 체크를 우회합니다:

파일 읽기/쓰기/삭제
모든 Bash 명령 실행
네트워크 요청
시스템 프로세스 제어

공식 경고

"Letting Claude run arbitrary commands is risky and can result in data loss, system corruption, or even data exfiltration (for example via prompt injection attacks)." — Anthropic Engineering Blog

안전하게 사용하는 방법

Anthropic이 권장하는 YOLO Mode 사용 조건:

컨테이너/VM 환경: Docker, 가상머신 내에서만 실행
인터넷 차단: 데이터 유출 방지
Git 백업: 언제든 git reset --hard로 복구 가능
명확한 범위: "코드베이스 전체 개선" ❌ → "이 모듈 리팩토링" ✅

# 권장 사용 예시
docker run -it --rm \
  -v $(PWD):/workspace \
  claude-sandbox \
  claude --dangerously-skip-permissions

언제 사용하나?

대량 린트 수정: 수백 개의 lint 오류 일괄 수정
보일러플레이트 생성: 프로젝트 초기 세팅
CI/CD 파이프라인: 자동화된 환경
테스트 주도 개발: 실패하는 테스트 → 통과할 때까지 반복

"This works well for workflows like fixing lint errors or generating boilerplate code." — Anthropic Engineering Blog

세 모드 비교

측면 Normal Auto-Accept Plan Mode YOLO

속도	느림	빠름	중간	매우 빠름
안전성	높음	중간	매우 높음	낮음
제어력	높음	중간	높음	없음
활성화	기본	Shift+Tab×1	Shift+Tab×2	CLI 플래그
용도	일반 작업	반복 작업	복잡한 계획	자동화

실전 워크플로우: Plan → Execute 패턴

복잡한 기능을 구현할 때 가장 효과적인 패턴입니다:

1단계: Plan Mode로 계획

[Shift+Tab 두 번 → Plan Mode 활성화]

You: 결제 시스템을 Stripe에서 Toss Payments로 마이그레이션해줘

Claude: 마이그레이션 계획을 세우겠습니다.

## 1단계: 현재 구조 분석
- src/payment/stripe.ts 분석
- API 호출 패턴 파악
- 테스트 커버리지 확인

## 2단계: Toss Payments SDK 설정
- 패키지 설치
- 환경 변수 설정
- 타입 정의

## 3단계: 결제 로직 교체
...

이 계획으로 진행할까요?

2단계: 계획 검토 및 수정

You: 2단계에서 타입 정의는 별도 파일로 분리해줘.
     그리고 기존 Stripe 코드는 삭제하지 말고 deprecated 처리해줘.

Claude: 계획을 수정했습니다.
...

3단계: 승인 후 실행

You: 좋아, 진행해줘

[Plan Mode 종료 → 실행 시작]

"The structured plan explains the approach, technical decisions, and potential challenges in writing, which is valuable documentation." — Claude AI: Plan Mode Guide

모드 선택 가이드

작업이 복잡하고 여러 파일에 걸쳐 있나요?
├─ Yes → Plan Mode로 시작
│         └─ 계획 확정 후 → Auto-Accept로 실행
│
└─ No → 작업이 반복적이고 안전한가요?
         ├─ Yes → Auto-Accept Mode
         │
         └─ No → 작업이 완전히 격리된 환경인가요?
                  ├─ Yes → YOLO Mode (Docker 내에서)
                  │
                  └─ No → Normal Mode

체크리스트

Plan Mode 사용 전

[ ] 작업 범위가 여러 파일에 걸쳐 있는가?
[ ] 아키텍처 결정이 필요한가?
[ ] 실수하면 롤백이 어려운 작업인가?

Auto-Accept 사용 전

[ ] 허용 목록(settings.json)을 확인했는가?
[ ] Git 상태가 clean인가?
[ ] 작업 범위가 명확한가?

YOLO Mode 사용 전

[ ] 컨테이너/VM 환경인가?
[ ] 인터넷이 차단되어 있는가?
[ ] Git으로 현재 상태를 백업했는가?
[ ] 작업 범위가 명확하고 제한적인가?

마무리

Permission Mode는 "안전 vs 속도"의 트레이드오프를 당신이 제어할 수 있게 해줍니다.

Plan Mode는 "생각 먼저, 실행 나중에" 원칙을 강제합니다
Auto-Accept는 신뢰할 수 있는 반복 작업을 가속화합니다
YOLO Mode는 완전한 자동화를 제공하지만, 격리 환경에서만 사용하세요

복잡한 작업일수록 Plan Mode로 시작하세요. 계획을 세우는 데 드는 시간이 잘못된 방향으로 가서 롤백하는 시간보다 훨씬 짧습니다.

참고 자료

Anthropic 공식

Claude Code Best Practices — Anthropic Engineering Blog
Common Workflows (Plan Mode) — Anthropic Docs

커뮤니티

Auto-Accept Permissions — ClaudeLog
Dangerous Skip Permissions — ClaudeLog
Plan Mode in Claude Code — Claude AI Blog
Permission Management — Claude Fast

Claude Code는 시니어가 아니라 "똑똑한 주니어"다

MoreLean — Tue, 20 Jan 2026 23:31:22 +0900

Claude Code를 처음 쓰면 기대가 큽니다. "AI니까 알아서 다 해주겠지?" 하지만 막상 써보면 결과물이 들쭉날쭉합니다. 어떤 때는 놀랍도록 잘하고, 어떤 때는 엉뚱한 방향으로 갑니다. 왜 그럴까요? 대부분 마인드셋의 문제입니다.

TL;DR

Claude Code를 시니어 개발자가 아닌 똑똑한 주니어 개발자로 대하세요
추상적 지시 대신 구체적이고 단계별로 쪼갠 지시를 주세요
작업 단위가 작을수록 결과물 품질이 올라갑니다
Anthropic도 공식적으로 Plan Mode와 작업 분할을 권장합니다

"똑똑한 주니어" 비유의 출처

이 비유는 Claude Code를 효과적으로 사용하는 개발자들 사이에서 널리 공유되는 멘탈 모델입니다.

"Claude Code operates as what Anthropic engineers call a 'fast intern with perfect memory.' This mental model is crucial for effective prompting." — Developer Toolkit

"It's like having a really enthusiastic junior developer who's confident about everything but actually knows nothing about the codebase or business goals." — Scott Spence, Working with Claude Code

"The biggest mistake I made initially was being too polite or vague. To get the most out of Claude Code, you need to be direct and specific, as if you're managing a junior developer." — Skywork AI

시니어 vs 주니어: 지시 방식의 차이

시니어 개발자에게 요청할 때

"인증 기능 만들어줘"

시니어는 이 한 마디로 알아서 합니다. 로그인/회원가입 폼, 비밀번호 해싱, JWT 발급, 리프레시 토큰, 세션 관리, 보안 고려사항까지 경험에서 우러나온 판단으로 구현합니다.

주니어 개발자에게 요청할 때

"인증 기능 만들어줘"

주니어는 어디서부터 시작해야 할지 막막해합니다. 또는 자기 나름대로 해석해서 예상과 다른 결과물을 내놓습니다. 그래서 이렇게 쪼개서 말해줘야 합니다:

1. 먼저 로그인 폼 UI 만들어줘
2. 이메일/비밀번호 유효성 검사 추가해줘
3. 로그인 API 엔드포인트 만들어줘
4. bcrypt로 비밀번호 검증 로직 넣어줘
5. JWT 액세스 토큰 생성해줘
6. 리프레시 토큰 구현해줘
7. 토큰 갱신 엔드포인트 만들어줘

Claude Code도 똑같습니다.

왜 이런 차이가 발생하나?

1. 컨텍스트의 한계

Claude Code는 대화 내용과 코드베이스를 참조하지만, **당신의 머릿속에 있는 "당연한 것들"**은 모릅니다.

우리 팀의 코딩 컨벤션
이 프로젝트의 아키텍처 결정 배경
비즈니스 요구사항의 뉘앙스
"인증"이라고 했을 때 당신이 기대하는 구체적 범위

2. 모호함 → 자의적 해석

추상적인 지시를 받으면 Claude Code는 나름대로 해석합니다. 그 해석이 당신의 의도와 일치할 수도 있고, 완전히 다를 수도 있습니다. 운에 맡기는 셈이죠.

3. 큰 작업 = 실수 누적

한 번에 큰 작업을 시키면 중간에 잘못된 방향으로 가도 끝까지 갑니다. 작은 단위로 쪼개면 각 단계에서 검증하고 방향을 수정할 수 있습니다.

Anthropic 공식 권장사항

이건 단순히 "커뮤니티 팁"이 아닙니다. Anthropic이 공식 문서에서 권장하는 방식입니다.

공식 블로그: 큰 작업은 쪼개라

"For large tasks with multiple steps or requiring exhaustive solutions—like code migrations, fixing numerous lint errors, or running complex build scripts—improve performance by having Claude use a Markdown file (or even a GitHub issue!) as a checklist and working scratchpad." — Anthropic Engineering Blog: Claude Code Best Practices

공식 기능: Plan Mode

Anthropic은 이 워크플로우를 공식 기능으로 제공합니다. Plan Mode는 Claude가 코드를 수정하기 전에 먼저 계획을 세우도록 강제하는 모드입니다.

"Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely." — Anthropic Docs: Common Workflows

Plan Mode 사용법:

Shift+Tab 두 번 눌러서 활성화
또는 claude --permission-mode plan으로 시작
Claude가 계획을 제시하면 검토 후 승인

공식 권장: "think" 키워드

"Ask Claude to make a plan for how to approach a specific problem. We recommend using the word 'think' to trigger extended thinking mode, which gives Claude additional computation time to evaluate alternatives more thoroughly." — Anthropic Engineering Blog

키워드 사고 깊이

think	기본
think hard	중간
think harder	깊음
ultrathink	최대

실전 예시: 좋은 지시 vs 나쁜 지시

❌ 나쁜 예시

사용자 대시보드 페이지 만들어줘

Claude Code가 해석할 수 있는 방향이 수십 가지입니다. 어떤 데이터를 보여줄지, 레이아웃은 어떻게 할지, 차트가 필요한지, 필터링은... 결과물이 마음에 안 들 확률이 높습니다.

✅ 좋은 예시

사용자 대시보드 페이지를 만들건데, 단계별로 진행하자.

1단계: 먼저 대시보드 레이아웃 컴포넌트를 만들어줘
- 왼쪽 사이드바 (240px 고정)
- 상단 헤더 (사용자 이름, 로그아웃 버튼)
- 메인 컨텐츠 영역
- Tailwind CSS 사용

1단계 결과물 확인 후:

좋아. 2단계로 메인 영역에 통계 카드 4개 추가해줘
- 총 주문 수
- 이번 달 매출
- 활성 사용자 수
- 평균 주문 금액
- 각 카드에 아이콘과 증감률 표시

작업 쪼개기 프레임워크

복잡한 기능을 요청할 때 이 순서로 쪼개보세요:

1. 데이터 구조 먼저

결제 기능을 만들건데, 먼저 필요한 DB 스키마부터 정의해줘.
- payments 테이블
- payment_methods 테이블
- 필요한 enum 타입들

2. API 엔드포인트

이 스키마 기반으로 결제 관련 API 엔드포인트 만들어줘.
- POST /payments (결제 생성)
- GET /payments/:id (결제 조회)
- POST /payments/:id/refund (환불)

3. 비즈니스 로직

결제 생성 로직에서 다음 검증 추가해줘:
- 재고 확인
- 사용자 잔액 확인
- 중복 결제 방지

4. UI 컴포넌트

결제 폼 컴포넌트 만들어줘.
- 카드 번호, 유효기간, CVC 입력
- 실시간 유효성 검사
- 로딩 상태 처리

5. 통합 및 에러 처리

결제 폼과 API를 연결하고, 에러 케이스 처리해줘.
- 카드 거절
- 네트워크 오류
- 타임아웃

주니어 다루듯이: 추가 팁

예시를 보여줘라

이런 형태로 응답 만들어줘:
{
  "success": true,
  "data": { ... },
  "error": null
}

제약 조건을 명시해라

- 외부 라이브러리 쓰지 마
- 파일 하나에 200줄 넘기지 마
- 기존 UserService 클래스 패턴 따라가줘

확인 질문을 유도해라

시작하기 전에 불명확한 부분 있으면 먼저 물어봐

중간 점검을 해라

여기까지 맞는지 확인할게. 잠깐 멈춰줘.

체크리스트: 지시하기 전에

[ ] 이 작업을 주니어에게 시킨다면 어떻게 설명할까?
[ ] 한 번에 하나의 명확한 목표만 있는가?
[ ] 예상 결과물의 형태를 구체적으로 설명했는가?
[ ] 사용할 기술/패턴/컨벤션을 명시했는가?
[ ] 하지 말아야 할 것도 명시했는가?

마무리

Claude Code는 분명 강력합니다. 하지만 그 능력을 제대로 끌어내려면 지시하는 방식을 바꿔야 합니다. "AI니까 알아서 하겠지"가 아니라 "똑똑한 주니어니까 명확하게 쪼개서 시키자"로요.

처음엔 번거롭게 느껴질 수 있습니다. 하지만 몇 번 해보면 오히려 전체 작업 시간이 줄어듭니다. 모호한 지시 → 엉뚱한 결과 → 수정 요청 → 또 수정... 이 루프를 도는 것보다 처음부터 명확하게 쪼개는 게 훨씬 빠릅니다.

Claude Code를 잘 쓰는 사람과 못 쓰는 사람의 차이는 프롬프트 스킬이 아닙니다. 상대를 어떻게 인식하느냐의 차이입니다.

참고 자료

Anthropic 공식

Claude Code Best Practices — Anthropic Engineering Blog
Common Workflows (Plan Mode) — Anthropic Docs

커뮤니티

32 Claude Code Tips — YK (ykdojo)
Claude Code as a Junior Engineer — Josh Roy
Prompt Engineering with Claude Code — Developer Toolkit

Claude Code가 느려졌다면? MCP 도구 관리가 답이다

MoreLean — Tue, 20 Jan 2026 23:25:14 +0900

Claude Code를 쓰다 보면 어느 순간 응답이 느려지고, 엉뚱한 도구를 선택하는 경험을 하게 됩니다. MCP 서버를 여러 개 연결해서 "만능 에이전트"를 만들었는데, 오히려 성능이 떨어진 것 같은 느낌. 이 글에서는 왜 이런 일이 발생하는지, 그리고 어떻게 최적화할 수 있는지 정리합니다.

TL;DR

MCP 도구는 매 요청마다 컨텍스트 윈도우를 차지합니다
도구가 많으면 느려지는 게 아니라 정확도도 떨어집니다
프로젝트별로 필요한 MCP만 활성화하세요
/doctor와 /context 명령으로 현재 상태를 점검하세요

문제: "도구가 많으면 좋은 거 아닌가요?"

GitHub MCP, Notion MCP, PostgreSQL MCP, Slack MCP... 연결할 수 있는 건 다 연결해두면 편할 것 같죠? 실제로는 정반대입니다.

한 개발자의 사례를 보면, MCP 도구들이 대화 시작 전에 이미 **82,000 토큰(전체의 41%)**을 차지했습니다. 200K 토큰 윈도우 중 143K(72%)가 이미 사용되어 **자유 공간이 5.8%**밖에 남지 않았어요. 코드 한 줄 보여주기도 전에 말이죠.

더 극단적인 사례도 있습니다. MCP_DOCKER 하나만으로 135개 도구, 125,964 토큰을 소비한 경우도 보고되었습니다.

왜 이런 일이 발생하나?

1. 컨텍스트 윈도우의 구조

Claude Code가 작업할 때 컨텍스트 윈도우는 대략 이렇게 나뉩니다:

┌─────────────────────────────────────────────────────┐
│  Claude의 컨텍스트 윈도우 (200K 토큰)                │
├─────────────────────────────────────────────────────┤
│  시스템 프롬프트: ~3K                                │
│  시스템 도구: ~12K                                   │
│  MCP 도구 정의: ???  ← 여기가 변수                   │
│  예약 공간: ~45K (autocompact + 출력)                │
│  실제 대화/코드: 남은 공간                           │
└─────────────────────────────────────────────────────┘

MCP 도구는 매 요청마다 전체 정의(이름, 설명, 파라미터 스키마)가 컨텍스트에 포함됩니다. 도구 하나당 수백~수천 토큰이 "고정 비용"으로 빠져나갑니다.

2. 도구 선택의 인지 부하

Claude가 응답할 때 내부적으로 이런 과정을 거칩니다:

사용자 요청 분석
사용 가능한 모든 도구 검토 ← 여기서 도구가 많으면 복잡해짐
적절한 도구 선택
파라미터 결정

비슷한 기능의 도구가 여러 개 있으면 "파일 읽기를 read_file로 할까, view로 할까, cat으로 할까?" 같은 판단이 필요해지고, 잘못된 선택 확률도 올라갑니다.

3. 실제 정확도 하락 데이터

Anthropic 내부 테스트 결과, 대규모 도구 라이브러리에서 도구 수를 최적화하면:

모델 최적화 전 최적화 후

Opus 4	49%	74%
Opus 4.5	79.5%	88.1%

도구가 많으면 Claude가 잘못된 도구를 선택할 확률이 거의 2배 높아집니다.

해결책 1: 수동 최적화

기본 원칙

✅ MCP 서버: 20~30개 설정해두되, 동시 활성화는 10개 미만
✅ 전체 도구 수: 80개 이하 유지
✅ 프로젝트별로 필요한 MCP만 켜기

현재 상태 점검하기

# 컨텍스트 사용량 확인
/context

# MCP 서버별 토큰 사용량 상세 확인
/doctor

/doctor 출력 예시:

Context Usage Warnings
└ ⚠️ Large MCP tools context (~81,986 tokens > 25,000)
└ MCP servers:
    └ mcp-omnisearch: 20 tools (~14,114 tokens)
    └ playwright: 21 tools (~13,647 tokens)
    └ mcp-sqlite-tools: 19 tools (~13,349 tokens)
    ...

MCP 토글 도구 활용

프로젝트마다 필요한 MCP를 켜고 끄는 게 번거롭다면, McPick 같은 CLI 도구를 활용할 수 있습니다:

npx mcpick

# 대화형으로 MCP 서버 켜기/끄기
? Select MCP servers to enable/disable:
◉ mcp-omnisearch (enabled)
◯ playwright (disabled)
◉ sequential-thinking (enabled)

해결책 2: Tool Search 활용 (2026년 1월~)

Anthropic이 이 문제를 인식하고 MCP Tool Search 기능을 출시했습니다.

Tool Search란?

모든 도구 정의를 미리 로드하는 대신, Claude가 필요할 때만 도구를 동적으로 검색하고 로드합니다.

효과

지표 기존 방식 Tool Search

토큰 사용량 (50+ 도구)	~77K	~8.7K
절감률	-	85%
자유 컨텍스트	5.8%	44%+

작동 방식

Claude Code가 MCP 도구 정의가 전체 컨텍스트의 ~10%를 넘는지 확인
임계값을 넘으면 도구를 defer_loading: true로 마킹
실제 필요할 때만 해당 도구 정의를 로드

설정 방법

# 환경 변수로 제어
ENABLE_TOOL_SEARCH=true  # 강제 활성화
ENABLE_TOOL_SEARCH=false # 비활성화
# 미설정 시 auto 모드 (임계값 기반 자동 활성화)

주의사항

Sonnet 4 이상, Opus 4 이상에서만 지원
Haiku 모델은 Tool Search 미지원
자주 쓰는 도구는 defer_loading: false로 미리 로드해두는 게 효율적

프로젝트별 MCP 구성 예시

MCP 설정 파일 위치

Claude Code의 MCP 설정은 **scope(범위)**에 따라 다른 파일에 저장됩니다:

Scope 파일 위치 용도

User (전역)	~/.claude.json	모든 프로젝트에서 사용하는 개인 설정
Project (프로젝트 공유)	프로젝트루트/.mcp.json	팀과 공유할 프로젝트별 설정 (Git에 커밋)
Local (프로젝트 개인)	프로젝트루트/.claude/settings.local.json	개인용 프로젝트 설정 (Git 제외)

팁: CLI로 MCP를 추가할 때 --scope 플래그로 저장 위치를 지정할 수 있습니다.

# 전역 설정에 추가
claude mcp add github --scope user  -- npx -y @modelcontextprotocol/server-github

# 프로젝트 설정에 추가 (팀 공유용)
claude mcp add github -s project -- npx -y @modelcontextprotocol/server-github

웹 개발 프로젝트

파일: 프로젝트루트/.mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}

사용하지 않는 MCP는 아예 파일에서 제외하거나, McPick 같은 도구로 토글하세요.

데이터 분석 프로젝트

파일: 프로젝트루트/.mcp.json

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "mcp-sqlite-tools"]
    }
  }
}

문서 작업

파일: ~/.claude.json (전역 설정으로 관리하면 편리)

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "${NOTION_API_KEY}"
      }
    },
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-gdrive"]
    }
  }
}

설정 확인 명령어

# 현재 연결된 MCP 서버 상태 확인
/mcp

# 출력 예시:
# MCP Server Status
# • github: connected
# • postgresql: connected
# • notion: disconnected

체크리스트: Claude Code 최적화

[ ] /doctor로 MCP 토큰 사용량 확인
[ ] 25,000 토큰 넘으면 경고 — 불필요한 MCP 비활성화
[ ] 프로젝트별 .claude.json 설정 분리
[ ] Tool Search 지원 모델 사용 시 auto 모드 활용
[ ] 자주 쓰는 도구는 항상 로드, 가끔 쓰는 도구는 검색 대상으로

마무리

"도구가 많을수록 좋다"는 직관과 달리, AI 에이전트에서는 적절한 도구 수 관리가 성능의 핵심입니다. 컨텍스트 윈도우는 유한한 자원이고, 도구 정의도 그 자원을 소비합니다.

Tool Search 기능이 나오면서 제약이 많이 완화되었지만, 여전히 프로젝트별로 필요한 MCP만 활성화하는 습관은 유효합니다. 더 빠른 응답, 더 정확한 도구 선택, 더 넓은 작업 공간을 원한다면 지금 바로 /doctor를 실행해보세요.

참고 자료

테츠 카츠야 2026 하이브리드 레시피

MoreLean — Sun, 4 Jan 2026 10:23:23 +0900

커피를 끊어야 하면서도 내리는 즐거움에 잘 안된다.

계속 4:6 으로 내려 마시다가, 이번에 새로 발표된 궁극의 방법이 있다고 해서 정리해봤다.

- 하리오 스위치

- 원두 : 20g

- 분쇄도 : Timemore S3 5.0, 코만단테 C40 MK4 28

- 물온도 : 90도

- 상온수 : 150g ( 70도 ~ 80도 사이를 맞추기 위함 )

시간	밸브상태	물온도	주입량(g)	누적량(g)
0:00	닫힘	90도	40 ~ 50 ( 잠길정도 )	40
0:40	열림		80	120
1:30	열림		80	200
2:10	닫힘	70 ~ 80도	100	300
2:45	열림			300
3:30내외	열림			300

https://www.youtube.com/watch?v=4FeUp_zNiiY

제대로 내리기 위해서 정리해둠 -> 아직 제대로 마셔보지 못한 레시피

Auto-Claude macOS 설치 트러블슈팅 가이드

MoreLean — Fri, 2 Jan 2026 13:19:33 +0900

Auto-Claude는 자율적으로 코딩을 수행하는 멀티 에이전트 프레임워크입니다. macOS에서 DMG 파일로 설치한 후 발생할 수 있는 문제들과 해결 방법을 정리했습니다.

환경

macOS (Apple Silicon / Intel)
Python 3.12+ (Homebrew로 설치)
Auto-Claude 2.7.x (DMG 설치)

문제 1: spawn python ENOENT

증상

Context 메뉴에서 프로젝트 분석 시 다음 에러 발생:

Failed to load project index
spawn python ENOENT

원인

macOS에서 Homebrew로 Python을 설치하면 python3 명령어만 생성되고, python 명령어는 생성되지 않습니다. Auto-Claude는 python 명령어를 사용하기 때문에 이 문제가 발생합니다.

해결 방법

1단계: Python 설치 확인

python3 --version  # Python 3.x.x 출력되면 설치됨
python --version   # command not found 발생

2단계: 심볼릭 링크 생성

sudo ln -s $(which python3) /usr/local/bin/python

3단계: 링크 확인

which python
# 출력: /usr/local/bin/python

python --version
# 출력: Python 3.x.x

문제 2: 심볼릭 링크 생성 후에도 동일한 에러 발생

증상

python 명령어가 터미널에서는 정상 동작하지만, Auto-Claude 앱에서는 여전히 spawn python ENOENT 에러 발생.

원인

macOS GUI 앱은 터미널과 다른 환경에서 실행되어 /usr/local/bin PATH를 인식하지 못합니다.

해결 방법

방법 A: 터미널에서 앱 실행 (권장)

open -a "Auto-Claude"

참고: 앱 이름에 하이픈이 포함되어 있습니다. Auto Claude가 아닌 Auto-Claude입니다.

방법 B: 시스템 PATH 영구 등록 후 재부팅

sudo launchctl config user path "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

이후 Mac을 재부팅하면 Dock에서 직접 실행해도 정상 동작합니다.

문제 3: ModuleNotFoundError - dotenv

증상

태스크 실행 시 다음 에러 발생:

Traceback (most recent call last):
  File ".../spec_runner.py", line 85, in <module>
    from dotenv import load_dotenv
ModuleNotFoundError: No module named 'dotenv'

원인

Auto-Claude 실행에 필요한 Python 패키지가 설치되지 않았습니다.

해결 방법

pip3 install python-dotenv --break-system-packages

--break-system-packages 플래그는 macOS의 Python 환경 보호 기능(PEP 668)을 우회합니다.

문제 4: externally-managed-environment 에러

증상

pip 설치 시 다음 에러 발생:

error: externally-managed-environment
× This environment is externally managed

원인

macOS Sonoma부터 시스템 Python 환경을 보호하기 위해 PEP 668이 적용되었습니다.

해결 방법

모든 pip 설치 명령에 --break-system-packages 플래그를 추가합니다:

pip3 install <패키지명> --break-system-packages

문제 5: ModuleNotFoundError - claudeagentsdk

증상

dotenv 설치 후에도 추가 모듈 에러 발생:

ModuleNotFoundError: No module named 'claude_agent_sdk'

원인

Auto-Claude 실행에 필요한 의존성 패키지들이 추가로 필요합니다.

해결 방법

방법 A: requirements.txt로 일괄 설치 (권장)

pip3 install -r /Applications/Auto-Claude.app/Contents/Resources/auto-claude/requirements.txt --break-system-packages

방법 B: 개별 설치

pip3 install python-dotenv claude-agent-sdk --break-system-packages

최종 체크리스트

Auto-Claude를 정상적으로 실행하기 위한 체크리스트입니다:

[ ] Python 3.12+ 설치 확인
[ ] python 심볼릭 링크 생성
[ ] 필요한 Python 패키지 설치
[ ] 터미널에서 앱 실행 또는 시스템 PATH 등록

한번에 설정하기

# 1. python 심볼릭 링크 생성
sudo ln -s $(which python3) /usr/local/bin/python

# 2. 필수 패키지 설치
pip3 install -r /Applications/Auto-Claude.app/Contents/Resources/auto-claude/requirements.txt --break-system-packages

# 3. 앱 실행
open -a "Auto-Claude"

참고

Auto-Claude GitHub Repository
PEP 668 - Externally Managed Environments
Auto-Claude는 Claude Pro/Max 구독이 필요합니다.

커피 그라인더 사이즈 차트 사이트

MoreLean — Wed, 31 Dec 2025 18:47:26 +0900

내가 가지고 있는 그라인더는 Timemore S3 이다.

가장 유명하고 비싼 코만단테 MK4와는 가격차이가 엄청나지만 나름 괜찮은 만듦새로 만족하면서 쓰고 있다.

하지만 불편한 점이 있다면 상당수의 레시피가 코만단테를 기준으로 알려준다는 것이다.

이번에 새롭게 접한 레시피도 코만단테 MK4 기준 28 클릭이다.

그래서 이게 도대체 내 Timemore S3 기준으로는 몇일까?를 알아보려 했지만 정확한 사이즈를 몰라서 궁금해 하던차에 이런 사이트를 알게 되었다.

각 그라인더 브랜드 별로 사이즈 비교차트를 알려주는 사이트이다.

https://honestcoffeeguide.com/coffee-grind-size-chart/

Coffee Grind Size Chart | Honest Coffee Guide

Merch Coffee Tasting Cards for Dialling-in Espresso

honestcoffeeguide.com

이런게 브랜드를 검색하고, 제품 모델을 선택하면 Chart를 알려준다.

그래서 코만단테 기준 MK4는 28클릭은 몇일까를 찾아보니 대략 5.0 정도이네!

회사에서는 Timemore C3 ESP Pro를 쓰고 있어서 3개를 비교해뒀다. ( 이녀석은 조절하기 쉽지 않다. )