프로젝트 기억을 만드는 AGENTS.md

Codex에게 매번 같은 말을 하지 않는 방법

Codex를 처음 쓰면 신기합니다. "이 버튼 고쳐줘", "테스트 추가해줘"라고 말하면 실제 파일을 읽고 수정합니다. 그런데 며칠 쓰다 보면 조금 귀찮은 장면이 반복됩니다.

"우리 프로젝트는 npm이 아니라 pnpm을 써."

"테스트는 Jest가 아니라 Vitest야."

"그 폴더는 건드리면 안 돼."

"API 코드는 여기 말고 services 폴더에 넣어야 해."

이 말을 매번 채팅창에 다시 쓰고 있다면, 아직 Codex에게 프로젝트 기억을 만들어 주지 않은 것입니다. 그 기억 역할을 하는 파일이 바로 AGENTS.md입니다.

AGENTS.md는 사람을 위한 README.md와 닮았지만 목적이 다릅니다. README.md가 사람에게 "이 프로젝트가 무엇인지" 알려 준다면, AGENTS.md는 Codex 같은 코딩 에이전트에게 "이 프로젝트에서 어떻게 일해야 하는지" 알려 줍니다. 공식 AGENTS.md 설명에서도 이 파일을 코딩 에이전트를 위한 예측 가능한 안내 장소, 즉 에이전트용 README에 가깝게 소개합니다.¹

좋은 AGENTS.md는 길고 멋진 문서가 아닙니다. 좋은 AGENTS.md는 Codex가 실수하기 쉬운 부분을 짧고 분명하게 막아 주는 프로젝트 온보딩 문서입니다. 새 팀원이 들어왔을 때 "이 저장소에서는 이렇게 실행하고, 이 폴더는 이런 역할이고, 이 명령으로 확인하면 돼요"라고 알려 주는 문서를 Codex에게도 주는 셈입니다.

AGENTS.md는 어디에 두어야 할까

가장 먼저 만들 곳은 저장소 루트입니다. 저장소 루트란 보통 package.json, README.md, .git 폴더가 있는 가장 바깥 디렉터리입니다.

my-todo-app/
├── AGENTS.md
├── package.json
├── README.md
├── src/
└── tests/

초보자라면 일단 루트에 AGENTS.md 하나만 만들어도 충분합니다. 이 파일에는 프로젝트 전체에 적용되는 규칙을 적습니다. 예를 들어 이 앱이 무엇인지, 어떤 기술 스택을 쓰는지, 설치·실행·테스트 명령은 무엇인지, 절대 건드리면 안 되는 파일은 무엇인지 적습니다.

Codex는 작업을 시작할 때 이런 프로젝트 지침 파일을 읽고 맥락에 반영합니다. OpenAI의 Codex 문서에 따르면 Codex는 각 디렉터리에서 AGENTS.override.md, AGENTS.md, 설정된 대체 파일명 순서로 확인하며, 디렉터리마다 최대 한 파일만 포함합니다.² 이 말은 조금 어렵게 들리지만, 핵심은 간단합니다.

Codex는 "지금 내가 작업하는 위치에 가장 가까운 안내문"을 중요하게 봅니다.

예를 들어 모노레포처럼 프론트엔드와 백엔드가 한 저장소에 같이 있다면 이렇게 나눌 수 있습니다.

my-service/
├── AGENTS.md
├── apps/
│   ├── web/
│   │   └── AGENTS.md
│   └── api/
│       └── AGENTS.md
└── packages/
    └── ui/
        └── AGENTS.md

루트 AGENTS.md에는 공통 규칙을 씁니다. 예를 들어 "PR 전 테스트를 실행한다", "비밀키를 커밋하지 않는다", "사용자가 수정한 파일을 함부로 되돌리지 않는다" 같은 규칙입니다.

apps/web/AGENTS.md에는 프론트엔드 규칙을 씁니다. 예를 들어 "Next.js App Router를 사용한다", "UI는 Tailwind CSS와 shadcn/ui를 따른다", "컴포넌트 테스트는 Vitest로 작성한다" 같은 내용입니다.

