Codex와 Claude Code는 프로젝트의 코드를 읽을 수 있습니다. 하지만 코드만 보고 모든 의도와 규칙을 알 수는 없습니다.

이 프로젝트가 무엇을 만드는지, 어떤 파일을 수정하면 안 되는지, 어떤 말투로 설명해야 하는지, 작업을 마치기 전에 무엇을 확인해야 하는지는 따로 알려 줘야 합니다. 이런 내용을 세션마다 반복해서 설명하지 않도록 적어 두는 파일이 AGENTS.md와 CLAUDE.md입니다.

두 파일은 AI가 프로젝트에서 어떤 기준으로 일해야 하는지 알려 주는 작업 지침서입니다.

Codex는 AGENTS.md, Claude Code는 CLAUDE.md를 읽습니다

도구기본 지침 파일
CodexAGENTS.md
Claude CodeCLAUDE.md

프로젝트 폴더에 지침 파일을 두면 Codex와 Claude Code가 작업을 시작할 때 읽고 이후 작업에 반영합니다. 지침에는 다음과 같은 내용을 적을 수 있습니다.

예를 들어 로컬에서만 동작하는 메모 CLI라면 다음과 같이 시작할 수 있습니다.

## 역할과 응답 방식

- 주니어 개발자도 이해할 수 있게 설명합니다.
- 모든 답변은 한국어로 작성합니다.

## 프로젝트

- TypeScript로 만든 로컬 메모 CLI입니다.
- 외부 서버나 네트워크를 사용하지 않습니다.

## 명령어

- 빌드: `npm run build`
- 테스트: `npm test`
- 타입 검사: `npm run typecheck`

## 완료 기준

- 작업 완료를 보고하기 전에 관련 테스트와 타입 검사를 실행합니다.

“코드를 적절히 정리한다”처럼 해석이 필요한 표현보다는 “변경 후 npm run typecheck를 실행한다”처럼 확인할 수 있는 문장이 좋습니다.

현재 작업과 계속 지킬 규칙을 구분합니다

지침 파일은 할 일 목록이 아닙니다.

“검색 기능을 추가한다”는 지금 수행할 작업입니다. 반면 “새 명령어를 추가하면 도움말과 테스트도 함께 수정한다”는 앞으로도 반복해서 적용할 규칙입니다. 현재 작업은 대화나 작업 계획에 두고, 여러 작업에서 계속 지켜야 할 내용만 지침 파일에 남깁니다.

이 구분이 없으면 끝난 작업이 지침에 계속 남고, 정작 중요한 규칙은 오래된 할 일 사이에 묻힙니다.

/init은 첫 초안을 만드는 기능입니다

Codex와 Claude Code에서 /init을 실행하면 현재 프로젝트를 살펴보고 각 지침 파일의 초안을 만드는 데 도움을 줍니다.

다만 /init이 만든 문서는 완성본이 아닙니다. 실제 파일에서 확인한 명령과 구조뿐 아니라 일반적인 개발 관례가 함께 들어갈 수 있습니다. 생성된 내용을 그대로 사용하지 말고 다음 항목을 확인해야 합니다.

프로젝트에 근거가 없는 권고는 필요한 경우에만 채택하고, 나머지는 지우는 편이 안전합니다.

지침은 짧게 유지하고 프로젝트와 함께 고칩니다

새로운 결정이 생길 때마다 문장을 추가하면 지침 파일은 오래된 규칙과 예외로 빠르게 커집니다. 새 내용을 넣기 전에 기존 내용과 겹치는지 확인하고, 더는 적용되지 않는 규칙은 삭제하거나 교체합니다.

/init은 처음 초안을 만들 때 사용하면 됩니다. 이후에는 프로젝트와 현재 지침을 비교해 필요한 부분만 고치도록 요청하는 편이 낫습니다.

현재 프로젝트와 AGENTS.md를 비교해 오래된 명령, 경로, 규칙을 찾아줘.
바로 수정하지 말고 변경안을 먼저 보여 줘.

변경안을 확인한 뒤에는 다음과 같이 요청할 수 있습니다.

확인한 변경안만 AGENTS.md에 반영해 줘.
새로운 규칙은 임의로 추가하지 마.

CLAUDE.md도 같은 방식으로 관리할 수 있습니다. 단순히 “최신화해 줘”라고 요청할 수도 있지만, 무엇을 바꿀지 범위를 정해 주면 불필요한 규칙이 추가되는 일을 줄일 수 있습니다.

지침을 확인할 시점은 비교적 분명합니다.

규칙이 많아지면 적용 범위를 나눕니다

처음에는 프로젝트 최상위 폴더의 지침 파일 하나로도 충분합니다. 규칙이 많아지면 모든 작업에 필요한 공통 지침과 특정 디렉터리에만 필요한 지침을 나눌 수 있습니다.

Codex는 하위 디렉터리에 별도의 AGENTS.md를 둘 수 있습니다. Claude Code는 .claude/rules/ 아래에 주제나 경로별 규칙을 나눌 수 있습니다. 처음부터 복잡하게 구성할 필요는 없습니다. 실제로 규칙이 많아졌을 때 분리해도 됩니다.

두 도구를 같은 프로젝트에서 사용하면서 공통 지침을 하나만 관리하고 싶다면 AGENTS.md에 내용을 적고, 프로젝트 최상위 폴더의 CLAUDE.md에는 다음 한 줄을 둘 수 있습니다.

@AGENTS.md

Codex는 AGENTS.md를 직접 읽고, Claude Code는 CLAUDE.md를 통해 같은 파일을 불러옵니다.

지침과 강제 장치는 다릅니다

AGENTS.md와 CLAUDE.md는 AI가 참고하는 지침입니다. 설정 파일처럼 동작을 강제로 막지는 않습니다.

반드시 통과해야 하는 테스트는 CI나 hook으로 실행하고, main branch에 직접 push하지 못하게 하려면 branch protection을 사용해야 합니다. 운영 DB 접근처럼 중요한 권한도 실제 권한 설정으로 제한해야 합니다.

지침 파일에는 AI가 따라야 할 기준을 적고, 반드시 막아야 하는 동작은 별도의 장치로 통제합니다.

좋은 지침 파일은 프로젝트의 모든 내용을 담은 문서가 아닙니다. AI가 이 프로젝트에서 어떤 역할로, 어떤 규칙을 지키며, 무엇을 확인하고 일을 마쳐야 하는지 알려 주는 짧고 구체적인 작업 지침입니다.

참고한 문서