매번 같은 설명을 반복하지 않기: AGENTS.md로 AI 프로젝트 규칙 관리하기

한눈에 보는 결과

AI와 여러 작업을 이어 가다 보면 매번 같은 설명을 반복하게 된다.

• 작업을 시작할 때 어떤 문서를 읽어야 하는가?
• 비밀정보는 어디에 저장하면 안 되는가?
• 설정을 바꾸기 전에 무엇을 확인해야 하는가?
• 작업이 끝나면 어떤 기록을 남겨야 하는가?

이 문제를 해결하기 위해 프로젝트 루트에 AGENTS.md를 두고, Codex가 작업 전에 따라야 할 공통 규칙을 기록했다. 환경 정보, 학습 목표와 작업 이력은 각각 별도 Markdown 파일로 분리하고 AGENTS.md가 작업 시작 시 해당 파일들을 읽도록 연결했다.

여기서 가장 중요한 점은 다음과 같다.

Codex가 기본 규칙 파일로 자동 탐색하는 것은 AGENTS.md다. PROJECT_CONTEXT.md 같은 다른 문서는 이름만 만들어 두면 자동으로 읽는 것이 아니라, AGENTS.md에서 읽도록 명시해야 한다.

OpenAI 공식 문서에 따르면 Codex는 작업 전에 AGENTS.md를 읽고, 프로젝트 루트에서 현재 작업 디렉터리까지 지침 파일을 탐색해 결합한다. 현재 디렉터리에 가까운 지침이 앞선 지침보다 우선한다. OpenAI Docs: AGENTS.md로 Codex 구성하기

프로젝트 지침 구조

AGENTS.md를 중심으로 프로젝트 문서가 연결되고 작업, 검증, 기록 갱신으로 이어지는 구조다.

이 구조에서 AGENTS.md는 모든 내용을 담는 거대한 설명서가 아니다. 어떤 원칙으로 일하고, 어떤 문서를 언제 참조할지를 정하는 프로젝트 작업의 입구에 가깝다.

일반 프롬프트와 AGENTS.md의 역할 차이

AI에게 전달하는 정보는 수명이 서로 다르다. 한곳에 모두 섞기보다 다음처럼 나누는 편이 관리하기 쉽다.

구분	담을 내용	예시
현재 요청	이번 작업에만 필요한 목표	“로그인 오류의 원인만 진단해 줘”
AGENTS.md	반복해서 지켜야 할 행동 규칙	변경 전 현재 상태 확인, 비밀정보 기록 금지
컨텍스트 문서	여러 작업이 공유할 비민감 사실	사용 중인 시스템, 확정된 설계, 미해결 항목
학습 문서	목표와 실제 작업 증거	로드맵, 실패 원인, 검증 결과, 다음 실험
비밀 저장소	공개되면 안 되는 인증정보	API 키, 비밀번호, 액세스 토큰, 개인 키

OpenAI의 프롬프트 가이드는 요청을 작성할 때 목표(Goal), 맥락(Context), 결과물(Output), 경계(Boundaries)를 구분하도록 권장한다. AGENTS.md에도 같은 관점을 적용할 수 있다. 무엇을 해야 하는지뿐 아니라 어떤 변경을 승인받아야 하는지, 어떤 데이터를 기록하면 안 되는지, 완료를 무엇으로 검증할지 함께 적는 방식이다. OpenAI Docs: Prompting

Codex가 AGENTS.md를 찾는 방식

공식 문서에 설명된 탐색 순서는 크게 두 단계다.

1. 사용자 전체에 적용되는 전역 지침

Codex는 사용자 설정 디렉터리에서 먼저 AGENTS.override.md를 찾고, 없으면 AGENTS.md를 찾는다. 여기에는 여러 프로젝트에서 공통으로 지킬 개인 작업 방식을 둘 수 있다.

2. 현재 프로젝트에 적용되는 지침

그다음 프로젝트 루트에서 현재 작업 디렉터리까지 내려가며 각 디렉터리의 지침 파일을 찾는다. 기본적으로 같은 디렉터리에서는 AGENTS.override.md가 AGENTS.md보다 우선한다. 루트에서 가까운 지침부터 결합되고, 더 안쪽 디렉터리의 지침이 충돌하는 앞선 규칙을 덮어쓴다.

Codex는 전역 지침에서 현재 작업 폴더 방향으로 규칙을 결합하며, 가까운 지침이 우선한다.

예를 들어 프로젝트 전체는 Python을 사용하지만 frontend/ 폴더만 TypeScript 규칙을 적용해야 한다면, 루트 파일을 길게 만들기보다 frontend/AGENTS.md에 해당 규칙을 둘 수 있다.

공식 문서에는 결합된 프로젝트 지침의 기본 최대 크기가 32KiB이며 project_doc_max_bytes로 조정할 수 있다고 안내되어 있다. 크기를 늘릴 수 있더라도 같은 내용을 반복하기보다 핵심 규칙을 간결하게 유지하는 편이 좋다. OpenAI Docs: AGENTS.md로 Codex 구성하기

