AI 코딩 · 2026년 7월 10일 · 약 7분

Codex AGENTS.md 사용법: 프로젝트 규칙과 프롬프트 워크플로우 작성법

Codex가 읽는 AGENTS.md의 역할, 전역·프로젝트 지침 순서, 우선순위, Plan mode 활용법, 복사 가능한 템플릿까지 초보자도 바로 적용할 수 있게 정리했다.

• Codex AGENTS.md
• Codex 사용법
• AI 코딩 프롬프트
• AGENTS.md 작성법
• Codex Plan mode
• AI 코딩 에이전트

출처: OpenAI Codex Docs

Codex를 열고 “이 기능 만들어줘”라고만 말해도 어느 정도는 작업이 됩니다. 다만 테스트 명령어, 폴더 구조, 팀의 코드 스타일, PR 전에 볼 기준을 매번 다시 설명하다 보면 금방 피곤해져요. 이때 쓰는 파일이 AGENTS.md입니다. 한 번 잘 적어두면 Codex가 작업 전에 프로젝트 규칙을 먼저 읽고 움직입니다.

AGENTS.md는 AI 코딩 에이전트를 위한 프로젝트 안내서에 가까워요. 사람을 위한 README.md가 설치와 사용법을 설명한다면, AGENTS.md는 Codex에게 “이 저장소에서는 이렇게 일해줘”라고 알려주는 문서입니다.

이 글은 다른 AI 코딩 도구 비교보다 Codex의 공식 AGENTS.md 탐색 순서와 작업 프롬프트 조합에 집중합니다.

핵심 키워드

• Codex AGENTS.md 사용법
• AGENTS.md 작성법
• Codex 프롬프트 워크플로우
• Codex Plan mode 사용법
• AI 코딩 에이전트 테스트 검증

함께 확인한 문서

• OpenAI Codex AGENTS.md 문서: https://learn.chatgpt.com/docs/agent-configuration/agents-md
• OpenAI Codex best practices 문서: https://developers.openai.com/codex/learn/best-practices
• AGENTS.md open format 안내: https://agents.md/

Codex가 AGENTS.md를 읽는 방식

OpenAI Codex 문서에 따르면 Codex는 작업을 시작하기 전에 AGENTS.md 파일을 읽습니다. 전역 지침과 프로젝트 지침을 함께 사용할 수 있고, 현재 작업 위치에 가까운 디렉터리의 지침이 더 구체적인 기준으로 적용됩니다.

프로젝트 지침을 찾을 때 Codex는 프로젝트 루트에서 현재 작업 디렉터리까지 내려오며 각 디렉터리에서 AGENTS.override.md, AGENTS.md 순서로 확인합니다. 여러 지침이 합쳐질 때는 루트 쪽 지침이 먼저 들어가고, 현재 작업 위치에 가까운 지침이 나중에 들어갑니다.

기본값 기준으로 합쳐지는 프로젝트 지침의 크기 제한은 32 KiB입니다. 길게 쓰는 것보다 자주 쓰는 규칙만 작게 유지하는 편이 안정적입니다.

AGENTS.md에 꼭 넣을 내용

좋은 AGENTS.md는 거창한 문서가 아닙니다. Codex가 코드를 읽고, 바꾸고, 확인하는 데 필요한 규칙만 담으면 충분합니다.

복사해서 쓰는 AGENTS.md 템플릿

아래 항목을 새 AGENTS.md에 옮긴 뒤 대괄호 부분만 프로젝트에 맞게 바꿔보세요. 처음부터 완벽하게 쓰려 하지 말고, 실제로 쓰는 명령어와 완료 기준부터 넣는 것이 좋습니다.

기본 템플릿

• # AGENTS.md
• Goal: 이 저장소에서 Codex는 기존 구조와 스타일을 유지하면서 작고 검증 가능한 변경을 만든다.
• Project Context: 주요 앱 위치는 [예: apps/web], 공통 컴포넌트는 [예: src/components], 테스트는 [예: tests]에 있다.
• Commands: 설치 [예: npm install], 개발 서버 [예: npm run dev], 테스트 [예: npm test], 린트 [예: npm run lint], 빌드 [예: npm run build].
• Constraints: 기존 코드 스타일을 우선하고, 새 의존성은 꼭 필요할 때만 추가하며, 관련 없는 리팩터링은 하지 않는다.
• Done When: 요청한 기능이 동작하고, 관련 검증 명령을 실행했으며, 실행하지 못한 검증은 이유를 설명한다.
• Review Expectations: 바뀐 파일, 사용자가 확인할 동작, 실행한 테스트, 남은 위험을 마지막에 보고한다.

