CLAUDE.md에 무엇을 써야 할까

Claude Code를 사용하고 있습니다. 하지만 Claude Code를 사용하다 보면, 리포지토리(Repository) 직하에 CLAUDE.md를 둘 수 있다는 사실을 알게 됩니다. 세션마다 자동으로 읽히는 파일입니다.

그렇다면, 거기에 무엇을 써야 할까요?

코딩 규약(Coding Convention)일까요? 디렉토리 구조에 대한 설명일까요? 사용 중인 프레임워크의 버전일까요? 무엇이든 쓸 수 있고, 실제로 그렇게 작성된 사례도 자주 봅니다.

이 기사에서 소개하는 것은 다른 관점입니다. AI가 판단에 어려움을 겪을 때, 어떻게 행동해주길 바라는가를 쓰는 방식입니다.

추상적인 이야기처럼 들릴 수 있으므로, 먼저 동작을 하나 보여드리겠습니다.

go라고만 입력했을 때

저는 clone만 한 머신에서도 AI 주도 개발(AI-Driven Development) 방법론을 정리한 리포지토리를 공개하고 있습니다. 코드는 한 줄도 들어있지 않습니다. 이 기사에 나오는 규약도, 나중에 언급할 저의 실수도, 모두 그곳에서 확인할 수 있습니다.

이것을, 그 리포지토리를 한 번도 다룬 적이 없는 머신으로 가져갔습니다.

• 새로 c:\test라는 디렉토리를 만든다
• GitHub에서 git clone 한다
• 그 폴더를 VS Code로 열고, Claude Code 확장 기능에서 go라고만 입력한다

go는 특별한 명령어가 아닙니다. 슬래시 명령어(Slash Command)도 에일리어스(Alias)도 아닌, 그저 두 글자일 뿐입니다. 제가 평소에 '재개 신호'로서 사용하고 있을 뿐인, 아무런 특징 없는 입력입니다.

돌아온 결과는 이것입니다.

요점을 정리하겠습니다.

• BACKLOG.md를 읽었다.
• 작업 일지가 존재하지 않음을 검출했다. 이 리포지토리에는 '다음에 할 일'을 적은 작업 일지가 포함되어 있지 않습니다(후술합니다). AI는 그 부재를 머신 내의 검색까지 실행하여 확인했습니다.
• 무엇을 잃게 되는지를 명시했다. "'다음 세션의 시작점'을 읽을 수 없다", "'Check Action'을 읽을 수 없다 → 재개 절차의 스텝 2를 실행할 수 없다" — 그리고, 이렇게 말하며 멈췄습니다 (요약입니다. 원문은 위 캡처와 같습니다).

작업 일지는 '사람이 이미 무엇을 했는가 = 상태'의 정본(Source of Truth)이며, 여기에만 있는 정보입니다.

추측으로 보완하여 다음 태스크를 결정하면, 팀 공통 규칙이 반복해서 경계해 온 '상태를 실측하지 않고 발화하는' 오류 그 자체가 됩니다. 따라서 여기서는 멋대로 진행하지 않고 확인을 요청했습니다.

• 그 위에서, 실측할 수 있었던 사실(git의 상태, 최근의 커밋, BACKLOG에 남아있는 태스크)만을 나열하고, 선택지를 제시하며 판정을 요구했습니다.

주목해야 할 점은 AI가 "모르겠습니다"라고 말한 것이 아닙니다. 이 리포지토리에 적혀 있는 규약을 인용하여, 자신의 행동을 스스로 제약했다는 점입니다.

게다가, 이것을 유도한 입력은 go라는 두 글자뿐입니다.

CLAUDE.md에 무엇이 적혀 있었나

정답을 말씀드리면—Claude Code는 리포지토리 직하의 CLAUDE.md를 세션 시작 시에 읽습니다 (공식 문서: "Claude reads them at the start of every session").

⚠️ 단, 동일한 문서에는 다음과 같이 명시되어 있습니다.

Claude treats them as context, not enforced configuration.

