▲

좋은 Claude.md 작성법

 (humanlayer.dev)
58P by GN⁺ 3일전 | ★ favorite | 댓글 1개
  • LLM은 상태를 저장하지 않는 함수이므로, CLAUDE.md는 매 세션마다 Claude에게 코드베이스를 소개하는 핵심 문서로 작동함
  • 파일에는 프로젝트의 WHAT(구조) , WHY(목적) , HOW(작동 방식) 을 간결히 담아야 하며, 불필요한 명령어 과잉은 성능 저하로 이어짐
  • Claude는 시스템 메시지의 지시에 따라 CLAUDE.md의 내용을 관련성이 낮다고 판단하면 무시할 수 있음
  • 효과적인 파일은 짧고 보편적으로 적용 가능한 정보만 포함하고, 세부 지침은 별도 문서로 분리해 Progressive Disclosure 방식으로 관리해야 함
  • CLAUDE.md는 에이전트 하니스의 가장 높은 영향 지점이므로 자동 생성 대신 신중하게 수작업으로 작성해야 함

LLM의 무상태성과 CLAUDE.md의 역할

  • LLM은 추론 시점에 고정된 가중치를 사용하며, 세션 간 학습이나 기억을 유지하지 않음
    • 따라서 모델이 코드베이스를 이해하려면 입력 토큰으로 모든 정보를 제공해야 함
  • Claude Code 같은 코딩 에이전트는 메모리를 명시적으로 관리해야 하며, CLAUDE.md는 모든 대화에 자동 포함되는 유일한 파일임
  • 이로 인해 다음 세 가지가 필수적임
    1. 세션 시작 시 Claude는 코드베이스에 대해 아무것도 모름
    2. 매 세션마다 필요한 정보를 다시 알려야 함
    3. 이를 위한 표준 수단이 CLAUDE.md임

코드베이스 온보딩: WHAT, WHY, HOW

  • CLAUDE.md는 Claude가 프로젝트를 이해하도록 돕는 온보딩 문서 역할을 함
    • WHAT: 기술 스택, 프로젝트 구조, 모노레포 구성 등 코드 지도를 제공
    • WHY: 각 구성 요소의 목적과 기능을 설명
    • HOW: 빌드·테스트·타입체크 등 실제 작업 수행 방법을 명시
  • 단, 모든 명령어를 나열하는 것은 비효율적이며, 필요 최소한의 정보만 포함해야 함

Claude가 CLAUDE.md를 무시하는 이유

  • Claude Code는 사용자 메시지에 다음과 같은 시스템 리마인더를 삽입함 
    IMPORTANT: this context may or may not be relevant...
    • 이로 인해 Claude는 해당 문맥이 현재 작업과 관련 없다고 판단하면 무시함
  • 파일에 보편적이지 않은 지시사항이 많을수록 무시될 가능성이 커짐
  • Anthropic이 이를 추가한 이유는, 불필요한 지시를 무시할 때 결과 품질이 향상되었기 때문으로 추정됨

좋은 CLAUDE.md 작성 원칙

Less (instructions) is more

  • LLM은 약 150~200개의 지시사항을 안정적으로 따를 수 있음
    • 작은 모델일수록 성능 저하가 급격하며, 다단계 작업에는 부적합
  • Claude Code의 시스템 프롬프트에는 이미 약 50개의 지시사항이 포함되어 있음
    • 따라서 CLAUDE.md에는 보편적이고 필수적인 지시만 최소한으로 포함해야 함
  • 지시 수가 늘수록 전체 지시 수행 품질이 균등하게 저하됨

파일 길이와 적용 범위

  • LLM은 집중적이고 관련성 높은 문맥에서 더 잘 작동함
  • CLAUDE.md는 모든 세션에 포함되므로, 보편적으로 적용 가능한 정보만 유지해야 함
  • 일반적으로 300줄 미만, 가능하면 더 짧게 유지하는 것이 권장됨
    • HumanLayer의 예시 파일은 60줄 미만

