ONEDEV

CLAUDE.md

jbarbier파일 11개

★ 763주당 +11조회 4

무엇인가

세션마다 에이전트가 먼저 읽는 상시 계약 문서다. 지시가 없는 에이전트는 학습 데이터의 평균으로 수렴해 일을 일찍 끝내고, 테스트를 생략하고, 존재하지 않는 라이브러리를 만들어내고, 스스로 처리할 일을 승인 요청으로 되돌린다. 이 파일은 그 기본 동작을 덮어쓰는 것을 목적으로 하며, 규율 대상은 사고 방식, 코드를 쓸 시점과 추측을 멈출 시점, '완료'의 정의, 사용자에게 보고하는 화법이다.

어떻게 동작하나

실체는 저장소 루트의 CLAUDE.md 한 파일이다. Claude Code는 프로젝트 루트의 CLAUDE.md와 ~/.claude/CLAUDE.md를 세션 시작 시 자동 로드하므로 훅이나 슬래시 명령 없이 모델 컨텍스트에 요청보다 먼저 들어간다. 내용에는 작업 단위마다 독립 빌더 서브에이전트를 돌리고 별도 비평가가 결과를 블라인드로 비교 판정한 뒤 통과할 때까지 반복하는 fan-out + harsh critic 루프, 자기 작업에 점수를 매겨 만족할 때까지 루프하는 자기 채점 규칙, 브랜치·워크트리 운용 셸 명령, 코드 위치를 지시하는 형식 등이 담긴다.

무엇과 다른가

매 요청마다 프롬프트로 규칙을 다시 붙이는 방식과 달리 파일 하나가 모든 세션에 상시 적용된다. 또 AGENTS.md·GEMINI.md 같은 다른 이름의 규칙 파일에 내용을 복제해 두지 않고, CLAUDE.md를 단일 원본으로 두고 나머지를 심볼릭 링크로 연결해 드리프트를 막는다. 저장소 자체도 AGENTS.md를 심볼릭 링크 하나로만 제공한다.

어떻게 쓰나

프로젝트 루트에 파일을 내려받거나 복사한 뒤 그 디렉터리에서 claude를 실행하면 적용된다. 전역 적용은 ~/.claude/CLAUDE.md에 둔다. AGENTS.md를 읽는 Codex CLI·Cursor 등에는 ln -s CLAUDE.md AGENTS.md, Gemini CLI에는 ln -s CLAUDE.md GEMINI.md로 연결한다. 심볼릭 링크를 따라가지 않는 도구나 Windows에서는 파일을 복사해 이름만 바꾼다. 파일 안의 'Julien'을 sed로 자기 이름으로 치환하고, 자신의 스택에 맞지 않는 블록(LLM 접근 규칙, gstack·skills 참조)은 삭제한다.

전제와 한계

Claude Code를 1차 대상으로 하며 AGENTS.md 표준을 따르는 Codex CLI·Cursor·Gemini CLI·Jules 등에서 같은 내용이 동작한다. 판단 영역 규칙은 단위 테스트가 불가능하고, 브랜치 섹션의 셸 명령만 tests/run.sh로 검증된다. evals/branching_scenario.md는 규칙의 실행 가능성만 평가하며 점수의 신뢰는 evals/controls.sh 통제로 확인한다. LLM 접근 규칙과 gstack 참조는 특정 환경 전제이므로 그대로 쓰면 맞지 않는다.

관련 논문 5

유사 스킬