Category
앤트로픽의 터미널 기반 에이전트 코딩 도구 Claude Code를 다룬다. 파일 탐색, 멀티파일 수정, 테스트 실행, 커밋까지 명령으로 처리하며 대규모 코드베이스 작업에 강하다. 설정, 서브에이전트, MCP 연동, 비용 관리 같은 실전 운영 노하우를 정리한다.
Claude Code의 SessionStart·Stop 훅은 세션 시작 시 스크립트를 돌려 결과를 컨텍스트로 주입하고, 종료 시 대화를 로깅하는 자동화 지점이다. 흔한 패턴은 Stop 훅이 세션 요약을 파일에 남기고 다음 SessionStart 훅이 최근 로그를 읽어 다시 주입하는 것인데, 여기서 출력→입력 피드백 루프가 생긴다. 로그 본문을 통째로 주입하면 이전 세션이 다룬 민감 도메인 어휘가 누적돼 토큰 농도가 올라가고, 정당한 작업조차 안전 분류기에 걸려 차단되는 사례가 보고됐다. 해법은 본문이 아니라 메타데이터(타임스탬프·소스·작업명)만 주입하고, 민감 키워드가 일정 빈도를 넘는 로그는 스캔 대상에서 자동 격리하는 다층 게이트다. 훅이 비결정적 부작용을 만들 수 있다는 점이 핵심이다.
Claude Code가 Sonnet 계열 1M 토큰 컨텍스트를 붙이면서 '레포 통째로 넣기'가 가능해졌지만, 실무에서 드러난 건 한도가 늘어도 관리 부담은 안 사라진다는 점이다. 200K를 넘기는 구간부터 입력 토큰 단가가 프리미엄으로 올라가고, 컨텍스트가 길수록 중간에 묻힌 지시를 흘리는 lost-in-the-middle 경향이 다시 고개를 든다. 프롬프트 캐싱이 반복 호출의 입력 비용을 깎아주지만, 캐시는 접두사가 바뀌면 무효화돼서 대화 앞쪽에 큰 컨텍스트를 쌓고 뒤에서 계속 편집하는 패턴과 궁합이 나쁘다. 결국 '/compact로 요약 압축, 무관한 파일은 서브에이전트로 격리, 자주 쓰는 규칙은 CLAUDE.md로 고정'이라는 컨텍스트 예산 관리가 한도와 무관하게 여전히 필요하다.
Claude Code의 서브에이전트(.claude/agents/*.md)가 메인 대화와 분리된 독립 컨텍스트 창에서 돌도록 정리됐다. 각 서브에이전트는 자체 시스템 프롬프트·허용 도구 화이트리스트·모델을 지정하고, 메인 스레드는 호출 결과(요약 텍스트)만 돌려받는다. 핵심은 컨텍스트 격리다. 대형 코드베이스를 grep으로 훑거나 테스트 로그 수백 줄을 파싱하는 작업을 서브에이전트에 떠넘기면, 그 토큰 폭증이 메인 창을 오염시키지 않는다. 대신 호출당 새 컨텍스트를 채우는 비용과 왕복 지연이 붙어서, 잘게 쪼개진 다수 호출은 오히려 느리고 비싸진다. 한 번에 한 서브에이전트가 끝나야 다음이 시작되는 직렬 실행 구간이 길면 체감 속도가 떨어진다.