나만의 하네스 구축하기 - CLAUDE.md

오늘은 CLAUDE.md를 제대로 다루는 법을 정리해보려고 한다.

---

CLAUDE.md는 개인이 구축할 수 있는 가장 영향력 있는 하네스라고 생각한다. 그만큼 잘 다뤄야 하는 요소이므로, 잘 다루는 방법을 정리해봤다.

CLAUDE.md가 중요한 이유#

본격적으로 시작하기 전에 다음 내용을 먼저 이해하면 글을 읽는 데 훨씬 도움이 될 것이다. 요점은, CLAUDE.md나 AGENTS.md 같은 문서가 AI의 사고를 덜어줄 수 있는 도구가 되어야 한다는 것이다. AI는 세션이 종료되면 까먹는다. 그래서 새로운 세션을 열고 작업을 요청하면, 해당 작업에 필요한 이해와 프로젝트에 대한 이해를 거친 후 작업을 시작한다. 여기에서 가장 큰 문제는 매번 이해를 거친다는 것이다. 이로 인해 두 가지 큰 문제가 발생한다.

1. 토큰 소모량
2. Context 차지

여기서 토큰도 토큰이지만, Context를 차지하는 것은 꽤 큰 성능 하락으로 이어질 수 있다. Opus 4.7을 예로 들면, 가용한 Context는 백만 토큰이지만 사실 백만 토큰까지는 절대 못 쓴다. LLM은 Context가 길어질수록 성능 하락이 크게 발생하기 때문이다. 그래서 컨텍스트가 가득 차기 전에 /compact로 대화 기록을 요약·압축해 쓰는 경우가 많다(Claude Code는 한도에 가까워지면 자동 압축도 수행한다). 하지만 이 압축 작업은 만능이 아니다. 당연한 내용이지만 압축은 압축 이전의 히스토리를 완전히 보존하지 못한다. 그럼에도 LLM이 어느 정도라도 기억해주길 바라는 마음으로 사용하는 것이 압축 작업이다. 또한 매 턴마다 LLM은 그때까지 쌓인 Context 전체를 입력으로 다시 처리한다. 프롬프트 캐싱 덕분에 바뀌지 않은 앞부분은 캐시 히트로 재사용되어 비용이 낮아지고, 캐시 지점은 턴이 지날수록 앞으로 이동한다. 다만 캐시는 일정 시간(호출이 없으면 5분) 뒤 만료되어 그 앞부분을 다시 처리해야 하고, 무엇보다 누적된 입력의 총량 자체는 턴마다 계속 늘어난다. 세션이 길어질수록 한 번의 요청에 드는 입력 토큰이 커지는 것은 이 때문이다. 이처럼 세션이 길어지는 것은 AI와 인간 모두에게 큰 리스크로 다가온다. 이를 어느 정도 완화할 수 있는 방법이 CLAUDE.md, AGENTS.md를 잘 작성해서 AI가 쓸데없는 토큰으로 Context를 채우지 않게 하는 것이다. 핵심은 AI의 사고를 덜어줄 수 있는 방향으로 작성하는 것이다.

CLAUDE.md의 작동 방식#

종류#

CLAUDE.md는 다양한 곳에 존재할 수 있는데, 대표적으로 사용되는 케이스는 아래 세 가지이다.

전역·프로젝트 위치의 CLAUDE.md는 매 세션마다 통째로 Claude에게 전달된다. 서브디렉토리 CLAUDE.md는 동작이 조금 다른데, 이는 뒤에서 다시 다룬다.

참고로 Claude Code가 자동으로 읽는 파일 이름은 CLAUDE.md다. 다른 코딩 에이전트와 공유하는 AGENTS.md가 이미 있다면, CLAUDE.md에서 @AGENTS.md로 불러와 양쪽이 같은 지침을 보게 할 수 있다.

Claude Code의 컨텍스트 레이어#