실제 프로젝트에 사용한 문서 구성

이번 프로젝트에서는 다음과 같이 역할을 나눴다.

project/
├── AGENTS.md
├── PROJECT_CONTEXT.md
├── AI_SKILL_ROADMAP.md
├── AI_SKILL_LOG.md
└── CS_STUDY_GUIDE.md

AGENTS.md: 행동과 판단 규칙

• 작업을 시작할 때 읽어야 할 문서
• 설명 수준과 결과 보고 방식
• 공식 문서를 확인해야 하는 조건
• 변경 전 점검, 변경 후 검증과 승인 기준
• 비밀번호·API 키·토큰을 다루는 원칙
• 공통 정보와 학습 로그를 갱신하는 조건

PROJECT_CONTEXT.md: 여러 작업이 공유할 사실

• 확인된 실행 환경
• 이미 결정한 아키텍처와 보안 원칙
• 검증을 마친 결과
• 아직 확인하지 못한 항목
• 변경 이력

자주 바뀌는 상태를 AGENTS.md에 계속 추가하면 행동 규칙과 환경 정보가 뒤섞인다. 그래서 규칙은 AGENTS.md, 상태와 결정은 컨텍스트 문서로 분리했다.

학습 문서: 목표와 증거

AI_SKILL_ROADMAP.md에는 무엇을 어떤 순서로 익힐지 기록하고, AI_SKILL_LOG.md에는 실제 작업에서 AI가 맡은 역할, 실패와 수정, 검증 결과, 보안·비용과 다음 실험을 기록했다.

이렇게 하면 “공부했다”는 추상적인 기록 대신 어떤 문제에 어떤 도구와 판단을 사용했고, 무엇으로 결과를 검증했는지가 남는다.

AGENTS.md 예시

다음은 특정 프로젝트의 비밀정보 없이 재사용할 수 있도록 줄인 예시다.

# 프로젝트 작업 지침

## 작업 시작

- 작업 전에 `PROJECT_CONTEXT.md`를 끝까지 읽는다.
- 기존 결정과 실제 환경이 다르면 임의로 덮어쓰지 말고 차이를 설명한다.

## 설명 방식

- 결과를 먼저 설명한다.
- 전문용어는 처음 등장할 때 쉬운 말로 풀이한다.
- 명령에는 목적, 실행 위치, 예상 결과와 되돌리는 방법을 함께 적는다.

## 변경과 검증

- 설정을 바꾸기 전에 현재 상태를 읽기 전용으로 확인한다.
- 변경은 작고 되돌릴 수 있는 단위로 진행한다.
- 삭제·덮어쓰기·권한 변경은 실행 직전에 사용자 확인을 받는다.
- 변경 후 정상 동작과 실패해야 하는 동작을 모두 검증한다.

## 비밀정보

- 비밀번호, API 키, 액세스 토큰과 개인 키를 Markdown이나 소스에 저장하지 않는다.
- 예제에는 `<YOUR_API_KEY>` 같은 자리표시자를 사용한다.

## 기록

- 확정된 비민감 정보는 `PROJECT_CONTEXT.md`에 반영한다.
- 의미 있는 작업은 `AI_SKILL_LOG.md`에 목표, 실패, 검증과 다음 실험을 기록한다.

이 예시의 핵심은 “잘해 줘”처럼 모호한 표현이 아니라, 작업 시작 조건·변경 경계·검증 기준·기록 위치를 관찰 가능한 행동으로 적은 것이다.

프롬프트 규칙을 설계한 순서

1. 반복되는 요구사항을 모았다

대화할 때마다 다시 설명하게 되는 내용부터 찾았다. 보안 원칙, 설명 수준, 작업 후 문서화처럼 대부분의 작업에 반복해서 적용되는 항목이 대상이었다.

2. 규칙과 사실을 분리했다

“변경 전에 상태를 확인한다”는 규칙이지만 “현재 서비스가 어느 버전이다”는 사실이다. 전자는 AGENTS.md, 후자는 PROJECT_CONTEXT.md에 두었다.

3. 권한 경계를 명확히 했다

읽기와 진단은 바로 수행할 수 있지만 삭제, 덮어쓰기, 계정·권한 변경처럼 영향이 큰 작업은 정확한 대상을 먼저 보여 주고 승인받도록 했다.

4. 완료 조건을 기록했다

파일을 만들었다고 끝내지 않고 실제 동작, 실패 경로, 권한, 로그와 결과물을 확인하도록 했다. 중요한 작업에는 사람이 최종 검토하는 단계도 남겼다.

5. 자동 기록의 범위를 제한했다

모든 작은 작업을 문서로 남기면 기록이 빠르게 불어난다. 코드, 설계, 배포, 장애 해결과 보안 설정처럼 재사용 가치가 있는 작업만 학습 로그로 남겼다.

비밀정보는 프롬프트 파일에 넣지 않는다

AGENTS.md와 프로젝트 Markdown은 AI가 읽기 쉽게 만든 문서다. 따라서 비밀번호, OTP, API 키, 액세스 토큰, 쿠키, 인증서 개인 키를 저장하면 안 된다.

