클로드 코드 실전 팁 시리즈 — HoYeon Lee

한 줄 요약

HoYeon Lee(Builder & Educator, LinkedIn @hoyeonleekr)의 “클로드 코드 실전 팁” 시리즈를 발췌·정리한다. 클로드 코드 성능을 좌우하는 건 모델만이 아니라 지금 세션에 무엇이 들어 있는지이며, MEMORY·Hook·SKILL 점검, 멀티 에이전트의 용도별 선택, 세션 컨텍스트 관리, CLAUDE.md 정리가 그 축이다.

출처: HoYeon Lee LinkedIn 게시글 시리즈(@hoyeonleekr). 아래는 원문 발췌 요약이며, 각 편의 상세 가이드는 원저자가 게시글 댓글 링크로 별도 제공한다.

성능이 안 좋아졌을 때 먼저 보는 것 — MEMORY · Hook · SKILL

클로드 코드 성능이 떨어졌다고 느낄 때 가장 먼저 보는 건 세 가지다: MEMORY(CLAUDE.md·MEMORY.md), Hook, 그리고 쌓인 SKILL들.

• CLAUDE.md는 한 번에 커지지 않는다. 겪은 예외, 실수 한 번 막으려 넣은 규칙, 특정 기능에만 필요했던 지침이 조금씩 쌓이고, 몇 달 지나면 지금은 안 맞는 지침과 여전히 지켜야 할 지침이 섞여 구분이 안 된다(Boris도 같은 얘기를 했다).
• 오픈소스 플러그인·하네스를 이것저것 설치하다 보면 Hook과 SKILL이 하나씩 따라붙는다. 이게 쌓이면 도구 하나 쓸 때마다 여러 Hook·SKILL이 조용히 돌면서 지금 작업과 상관없는 컨텍스트까지 계속 주입한다 — 속도를 갉아먹는 진짜 주범은 대부분 여기다.
• 오해 정정: MCP는 dynamic load 방식이라 그 자체로 별도 컨텍스트를 차지하지 않는다.

멀티 에이전트 세 가지 방식 — Agent Teams · Cross-session messaging · 서브에이전트

클로드 코드에서 멀티 에이전트를 쓰는 길은 세 갈래다. 서브에이전트는 다들 쓰지만 Agent Teams와 최근 생긴 Cross-session messaging은 덜 알려져 있다.

• Agent Teams — 한 세션이 팀 리드를 맡고 팀원들이 각자 독립 컨텍스트에서 일하며 발견한 걸 공유한다. 서브에이전트는 결과만 던지고 끝나지만 여기선 작업자끼리 대화가 된다. 서로 다른 가설로 버그를 파거나, 프론트·백엔드처럼 역할 경계를 나눠 중간 조율이 필요한 일에 맞는다.
• Cross-session messaging — 앞의 둘이 에이전트를 새로 만드는 방식이라면, 이건 이미 열어둔 세션끼리 그대로 연결한다. (1) Handoff를 다른 터미널로 수월하게 넘기고, (2) Worktree를 나눠 병렬로 돌릴 때 변경 사항을 서로 알려 충돌을 미리 막고, (3) Orca·Herdr 같은 skill 형태로 세션을 직접 열면 오케스트레이션이 더 수월해진다.
• 정리 — 결과만 필요하면 서브에이전트, 작업자끼리 논의해야 하면 Agent Teams, 내가 직접 연 세션을 연결하고 싶으면 Cross-session messaging.
• 단서 — 멀티 에이전트가 항상 더 낫지는 않다. 간단하거나 순차적인 작업이면 메인 세션 하나가 제일 낫다. 나누는 순간 지시하고 다시 합치는 비용이 붙으니 용도에 맞춰 쓰는 게 핵심이다.

실전 팁 3편 — 세션의 컨텍스트 관리하기

같은 세션을 오래 붙잡으면 어느 순간부터 에이전트가 멍청해진다 — 방금 정한 규칙을 다시 묻고, 반복해서 실수한다. 세션 컨텍스트는 성능을 생각보다 직접 좌우한다. 어떤 모델을 쓰는지만큼이나 지금 세션에 무엇이 들어 있는지가 결과를 크게 흔든다(RTK·Headroom처럼 토큰을 미리 걷어내는 오픈소스가 계속 나오는 이유다). 멀티 에이전트가 퀄리티를 올리는 이유 하나도 여기 있다 — 작업 단위에 맞춰 응집도 높은 컨텍스트를 유지하기 때문.

• 증상: 답이 나빠진다(정한 규칙을 다시 묻고, 읽은 파일을 또 읽는다).
• 먼저 확인: /context(또는 /context all)로 무엇이 자리를 먹는지 본다.
• 처방 방향: 찼을 때 비우거나, 덜 차게 만든다.