Claude Code는 매 요청마다 여러 레이어의 컨텍스트를 위에서 아래로 쌓아 하나로 합친다. 대략 다음과 같은 순서다.

1. 시스템 프롬프트
2. 도구 정의
3. 전역 CLAUDE.md
4. 프로젝트 CLAUDE.md
5. 세션 히스토리
6. 현재 사용자 메시지

서브디렉토리의 CLAUDE.md가 이 목록에 없는 것은 의도된 동작이다. 이 파일은 세션 시작 시 한꺼번에 올라가지 않고, Claude가 그 디렉토리의 파일을 읽을 때 비로소 컨텍스트에 추가된다. 또 한 가지, CLAUDE.md는 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 다음에 오는 사용자 메시지 형태로 전달된다.

CLAUDE.md가 중요한 이유를 위 계층에서 찾을 수 있다. 시스템 프롬프트와 도구 정의는 Claude Code가 기본으로 제공하는 native harness다. Anthropic이 관리하는 영역이라 사용자가 손댈 수 없다. 반면에 CLAUDE.md는 개인이 다룰 수 있으며, 특정 프로젝트에 대한 내용을 자동으로 AI에게 심어주기에 가장 좋은 수단이다. 즉, 가장 기초적이면서도 개인적인 커스텀 하네스가 된다.

CLAUDE.md 작성 팁#

앞서 CLAUDE.md가 중요한 이유에서 말했듯이, AI의 반복적인 사고를 줄일 수 있는 방향으로 작성해야 한다. 구체적인 방법을 설명하겠다.

0. Anthropic 공식 문서#

Anthropic 공식 문서는 효과적인 CLAUDE.md 작성 지침으로 네 가지를 든다.

1. 구체적으로 쓴다.
   • "테스트를 잘 짜라"가 아니라, 무엇으로 어떻게 짜고 무엇은 쓰면 안 되는지 규칙까지 적는다. 구체적일수록 강력하다.
2. 구조화된 마크다운을 쓴다.
   • 헤딩과 리스트로 스캔 가능하게 만든다.
3. 일관성을 유지하고 정기적으로 검토한다.
   • 서로 모순되는 규칙이 있으면 Claude가 둘 중 하나를 임의로 고른다. CLAUDE.md도 유지보수가 필요한 코드처럼 다뤄, 오래됐거나 상충하는 규칙을 주기적으로 솎아낸다.
4. 간결하게 유지한다.
   • Anthropic은 파일당 200줄 이하를 권장한다. 길어질수록 컨텍스트를 더 차지하고 지시 준수율이 떨어진다. 분량이 커지면 path-scoped rules나 서브디렉토리 CLAUDE.md로 분산한다.

1. AI의 사고를 덜어줄 수 있는 내용 작성#

Claude는 코드를 읽을 수 있다. 코드만 봐도 알 수 있는 내용을 CLAUDE.md에 적는 건 CLAUDE.md를 지저분하게 만든다. 대신, Claude가 프로젝트를 대충 훑어봐도 알 수 없는, 어느 정도의 추론을 거쳐야 알 수 있는 내용을 CLAUDE.md에 작성한다면 Claude의 사고를 덜어줄 수 있다. 사고를 덜어준다는 것은, 매 세션마다 차지하게 되는 Context를 깔끔하게 유지하면서 토큰 소모량도 줄인다는 뜻이다.

나쁜 예:

• "React를 사용한다"
• "컴포넌트는 src 폴더에 있다"
• "TypeScript로 작성됐다"
• "테스트 폴더는 여기 있다"

좋은 예: 코드만 봐서는 알 수 없는 함정(gotcha), 숨겨진 규칙, 이 프로젝트에서 반드시 알아야 할 약속. Claude가 반복하는 실수가 있다면 "이런 실수를 반복하지 마라"고 명시한다.

CLAUDE.md에 들어갈 자리는 한정되어 있다. 그 자리는 Claude가 모르거나 추측할 수밖에 없는 정보로 채워야 한다.