Progressive Disclosure

  • 대형 프로젝트에서는 모든 정보를 한 파일에 담기 어렵기 때문에, 점진적 공개(Progressive Disclosure) 방식을 권장
    • 세부 지침은 agent_docs/ 폴더 내 별도 마크다운 파일로 분리
    • 예: building_the_project.md, running_tests.md, code_conventions.md 등
  • CLAUDE.md에는 이 파일들의 목록과 간단한 설명, 그리고 Claude가 필요 시 읽도록 하는 지시만 포함
  • 코드 스니펫 대신 file:line 참조를 사용해 최신성을 유지
  • 이는 Claude Skills 개념과 유사하나, 도구 사용보다는 지시 관리에 초점

Claude는 린터가 아님

  • 코드 스타일 가이드라인을 CLAUDE.md에 포함하는 것은 비효율적임
    • LLM은 비용이 높고 느리며, 린터보다 비결정적임
  • 스타일 규칙은 기존 코드 패턴을 통해 자연스럽게 학습되므로 별도 지시 불필요
  • 포맷팅은 자동 수정 가능한 린터(Biome 등) 를 활용하고, Claude에는 수정 결과만 전달
  • 필요 시 Stop Hook이나 Slash Command를 사용해 포맷팅·검증을 자동화

자동 생성 금지

  • /init 명령이나 자동 생성 기능으로 만든 CLAUDE.md는 비추천
    • 이 파일은 모든 세션과 산출물에 영향을 미치는 고레버리지 지점이기 때문
  • 잘못된 한 줄의 지시가 전체 코드 품질에 연쇄적 악영향을 줄 수 있음
  • 따라서 모든 문장을 신중히 검토하고 수작업으로 작성해야 함

결론

  • CLAUDE.md는 Claude를 코드베이스에 온보딩하기 위한 문서로, WHY·WHAT·HOW를 명확히 정의해야 함
  • 지시사항은 최소화하고, 보편적이고 간결한 내용만 포함
  • Progressive Disclosure를 통해 필요한 정보만 단계적으로 제공
  • Claude를 린터로 사용하지 말고, 전용 도구와 훅·명령어 기능을 병행 활용
  • 자동 생성 대신 신중한 수작업 작성으로 하니스 전체 품질을 극대화해야 함
