AGENTS.md 작성법: Codex가 프로젝트 규칙을 잊지 않게 만드는 실전 구조

AGENTS.md는 AI용 온보딩 문서다

Codex를 프로젝트에 붙여 쓰다 보면 같은 문제가 반복됩니다. 폴더 위치를 잘못 잡거나, 기존 스타일과 다른 코드를 만들거나, 테스트 없이 마무리하는 식입니다. 이때 루트의 AGENTS.md는 사람 개발자에게 주는 README가 아니라, AI 에이전트에게 주는 작업 규칙서에 가깝습니다.

좋은 AGENTS.md는 길지 않아도 됩니다. 핵심은 “이 프로젝트에서는 무엇을 기준으로 판단해야 하는가”를 짧고 명확하게 적는 것입니다. 1인 개발자라면 특히 유용합니다. 매번 프롬프트에 같은 설명을 붙이지 않아도 되고, 바쁜 날에도 코드 품질 기준을 어느 정도 일정하게 유지할 수 있습니다.

먼저 적어야 할 5가지 블록

AGENTS.md는 보통 아래 순서로 쓰면 Codex가 읽고 행동하기 쉽습니다.

블록	적을 내용
프로젝트 개요	무엇을 만드는 앱인지, 주요 사용자
기술 스택	프레임워크, DB, 인증, 배포 환경
디렉토리 규칙	새 파일을 어디에 둘지
작업 규칙	코딩 컨벤션, 상태 관리, 네이밍
검증 명령	테스트, lint, build 실행법

예를 들어 “새 API는 app/api 아래에 둔다”처럼 위치를 명확히 적으면 파일 구조가 덜 흔들립니다. “기존 컴포넌트 패턴을 먼저 확인한다”처럼 판단 기준을 적는 것도 좋습니다. 반대로 “깔끔하게 작성” 같은 표현은 사람에게는 자연스럽지만 AI에게는 기준이 모호합니다.

예시 골격: 짧지만 충분한 AGENTS.md

아래처럼 시작해도 충분합니다.

# AGENTS.md

## Project
- 한국 1인 빌더를 위한 제품 탐색 서비스
- 사용자는 제품을 제출하고, 둘러보고, 반응을 남긴다

## Stack
- Next.js App Router
- TypeScript
- Tailwind CSS
- Drizzle ORM

## Directory Rules
- 페이지는 app/ 아래에 둔다
- 재사용 UI는 components/ 아래에 둔다
- 서버 전용 로직은 lib/ 아래에 둔다
- DB 스키마 변경은 drizzle/ 경로를 먼저 확인한다

## Coding Rules
- TypeScript 타입을 우선 사용한다
- 기존 UI 컴포넌트와 스타일을 먼저 재사용한다
- 불필요한 새 라이브러리를 추가하지 않는다
- 한국어 사용자 문구는 messages/ 또는 기존 i18n 구조를 따른다

## Verification
- 변경 후 가능한 경우 아래 명령을 실행한다
- npm run lint
- npm run typecheck
- npm run build

## Do Not
- 사용자 변경사항을 임의로 되돌리지 않는다
- 비밀키나 실제 토큰을 코드에 넣지 않는다
- 테스트 없이 큰 리팩터링을 하지 않는다

이 골격의 장점은 Codex가 “어디를 먼저 봐야 하는지”와 “무엇을 하면 안 되는지”를 동시에 알 수 있다는 점입니다. 특히 Do Not 섹션은 중요합니다. AI는 요청을 해결하려는 압력이 강하기 때문에, 금지사항을 명시해 두면 위험한 우회가 줄어듭니다.

좋은 규칙은 행동으로 번역된다

AGENTS.md에 쓸 문장은 결과물이 아니라 행동을 지시해야 합니다.

나쁜 예시는 이런 식입니다.

좋은 코드로 작성한다
성능을 고려한다
일관성 있게 만든다

좋은 예시는 더 구체적입니다.

새 컴포넌트를 만들기 전에 components/의 유사 컴포넌트를 검색한다
서버에서만 쓰는 함수는 클라이언트 컴포넌트로 import하지 않는다
새 env가 필요하면 .env.example도 함께 갱신한다
DB 컬럼을 바꾸면 마이그레이션 파일과 사용처를 함께 확인한다

핵심은 Codex가 다음 행동을 고를 수 있게 만드는 것입니다. “성능 고려”보다 “목록 조회는 기존 pagination 패턴을 따른다”가 낫습니다. “일관성”보다 “버튼은 기존 Button 컴포넌트를 사용한다”가 낫습니다.

1인 개발자에게 특히 필요한 금지사항

혼자 만드는 프로젝트에서는 빠른 수정이 쌓여 구조가 쉽게 무너집니다. AGENTS.md에는 다음 금지사항을 넣어두면 도움이 됩니다.

요청 범위를 벗어난 대규모 리팩터링 금지
기존 사용자 변경사항 되돌리기 금지
임의 패키지 설치 금지
가짜 데이터, 가짜 통계, 임의 성공 사례 작성 금지
인증, 결제, 권한 로직 수정 시 관련 경로 재검토

이런 규칙은 속도를 늦추기 위한 것이 아닙니다. 오히려 혼자 개발할 때 생기는 “나중에 정리해야지”를 줄이는 장치입니다. AI가 빠르게 코드를 만들수록, 경계선은 더 선명해야 합니다.

업데이트는 큰 문서가 아니라 작은 패치로

AGENTS.md는 한 번에 완성하는 문서가 아닙니다. Codex가 같은 실수를 두 번 하면 그때 한 줄을 추가하세요. 예를 들어 새 파일 위치를 자주 틀리면 디렉토리 규칙을 보강하고, 테스트를 빼먹으면 검증 명령을 더 구체적으로 적습니다.

좋은 운영 방식은 간단합니다.

반복 실수 발견
AGENTS.md에 짧은 규칙 추가
다음 작업에서 지켜지는지 확인
오래된 규칙은 제거하거나 수정

규칙이 너무 많아지면 오히려 잘 읽히지 않습니다. 프로젝트의 현재 위험에 맞는 규칙만 남기는 편이 좋습니다. 1인 개발자에게 AGENTS.md는 거대한 매뉴얼이 아니라, Codex가 내 프로젝트에서 길을 잃지 않게 하는 작은 작업 지도입니다.