SKILL은 특정 태스크 호출형 지시서입니다. 그렇다면 프로젝트 전체에 항상 적용하고 싶은 규칙은 어디에 적어야 할까요.

그 답이 CLAUDE.md입니다.

리포지토리 루트(Repository root)에 두기만 하면, Claude Code가 기동될 때마다 자동으로 읽어 들여 줍니다. 이 기사에서는 agent01 리포지토리의 실제 CLAUDE.md를 소재로, 작성법·키우는 법·SKILL.md와의 구분 사용법을 해설합니다.

시리즈 구성

CLAUDE.md란 무엇인가

CLAUDE.md는 Claude Code가 기동 시 자동으로 읽어 들이는 프로젝트 전용 지시서입니다. 배치 장소는 리포지토리 루트의 CLAUDE.md로 고정되어 있으며, 한 번 작성하면 매 세션마다 읽힙니다.

SKILL.md와의 차이점을 정리하면 다음과 같습니다.

CLAUDE.md의 구조

agent01 리포지토리의 CLAUDE.md는 다음과 같은 섹션 구성으로 되어 있습니다.

## 프로젝트 개요
## 작업 진행 방식
## 코딩 규약
...

각 섹션의 역할을 살펴보겠습니다.

프로젝트 개요 — Claude Code에 프로젝트의 목적·배경을 전달합니다. agent01에서는 「소스 코드의 개량·보수를 지원하는 AI 에이전트」라는 문구와 관련 리포지토리의 URL을 기재하고 있습니다.

작업 진행 방식 — 세션 시작 시의 행동 절차를 정의합니다. agent01에서는 「처음 읽을 파일의 순서 (PROGRESS.md → AGENT_SPEC.md → 구현 지시서)」를 명기하고 있습니다.

작업 시작 시에는 다음 순서로 읽을 것.
1. `PROGRESS.md` ← 현재 위치·전달 사항을 확인
2. `AGENT_SPEC.md` ← 사양·설계를 확인
...

이것을 적어 두는 것만으로도, 매번 「먼저 PROGRESS.md를 확인해줘」라고 말할 필요가 없어집니다.

코딩 규약 — 명명 규칙(Naming convention)·타입 어노테이션(Type annotation)·파일 구성 등의 코드 품질 기준을 기재합니다. agent01에서는 PascalCase·snake_case·UPPER_SNAKE_CASE의 구분 사용이나, Google 스타일의 docstring을 정의하고 있습니다.

Git 운용 규칙 — 커밋 메시지의 프리픽스(Prefix)와 브랜치 운용 규칙입니다. agent01에서는 프리픽스를 표로 정의하고 있습니다.

| 프리픽스 | 용도 |
|---|---|
| `feat:` | 기능 추가 |
...

금지 사항 — 해서는 안 되는 조작을 명시합니다. agent01에서는 .env 파일에 대한 액세스·API 키를 포함한 파일의 커밋·테스트 미확인 상태에서의 커밋 등을 금지 사항으로 열거하고 있습니다. 이것들을 적어 둠으로써 의도치 않은 사고를 미연에 방지할 수 있습니다.

CLAUDE.md를 키우기

CLAUDE.md는 처음부터 완벽하게 작성할 필요가 없습니다. 사용하면서 키워 나가는 것입니다.

실제 키우는 방법으로는, 「매번 똑같은 주의를 주게 된다」고 느꼈을 때 금지 사항이나 작업 절차에 추가하기, 「Claude Code가 의도와 다르게 동작했다」고 느꼈을 때 해당 규칙을 구체화하기, 「새로운 규약을 정했다」고 느꼈을 때 코딩 규약 섹션에 추가하기 등이 있습니다.

Claude Code와 함께 일하다 보면, 「이 지시는 매번 말하고 있다」, 「또 여기서 헤맸다」는 깨달음이 쌓입니다. 그 깨달음을 CLAUDE.md에 써 내려감으로써 프로젝트에 최적화된 지시서가 자연스럽게 성장해 나갑니다. agent01에서는 13개의 Step을 통해 CLAUDE.md에 조금씩 추가하여 최종적으로 지금의 형태가 되었습니다.

헤맨 점·깨달은 점

CLAUDE.md에 너무 많은 내용을 작성하면 로딩이 무거워져 Claude Code의 응답(Response)에 영향을 미칩니다. '항상 필요한 것'으로 내용을 압축하는 것이 중요합니다. 특정 태스크의 절차는 SKILL.md로 옮긴다는 판단이 중요해집니다. 초반에는 SKILL.md에 넣어야 할 내용을 CLAUDE.md에 작성해 버리는 실수를 자주 하게 됩니다.

'금지 사항' 섹션은 처음부터 충실하게 작성해 두는 것이 효과적입니다. .env 파일의 편집 금지나 API 키를 포함한 커밋 금지 등, 한 번이라도 발생하면 곤란한 작업은 미리 명시해 두는 것이 좋습니다. 또한, CLAUDE.md를 Git으로 관리하면 팀 내에서 공유 및 버전 관리(Version Control)를 할 수 있습니다. 어느 시점에 어떤 규칙을 추가했는지 git log를 통해 확인할 수 있다는 점도 장점입니다.

요약

CLAUDE.md는 'Claude Code를 위한 프로젝트 설명서 겸 행동 지침'입니다. 리포지토리 루트(Repository Root)에 두는 것만으로 매 세션에 적용되며, 코딩 규약, Git 운용, 금지 사항 등을 Claude Code에 항상 지속적으로 전달해 줍니다.

CLAUDE.md(상시 적용)와 SKILL.md(호출형)의 2층 구조로 지시를 관리함으로써, Claude Code에 대한 지시가 정리되고 매번 같은 내용을 전달해야 하는 번거로움이 사라집니다. Series C에서 소개했던 '외부 파일을 통한 지시 관리'의 마무리로서, 꼭 CLAUDE.md를 프로젝트에 도입해 보시기 바랍니다.

시리즈 링크 (Series C)

Discussion