CLAUDE.md는 문맥(Context)으로 전달될 뿐, 강제되는 설정(Enforced Configuration)이 아닙니다. 확실히 막고 싶은 조작이 있다면 PreToolUse hook을 사용하라고도 적혀 있습니다.

즉, 이 기사에서 보여드린 동작은 "반드시 이렇게 된다"가 아닙니다. 오늘 한 번, 그렇게 움직였다는 기록입니다. 이 부분을 혼동하면 .md에 적은 규약이 "적용되고 있을 것"이라고 착각하게 됩니다.

그럼에도 불구하고, AI의 응답으로부터 실제로 추적할 수 있는 것은 다음 두 곳입니다.

첫 번째는 "재개 절차"입니다. 세션을 재개했을 때, 가장 먼저 무엇을 읽을지를 절차로서 적어두었습니다 (이하는 발췌입니다).

1. CLAUDE.md(현재 모드)와 작업 일지(다음에 할 일·현재 위치)를 확인한다
2. Check Action을 실행한다 —— 이전 세션의 개선 Action을, 작업에 착수하기 전에 검증한다
3. 착수 태스크가 지칭하는 파일만을 참조한다

두 번째는, 이런 문장입니다.

두 번째는, 이런 문장입니다.

저자의 환경·이전 작업(＝상태: 이미 무엇을 했는가)에 대해 기술할 때는, 실측하거나 본인에게 확인한 후 발화한다. 특히 원인 조사·경위의 재구성 시에 발화한다.

AI가 자신의 정지 이유로 인용한 것은 이 규약입니다(실물은 v1.2.0 시점의 리포지토리(Repository)에 있습니다. 본문은 향후 변경될 수 있으므로, 태그로 고정된 시점을 나타냅니다).

여기에 제가 CLAUDE.md에 대해 배운 것들이 담겨 있습니다. 이 한 문장에는 '무엇을'뿐만 아니라 '언제'가 적혀 있습니다.

비교해 보세요.

• ❌ "정확하게 작업한다" —— 무엇에 대해 실행하는지 알 수 없다. 읽어도 발화하지 않는다.
• ⭕ "상태에 대해 기술할 때는, 실측하거나 본인에게 확인한 후 발화한다. 특히 원인 조사 시에 발화한다" —— 대상과 신호가 지정되어 있다.

❌ 형태는 읽어도 발화하지 않습니다. 지켜지지 않는 것이 아니라, 실행될 장면이 지정되어 있지 않기 때문에 지킬 방법이 없기 때문입니다. 공식 문서도 같은 내용을 더 짧게 쓰고 있습니다. "Format code properly"가 아니라 "Use 2-space indentation"이라고 쓰라고 말이죠.

무엇을 배포하고, 무엇을 배포하지 않을 것인가

방금 "작업 일지가 포함되어 있지 않다"라고 썼습니다. 이것은 설계입니다.

이 리포지토리는 공개하고 있지만, "다음에 할 일", "지금 어디까지 진행되었는가", "언제 작업했는가"를 적은 파일은 들어있지 않습니다. 그것들은 별도의 리포지토리에 두고 공개하지 않습니다.

이유는 그것이 방법론이 아니라 작성자의 생활 기록이기 때문입니다. 하나하나의 기술은 무해하더라도, 시계열로 쌓이면 가동 경향이 형체를 드러냅니다.

처음에는 같은 리포지토리 안에 두고 .gitignore로 제외했습니다. 이것은 그만두었습니다. 제외하면 변경 사항을 차분(Diff)으로 확인할 수 없게 되어, AI가 다시 쓴 내용이 리뷰 대상에서 벗어나기 때문입니다. 지금은 독립된 리포지토리로서 git 관리하고 있습니다.

결과적으로 다음과 같이 분할되어 있습니다.

서두의 테스트에서 일어난 일은 이 분할이 그대로 동작에 나타난 것입니다. 규율은 clone에 따라왔기에 발화했다. 기록은 따라오지 않았기에, AI는 올바르게 멈췄다.

솔직하게 쓰기 —— 배포하지 않으면 무엇이 곤란한가

