Claude Code 효율을 극대화하는 컨텍스트 관리의 기술

Claude Code를 비서처럼 부리기 위한 컨텍스트 관리 전략

최근 AI 도구들이 쏟아져 나오면서, 이들을 어떻게 하면 더 잘 활용할 수 있을지에 대한 고민이 깊어진다. 이전 글에서 omo(Oh My OpenCode)를 다루었던 것처럼, 도구의 선택만큼이나 중요한 것이 바로 ‘활용의 기술’이다.

인공지능을 얼마나 잘 다루느냐는 결국 사용하는 토큰량 대비 원하는 산출물을 얼마나 정확하게 뽑아냈느냐라는 정량적 수치로 증명된다고 본다. 불필요한 대화 핑퐁을 줄이고, 단 한 번의 요청으로 의도를 정확히 관철시키는 것. 그것이 AI 시대의 새로운 생산성 척도가 아닐까.

지금까지 ChatGPT, Claude Code, Gemini 등 다양한 도구를 주력으로 사용해 보았는데, 그중에서도 특히 강력한 성능을 자랑하는 Claude Code를 더 효율적으로 쓰기 위해 고민했던 지점들을 공유해 보고자 한다.

claude.md: 치매 걸린 슈퍼 개발자를 위한 지도

Claude는 세션이 초기화될 때마다 이전의 기억을 모두 잃어버린다. 이는 마치 ‘기억상실증에 걸린 천재 개발자’를 조수로 둔 것과 같다. 실력은 출중하지만, 매번 우리 프로젝트의 규칙과 맥락을 새로 가르쳐야 하는 번거로움이 있다.

이때 가장 중요한 역할을 하는 것이 바로 claude.md 파일이다. 이 파일은 Claude Code에게 건네주는 일종의 안내문이자 지도다. 이 파일을 어떻게 작성하느냐에 따라 우리가 원하는 결과를 얻기까지의 시행착오가 결정된다.

• 압축과 엄밀함: 프로젝트 아키텍처, 디렉토리 구조(tree), 공통 룰 등을 담되, 너무 길어지지 않도록 핵심만 엄밀하게 적어야 한다.
• 컨텍스트의 격리: 내용이 방대해진다면 claude.md를 쪼개어 하위 디렉토리로 분산시키는 것이 좋다. 예를 들어 프론트엔드와 백엔드 룰이 섞여 있다면, 각각의 디렉토리에 별도의 가이드를 두는 식이다.
• 무시되지 않는 규칙: Claude Code는 작업 중인 내용과 관련이 없다고 판단하면 가이드 파일을 무시하기도 한다. 백엔드 작업을 하는데 프론트엔드 룰이 가득한 파일을 읽게 하는 것은 자원 낭비일 뿐만 아니라, AI의 집중력을 흐트러뜨리는 요인이 된다.

나는 대화 핑퐁이 길어진다 싶으면 현재의 소통 방식을 회고하고, Claude Code 스스로 claude.md를 업데이트하게 만드는 커스텀 커맨드를 활용하고 있다.

컨텍스트 메모리: 비울수록 똑똑해진다

Claude Code를 사용하며 반드시 주시해야 할 것이 바로 컨텍스트 메모리(Context Memory)다. /context 명령어를 입력하면 현재 어떤 요소가 메모리를 얼마나 차지하고 있는지 확인할 수 있다.

특히 MCP(Model Context Protocol)를 사용하면 메모리 점유율이 급격히 올라간다. 나는 꼭 필요한 경우가 아니라면 MCP를 최소화하며, 당장 필요 없는 MCP는 일시적으로 비활성화했다가 필요할 때만 다시 켠다.

또한, 대화 중간중간 메모리 상태를 체크하며 /clear 명령어로 틈틈이 메모리를 비워주는 습관이 큰 도움이 된다. 가득 찬 메모리는 AI의 추론 성능을 떨어뜨리고, 과거의 잘못된 맥락에 휘둘리게 만드는 원인이 되기 때문이다.

커맨드와 스킬: 전략적 규칙 배치

Claude Code의 기능을 확장하는 커맨드(Command)와 스킬(Skill)은 관리 전략 면에서 큰 차이가 있다.

• 스킬(Skill): 파일 내용 전체를 로드하지 않고 Frontmatter 부분만 메모리에 적재한다. 따라서 스킬을 정의할 때는 Frontmatter를 매우 정교하게 작성해야 한다. AI가 특정 상황에서 ‘이 스킬을 꺼내 써야겠다’라고 판단할 수 있는 정확한 단서가 되기 때문이다.
• 커맨드(Command): Frontmatter를 컨텍스트에 적재하지 않으며, 미리 정의된 특정 작업을 수행하기 위한 프롬프트 프리셋에 가깝다.

이 두 가지 특성을 이용해 claude.md의 크기를 최적화할 수 있다. 예를 들어 복잡한 테스트 작성 규칙을 claude.md에 일일이 적는 대신, “테스트 작성 시에는 write-test 스킬의 가이드를 따르라”는 문장 한 줄로 대체하고, 상세한 룰은 스킬 내부로 위임하는 방식이다. 이는 claude.md를 슬림하게 유지하면서도 필요할 때만 강력한 규칙을 소환할 수 있는 영리한 방법이다.

서브 에이전트: 메인 세션의 순결함을 지키는 법

마지막으로 언급하고 싶은 것은 서브 에이전트(Sub-agent)의 활용이다. 서브 에이전트는 메인 세션의 메모리를 공유하지 않는데, 이는 단점이 아니라 오히려 ‘관점의 독립성’이라는 강력한 장점이 된다.

• 메모리 오염 방지: 디버깅 과정에서 “그래도 안 되는데?” 같은 감정 섞인 핑퐁이 이어지면 메인 세션의 메모리는 금세 지저분해진다. 이런 작업은 서브 에이전트에게 맡겨 메인 세션의 메모리를 깨끗하게 유지해야 한다.
• 새로운 시각의 QA: 작업을 수행한 에이전트가 아닌, 다른 관점을 가진 서브 에이전트에게 QA를 시키면 본인이 놓친 버그를 더 잘 찾아내곤 한다.

토큰 소모량 관점에서는 서브 에이전트 간의 소통이 낭비처럼 보일 수 있으나, 메인 세션의 맥락을 보존하고 작업의 정확도를 높이는 측면에서는 충분히 투자할 가치가 있다고 생각한다.

---

결국 Claude Code를 잘 쓴다는 것은 인공지능의 한계를 이해하고, 그들이 최상의 퍼포먼스를 낼 수 있는 최적의 환경을 설계해 주는 일이다. 다음 글에서는 실제로 어떤 플러그인들을 사용하고, 어떻게 구체적으로 환경을 구성했는지에 대해 다루어 보겠다.

인공지능은 도구가 아니라, 우리가 관리하고 협업해야 할 지능적인 파트너다.