apps/api/AGENTS.md에는 백엔드 규칙을 씁니다. 예를 들어 "API 핸들러에서 DB를 직접 호출하지 않는다", "서비스 계층을 거친다", "마이그레이션 파일은 기존 파일을 수정하지 말고 새 파일을 추가한다" 같은 내용입니다.

이렇게 나누면 Codex가 프론트엔드 작업을 할 때 백엔드의 긴 규칙까지 모두 들고 다니지 않아도 됩니다. 작업에 필요한 기억만 가까운 곳에 놓는 것입니다.

Codex가 AGENTS.md를 읽는 순서 이해하기

AGENTS.md를 제대로 쓰려면 "어떤 파일이 더 우선하는지"를 알아야 합니다. 초보자에게는 이 부분이 조금 헷갈릴 수 있으니, 건물 안내판에 비유해 보겠습니다.

회사 1층 로비에는 전체 안내문이 있습니다. "출입증을 착용하세요", "방문객은 안내 데스크에 등록하세요" 같은 공통 규칙입니다. 그런데 연구실 문 앞에는 별도 안내문이 붙어 있습니다. "이 방은 정전기 방지 장갑을 착용하세요." 연구실 안에서는 로비 안내문도 중요하지만, 문 앞 안내문이 더 직접적입니다.

Codex의 지침도 비슷합니다. 전역 지침, 루트 지침, 하위 폴더 지침이 차례로 적용됩니다. 일반적으로 더 가까운 디렉터리의 지침이 더 구체적인 규칙입니다.

Codex의 프로젝트 문서 탐색은 대략 이런 식으로 생각하면 됩니다.

~/.codex/AGENTS.md               개인 공통 지침
my-service/AGENTS.md             저장소 공통 지침
my-service/apps/web/AGENTS.md    웹 앱 전용 지침

apps/web에서 Codex를 실행하면 개인 지침, 저장소 지침, 웹 앱 지침이 함께 읽힐 수 있습니다. 반대로 저장소 루트에서 실행하면 apps/web/AGENTS.md는 적용되지 않을 수 있습니다. 그래서 작업할 폴더에서 Codex를 시작하는 습관이 중요합니다.

또 하나 알아둘 파일이 AGENTS.override.md입니다. 이름 그대로 같은 디렉터리의 일반 AGENTS.md보다 우선하는 override 파일입니다. OpenAI 문서 기준으로 Codex는 각 디렉터리에서 AGENTS.override.md를 먼저 확인하고, 있으면 같은 위치의 AGENTS.md 대신 그 파일을 사용합니다.²

그렇다고 초보자가 처음부터 override 파일을 자주 쓸 필요는 없습니다. 대부분의 프로젝트는 AGENTS.md만으로 충분합니다. AGENTS.override.md는 임시 실험, 특정 폴더의 강한 예외, 긴급한 규칙 변경처럼 정말 필요한 경우에만 쓰는 편이 좋습니다.

또 Codex 설정에는 project_doc_fallback_filenames 같은 대체 파일명 설정이 있을 수 있습니다. 예를 들어 팀이 이미 CONTRIBUTING.md나 TEAM_GUIDE.md에 개발 규칙을 잘 정리해 두었다면, Codex가 그런 파일도 참고하도록 설정할 수 있습니다. Codex CLI 설정 자료에 따르면 프로젝트 문서 최대 크기는 기본적으로 32KiB이며, 필요하면 설정으로 조정할 수 있습니다.³ 다만 처음에는 한 가지 원칙만 기억하세요.

AGENTS.md는 짧고 정확할수록 좋습니다.

루트 AGENTS.md에 꼭 들어가야 할 내용

처음 만드는 AGENTS.md는 거창하지 않아도 됩니다. 오히려 너무 길면 Codex도 핵심을 놓치기 쉽고, 사람도 유지보수하기 싫어집니다. 처음에는 다음 정도만 넣어도 효과가 큽니다.

