# 좋은 Claude.md 작성법 > Clean Markdown view of GeekNews topic #24744. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=24744](https://news.hada.io/topic?id=24744) - GeekNews Markdown: [https://news.hada.io/topic/24744.md](https://news.hada.io/topic/24744.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2025-12-01T10:33:06+09:00 - Updated: 2025-12-01T10:33:06+09:00 - Original source: [humanlayer.dev](https://www.humanlayer.dev/blog/writing-a-good-claude-md) - Points: 78 - Comments: 1 ## Summary LLM이 **무상태 함수**라는 전제에서 출발해, `CLAUDE.md`는 매 세션마다 Claude에게 코드베이스를 “소개”하는 핵심 온보딩 문서로 작동합니다. 이 파일에는 프로젝트의 **WHAT·WHY·HOW**를 간결하게 담는 것이 중요한데, 지시사항을 과하게 넣으면 오히려 **모델의 추론 품질이 떨어질 수 있다**고 말합니다. 더 복잡한 설명은 `agent_docs/`로 분리하는 **Progressive Disclosure** 방식이 권장되며, 자동 생성 문서보다 **신중하게 손으로 직접 작성하는 문서**가 훨씬 낫다고 강조합니다. 결국 `CLAUDE.md`는 단순한 설정 파일이 아니라, 에이전트가 어떤 방식으로 사고하고 문제를 풀지 정의하는 일종의 인터페이스라는 점을 다시 확인하게 됩니다. ## Topic Body - **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를 린터로 사용하지 말고, **전용 도구와 훅·명령어 기능**을 병행 활용 - 자동 생성 대신 **신중한 수작업 작성**으로 하니스 전체 품질을 극대화해야 함 ## Comments ### Comment 47020 - Author: neo - Created: 2025-12-01T10:33:07+09:00 - Points: 1 ###### [Hacker News 의견](https://news.ycombinator.com/item?id=46098838) - Claude가 종종 **CLAUDE.md**의 지시를 무시하는 경향이 있음 파일에 특정 작업과 관련 없는 정보가 많을수록 Claude가 그 지시를 따르지 않게 됨 친구가 Claude에게 자신을 “Mr Tinkleberry”라고 부르라고 했는데, Claude가 그걸 잊을 때마다 파일을 무시하고 있다는 걸 알 수 있었음 - 나는 예전부터 **Table-of-Contents 접근법**을 써왔음 작업별 지침을 각각의 markdown 파일로 분리하고, CLAUDE.md에는 그 목록과 간단한 설명만 넣음 이렇게 하면 **context window**가 깔끔하게 유지됨 내 예시 파일은 [여기](https://gist.github.com/scpedicini/179626cfb022452bb39eff10becb95fa)에서 볼 수 있음 - 나도 같은 방식을 써봤지만 결과가 들쭉날쭉했음 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가 자기 자신을 가장 잘 프롬프트할 이유는 없어 보임