Claude Code로 Laravel 앱을 하나 완성해 나가는 과정에서, CLAUDE.md를 작성하는 방법에 대해 고민한 내용을 정리합니다.

결론부터 말하자면, CLAUDE.md를 「AI에게 읽히는 README」라고 생각하고 작성하면 실패합니다.

README와 CLAUDE.md는 독자도 목적도 다르다

README는 인간을 위한 설명 문서입니다. 프로젝트를 이해시키기 위해 작성합니다.

반면 CLAUDE.md는 세션마다 AI가 다시 읽는 **행동 강령 (Code of Conduct)**입니다.

이 차이는 작성해야 할 내용과 직결됩니다.

개요와 절차를 적는 것에 만족해 버리면, 「읽히기는 하지만 행동은 제어하지 못하는」 CLAUDE.md가 됩니다.

3가지 원칙

실제로 작성하고 운용해 보니, 제대로 기능하는 조문에는 공통된 형식이 있다는 것을 깨달았습니다.

원칙 1: 「해주길 바라는 것」보다 「하지 말아야 할 것」을 적는다

AI는 능력이 높은 만큼, 내버려 두면 「일반적인 베스트 프랙티스 (Best Practice)」대로 작성합니다.

자신의 프로젝트 스타일이 일반론과 어긋나는 부분이야말로 명문화할 가치가 있습니다.

- Blade + 바닐라 JS (SPA 프레임워크는 사용하지 않음)
- Pest (PHPUnit 표기법은 사용하지 않음)

괄호 안의 부정형이 핵심입니다. Laravel의 학습 데이터에는 Vue/React가 혼재된 코드나 PHPUnit 표기법의 테스트가 대량으로 포함되어 있기 때문에, 명시적으로 금지하지 않으면 혼입됩니다.

원칙 2: 판단 기준까지 전달한다

「테스트를 작성해 줘」가 아니라 「Pest 표기법으로, Factory를 사용하고, RefreshDatabase를 사용하여」라고 해야 합니다.

모호함을 남겨두면 세션마다 다른 방식으로 작성합니다.

- 기능 추가·변경 시에는 반드시 대응하는 Feature 테스트를 작성할 것 (Pest 표기법)
- 테스트 DB는 RefreshDatabase를 사용한다
- Factory를 반드시 준비한다. 테스트 내에서 수동 INSERT 하지 않는다

원칙 3: 사고를 방지하는 명령은 「금지 + 대체 수단」 세트로 작성한다

「~하지 마라」라고만 하면 AI는 목적 달성을 위해 다른 경로를 찾습니다.

올바른 우회로까지 지정하는 것이 포인트입니다.

- 마이그레이션 실행 (migrate, migrate:fresh 등)을 무단으로 수행하지 않는다.
  명령어를 제시하고 승인을 기다린다.

「무단으로 실행하지 마라」가 아니라 「명령어를 제시하고 승인을 기다려라」입니다.

금지만 하면 목적(마이그레이션 실행)은 남은 상태이기 때문에, AI는 다른 방법을 찾기 쉽습니다. 올바른 행동으로 이어지는 경로까지 보여줌으로써 우회 자체를 방지할 수 있습니다.

가장 효과적이었던 조문: 테스트 skip화 금지

운용하면서 실제로 효과를 실감한 조문이 이것입니다.

## 금지 사항
- 기존 테스트의 삭제·skip화로 「테스트를 통과시키는」 행위

테스트가 통과되지 않을 때, AI는 구현을 수정하는 대신 테스트를 약화시키려는 유혹에 빠질 때가 있습니다. 이는 태만이라기보다, 「태스크를 완료시키고 싶다」는 목적에 대해 합리적인 지름길로 보이기 때문입니다. 명시적으로 봉쇄함으로써 구현을 수정하는 방향으로 유도할 수 있습니다.

CLAUDE.md는 「키워 나가는 문서」

가장 중요한 운용 규칙은 이것입니다. CLAUDE.md는 처음부터 완벽할 필요가 없으며, AI의 일탈을 관측할 때마다 조문을 추가해 나가는 것이라고 생각합니다.

실제로 개발 중에 AI가 요구 정의에 「권한 부여(Authorization)는 나중에 구현」이라고 적혀 있음에도 불구하고, 보안상의 이유로 Policy를 앞서서 구현해 온 적이 있었습니다. 나쁜 사례는 아니었고, 선언을 동반한 제안이었기에 채택했지만, 이 경험을 바탕으로 다음과 같이 추가했습니다.

## 작업 진행 방식
4. 지시 범위 외의 구현이 필요하다고 판단한 경우에는 이유와 함께 제안으로서 제시하고,
   승인을 얻은 후 구현한다 (보안상의 결함을 발견한 경우도, 
...

「눈치껏 행동하지 마라」가 아니라 「알게 되면 말해라, 멋대로 하지 마라」입니다.

AI의 판단력은 활용하되, 결정권은 인간에게 남기는 작성법입니다. 이상론을 미리 나열하는 것이 아니라, 실제로 일어난 사건으로부터 조문을 만드는 것이 결과적으로 더 잘 지켜지는 규범이 된다고 느끼고 있습니다.

요약

• CLAUDE.md는 README가 아니라 행동 강령(Code of Conduct)이다. "하지 말아야 할 것", "판단 기준", "금지 사항 + 대체 수단"으로 작성하라
• 가장 효과적인 것은 "테스트 스킵(skip) 금지"와 같이, AI의 지름길 행동(shortcut behavior)을 선제적으로 차단하는 조항이다
• 완벽을 목표로 하지 말고, 실제 일탈을 관측한 뒤에 조항을 추가하는 "성장하는 문서"로서 운용하라

이 이야기는 Claude Code로 Laravel 애플리케이션을 하나 완성해 나간 기록을 정리한 책의 일부를 기사용으로 재구성한 것입니다. CLAUDE.md의 전문 해설이나, 실제로 AI가 규약을 어길 뻔했거나 준수했던 구체적인 사례는 책의 제2장에 자세히 기술되어 있습니다.

『Laravel × Claude Code 실전 도입 가이드』(Zenn · ¥1,200 · 제1장 무료)

Discussion