## Project
This is a personal todo app built with Next.js, TypeScript, and Tailwind CSS.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Structure
- `src/app/`: Next.js routes and pages
- `src/components/`: reusable UI components
- `src/lib/`: utility functions and API clients
- `src/server/`: server-only logic
- `tests/`: integration and UI tests

## Rules
- Use pnpm, not npm or yarn.
- Use TypeScript strict patterns. Do not use `any` unless there is no safe alternative.
- Keep UI components small and reusable.
- Do not edit generated files in `src/generated/`.
- Do not read or modify `.env`, `.env.local`, or secret files.

## Before finishing
- Run `pnpm lint` when changing source files.
- Run `pnpm test` when changing behavior.
- Summarize changed files and verification results.

위 예시는 영어로 되어 있지만, 한국어로 써도 됩니다. Codex는 마크다운 문서를 읽고 의미를 파악할 수 있습니다. 다만 명령어, 폴더명, 파일명은 실제 프로젝트와 정확히 맞아야 합니다.

초보자가 가장 많이 하는 실수는 "좋은 코드를 작성해라", "최선의 방법을 따라라", "깔끔하게 만들어라"처럼 너무 추상적으로 쓰는 것입니다. 이런 문장은 기분은 좋지만 Codex의 행동을 거의 바꾸지 못합니다.

대신 이렇게 써야 합니다.

- API 요청 함수는 `src/lib/api/`에 만든다.
- 새 컴포넌트는 기본적으로 named export를 사용한다.
- 상태 관리는 기존 Zustand store를 사용하고 Redux를 추가하지 않는다.
- 날짜 포맷은 `src/lib/date.ts`의 `formatDate`를 사용한다.
- 기존 DB 마이그레이션 파일은 수정하지 않는다. 필요한 경우 새 마이그레이션을 추가한다.

좋은 규칙은 Codex가 바로 행동으로 옮길 수 있습니다. 나쁜 규칙은 해석의 여지가 너무 많습니다.

해야 할 일과 하지 말아야 할 일을 분리하기

AGENTS.md에서 가장 강력한 부분은 "하지 말아야 할 일"입니다. Codex는 성실합니다. 그래서 작업 범위를 넓게 이해하면 요청하지 않은 리팩터링, 패키지 추가, 파일 이동까지 해버릴 수 있습니다. 지난 장에서 Git과 worktree로 안전장치를 만들었다면, 이번 장에서는 문서로 작업 경계를 세우는 셈입니다.

예를 들어 이렇게 나눠 쓰면 Codex가 훨씬 안정적으로 움직입니다.

## Do
- Follow existing file and folder patterns before creating new ones.
- Add or update tests when behavior changes.
- Keep changes focused on the requested task.
- Prefer small, readable functions over large rewrites.
- Report commands that were run and whether they passed.

## Do not
- Do not modify files in `legacy/` unless explicitly asked.
- Do not edit generated files in `src/generated/`.
- Do not add new dependencies without explaining why.
- Do not change public API response shapes unless the task asks for it.
- Do not touch `.env*`, credentials, production config, or deployment secrets.

여기서 중요한 단어는 "unless explicitly asked", 즉 "명시적으로 요청받지 않는 한"입니다. Codex에게 완전히 금지할 것인지, 요청이 있으면 허용할 것인지 구분해 주면 좋습니다.

예를 들어 legacy/ 폴더는 보통 오래된 코드라서 건드리기 위험합니다. 하지만 언젠가는 그 폴더를 수정해야 할 수도 있습니다. 그러니 "절대 수정 금지"보다 "명시적 지시 없이는 수정 금지"라고 쓰는 편이 실전적입니다.

보안 파일은 더 강하게 적어야 합니다.

## Security
- Never print, read aloud, modify, or commit secrets.
- Do not open `.env`, `.env.local`, `*.pem`, `*.key`, or credential files unless the user explicitly approves and the task requires it.
- Use environment variable names in examples, not real values.

