팡고지와이에서 사용하는 글로벌 CLAUDE.md. Claude Code가 모든 프로젝트에서 일관된 코딩 원칙을 따르도록 만드는 행동 지침이다.
CLAUDE.md는 Claude Code가 작업을 시작할 때 자동으로 읽어 들이는 컨텍스트 파일이다. 사용자별 글로벌 지침은 ~/.claude/CLAUDE.md에, 프로젝트별 지침은 각 저장소 루트의 CLAUDE.md에 둔다.
이 저장소는 팡고지와이의 모든 프로젝트에서 공통으로 적용하는 글로벌 버전을 관리한다. LLM이 코딩 작업에서 자주 저지르는 실수(과도한 추상화, 범위 초과 리팩터링, 임시방편 코드, 일어나지 않을 시나리오에 대한 방어 코드 등)를 줄이기 위해 만들어졌다.
| 파일 | 설명 |
|---|---|
| CLAUDE.md | 한국어 원본. 실제 적용에 사용한다. |
| CLAUDE.en.md | 영문 번역본. 영어 환경에서 작업하거나 공유할 때 참고용. |
자세한 내용은 CLAUDE.md에서 확인할 수 있다.
- 핵심 작업 원칙 — 요청을 기계적으로 처리하지 말고 주변 코드·호출 흐름·테스트까지 확인한 뒤 작업한다. 범위를 불필요하게 넓히지 않는다.
- 코드 작성 전: 가정을 드러내고 모호함을 없앤다 — 추측하지 않는다. 모호하면 멈추고 묻는다.
- 단순함 우선 — 문제를 해결하는 최소한의 코드만 작성한다. 미리 짜놓는 코드, 일어날 수 없는 시나리오에 대한 방어 코드는 만들지 않는다.
- 최소 변경 원칙 — 요청과 직접 관련된 부분만 건드린다. 변경된 모든 줄은 사용자의 요청으로 직접 추적되어야 한다.
- 목표 기반 실행과 검증 — 작업을 검증 가능한 목표로 변환하고, 검증될 때까지 반복한다.
- 아키텍처와 유지보수성 — 한 파일 = 하나의 명확한 논리 단위. 도메인·UI·API·상태·유틸이 한 파일에 뒤섞이지 않게 한다.
- 파일 크기와 책임 경계 — 책임이 2개 이상 섞이거나, 분기·상태가 폭증하면 파일을 분리한다.
- 에러 처리 — 나중에 덧붙이지 말고 설계에 포함한다. 단, 일어날 수 없는 시나리오까지 방어하지 않는다.
- 주석과 TODO — "무엇을 하는지"가 아니라 "왜 이렇게 했는지"를 적는다.
- 의사소통 — 확인한 것, 가정, 변경 사항, 검증, 남은 리스크를 함께 보고한다.
# 원본을 글로벌 위치에 심볼릭 링크로 연결
ln -s "$(pwd)/CLAUDE.md" ~/.claude/CLAUDE.md또는 단순 복사:
cp CLAUDE.md ~/.claude/CLAUDE.md각 프로젝트 루트에 CLAUDE.md를 두면 해당 프로젝트에서만 적용된다. 글로벌과 프로젝트별 지침은 함께 로드되므로, 프로젝트별 파일에는 그 프로젝트 고유의 컨벤션·스택·도메인 지식만 두는 것을 권장한다.
- 새로운 원칙을 추가하기 전에, 기존 섹션 중 같은 의도를 다루는 곳이 없는지 먼저 확인한다.
- 한국어 원본(CLAUDE.md)을 먼저 수정한 뒤, 영문 버전(CLAUDE.en.md)에 같은 변경을 반영한다.
- 지침은 추상적인 문장보다 구체적인 행동 규칙으로 작성한다. "좋은 코드를 짜라" 대신 "200줄을 썼는데 50줄로 가능하다면 다시 쓴다"처럼.
- 이 지침이 잘 작동하고 있다는 신호: diff에 불필요한 변경이 적고, 과도한 복잡성 때문에 다시 짜는 일이 줄고, 실수 후가 아니라 구현 전에 질문이 나온다.