비밀정보가 필요한 경우에는 다음처럼 분리한다.

• 운영체제 키체인 또는 승인된 비밀 저장소에 실제 값을 저장한다.
• 애플리케이션 설정에는 환경변수 이름만 기록한다.
• 문서와 예제에는 <YOUR_API_KEY> 같은 자리표시자를 사용한다.
• 명령 출력, 오류 로그와 스크린샷에도 값이 노출되지 않았는지 확인한다.

“사설 프로젝트이므로 괜찮다”는 판단도 피해야 한다. 프로젝트가 Git 저장소에 들어가거나, 로그가 공유되거나, AI 컨텍스트에 포함되면 예상하지 못한 경로로 값이 복사될 수 있기 때문이다.

적용 여부를 확인하는 방법

파일을 만들었으면 Codex가 지침을 실제로 발견했는지 확인해야 한다. OpenAI 공식 문서는 프로젝트 루트에서 다음과 같이 현재 지침을 요약하게 하는 검증 방법을 안내한다.

codex --ask-for-approval never "Summarize the current instructions."

명령의 목적은 실제 작업을 변경하는 것이 아니라 현재 실행에서 어떤 지침을 읽었는지 요약하게 하는 것이다. 결과에는 루트와 하위 폴더의 규칙이 기대한 우선순서로 반영되어야 한다.

지침 파일을 바꿨는데 기존 실행이 이전 내용을 따르는 것처럼 보이면 새 Codex 실행을 시작해 다시 확인한다. 공식 문서에 따르면 지침 체인은 실행 시작 시 구성되므로, 실행 중 변경한 내용을 즉시 다시 읽는다고 가정하면 안 된다. OpenAI Docs: AGENTS.md로 Codex 구성하기

검증할 때는 요약만 보지 말고 대표 작업도 작게 시험하는 편이 좋다.

• 비밀 값 대신 자리표시자를 쓰는가?
• 변경 전에 현재 상태를 먼저 확인하는가?
• 영향이 큰 작업에서 승인을 요청하는가?
• 완료 후 지정된 문서만 갱신하는가?
• 하위 폴더의 별도 규칙이 필요한 범위에서만 우선하는가?

사용하면서 알게 된 실수와 개선점

모든 정보를 AGENTS.md 한 파일에 넣기

규칙, 시스템 상태, 작업 일지와 긴 참고자료를 모두 넣으면 중요한 지침을 찾기 어렵다. AGENTS.md는 짧은 작업 규칙과 문서 연결에 집중하고, 세부 정보는 목적별 문서로 분리한다.

다른 Markdown도 자동으로 읽을 것이라 생각하기

Codex의 기본 탐색 규칙은 AGENTS.md 계열을 대상으로 한다. 임의로 만든 컨텍스트 파일은 AGENTS.md에서 읽도록 지시하거나 작업 요청에서 명시해야 한다.

실제 인증정보를 편의상 기록하기

AI가 자동으로 사용할 수 있다는 장점보다 유출 위험이 훨씬 크다. 문서에는 비밀 값이 아니라 저장 위치와 환경변수 이름만 기록한다.

같은 규칙을 여러 위치에서 반복하기

서로 다른 파일에 비슷하지만 미묘하게 다른 규칙이 있으면 어느 지침을 따라야 하는지 불명확해진다. 공통 규칙은 상위 파일에 한 번만 쓰고, 하위 파일에는 차이만 둔다.

행동이 아니라 희망 사항만 적기

“안전하게 작업한다”보다 “설정 변경 전에 현재 상태를 읽기 전용으로 확인하고, 변경 후 권한과 실패 경로를 검증한다”처럼 확인 가능한 행동으로 적는다.

자동화와 최종 승인을 구분하지 않기

상태 점검과 변경안 작성은 자동화할 수 있지만 외부 전송, 삭제, 권한 확대처럼 되돌리기 어렵거나 영향 범위가 큰 동작은 사람의 확인 단계를 둔다.

배운 점과 다음 단계

좋은 프로젝트 프롬프트는 길고 화려한 문장이 아니라 반복되는 판단을 일관된 행동으로 바꾸는 운영 규칙에 가까웠다.

이번 구성으로 다음 흐름을 만들었다.

1. Codex가 AGENTS.md를 자동으로 찾는다.
2. AGENTS.md의 지시에 따라 컨텍스트와 학습 문서를 읽는다.
3. 현재 요청의 목표와 경계를 확인한 뒤 작업한다.
4. 변경 후 동작과 보안 경계를 검증한다.
5. 확정된 공통 정보와 학습 증거를 갱신한다.

다음 단계에서는 하위 프로젝트마다 실제로 다른 규칙이 필요한지 관찰하고, 필요한 경우에만 하위 AGENTS.md를 추가할 예정이다. 또한 대표 작업을 이용한 지침 준수 점검표를 만들어 규칙을 고친 전후의 행동 차이를 비교해 볼 계획이다.