AGENTS.md도 저장소에 커밋되는 파일입니다. 그러므로 비밀번호, API 키, 토큰, 실제 DB 접속 문자열은 절대 넣으면 안 됩니다. 환경 변수 이름과 예시 형식만 적으세요.

## Environment variables
Create `.env.local` from `.env.example`.

Required variables:
- `NEXT_PUBLIC_API_BASE_URL`: public API base URL
- `DATABASE_URL`: local database connection string
- `AUTH_SECRET`: auth signing secret

Do not commit real values.

이렇게 쓰면 Codex는 어떤 환경 변수가 필요한지 알 수 있지만, 실제 비밀값은 보지 않아도 됩니다.

기존 프로젝트에서 AGENTS.md 초안 만들기

이미 만들어 둔 프로젝트가 있다면 처음부터 빈 문서에 직접 쓰려고 하지 않아도 됩니다. Codex에게 프로젝트를 먼저 읽게 한 뒤 초안을 만들게 할 수 있습니다.

이때 중요한 것은 "바로 파일을 만들라"고 하기보다, 먼저 읽을 범위를 지정하는 것입니다.

이 저장소의 AGENTS.md 초안을 만들고 싶어.
먼저 package.json, README.md, 폴더 구조, 테스트 설정 파일을 읽고
프로젝트 목적, 기술 스택, 주요 명령, 폴더 역할, 코딩 규칙, 금지 파일을 추정해줘.
아직 파일을 수정하지 말고 초안만 채팅에 보여줘.

Codex가 초안을 보여 주면 사람이 반드시 검토해야 합니다. 특히 명령어는 실제로 맞는지 확인해야 합니다. npm test라고 써 놨는데 실제 프로젝트는 pnpm test를 써야 한다면, Codex는 앞으로 계속 잘못된 명령을 실행하려고 할 수 있습니다.

검토할 때는 다음 질문을 던져 보세요.

• 설치, 실행, 빌드, 테스트, 린트 명령이 실제로 동작하는가?

• Codex가 건드리면 안 되는 폴더와 파일이 빠지지 않았는가?

• 팀이 실제로 쓰는 패키지 매니저와 테스트 도구가 정확히 적혔는가?

• 개인 취향과 프로젝트 규칙이 섞여 있지 않은가?

• 너무 긴 설명 때문에 중요한 규칙이 묻히지 않는가?

수정이 끝나면 그때 파일로 저장합니다.

좋아. 방금 초안에서 명령어를 pnpm 기준으로 고치고,
legacy/와 src/generated/는 명시적 요청 없이는 수정 금지로 추가해서
저장소 루트에 AGENTS.md 파일을 만들어줘.

이 흐름은 안전합니다. Codex가 한 번에 프로젝트 규칙을 추측해 파일을 써버리게 하지 않고, 사람이 중간에서 확인하기 때문입니다.

실전 예제: 할 일 관리 앱용 AGENTS.md

이 책의 다음 장부터는 실제 앱을 만들기 시작합니다. 그 전에 간단한 할 일 관리 앱을 기준으로 AGENTS.md를 하나 만들어 보겠습니다.

## Project
This is a beginner-friendly todo app built with Vite, React, TypeScript, and Tailwind CSS.
The app lets users create, complete, filter, and delete todos in the browser.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Structure
- `src/main.tsx`: app entry point
- `src/App.tsx`: top-level app composition
- `src/components/`: reusable React components
- `src/features/todos/`: todo state, types, and todo-specific UI
- `src/lib/`: shared utilities
- `src/styles/`: global styles

## Coding rules
- Use React function components and hooks.
- Use TypeScript types for props and todo data.
- Keep todo-specific logic inside `src/features/todos/`.
- Use Tailwind utility classes for styling.
- Do not introduce a new state management library unless explicitly asked.

## Testing rules
- Use the existing test runner.
- Add tests when todo behavior changes.
- Prefer user-visible behavior tests over implementation-detail tests.

## Do not touch
- Do not modify lockfiles unless dependencies change.
- Do not edit `.env*` files.
- Do not rewrite the whole app for a small requested change.