2. 실수를 그 자리에서 반영#

Claude가 실수했을 때 그 자리에서 바로 지적하고, "이 실수는 다시 안 하게 CLAUDE.md에 반영해줘"라고 말하면 같은 실수를 반복하지 않는다.

CLAUDE.md는 한 번에 완벽하게 쓸 수 없다. 에이전트가 어떤 실수를 할지 미리 알 수 없기 때문이다. 그러니 처음부터 완벽한 문서를 쓰려 하지 말고, 프로젝트를 진행하면서 CLAUDE.md를 보완해나가는 식으로 작성해야 한다. 예를 들어 Claude가 테스트를 mock으로 짜 버렸다면, 즉시 "mock 쓰지 마, CLAUDE.md에 반영해"라고 말한다. 그러면 해당 규칙이 추가되고, 다음 세션부터 같은 실수의 재발 확률이 낮아진다.

3. 빌드·테스트·린트 명령어 명시#

단순히 테스트를 진행하라고만 해도 Claude가 알아서 테스트 방법을 찾아 진행할 수도 있지만, 우리는 Claude의 사고를 덜어야 한다.

불필요한 사고를 피하기 위해 빌드, 테스트, 린트 명령어를 CLAUDE.md에 작성한다. 이것만으로도 Claude는 추측과 탐색 과정을 건너뛰고 곧장 정답으로 향하기 때문에 품질이 눈에 띄게 올라간다.

# CLAUDE.md

- build: `npm run build`
- test: `npm test -- --run`
- lint: `npm run lint:fix`
- typecheck: `tsc --noEmit`

4. 길어지면 분할하기#

CLAUDE.md가 200줄을 넘기거나 한 파일에 담기엔 버거울 만큼 복잡해지면 분할을 고려한다. 다만 분할 방식에 따라 효과가 다르므로 구분이 필요하다.

@import — 정리는 되지만 컨텍스트는 줄지 않는다. CLAUDE.md에서 @경로 문법으로 다른 파일을 불러올 수 있다. 코딩 컨벤션을 coding-style.md로 빼고 CLAUDE.md에는 참조 한 줄만 남기는 식이다. 단, 공식 문서에 따르면 import된 파일은 세션 시작 시 전부 펼쳐져 컨텍스트에 올라간다. 파일을 보기 좋게 나누는 효과는 있지만, 컨텍스트 점유량 자체는 한 파일에 다 적는 것과 같다.

# CLAUDE.md

@docs/coding-style.md
@docs/testing-rules.md

컨텍스트를 실제로 줄이려면 — 서브디렉토리 CLAUDE.md, path-scoped rules. 앞서 봤듯 서브디렉토리의 CLAUDE.md는 Claude가 그 디렉토리의 파일을 읽을 때만 로드된다. 모노레포에서 패키지별 규칙을 각 패키지 디렉토리에 두면, 그 패키지를 건드릴 때만 컨텍스트에 들어온다. 또 .claude/rules/에 규칙 파일을 두고 paths: 프런트매터로 적용 대상 경로를 지정하면, 매칭되는 파일을 다룰 때만 해당 규칙이 로드된다. 루트 CLAUDE.md를 작게 유지하면서 컨텍스트도 아끼고 싶다면 이 방식을 사용하는 게 적절하다.

---
paths:
  - "src/api/**/*.ts"
---

# API 규칙

- 모든 엔드포인트에 입력 검증을 넣는다

플러그인과 스킬로 관리하기#

CLAUDE.md를 다룰 때 도움이 되는 도구 두 가지를 소개한다.

1. Andrej Karpathy의 관찰을 정리한 CLAUDE.md#

Andrej Karpathy가 공개적으로 언급해 온 "LLM이 코딩에서 자주 저지르는 실수"를, 한 커뮤니티(multica-ai)가 CLAUDE.md 형태로 정리해 GitHub에 공개했다. 저장소 설명도 "Andrej Karpathy의 관찰을 바탕으로 만든 단일 CLAUDE.md 파일"이라고 밝히고 있으며, Karpathy 본인이 배포한 것은 아니다.