매번 보내는 프롬프트는 따로 좁힌다

AGENTS.md는 기본 규칙이고, 매번 보내는 요청은 현재 작업의 목표를 좁히는 역할입니다. OpenAI Codex best practices 문서에서도 Goal, Context, Constraints, Done when을 나눠 적는 방식을 좋은 기본값으로 제시합니다.

작업 요청 템플릿

• Goal: 사용자 프로필 페이지에서 저장 버튼이 비활성화되지 않는 문제를 고쳐줘.
• Context: 프로필 폼은 src/features/profile 안에 있고, API 호출은 src/lib/api.ts를 사용해.
• Constraints: 기존 폼 라이브러리는 바꾸지 말고, 새 의존성도 추가하지 마. 관련 없는 UI 리팩터링은 하지 마.
• Done when: 값이 바뀌지 않았을 때 저장 버튼이 비활성화되고, 값이 바뀌면 활성화되어야 해.
• Verification: 기존 테스트가 통과하거나, 실행하지 못하면 이유를 설명해. 마지막에 변경 diff를 검토해줘.

복잡한 작업은 Plan mode부터

작은 오타 수정이나 한 줄 변경은 바로 맡겨도 됩니다. 하지만 인증 흐름, 결제, 데이터 마이그레이션, 여러 파일이 얽힌 리팩터링은 먼저 계획을 세우게 하는 편이 좋습니다. Codex에서는 /plan 또는 Shift+Tab으로 Plan mode를 켤 수 있습니다.

Plan mode 요청 예시

• /plan
• Goal: 검색 결과 페이지의 필터 UI를 고쳐줘.
• Context: 현재 필터 상태가 URL 쿼리와 맞지 않는 문제가 있어.
• Constraints: 기존 라우터 구조는 유지해. 먼저 관련 파일을 찾고, 수정 계획을 설명한 뒤 진행해.
• Done when: 필터 선택, 새로고침, 뒤로 가기에서 같은 조건이 유지되는지 확인해.

작업 후 꼭 요청할 확인

Codex가 코드를 바꿨다면 마지막 확인까지 같은 흐름에 넣는 편이 좋습니다. “고쳤다”는 말보다 테스트, 동작 확인, diff 리뷰가 남아야 사람이 리뷰하기 쉽습니다.

마무리 체크 문장

• 테스트를 실행했는지 확인해줘.
• 실행하지 못한 검증이 있으면 이유를 알려줘.
• 사용자 입장에서 바뀐 동작을 설명해줘.
• 의도하지 않은 diff가 있는지 검토해줘.
• 이 변경으로 깨질 수 있는 부분이 있다면 짚어줘.

초보자가 자주 하는 실수

작게 유지하는 기준

AGENTS.md는 길수록 좋은 문서가 아닙니다. 설치법 전체, 오래된 회의록, 제품 소개 문장, 팀 문화 선언문은 보통 도움이 적습니다. Codex에게 매번 필요한 기준만 남겨야 합니다.

넣을 곳을 나누는 기준

• 한 번만 필요한 내용은 현재 프롬프트에 적는다.
• 모든 저장소에서 반복되는 개인 선호는 전역 지침에 둔다.
• 이 저장소에서 계속 지켜야 하는 규칙은 프로젝트 AGENTS.md에 둔다.
• 특정 폴더에서만 필요한 규칙은 그 폴더 가까이에 둔다.
• 반복 실수가 생겼을 때 한 줄 규칙으로 추가한다.

Codex를 잘 쓰는 핵심은 긴 프롬프트를 매번 잘 쓰는 데 있지 않습니다. 반복되는 기준을 AGENTS.md에 옮기고, 현재 작업은 Goal, Context, Constraints, Done when으로 좁히는 쪽이 더 실용적입니다. 처음에는 실행 명령어, 테스트 명령어, 완료 기준만 적어도 충분합니다.