AGENTS.md 작성법: Codex에 프로젝트 규칙 알려 주기

요약: AGENTS.md에는 프로젝트에서 반복적으로 필요한 작업 규칙을 적습니다. 설치 명령, 검증 방법, 변경 경계를 간결하게 남기고 현재 코드와 맞는지 관리하세요.

1. AGENTS.md가 필요한 순간

Codex에 일을 맡길 때마다 “이 저장소는 npm이 아니라 다른 패키지 관리자를 쓴다”, “생성 파일은 직접 수정하지 않는다”를 반복한다면 프로젝트 지침 파일이 유용합니다. AGENTS.md는 이런 작업 약속을 프로젝트와 함께 관리하는 문서로 생각하면 쉽습니다.

OpenAI 공식 문서는 Codex가 작업을 시작할 때 AGENTS.md 지침을 읽으며, 전역 지침과 프로젝트 지침을 함께 구성한다고 설명합니다. 이 글의 예시는 가상의 저장소를 위한 초안입니다. 예시의 명령을 실제 프로젝트에서 확인하지 않고 그대로 넣는 것은 피하세요.

2. 처음에는 저장소 루트의 짧은 파일로 시작하기

첫 파일은 팀원이 저장소에 처음 들어왔을 때 필요한 안내를 기준으로 작성하세요. 어떤 폴더가 소스인지, 어떤 명령으로 실행하는지, 수정 후 어떤 확인이 필요한지를 적으면 됩니다. 사용하지 않는 명령이나 오랫동안 갱신하지 않은 설명은 작업을 잘못된 방향으로 보낼 수 있습니다.

# 프로젝트 작업 규칙

## 구조
- 화면 코드는 src/ui, 데이터 처리 코드는 src/data에 있습니다.
- generated 폴더의 산출물은 직접 편집하지 마세요.

## 변경 기준
- 기존 공개 함수의 입력과 반환 형식을 유지하세요.
- 요청과 관계없는 파일은 수정하지 마세요.
- 다른 작업자의 변경을 덮어쓰지 마세요.

## 검증
- package.json에서 현재 테스트 명령을 확인해 실행하세요.
- 실행 명령, 결과, 실행하지 못한 이유를 구분해 보고하세요.

명령을 확실히 알고 있다면 “확인해 실행” 부분을 실제 명령으로 바꿀 수 있습니다. 반대로 아직 모른다면 임의의 npm test를 규칙으로 못 박기보다 프로젝트 설정에서 찾도록 적는 편이 낫습니다. 규칙은 멋진 선언보다 실행 가능한 안내가 되어야 합니다.

3. 하위 폴더 규칙은 필요한 경우에만 나누기

공식 문서에 따르면 프로젝트 루트에서 현재 작업 디렉터리까지의 경로에 있는 지침을 모으며, 더 가까운 디렉터리의 지침이 뒤에 반영됩니다. 각 디렉터리에서는 AGENTS.override.md, AGENTS.md 등의 탐색 우선순위가 적용됩니다. 여러 파일이 있다면 실제 작업을 시작한 위치가 중요합니다.

작은 저장소는 루트 파일 하나로 충분할 수 있습니다. 화면과 서버가 서로 다른 검증 절차를 가진다면 각 영역에 별도 지침을 두는 방법을 검토하세요. 공통 규칙을 하위 파일마다 복사하면 나중에 서로 다른 내용으로 바뀌기 쉽습니다. 공통 약속은 루트에, 영역별로 꼭 필요한 차이만 하위 문서에 남기는 구성이 관리하기 편합니다.

4. 지침을 작성한 뒤에는 적용 내용을 확인하기

파일을 만들었다고 끝내지 말고 새 작업에서 읽히는 규칙을 확인하세요. 다음은 실행을 제한한 상태에서 내용을 점검하려는 요청 예시입니다. 이 확인은 실제 작업을 맡기기 전에 문서의 오류를 찾는 용도로 사용할 수 있습니다.