여기서부터는 잘 풀리지 않은 이야기입니다.

앞선 테스트에는 뒷이야기가 있습니다. AI가 제시한 선택지 중 "이 머신에는 없다"를 선택하여 그대로 진행하도록 했습니다.

• AI는 Check Action을 스킵할 것을 명시적으로 선언했습니다. "의도적으로 건너뛴 것을 기록으로 남긴다"라는 취지를 덧붙여서 말이죠. 묵묵히 건너뛰지 않은 점은 규율이 작동하고 있다고 해도 좋을 것 같습니다. - 그리고 BACKLOG.md를 기점으로, 착수 후보 3건을 제시했습니다.

문제는 그 내용이었습니다. 3건 모두 저의 과제였던 것입니다.

"Zenn 기사 1건 쓰기", "요건 리뷰용 Skill의 초회 운용 검증", "완료된 항목의 뒷정리" —— clone한 사람이 자신의 업무로 연결할 수 있는 것은 단 하나도 없습니다.

즉, 폴백(Fallback, 작업 일지가 없으면 BACKLOG.md를 기점으로 삼는다)은 기점을 제공하는 데는 성공했지만, 의미 있는 기점을 제공하는 데는 실패했다. 이것은 오늘 알게 되었습니다.

게다가 후보 중 3번째는 이미 끝난 항목이었습니다. 전날 AI가 README에 절을 쓰고, 동일한 커밋으로 BACKLOG 측에 "대응 완료"라고 쓰고 그대로 남겨두었습니다. "끝난 항목은 지운다"라는 규약은 리포지토리에 적혀 있습니다. 규약은 있고, AI는 따르지 않았으며, 그리고 저는 그 차분(Diff)을 승인했습니다. 제 환경에서는 익숙한 잔해이지만, 타인의 환경에서는 선택지로서 제시되는 것입니다.

심지어 이 잔해는 그로부터 약 1분 뒤에 입력한 v1.2.0 태그에 그대로 들어있습니다.

태그는 나중에 수정할 수 없으므로, 지금 v1.2.0

v1.2.0를 clone 한 사람에게는 오늘도 보입니다. 그리고 애초에 말하자면——독자는 go라고 입력하는 법을 모릅니다. 그것은 명령어가 아니라, 셋업(Setup) 절차서에 "작가는 이렇게 운용하고 있다"라고 적혀 있을 뿐인 관행입니다. 오늘의 테스트가 성립할 수 있었던 것은, 제가 알고 있었기 때문입니다.

이 기사를 쓰기 직전, 내 리포지토리(Repository)의 단정 하나가 거짓임을 알게 되었다

사실, 위의 테스트를 수행하기 전까지 제 리포지토리에는 이렇게 적혀 있었습니다.

clone 한 독자가 같은 일을 해도

아무 일도 일어나지 않는다 —— 읽을 대상이 존재하지 않기 때문에.

실측해 보니 거짓이었습니다. 아무 일도 일어나지 않기는커녕, AI는 부재를 감지하고, 규약(Convention)을 인용하며, 판결을 요구하며 멈춰 섰습니다.

이 내용이 실린 이유는, 아무도 한 번도 실행하지 않은 채 작성되었고, 그대로 승인되었기 때문입니다. "읽을 파일이 없다 → 아무 일도 일어나지 않는다"라는 것은, 부재라는 사실로부터 거동을 추론한 것이지, 확인한 결과가 아니었습니다.

이 단정은 공개한 초판의 커밋(Commit)부터 실려 있었고, 정정 커밋을 할 때까지 약 2일 18시간 반 동안 아무도 눈치채지 못했습니다.

이는 저에게 큰 수확이었습니다. "~해도 소용없다", "~는 작동하지 않는다"와 같은 부정형의 단정에는, 반증할 기회가 자연스럽게 찾아오지 않습니다. 긍정형의 주장은 사용하면 깨지기 마련이지만, 부정형의 주장은 아무도 시도하지 않기 때문에, 거짓인 채로 조용히 살아남습니다.