내용은 약 65줄 분량으로, "흔히 발생하는 LLM 코딩 실수를 줄이기 위한 행동 지침"이다. 프로젝트별 지침과 병합해 쓰는 것을 전제로 하며, 속도보다 신중함을 택하는 트레이드오프를 깔고 있다. 핵심은 네 가지 원칙이며, 자세한 내용은 CLAUDE.md를 직접 읽어보는 것을 추천한다.

1. 코딩 전에 먼저 생각하라. 가정하지 말고 질문하라.
2. 단순하게 하라. LLM은 쉬운 코드를 복잡하게 오버엔지니어링하는 경향이 있다. 최소한의 코드만 쓰고, 추측성 코드나 요청받지 않은 기능은 만들지 않는다.
3. 외과적(surgical) 수정을 하라. 꼭 필요한 곳만 건드린다. 변경된 모든 줄은 사용자 요청과 직접 연결되어야 한다.
4. 목표 중심으로 실행하라. 성공 기준을 정의하고, 검증될 때까지 반복한다.

2. Anthropic 공식 플러그인 — claude-md-management#

Anthropic이 CLAUDE.md 관리용 공식 플러그인을 공개했다. 설치는 간단하다. GitHub 링크를 Claude에게 주고 "설치해줘"라고 하면 끝이다. 커맨드 하나와 스킬 하나를 제공한다.

• /revise-claude-md (커맨드): 현재 세션에서의 학습 — 주로 Claude가 한 실수, CLAUDE.md에 추가할 가치가 있는 정보 — 을 검토해 알맞은 CLAUDE.md(또는 CLAUDE.local.md)에 반영할 변경안을 제안한다. "이런 실수 했어, 다음엔 하지 마, CLAUDE.md 업데이트해"를 매번 손으로 시킬 필요가 없어진다. 세션 단위 반영용이다.
• claude-md-improver (스킬): 저장소에 있는 모든 CLAUDE.md를 찾아 품질 기준 — 명령어, 아키텍처 설명, 함정(gotcha), 간결성 — 에 비춰 검수한다. 예를 들어 사이드 프로젝트에 CLAUDE.md가 루트·web·API·DB용으로 여러 개 흩어져 있다면, 이 스킬을 실행해 "CLAUDE.md 품질 보고서"를 받을 수 있다. 보고서에는 발견한 파일 목록, 파일별 점수와 등급, 개선이 필요한 이슈, 우선순위가 담긴다. "내 CLAUDE.md 점검해줘"처럼 요청하면 실행된다.

직접 손으로 정돈하는 것보다 빠르고, Anthropic이 정한 품질 기준을 잣대로 삼는다. CLAUDE.md가 커질수록 이런 도구의 도움을 받아 가드레일을 깔끔하게 유지하는 편이 낫다.

맺음말#

한 걸음 떨어져서 보면, Claude Code 자체가 이미 잘 만들어진 하네스다. Anthropic의 모델들을 감싸는 하네스가 곧 Claude Code이고, Anthropic이 이 native harness를 계속 좋은 방향으로 업데이트하므로 하네스는 갈수록 좋아진다.

다만 개인 프로젝트 단위에서의 하네스를 제공해주진 않는다. 이는 지금 당장은 개인이 해야 할 일이며, 개인이 구축할 수 있는 가장 기초적인 하네스가 CLAUDE.md이다.

참고 자료#

• Claude Code Docs, How Claude remembers your project
• Claude API Docs, Prompt caching
• anthropics/claude-plugins-official, claude-md-management 플러그인
• multica-ai/andrej-karpathy-skills
• 실밸개발자, 안드레 카파시가 알려준 CLAUDE.md 의 비밀 (YouTube)