현재 작업 디렉터리에 적용되는 AGENTS.md 지침을 요약해 주세요.
적용 파일의 경로와 검증 명령을 알려 주세요.
서로 충돌하거나 실행할 수 없는 지침이 있으면 설명해 주세요.
이 요청에서는 파일을 수정하거나 설치하지 마세요.

답변에서 의도한 파일이 빠졌다면 작업 디렉터리와 파일 이름부터 확인합니다. 지침 변경이 반영되지 않은 것 같다면 새 세션에서 다시 확인하세요. 공식 문서는 지침 구성이 실행 시작 시 이루어진다고 설명하므로, 기존 세션이 새 내용을 언제 반영하는지 추측하는 것보다 다시 확인하는 편이 명확합니다.

5. 자주 실패하는 규칙과 고치는 방법

• “항상 최고 품질”처럼 추상적인 규칙: 공개 API 유지, 검증 명령 등 확인 가능한 조건으로 바꿉니다.
• 존재하지 않는 테스트 명령: 현재 설정과 맞추거나 찾는 위치를 안내합니다.
• 모든 작업에 긴 절차 강제: 반드시 필요한 단계와 조건부 단계를 구분합니다.
• 서로 모순되는 파일: 공통 규칙을 정리하고 하위 영역의 예외를 분명히 적습니다.

비밀번호나 토큰은 작업 지침에 적지 마세요. 팀이 공유하는 저장소에 넣을 문서라면 비밀값 대신 필요한 환경 변수의 이름과 설정을 확인할 위치를 안내하는 편이 좋습니다. 지침 변경도 코드 변경처럼 차이를 검토하면 오래된 명령이나 불필요한 예외를 발견하기 쉽습니다.

6. 실제 명령이 있는 가상 저장소로 작성해 보기

다음은 JavaScript 기반 가상 프로젝트의 예시입니다. 실제로 이 프로젝트를 실행한 결과가 아니라, 지침을 구체화하는 작성 예시입니다. 먼저 README와 package.json을 읽어 개발 서버·검증 명령을 찾았다고 가정합니다. 이 가상의 scripts에는 dev, test, lint가 있으므로 문서에 그 이름을 사용할 수 있습니다. 실제 저장소에 없는 이름을 그대로 넣으면 지침이 오히려 실행을 방해합니다.

{
  "scripts": {
    "dev": "vite",
    "test": "vitest run",
    "lint": "eslint src"
  }
}

이 scripts 예시 자체를 프로젝트에 덮어쓰라는 뜻은 아닙니다. 현재 사용하는 도구가 다르면 해당 도구의 기존 명령을 적으세요. lock 파일과 README에서 패키지 관리자를 정하고, 테스트가 특정 서비스나 환경 변수에 의존하면 필요한 조건도 함께 남깁니다. “테스트를 실행한다”는 문장보다 “어디에서 어떤 명령을 실행하며 무엇이 준비되어야 하는가”가 작업자에게 더 유용합니다.

# AGENTS.md

## 프로젝트 구조
- src/ui: 사용자 화면, src/data: 데이터 처리
- tests: 기능 검증, public: 정적 파일
- dist는 생성 산출물이므로 소스를 먼저 수정합니다.

## 실행과 검증
- 저장소 루트에서 npm run dev로 개발 서버를 실행합니다.
- 동작을 바꾸면 관련 사례를 npm test로 확인합니다.
- JavaScript 소스를 바꾸면 npm run lint도 확인합니다.
- 실행에 필요한 조건이 없으면 실패 원인을 보고합니다.
  테스트를 건너뛰고 통과했다고 표현하지 않습니다.

## 변경 기준
- 저장된 데이터 형식은 이번 요청에 포함될 때만 변경합니다.
- 기존 사용자의 정상 입력 동작을 유지합니다.
- 다른 작업자의 변경과 생성 산출물을 덮어쓰지 않습니다.

## 보고 형식
- 변경한 동작과 파일, 실제 실행한 검증, 남은 확인을 설명합니다.