같은 곳에서, 차원이 다른 규모로도 도달하는 듯하다

이것은 저의 실수이지만, 구조적으로는 개인의 부주의 때문만은 아니라고 생각합니다. AI가 작성하면 산출물은 빨라지지만, 검사(Inspection)만이 인간의 속도에 머뭅니다. 단위 시간당 "아직 아무도 검사하지 않은 기술(Description)"이 늘어납니다 —— 이번에는 그것이 거짓된 단정으로서 3일이 채 안 되는 시간 동안 그대로 남아 있었습니다.

비슷한 이야기가 비교도 안 될 만큼 큰 규모에서도 일어나고 있는 듯합니다. Anthropic의 Head of Claude Code인 Boris Cherny 씨는, Fortune Brainstorm Tech에서 "I haven't written a line of code by hand in, I think, eight months now"라고 말했다고 보도되었습니다 (Fortune · 2026년 6월 11일 자). 그리고 Fortune은 이 변화를 "Code review became the new constraint."라고 요약했습니다. ⚠️ 이 요약은 기자의 말이며, Cherny 씨 본인의 발언이 아닙니다.

저에게 와닿은 것은, 씨 본인의 발언으로 보도된 대책 쪽입니다 —— 서로 다른 페르소나(Persona)를 부여한 여러 Claude가 풀 리퀘스트(Pull Request) 리뷰에서 협업한다.

제 리포지토리에도 "크로스 리뷰(Cross-review)"라는 방법론이 적혀 있습니다. 그리고 지식의 활성화를 나열한 표에서는, 여전히 "미착수(실물 없음)" 상태로 남아 있습니다. 적혀 있는 것과 움직이고 있는 것은 별개다 —— 라는 저 자신의 주장을, 저 자신의 BACKLOG에 직면하게 된 셈입니다.

이 기사 자체는 어떻게 만들어졌는가

먼저 전제 하나를 적어두겠습니다. 이 리포지토리의 .md는 제가 직접 작성한 것이 아닙니다. 제가 하는 일은 지적·상담·판결이며, 파일로의 출력과 편집은 모두 AI 측에서 수행합니다. 이 운용 방식은 현재의 리포지토리 이전부터 계속되어 왔기에, 초기에 제 손으로 직접 쓴 원형은 이제 남아 있지 않습니다.

⚠️ 미리 말씀드리자면, 어디까지를 AI가 작성했는가는 저의 신고에 따릅니다. git의 이력(History)을 통해 알 수 있는 것은, 커밋의 작성자(Author)가 모두 저라는 사실과, 대부분의 커밋에 Co-Authored-By: Claude Opus 4.8이 붙어 있다는 것( v1.2.0 시점에서 14건 중 12건) —— 즉 AI가 관여했다는 사실까지이며, 분담 비율은 이력에 남지 않습니다.

그럼에도 불구하고, 이 기사는 저와 Claude Opus 4.8의 주고받음(Back-and-forth)을 통해 작성되었습니다. "공저입니다"라고 쓰는 것보다, 오늘의 주고받음을 하나 보여주는 것이 빠를 것 같아 그렇게 하겠습니다.

기사의 뼈대가 되는 초안을 낸 것은 AI 측이었으며, 다음과 같았습니다 —— "clone 하면 세션을 이어가는 경험을 얻을 수 있다".

저는 이렇게 지적했습니다. 독자는 이 리포지토리가 private이었던 시절을 모르며, 저 자신도 퍼블릭 리포지토리(Public Repository)만 있는 상태에서 테스트해 본 적이 없다고 말입니다.

그래서 실제로 측정한 것이 이 기사 서두에 있는 테스트입니다. 결과적으로, AI의 초안은 "저자의 환경에서만 성립하는 주장"이라는 것을 알게 되었습니다. 덤으로, 리포지토리에 적혀 있던 단정적인 표현("아무 일도 일어나지 않는다")마저 거짓임을 알게 되었습니다.

