---
name: opencurrent-codex-agents-md
description: "테스트 명령이나 패키지 관리자 같은 저장소 규칙을 작업마다 다시 말하지 않아도, Codex가 작업 전에 먼저 읽고 시작합니다. 이럴 때 사용: 모든 저장소에 쓸 공통 규칙은 ~/.codex/AGENTS.md에, 저장소 규칙은 루트의 AGENTS.md에 적습니다. 폴더마다 다른 규칙은 그 폴더에 따로 두고, 마지막으로 Codex가 어떤 규칙을 읽었는지 확인합니다. 도구: Codex CLI."
metadata:
  source: "https://opencurrent.ai/w/codex-agents-md"
  opencurrent-id: "codex-agents-md"
  verification: "pending"
  exported-at: "2026-11-21T11:08:55.354Z"
---

# 저장소 규칙을 에이전트에게 매번 자동 전달 (Codex AGENTS.md)

테스트 명령이나 패키지 관리자 같은 저장소 규칙을 작업마다 다시 말하지 않아도, Codex가 작업 전에 먼저 읽고 시작합니다.

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/codex-agents-md
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("codex-agents-md")로 최신 상태를 확인할 것.
> 주의: 검수 대기 상태. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 준비물이 갖춰졌는지 먼저 확인할 것.
2. body를 처음부터 끝까지 읽고 순서대로 따라 할 것. 코드 블록의 명령은 사용자의 허락을 받고 실행하고, 사람이 해야 하는 일은 사용자에게 안내하고 끝났는지 물을 것.
3. 본문에 확인 방법이 있으면 그대로 확인하고, 다르면 다음으로 넘어가지 말고 사용자에게 알릴 것.
4. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

모든 저장소에 쓸 공통 규칙은 ~/.codex/AGENTS.md에, 저장소 규칙은 루트의 AGENTS.md에 적습니다. 폴더마다 다른 규칙은 그 폴더에 따로 두고, 마지막으로 Codex가 어떤 규칙을 읽었는지 확인합니다.

## 준비물

- Codex CLI 설치
- Git 저장소 하나

## 입력값

시작하기 전에 사용자에게 받아서 프롬프트의 `{{이름}}` 자리에 넣을 것.

- `{{subdir}}` 하위 폴더 (선택): 따로 규칙을 줄 하위 폴더 경로
  - 예: services/payments

## 본문

## 준비

- Codex CLI 설치
- Git 저장소 하나

### 1. 전역 규칙 파일 만들기

`~/.codex` 폴더를 만들고 `AGENTS.md`에 모든 저장소에 공통인 선호를 적습니다. 예를 들면 JavaScript를 고친 뒤 npm test 실행, pnpm 우선, 운영 의존성 추가 전 확인 같은 규칙입니다. 빈 파일은 건너뛰므로 몇 줄이라도 적습니다.

```bash
mkdir -p ~/.codex
$EDITOR ~/.codex/AGENTS.md
```

### 2. 전역 규칙 적용 확인

승인 없이 한 번 실행해 지금 읽힌 지시를 요약하게 합니다.

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

방금 적은 규칙이 답에 나오면 됩니다.

### 3. 저장소 루트에 AGENTS.md 추가

Git 저장소 루트의 `AGENTS.md`에 이 저장소만의 규칙을 적습니다. 예를 들면 PR 전 npm run lint 실행, 공개 유틸리티는 docs/에 문서화 같은 규칙입니다.

### 4. 하위 폴더에 덮어쓰기 규칙 추가

명령이 다른 하위 폴더에는 `AGENTS.override.md`를 만듭니다. 예를 들어 npm test 대신 make test-payments를 쓰게 합니다. 깊은 폴더의 지시가 위쪽 지시보다 우선합니다.

```bash
$EDITOR <하위 폴더>/AGENTS.override.md
```

### 5. 읽힌 규칙 순서 확인

하위 폴더 기준으로 실행해 읽은 지시의 출처를 나열하게 합니다.

```bash
codex --cd <하위 폴더> --ask-for-approval never "List the instruction sources you loaded."
```

전역 파일, 루트 `AGENTS.md`, 하위 폴더의 override 순서로 세 파일이 나오면 됩니다.

### 6. 다른 파일 이름 쓰기 (선택)

이미 다른 이름의 안내 파일이 있으면 `config.toml`에 대체 이름을 등록하고 크기 한도도 함께 조정합니다. 저장한 뒤 Codex를 다시 시작합니다.

```bash
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```

이제 폴더마다 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md 순서로 찾습니다. 다시 시작한 뒤 출처 목록에 TEAM_GUIDE.md가 보이면 됩니다.

## 주의

- 합친 크기가 `project_doc_max_bytes`(기본 32 KiB)에 닿으면 그 뒤 파일은 읽지 않습니다. 한도를 올리거나 하위 폴더로 나눕니다.
- 현재 폴더보다 아래는 찾지 않습니다. 덮어쓰기 파일은 해당 작업 폴더 가까이에 둡니다.
- 규칙이 엉뚱하게 적용되면 위쪽 폴더나 Codex 홈의 `AGENTS.override.md`를 확인합니다.
- 지시 목록은 실행(세션)마다 한 번 만들어집니다. 바뀐 내용이 안 보이면 대상 폴더에서 Codex를 다시 시작합니다.
- 프로필이 헷갈리면 실행 전에 `echo $CODEX_HOME`으로 확인합니다.

## 주의할 점

- 합친 크기가 project_doc_max_bytes(기본 32 KiB)에 닿으면 이후 파일은 읽지 않음. 한도를 올리거나 하위 폴더로 나누기
- 현재 폴더보다 아래는 탐색하지 않음. 덮어쓰기 파일은 해당 작업 폴더 가까이에 두기
- 규칙이 엉뚱하면 위쪽 폴더나 Codex 홈의 AGENTS.override.md 확인
- 지시 목록은 실행(세션)마다 한 번 만들어짐. 바뀐 내용이 안 보이면 대상 폴더에서 Codex 다시 시작
- 프로필이 헷갈리면 실행 전 echo $CODEX_HOME 확인

## 출처

- [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/codex-agents-md 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.