이렇게 작성하면 정상 작업 경로가 먼저 보입니다. 금지 문장만 긴 문서보다 개발자가 다음에 실행할 명령을 찾기 쉽습니다. 검증이 없는 문구 수정에도 모든 단계가 필요한지는 프로젝트 기준으로 조정하세요. 규칙의 목적은 절차를 많이 만드는 것이 아니라 반복 작업에서 생기는 혼선을 줄이는 것입니다.

7. 루트와 하위 폴더에 무엇을 나눠 적을까?

화면과 서버가 함께 있는 저장소를 생각해 보겠습니다. 아래 배치는 경로별 지침을 나누는 예시입니다. 루트에는 데이터 형식 보존과 보고 방식 같은 공통 약속을 두고, 서버 폴더에는 서버만의 실행 조건을 적습니다. 같은 공통 규칙을 세 파일에 복사하기보다 어느 범위에 적용되는지 한 곳에서 읽을 수 있게 만드는 편이 유지 관리에 유리합니다.

project/
  AGENTS.md
  frontend/
    AGENTS.md
  services/
    api/
      AGENTS.override.md

공식 문서의 탐색은 프로젝트 루트부터 현재 작업 디렉터리까지의 경로를 기준으로 합니다. 루트에서 시작했다고 모든 하위 지침이 일괄적으로 합쳐지는 것으로 이해하지 마세요. api 폴더에서 시작하는 작업이라면 그 경로에 있는 지침을 확인하고, 루트에서 여러 영역을 맡길 때는 필요한 하위 지침을 읽도록 요청에 명시할 수 있습니다. 적용 여부는 실제 세션에서 경로와 내용으로 확인하는 것이 정확합니다.

같은 폴더에 AGENTS.override.md와 AGENTS.md가 있다면 두 문서의 내용이 모두 자동으로 합쳐진다고 기대하면 안 됩니다. 공식 탐색 우선순위에서는 override 파일을 먼저 확인하고 디렉터리마다 최대 하나의 지침을 사용합니다. 일시적 예외를 만든 뒤 원래 문서가 읽히지 않는 상황을 피하려면 예외의 목적과 제거 시점을 기록하세요. 예외를 계속 쓰게 된다면 일반 지침으로 정리하는 편이 낫습니다.

# services/api/AGENTS.override.md

## API 영역의 추가 기준
- 저장소 루트의 공통 변경 기준을 유지합니다.
- API 검증은 이 영역의 README에 적힌 절차를 따릅니다.
- 데이터베이스가 필요한 검증은 연결 대상과 준비 상태를 먼저 확인합니다.
- 테스트용 데이터 변경과 운영 데이터 변경을 구분합니다.
- 데이터 형식 변경은 영향과 이전 버전 호환 여부를 보고합니다.

8. 지침이 잘못 읽힐 때 경로부터 조사하기

규칙이 적용되지 않는 것처럼 보이면 문장을 더 강하게 쓰기 전에 실제 파일과 시작 위치를 확인하세요. Windows에서 파일 확장자가 숨겨져 있으면 AGENTS.md.txt로 저장했는데 화면에는 AGENTS.md처럼 보일 수 있습니다. 탐색기에서 확장자를 표시하거나 아래처럼 이름을 조회하면 정확한 파일명을 확인할 수 있습니다. 다음 명령은 파일 이름과 현재 위치를 읽기 위한 예시입니다.

Get-Location
Get-ChildItem -Name AGENTS*
Get-Content -LiteralPath .\AGENTS.md

1. 현재 디렉터리가 의도한 프로젝트인지 봅니다. 다른 복사본이라면 해당 프로젝트로 이동합니다.
2. 파일명이 정확하고 내용이 비어 있지 않은지 확인합니다. 잘못된 확장자라면 편집기에서 이름을 바로잡습니다.
3. 같은 경로나 상위 범위에 override 파일이 있는지 살펴봅니다. 예상하지 못한 규칙의 출처를 찾습니다.
4. 새 세션에서 적용 파일 경로와 명령을 요약하게 합니다. 이전 세션 답변만 보고 새 파일이 적용됐다고 판단하지 않습니다.