## Before finishing
- Run `pnpm lint` after source changes.
- Run `pnpm test` after behavior changes.
- Explain what changed and which checks passed or failed.

이 정도면 아주 훌륭한 시작점입니다. Codex는 이제 할 일 앱의 기본 구조를 알고, 어디에 파일을 만들어야 하는지 알고, 무엇을 실행해야 하는지 알고, 어떤 일을 피해야 하는지도 압니다.

여기서 더 욕심을 내서 모든 React 스타일 가이드, 모든 Tailwind 규칙, 모든 테스트 철학을 붙여 넣을 필요는 없습니다. 자세한 문서가 필요하다면 별도 문서에 두고 AGENTS.md에서는 링크나 짧은 요약만 남기는 편이 낫습니다.

개인 취향은 전역 지침으로 분리하기

프로젝트마다 매번 반복되는 개인 취향이 있을 수 있습니다. 예를 들어 "항상 설명을 한국어로 해줘", "변경 전 계획을 먼저 말해줘", "새 의존성을 추가하기 전에 물어봐" 같은 규칙입니다.

이런 규칙은 특정 저장소의 규칙이 아니라 내 작업 방식에 가깝습니다. 그러면 프로젝트 AGENTS.md에 넣기보다 전역 지침으로 분리하는 편이 좋습니다. Codex는 보통 사용자 홈의 ~/.codex/AGENTS.md 같은 전역 지침과 프로젝트 지침을 함께 사용할 수 있습니다.³

전역 지침에는 이런 내용을 둘 수 있습니다.

## My working preferences
- Reply in Korean unless the project requires English.
- Before large edits, summarize the plan briefly.
- Do not add production dependencies without asking first.
- Prefer the package manager already used by the repository.

반대로 프로젝트 AGENTS.md에는 해당 저장소에만 맞는 내용을 둡니다.

## Project-specific rules
- This repo uses pnpm workspaces.
- The web app lives in `apps/web/`.
- The API server lives in `apps/api/`.
- Use Prisma migrations for database schema changes.

이 구분이 중요합니다. 개인 취향을 모든 프로젝트 파일에 복사해 넣으면 나중에 관리가 어려워집니다. 더 큰 문제는 다른 프로젝트의 규칙이 섞이는 것입니다. 예를 들어 어떤 프로젝트는 pnpm을 쓰고, 어떤 프로젝트는 uv나 poetry를 쓸 수 있습니다. 그런데 전 프로젝트에서 "항상 pnpm 사용"이라고 써 두면 Codex가 엉뚱한 명령을 실행할 수 있습니다.

개인 취향은 전역으로, 저장소 규칙은 저장소 안으로. 이 원칙만 지켜도 지침 파일이 훨씬 깨끗해집니다.

하위 폴더별 AGENTS.md가 필요한 순간

처음부터 폴더마다 AGENTS.md를 만들 필요는 없습니다. 작은 앱은 루트 하나면 충분합니다. 하지만 프로젝트가 커지면 하위 폴더별 지침이 큰 도움이 됩니다.

예를 들어 프론트엔드와 백엔드 규칙이 확실히 다를 때입니다.

my-saas/
├── AGENTS.md
├── apps/
│   ├── web/
│   │   └── AGENTS.md
│   └── api/
│       └── AGENTS.md
└── packages/
    └── database/
        └── AGENTS.md

루트에는 공통 규칙을 둡니다.

## Common rules
- Use pnpm from the repository root.
- Keep changes focused and small.
- Do not commit secrets.
- Run relevant tests before finishing.

apps/web/AGENTS.md에는 웹 규칙을 둡니다.

## Web app rules
- Use Next.js App Router patterns.
- Put route components under `app/`.
- Put reusable UI in `components/`.
- Use existing design tokens before adding new colors.
- Run `pnpm --filter web test` for web changes.

apps/api/AGENTS.md에는 API 규칙을 둡니다.