반면, 반대의 경우도 있었습니다. 이 기사의 초고에는 "CLAUDE.md에 쓰면 AI는 그렇게 동작한다"라고 읽힐 수 있는 서술 방식이 남아 있었는데, 그것을 바로잡은 것은 AI 측이었습니다 —— 공식 문서를 찾아보고 "context(컨텍스트)일 뿐 강제 설정이 아니다"라는 기술을 가져왔습니다.

따라서 정확히 말할 수 있는 범위는 여기까지입니다. 생성과 검사의 왕복이 있었고, 오늘 가장 큰 오류를 바로잡은 기점은 인간의 지적이었다. 그리고 AI 측이 바로잡은 오류도 별도로 있었다. 어느 한쪽으로 치우쳐서 쓰면 실태와 다른 내용이 됩니다.

이 리포지토리가 누구에게 적합한가

이 가이드는 두 층위의 독자를 상정하고 있습니다.

• 생성 AI와의 협업을 규율하고 싶은 인간
• .md를 읽어 들여 동작하는 AI 도구 자체 (Claude Code 등)

.md는 "읽는 대상"인 동시에 "로드하여 실행하는 대상"이기도 하다는 전제하에 작성되었습니다. 오늘의 테스트는 후자가 실제로 실행된 기록입니다.

다만, 두 층위라고 해서 "AI를 위한 것이 주 목적"이라는 의미는 아닙니다. 인간의 판단이 항상 상위에 있으며, AI는 그것을 빠르게 발화·검사하는 쪽에 있습니다.

또 하나, 방침으로 정해둔 것이 있습니다. 망라하는 것이 아니라, 판단을 읽어낼 수 있는 것에 가치를 둔다 —— 그래서 아직 검증하지 못한 사항의 목록 (BACKLOG)과 자신의 오류를 정정한 기록을 동일한 리포지토리 안에 공개하고 있습니다. 이 기사의 바로 앞 절도 그 일부입니다.

원래 무엇을 하고 싶었는가

이 리포지토리의 출발점은 제가 개인용으로 키워오던 .md 군(群)이었습니다.

의도는 단순합니다. 자신의 업무 리포지토리의 AI에게 이 .md 군을 읽히게 하여 확장하는 것입니다. 프로젝트 고유의 지식은 프로젝트 측에 두고, 진행 방식의 규율은 공통된 .md로부터 공급한다는 식으로 나누는 것을 생각했습니다. ⚠️ 이 부분은 솔직하게 적겠습니다. 이 가이드를 다른 프로젝트에 적용한 실적은 공개 이후 아직 없습니다.

private(비공개)였던 시기의 운용은 공개된 쪽에 기록이 남아 있지 않아 검증할 수 있는 형태가 아닙니다. 따라서 "이것을 넣으면 생산성이 올라간다"라고는 쓸 수 없습니다. 이 기사에서 쓸 수 있는 것은 설계 의도와, 오늘 실제로 측정한 하나의 동작까지입니다.

오늘부터 시도할 수 있는 최소한의 것

CLAUDE.md를 한 장 써보는 것만으로도 충분하다고 생각합니다. 쓰는 내용은 우선 세 가지만 있으면 될 것입니다.

이 리포지토리가 무엇인지, 어떤 파일이 무엇을 담당하는지
세션을 재개할 때 가장 먼저 무엇을 읽을지
AI가 판단에 어려움을 겪을 때 어떻게 행동할지

오늘 보여드린 동작을 실제로 만든 것은 세 번째 항목입니다. 1과 2는 AI가 리포지토리를 보면 추측할 수 있는 것도 많습니다. 하지만 3은 쓰지 않으면 발화하지 않습니다.

그리고 3을 쓸 때는, "언제 발화할지"를 덧붙여 주세요. "정확하게 한다"가 아니라 "상태에 대해 말할 때는, 실제로 측정하거나 확인한 뒤에 발화한다"와 같이 말입니다. 이 차이가, 단순히 읽히기만 하는 규약과 AI가 자신을 멈추기 위해 인용하는 규약을 가릅니다.

리포지토리는 여기 있습니다. 미검증 목록도, 정정 기록도 그대로 두었습니다.

Discussion