전역 규칙과 프로젝트 규칙을 섞어 썼는지도 점검하세요. 모든 저장소에 npm test를 요구하는 전역 지침은 Python 저장소에서는 맞지 않을 수 있습니다. 한국어로 설명하거나 실행과 미실행을 구분해 보고하는 개인 선호는 전역에 둘 수 있지만, 특정 프로젝트의 명령은 해당 저장소 지침에 두는 편이 자연스럽습니다. Codex 홈 경로를 별도로 설정했다면 기본 위치를 수정해도 다른 설정을 읽을 수 있습니다.

9. 오래된 규칙을 줄이는 개정 체크리스트

지침도 프로젝트 변화에 따라 갱신해야 합니다. 테스트 도구를 바꿨거나 소스 폴더를 옮겼다면 관련 명령과 경로를 함께 수정하세요. 기능 변경이 필요할 때 오래된 명령을 우회하는 방법만 대화에 남기면 다음 작업에서 같은 문제가 반복됩니다. 아래 프롬프트로 문서와 현재 설정의 차이를 먼저 살펴볼 수 있습니다.

AGENTS.md의 경로와 실행 명령을 현재 저장소와 비교해 주세요.
존재하지 않는 파일·스크립트·생성 경로를 찾아 주세요.
항목별로 현재 근거 파일과 수정 제안을 표로 정리해 주세요.
새 규칙을 임의로 늘리지 말고 오래된 규칙의 갱신부터 제안하세요.
이 단계에서는 문서를 수정하거나 의존성을 설치하지 마세요.

검토 결과에서는 세 가지를 구분하세요. 실행 명령이 없어졌다면 실제 오류를 고치는 개정이고, 새 도구를 도입하자는 제안은 별도 선택입니다. “항상 모든 테스트”를 관련 테스트와 필수 검사로 나누는 것은 작업 기준 조정입니다. 종류를 구분하면 단순 갱신 요청이 갑자기 도구 교체나 큰 구조 변경으로 번지는 일을 줄일 수 있습니다.

• 경로와 명령이 현재 저장소에 존재하는가?
• 조건부 작업과 매번 필요한 작업이 나뉘어 있는가?
• 특정 기능의 임시 요구사항을 영구 규칙으로 남기지는 않았는가?
• 실패나 미실행 때 다음 행동을 알 수 있는가?
• 비밀값 대신 환경 변수 이름과 준비 방법을 안내하는가?

좋은 AGENTS.md는 새 작업자가 파일 하나를 읽고 정상 작업을 시작할 수 있는 문서입니다. 코딩 규칙을 길게 모으기보다 현재 프로젝트에서 자주 틀리는 선택과 실제 실행 절차를 남기세요. 반복되는 복잡한 업무 순서가 필요해졌다면 모든 내용을 루트 지침에 넣기보다 별도 스킬이나 참고 문서로 나누는 것도 검토할 수 있습니다.

10. 자주 묻는 질문

AGENTS.md와 README는 같은가요? README는 사람에게 프로젝트를 소개하는 데 많이 쓰이고, AGENTS.md는 에이전트가 작업할 때 필요한 지침을 정리합니다. 같은 설명을 두 곳에 길게 복제하기보다 필요한 문서를 참조하도록 작성할 수 있습니다.

규칙이 많을수록 좋나요? 적용할 수 있고 현재 프로젝트에 필요한 규칙이 중요합니다. 중복되거나 충돌하는 문장은 줄이세요.

지침으로 실행 권한도 바뀌나요? 작업 방법을 안내하는 것과 실제 권한 설정은 별개입니다. 파일에 허용한다고 적었다는 이유만으로 도구의 접근 경계가 자동으로 넓어지지는 않습니다.

공식 출처 및 확인일: OpenAI 공식 문서: Custom instructions with AGENTS.md. 2026년 10월 3일 확인. 예시의 경로와 명령은 자신의 프로젝트에 맞게 조정하세요.