## API rules
- Put route handlers in `src/routes/`.
- Put business logic in `src/services/`.
- Do not access the database directly from route handlers.
- Add integration tests for new endpoints.
- Run `pnpm --filter api test` for API changes.

이렇게 나누면 Codex가 API 작업 중에 UI 색상 규칙을 신경 쓰지 않아도 되고, 웹 작업 중에 DB 마이그레이션 규칙에 눌리지 않아도 됩니다.

단, 하위 AGENTS.md를 만들 때는 루트 규칙과 충돌하지 않게 주의해야 합니다. 루트에서 "모든 테스트는 pnpm test"라고 해 놓고, 하위 폴더에서 "테스트는 npm test"라고 쓰면 Codex도 헷갈립니다. 정말 하위 폴더만 예외라면 이유를 적어 주세요.

## Commands
Run these commands from `apps/api/`.
This package uses Poetry because it is a Python service.

- Install: `poetry install`
- Test: `poetry run pytest`
- Lint: `poetry run ruff check .`

AGENTS.md에 넣지 말아야 할 것

좋은 문서를 만들려면 무엇을 넣을지보다 무엇을 빼야 할지가 더 중요할 때가 많습니다. AGENTS.md는 프로젝트 운영에 필요한 "작업 지침"입니다. 모든 문서를 여기에 몰아넣는 창고가 아닙니다.

넣지 않는 편이 좋은 내용은 다음과 같습니다.

• 실제 API 키, 토큰, 비밀번호, 인증서 같은 비밀 정보

• "깨끗한 코드 작성", "최신 모범 사례 준수"처럼 행동으로 연결되지 않는 추상 문장

• 이미 ESLint, Prettier, Biome 설정 파일에 들어 있는 세부 포맷 규칙 전체

• 사람을 위한 긴 제품 소개, 회사 소개, 마케팅 설명

• 거의 쓰지 않는 배포 절차의 장문 매뉴얼

물론 배포 절차가 Codex 작업에 자주 필요하다면 짧게 요약해도 됩니다. 하지만 길다면 별도 문서로 분리하고 링크를 둡니다.

## Deployment
Codex should not deploy production manually.
For release steps, see `docs/release.md`.

이 한 줄이면 충분한 경우가 많습니다. Codex에게 "배포하지 말라"는 핵심 경계와 "필요하면 어디를 보라"는 위치를 동시에 알려 주기 때문입니다.

AGENTS.md도 코드처럼 유지보수하기

AGENTS.md는 한 번 만들고 잊어버리는 문서가 아닙니다. 프로젝트가 바뀌면 같이 바뀌어야 합니다.

예를 들어 처음에는 테스트 명령이 pnpm test였는데 나중에 pnpm test:unit과 pnpm test:e2e로 나뉘었다고 해봅시다. 그런데 AGENTS.md가 계속 pnpm test만 알려 주면 Codex는 오래된 명령을 반복 실행합니다. 실패 로그가 쌓이고, 사람은 "왜 Codex가 계속 같은 실수를 하지?"라고 느낍니다. 사실 Codex가 고집을 부리는 게 아니라, 우리가 오래된 안내판을 방치한 것입니다.

그래서 다음이 바뀌면 AGENTS.md도 함께 고쳐야 합니다.

• 패키지 매니저, 설치 명령, 실행 명령

• 테스트 도구, 린트 도구, 타입 체크 명령

• 주요 폴더 구조와 아키텍처 경계

• 생성 파일 위치와 수정 금지 범위

• 배포 방식, PR 체크리스트, 리뷰 기준

실전에서는 Codex가 실패한 로그를 문서 개선 재료로 쓰면 좋습니다. 예를 들어 Codex가 계속 npm install을 실행하려고 한다면 AGENTS.md에 이렇게 추가합니다.

## Package manager
- Use pnpm only.
- Do not use npm or yarn in this repository.
- If a dependency must be added, run `pnpm add <package>` and explain why.

Codex가 계속 테스트 파일을 엉뚱한 위치에 만든다면 이렇게 추가합니다.

