프로젝트 CLAUDE.md와 AGENTS.md는 현재 저장소에서만 유효한 팀의 규칙과 계약을 담습니다.
- Claude Code:
./CLAUDE.md또는./.claude/CLAUDE.md - Codex:
./AGENTS.md
전역 파일이 개인의 작업 방식을 정한다면, 프로젝트 파일은 에이전트가 이 저장소에서 잘못된 선택을 하지 않도록 필요한 사실을 제공합니다.
저장소에서만 유효한 사실을 기록합니다
프로젝트 파일에는 다음 내용이 적합합니다.
공식 명령
- 의존성 설치 명령
- 단위 테스트와 통합 테스트 명령
- Type Check와 Lint 명령
- 빌드와 계약 검증 명령
여러 명령 중 어느 것이 팀의 공식 기준인지 코드만 보고는 알기 어렵기 때문입니다.
활성 계약
- 외부에서 사용 중인 API와 SDK
- 호환성을 유지해야 하는 Request와 Response
- 데이터 Schema와 메시지 포맷
- 영속 데이터와 Migration 정책
현재 사용 중인 계약을 에이전트가 정리나 단순화의 대상으로 판단하지 않도록 해야 합니다.
아키텍처 경계
- 주요 모듈의 책임
- 허용되는 의존 방향
- 직접 수정하면 안 되는 자동 생성 코드
- 공통 모듈 변경 시 영향 범위
데이터·보안 경계
- 운영 DB 변경 제한
- 개인정보와 Secret 처리 원칙
- 배포와 Migration 승인 경계
- 규제나 감사상 지켜야 하는 조건
비직관적인 제약
- 코드만 읽어서는 쉽게 알 수 없는 도메인 규칙
- 과거 장애 때문에 유지하는 처리 방식
- Timeout, Retry, Idempotency와 같은 중요한 실패 조건
결제 API 프로젝트 예시
다음은 결제 API 저장소의 프로젝트 파일을 짧게 작성한 예시입니다.
# Project Instructions
## Active Contracts
- `v1` 결제 API는 모바일 앱과 외부 가맹점이 사용 중인 활성 계약이다.
- Request, Response와 Error Code의 하위 호환을 임의로 깨지 않는다.
- 계약 변경이 필요하면 영향받는 Consumer와 Migration 방안을 먼저 제시한다.
- `generated/` 아래 파일은 직접 수정하지 않는다.
## Canonical Verification
- 단위 테스트: `pnpm test --filter payments`
- Type Check: `pnpm typecheck --filter payments`
- Lint: `pnpm lint --filter payments`
- API 계약 테스트: `pnpm test:contract --filter payments`
공개 API나 공통 모듈을 변경하면 전체 계약 테스트를 실행한다.
## High-Impact Boundaries
- 운영 DB Migration을 실행하지 않는다.
- 운영 환경에 배포하지 않는다.
- Secret, 인증서와 운영 설정을 변경하지 않는다.
- 필요한 경우 실행안과 명령을 준비하고 승인 요청까지만 진행한다.
## Project-Specific Gotchas
- 결제 승인 재시도는 `paymentKey`를 기준으로 Idempotent해야 한다.
- 정산 데이터는 승인 원장을 직접 수정하지 않고 보정 거래로 처리한다.
- 외부 응답 Timeout은 결제 실패를 의미하지 않으므로 승인 결과를 재조회한다.
이 파일에는 전역 원칙의 “최소 변경”, “관련 없는 리팩터링 금지”, “검증 후 보고”를 중복해서 적지 않았습니다.
대신 결제 프로젝트에서만 유효한 계약, 명령과 실패 조건만 남겼습니다.
프로젝트 파일에 넣지 않을 내용
다음 내용은 프로젝트 파일을 불필요하게 길게 만듭니다.
- README 전체 복사
- 전체 파일 트리와 모든 모듈 설명
- 코드에서 바로 확인할 수 있는 API 목록
- 변경 이력
- 모든 프로젝트에 공통인 일반적인 작업 원칙
- 특정 작업에서만 필요한 목표와 완료 기준
- 특정 상황에서만 사용하는 긴 운영 절차
프로젝트 파일은 저장소의 설명서가 아닙니다.
저장소를 읽어도 알 수 없는 팀의 공식 선택과, 잘못 판단했을 때 영향이 큰 제약을 기록하는 문서입니다.
Claude Code와 Codex를 함께 사용한다면
Claude Code와 Codex를 같은 저장소에서 사용한다면 AGENTS.md를 공통 원본으로 두는 구성이 단순합니다.
프로젝트 루트의 CLAUDE.md에는 다음과 같이 작성할 수 있습니다.
@AGENTS.md
Claude Code에만 필요한 규칙이 있다면 아래에 추가합니다.
@AGENTS.md
## Claude Code
- 현재 적용된 지침 파일은 `/context`에서 확인한다.
- Claude Code 전용 경로별 규칙은 `.claude/rules/`에 둔다.
Claude Code는 AGENTS.md를 자동으로 읽지는 않지만, CLAUDE.md의 import 문법을 통해 같은 내용을 사용할 수 있습니다. Anthropic 공식 문서도 여러 코딩 에이전트가 하나의 저장소를 사용할 때 이 방식을 안내합니다.
파일이 길어진다면 위치가 잘못되었는지 확인합니다
프로젝트 파일이 계속 길어진다면 내용을 압축하기보다 적용 범위에 따라 다시 나눠야 합니다.
- 특정 경로에만 필요한 규칙은 경로별 Rule로 옮깁니다.
- 반복되는 단계별 절차는 Skill로 옮깁니다.
- 반드시 차단해야 하는 행동은 Hook·CI·권한 설정으로 강제합니다.
- 코드나 기존 문서에서 확인 가능한 정보는 삭제합니다.
프로젝트 CLAUDE.md와 AGENTS.md는 저장소의 모든 정보를 담는 문서가 아닙니다.
에이전트가 저장소를 읽는 것만으로는 알 수 없지만, 작업 전에 반드시 알아야 하는 사실만 남겨야 합니다.
세 글의 전체 구분은 CLAUDE.md를 길게 쓸수록 AI가 더 잘할까요?에서 다시 확인할 수 있습니다.