CLAUDE.md에 담은 4가지 규칙으로 대부분의 잘못된 Claude 코드 세션을 해결한 방법

Claude Code는 약 일주일 동안은 놀랍습니다. 하지만 사용자가 요청하지 않은 파일을 리팩토링하거나, 다섯 줄짜리 수정사항을 지나치게 복잡하게 만들거나, 작동하지 않는 것에 대해 자랑스럽게 '완료'를 선언합니다.

저는 클라이언트 프로젝트에서 매일 이것을 사용하며, 그 순간 대부분은 단 하나의 아이디어로 귀결되었습니다:

에이전트는 현재의 컨텍스트 윈도우(context window) 안에 있는 것만 알고 있다.

어제 '학습한' 것이 아닙니다. 팀의 컨벤션도 아닙니다. 만약 그것이 컨텍스트 안에 없다면, 존재하지 않는 것입니다. 따라서 이 작업은 단순히 '프롬프팅(prompting)'하는 것이 아니라, 무엇을 컨텍스트에 넣고 무엇을 밖에 둘지 결정하는 것입니다.

가장 저렴하고 영향력이 큰 시작 지점은 전역 ~/.claude/CLAUDE.md 파일입니다. 여기에 제가 담아둔 네 가지 규칙이 있습니다.

규칙 1 - 코딩 전에 생각하기 (Think before coding)

No silent assumptions. State what you're assuming. Surface tradeoffs.
Ask before guessing. Push back when a simpler approach exists.

이는 확신에 찬 잘못된 방향을 방지합니다: 5초 만에 수정했을 가정 위에 구축된 300줄의 코드.

규칙 2 - 단순성 우선 (Simplicity first)

Minimum code that solves the problem. No speculative features. No
abstractions for single-use code. If a senior engineer would call it
overcomplicated - simplify.

이는 '엔터프라이즈'적인 반사 작용을 방지합니다: 하나의 구현체와 인터페이스, 아무도 요청하지 않은 설정 옵션들.

규칙 3 - 수술적 변경 (Surgical changes)

Touch only what you must. Don't "improve" adjacent code, comments, or
formatting. Don't refactor what isn't broken. Match existing style.

이것 덕분에 제 코드 리뷰 속도가 약 두 배 빨라졌습니다. 이제 diff는 마침내 순수한 작업 내용만 담고 있습니다.

규칙 4 - 목표 중심 실행 (Goal-driven execution)

Define success criteria. Loop until verified.

'코드를 작성해줘'가 '이 테스트를 통과시키고, 브라우저에서 검증할 때까지 반복해줘'로 바뀝니다. 성급하게 승리를 선언하는 것을 막아줍니다.

왜 이것들이 작동하는가: 소망이 아닌 제약 조건 (constraints, not wishes)

대부분의 CLAUDE.md 파일은 소망들로 가득 차 있습니다: "Clean하고 유지보수하기 쉬운 코드를 모범 사례를 따라 작성해줘." 모델은 이미 그렇게 한다고 생각합니다. 이 문장은 아무것도 바꾸지 못합니다.

제약 조건(constraint)은 구체적이고 검증 가능합니다—사용자(당신)와 모델 모두가 확인할 수 있습니다. 여기에 **이유(reason)**를 추가하면 훨씬 더 강력해집니다: 에이전트는 압박을 받을 때 규칙을 무시하는 대신, 사용자가 명시하지 않은 상황에도 그 규칙을 적용할 수 있게 됩니다.

간결하게 유지하기 (Keep it short)

CLAUDE.md의 모든 줄은 세션마다 비용이 청구됩니다. 제 예산: 전역적으로 약 60줄 미만, 프로젝트당 약 150줄 미만입니다. 절차("릴리스하려면, 먼저 X를 하고 그 다음 Y를 해야 한다...")에 해당하는 것은 필요한 경우에만 로드되는 스킬(skill)에 포함되어야 합니다.

그리고 에이전트가 합리적인 초보자도 저지를 만한 실수를 할 때마다, 프로젝트 파일의 Gotchas 섹션에 한 줄을 추가하세요. 시간이 지남에 따라 이 문서는 저장소(repo)에서 가장 가치 있는 문서가 됩니다.

이 내용은 나의 **Claude Code Field Manual**의 2장으로부터 각색된 것입니다—CLAUDE.md, 권한(permissions), 스킬(skills), 서브에이전트(subagents), 후크(hooks) 및 git flow에 대한 12개 장으로 구성되어 있으며, 모든 템플릿은 복사-붙여넣기 파일 형태로 제공됩니다.

• 무료 샘플 (1~2장): https://robertwalaski.gumroad.com/l/claude-code-field-manual-free
• 전체 매뉴얼 + 템플릿: https://robertwalaski.gumroad.com/l/claude-code-field-manual