컨텍스트가 찼을 때 — 다섯 가지(끊는 정도 순). 고르는 기준은 하나, “지금 대화를 이어가야 하는가”:

• /clear [이름] — 주제가 바뀌어 앞 내용이 필요 없을 때. 대화를 비우고 새로 시작하되, 이름을 붙이면 /resume 목록에서 그 라벨로 되찾는다.
• /compact [지시] — 같은 대화를 이어가며 자리만 비울 때. 요약으로 남고, 지시를 붙이면 그 기준으로 요약한다(부분만 줄이려면 /rewind).
• handoff 문서 — 작업을 파일로 넘길 때. 남는 건 문서에 적은 것뿐이라, 원저자는 이보다 아래 peer messaging을 더 권장한다.
• 세션 + peer messaging — 다른 세션에 이어 시킬 때. /list-agents로 상대를 확인하고 넘긴다. 넘어가는 건 평문 텍스트뿐이라, “한 일”보다 “다음에 할 일과 이유”를 보내는 게 낫다.
• /btw [질문] — 곁가지 질문 하나만 할 때. 메인 컨텍스트를 건드리지 않는다(대화를 갈라 실제 작업을 하려면 /branch).

덜 차게 만들기(한 번 걸면 계속 적용).

• /autocompact [값] — 자동 압축 시점을 절대 토큰 수로 앞당긴다(예: 500k). 원저자는 보통 500K로 둔다 — 그 이상은 성능이 더 나빠진다고.
• 큰 읽기는 Subagent 위임 — 파일 내용은 서브에이전트 컨텍스트에 쌓이고 내 쪽엔 경로·결론만 돌아온다.
• MCP·메모리 정리 — MCP 스키마는 기본 지연 로드라 그 자체로 컨텍스트를 크게 먹지 않는다. 메모리가 많이 차지하면 /memory로 CLAUDE.md·auto memory를 정리한다.

토큰을 미리 줄이는 오픈소스(줄이는 지점이 달라 겹치지 않음).

• RTK — 명령 실행 결과가 컨텍스트에 닿기 전 걸러낸다(자체 주장 토큰 80%↓). 단 Bash 도구 호출에만 걸린다.
• Headroom — 파일·데이터를 읽어 들이는 단계에서 압축한다(자체 주장 87.6%↓).
• Caveman — 모델이 답을 내보내는 단계에서 군더더기를 걷어낸다(자체 주장 출력 65%↓, 코드·URL은 보존).

원저자 상세 가이드: https://www.grabity.me/resources/cladue-code-context-management

실전 팁 4편 — CLAUDE.md 체계적으로 관리하기

문제는 “안 쓰는 것”보다 “쓰고 나서 방치하는 것”이다. 좋다고 계속 추가만 하고 예전 규칙이 지금도 맞는지 확인하지 않으면, 방치된 CLAUDE.md는 안 쓰는 것보다 못할 수 있다. 관리 기준 5가지:

• 200줄 넘어가면 일단 의심한다. 파일시스템만 봐도 뻔한 정보(디렉토리 구조·의존성 목록)는 빼고, 코드로는 안 보이는 함정과 관례만 남긴다.
• 조건부 로딩으로 쪼갠다. .claude/rules/에 주제별로 나누고, 특정 폴더에만 필요한 규칙은 하위 CLAUDE.md로 뺀다. “항상 필요한 것”과 “특정 상황에만 필요한 것”을 구분하는 게 핵심.
• 반복되는 실수만 기록한다. 같은 실수를 반복하거나 지난 세션에 한 말을 또 하고 있다면 추가한다. 반복 실수인지 파악하려면 결과가 의도와 다를 때 의도적으로 세션을 분석시켜야 한다.
• 그래도 늘어나면 스킬·문서로 완전히 빼고 포인터만 남긴다(Progressive Disclosure). CLAUDE.md는 목차 역할만 하고 실제 내용은 필요할 때 찾아 읽게 만든다.
• Routine·cron으로 주기적으로 검사한다. 한 번 정리해도 시간이 지나면 또 방치되니 주기적으로 세션을 분석시켜 반복 문제는 추가하고 불필요한 건 삭제한다. 다만 병합은 사람이 한다.

핵심 한 줄

성능은 모델보다 “지금 세션에 무엇이 들어 있는가”가 좌우한다. CLAUDE.md·Hook·SKILL·컨텍스트는 쌓는 게 아니라 주기적으로 덜어내는 대상이고, 멀티 에이전트는 용도에 맞을 때만 쓴다.