## Test placement
- Component tests live next to the component as `*.test.tsx`.
- API integration tests live in `tests/api/`.
- Do not create a new top-level `__tests__/` folder.

이런 식으로 실패를 문서에 반영하면, 같은 실수를 다음 세션에서 줄일 수 있습니다. AGENTS.md는 Codex를 혼내는 문서가 아니라, Codex가 다음번에 더 잘 일하도록 길을 닦는 문서입니다.

커밋 전 체크리스트를 넣어 두기

지난 장에서 다룬 Git 안전 습관도 AGENTS.md에 짧게 넣어 두면 좋습니다. Codex는 코드를 수정한 뒤 어떤 검증을 해야 하는지, 변경을 어떻게 보고해야 하는지 더 잘 따르게 됩니다.

## Git safety
- Start from a clean working tree when possible.
- Keep changes focused on the requested task.
- Show the diff summary before suggesting commit.
- Do not revert user changes unless explicitly asked.
- Do not commit automatically unless the user asks.

## PR checklist
- Relevant tests passed or failures are explained.
- Lint/typecheck passed or failures are explained.
- New behavior has tests when practical.
- Public API or environment variable changes are documented.
- No secrets, tokens, or local-only paths are included.

여기서 "실패했으면 설명하라"는 표현이 중요합니다. 모든 프로젝트에서 모든 테스트를 항상 로컬로 돌릴 수 있는 것은 아닙니다. 시간이 너무 오래 걸리거나 외부 서비스가 필요할 수도 있습니다. 그럴 때 Codex가 조용히 넘어가지 않고 "이 명령은 이런 이유로 실행하지 못했다" 또는 "실행했지만 이런 오류가 났다"고 보고하게 해야 합니다.

바로 써먹는 AGENTS.md 작성 프롬프트

마지막으로, 실제 프로젝트에서 바로 사용할 수 있는 프롬프트를 정리해 보겠습니다.

새 프로젝트라면 이렇게 요청하세요.

이 프로젝트를 위한 AGENTS.md를 만들어줘.
초보자도 이해할 수 있게 짧고 명령형으로 작성해.
포함할 내용:
- 프로젝트 목적
- 기술 스택
- 설치, 실행, 빌드, 테스트, 린트 명령
- 주요 폴더 역할
- 코딩 규칙
- 수정 금지 파일과 폴더
- PR 전 확인 사항
아직 확실하지 않은 명령은 추측하지 말고 확인 질문으로 남겨줘.

기존 프로젝트라면 이렇게 요청하세요.

AGENTS.md 초안을 만들기 전에 package.json, README.md, 폴더 구조,
테스트 설정 파일, 린트 설정 파일을 읽어줘.
그다음 이 저장소에서 Codex가 따라야 할 규칙을 요약해줘.
파일은 아직 만들지 말고, 초안을 먼저 보여줘.

이미 AGENTS.md가 있는데 Codex가 자꾸 실수한다면 이렇게 요청하세요.

최근 실패 로그와 현재 AGENTS.md를 비교해서,
Codex가 반복 실수하지 않도록 추가하거나 고칠 규칙을 제안해줘.
규칙은 짧고 구체적으로 작성해.
기존 내용과 중복되는 문장은 줄여줘.

이제 Codex에게 매번 같은 설명을 반복할 필요가 줄어듭니다. 프로젝트의 기억은 채팅창에 흩어져 있으면 사라지지만, AGENTS.md에 들어가면 저장소의 일부가 됩니다. 그리고 저장소의 일부가 된 기억은 팀원과 Codex가 함께 공유할 수 있습니다.

다음 장부터는 이 기억을 가진 Codex와 함께 실제 앱을 만들어 보겠습니다. 이제 Codex는 빈손으로 프로젝트에 들어오는 손님이 아니라, 온보딩 문서를 읽고 출근한 팀원에 더 가까워졌습니다.

참고

¹AGENTS.md 공식 소개

²OpenAI Developers - Custom instructions with AGENTS.md

³Codex CLI Cheatsheet: config, commands, AGENTS.md, + best practices