▲
GN⁺ 3일전  [-]
Hacker News 의견

  • Claude가 종종 CLAUDE.md의 지시를 무시하는 경향이 있음
    파일에 특정 작업과 관련 없는 정보가 많을수록 Claude가 그 지시를 따르지 않게 됨
    친구가 Claude에게 자신을 “Mr Tinkleberry”라고 부르라고 했는데, Claude가 그걸 잊을 때마다 파일을 무시하고 있다는 걸 알 수 있었음

  • 나는 예전부터 Table-of-Contents 접근법을 써왔음
    작업별 지침을 각각의 markdown 파일로 분리하고, CLAUDE.md에는 그 목록과 간단한 설명만 넣음
    이렇게 하면 context window가 깔끔하게 유지됨
    내 예시 파일은 여기에서 볼 수 있음

    • 나도 같은 방식을 써봤지만 결과가 들쭉날쭉했음
      Claude가 다른 문서 파일들을 실제로 읽는 경우가 거의 없었음

  • 나는 Claude에게 너무 많은 context를 주면 오히려 품질이 떨어진다고 느꼈음
    그래서 항상 두 가지 버전의 코드를 유지함

    1. 주석과 공백이 없는 원본 코드
    2. 주석이 포함된 코드
      LLM에는 첫 번째 버전만 줌
      Compute 대 정보 비율이 핵심이라고 생각함. 계산량은 한정되어 있으니까
    • 나도 비슷한 경험을 했지만, 반복되는 내용을 Claude notes 파일에 넣으니 효율이 높아졌음
      모든 걸 넣을 필요는 없지만 핵심 정보를 넣는 건 ROI가 높았음
      Claude는 일반적인 프로젝트에서는 잘 작동하지만 새로운 프레임워크나 툴에서는 자주 혼란스러워함
    • 두 가지 코드 버전을 유지한다고 했는데, 그 일관성을 어떻게 관리하는지 궁금함
      수정 후 주석과 공백을 제거하는 스크립트를 쓰는지 묻고 싶음
    • 문서 파일 내에서는 정보 밀도를 높게 유지해야 한다고 생각함
    • LLM에 주석이 포함된 버전을 주지 않는다고 했는데, 실제로 그걸 어떻게 구현하는지 궁금함
    • 결국 attention은 유한함. context를 과하게 넣으면 집중이 분산됨

  • 사실 이런 복잡한 설정 없이도 해결 방법이 있음
    바로 코드를 명확하게 문서화(documenting) 하는 것임
    각 파일이 무엇을 하는지 간결하게 적으면 그것이 곧 프롬프트 역할을 함
    README.md를 적극적으로 활용하면 됨
    LLM은 이미 공개된 정보로 학습되었기 때문에 새로운 걸 발명할 필요는 없음

    • 하지만 AI를 대상으로 문서를 쓸 때는 인간 독자용 문서와는 다른 방식이 필요함
      단순히 “코드를 잘 문서화하라”는 조언은 이 맥락에 맞지 않음
    • 나도 AI 커뮤니티가 종종 불필요하게 바퀴를 다시 발명한다고 생각함
      README는 좋지만 CLAUDE.md에는 다른 목적이 있음
      예를 들어 Claude/agents.md는 특정 디렉터리에 접근할 때 자동으로 context에 삽입되는 기능이 있음
      복잡한 코드베이스에서는 context 관리가 훨씬 중요함
    • CLAUDE.md는 단순한 문서가 아니라 모델의 초기 프롬프트를 커스터마이즈하는 역할을 함
      그래서 “적절히 프롬프트를 작성하라”는 조언은 핵심을 놓친 것임
    • 예를 들어 “데이터베이스 쿼리가 항상 인덱스를 사용해야 한다”는 규칙을 어디에 적을까?
      README에 넣으면 결국 CLAUDE.md와 같은 역할을 하게 됨
      CLAUDE.md의 목적은 Claude가 매번 모든 문서를 다시 읽지 않도록 핵심 정보를 미리 주는 것임
      인간은 기억하지만 Claude는 매 작업마다 잊기 때문에, 재온보딩을 줄이는 구조가 필요함

  • 솔직히 이렇게까지 AI 인프라를 세팅해야 한다면 그냥 내가 직접 코딩하는 게 낫다고 느낌

    • 하지만 스타일 관련 설정은 한 번만 해두면 재사용 가능함
      나는 공통 규칙과 프로젝트별 규칙을 분리해서 관리함
    • 기사에서 말한 세팅은 몇 시간 정도면 끝남
      AI를 안 쓰는 건 단순히 생산성 손실임
    • 대부분의 초기 설정은 LLM에게 맡길 수도 있음
    • 사실 그렇게 큰 노력이 들지 않음. 도구를 과하게 최적화하려는 게 문제임
    • 중요한 건 비용이 반복되는가, 일회성인가임
      설정이 한 번만 필요하다면 충분히 투자할 가치가 있음
      “세팅이 귀찮다”는 건 디버거 설정을 회피하는 사람들의 변명과 비슷함

  • 나는 그냥 필요한 코드를 복사해서 대화창에 붙여넣고 대화하듯 사용함
    요즘은 모델이 많이 개선돼서 .md 파일이 없어도 꽤 괜찮은 결과를 줌
    이런 파일들이 약간의 개선은 줄 수 있겠지만, 생산성 100배의 마법은 아니라고 생각함

    • 하지만 이건 다른 사용 사례임
      여기서 논의하는 건 Claude가 전체 기능 구현이나 버그 수정을 스스로 수행하는 경우임
    • 나도 비슷한 경험임. CLAUDE.md를 한 번 만들어봤지만 지금은 안 씀
      그냥 필요한 context만 주면 충분히 잘 작동함. 약간 bikeshedding 같음
    • 그래도 데이터베이스 테이블이나 컬럼 목록 정도는 미리 정리해두면 반복을 줄일 수 있음

  • 나는 Claude에게 CLAUDE.md를 직접 작성하게 함
    “README.md는 사용자용, CLAUDE.md는 너용”이라고 알려주면
    “API 문서를 항상 확인하라” 같은 지시도 자동으로 업데이트해줌
    마법 같은 프롬프트를 몰라도 결과만 잘 나오면 됨

    • 하지만 AI가 스스로 쓴 지시가 인간이 쓴 것보다 낫다는 증거가 있는지는 의문임
      AI가 자기 자신을 가장 잘 프롬프트할 이유는 없어 보임
답변달기