Part II: Codex에서 하네스 엔지니어링 새로 배우기

Chapter 5: Codex에서 하네스 짓기 — AGENTS.md, 설정, 디렉토리 구조

집필일: 2026-04-28 최종수정일: 2026-04-28

5.1 OpenAI가 자기 자신에게 쓴 AGENTS.md

가장 좋은 AGENTS.md 예시는 OpenAI의 Codex 저장소 자체다 [OpenAI, 2026]. 실제로 어떻게 생겼는지 보면:

  • Rust crate 이름은 codex- 접두사 (예: codex-core, codex-cli)
  • 모듈 크기 500줄 이하 (800줄에서 분리)
  • Clippy: "항상 if 구문을 한 줄로 접어라"
  • 클로저 대신 메서드 참조(method references) 선호

이것이 프로덕션 AGENTS.md가 실제로 어떻게 생겼는지다. 범용 코딩 규칙이 아니라, 이 코드베이스에서 틀리기 쉬운 것들을 구체적으로 명시하는 것이다.

5.2 세 가지를 만들어야 한다

Codex에서 하네스를 짓는다는 것은 세 가지 파일/디렉토리를 만드는 것이다:

  1. 최상위 AGENTS.md — 프로젝트 전체에 적용되는 도구 독립적 규칙
  2. ~/.codex/config.toml — Codex 전용 설정
  3. .codex/agents/.toml — 첫 서브에이전트 정의

순서대로 만들어보자.

5.3 AGENTS.md — 실전 작성법

Figure 5.1: 프로덕션 AGENTS.md의 구조 — Overview, Stack, Code Standards, Testing, Git Workflow, Common Mistakes 6개 섹션이 살아있는 문서로 진화한다. illustration by author Gemini assisted
Figure 5.1: 프로덕션 AGENTS.md의 구조 — Overview, Stack, Code Standards, Testing, Git Workflow, Common Mistakes 6개 섹션이 살아있는 문서로 진화한다. illustration by author Gemini assisted

AGENTS.md의 철학: 새로운 에이전트가 이 코드베이스에 처음 투입됐을 때 알아야 할 것들을 적는다. 일회성 컨텍스트가 아니라 영속적 프로젝트 규칙이다.

AGENTS.md 표준은 현재 60,000+ 오픈소스 프로젝트에서 채택됐다 [Foundation, 2026]. Linux Foundation 산하 Agentic AI Foundation으로 이관된 크로스벤더 표준이다.

좋은 AGENTS.md의 구조 [Code, 2026]:


# Project Rules

## Overview
<2-3 문장으로 이 프로젝트가 무엇을 하는지>

## Stack & Architecture
<핵심 기술 스택, 주요 디렉토리 역할>

## Code Standards
<린터, 포맷터, 네이밍 컨벤션, 함수 길이 등>

## Testing
<테스트 명령어, 커버리지 기대치, 모킹 정책>

## Git Workflow
<브랜치 전략, 커밋 메시지 형식>

## Common Mistakes to Avoid
<에이전트가 자주 틀리는 것들 — 실제 경험 기반>

구체적인 예시 (Node.js / TypeScript 프로젝트):


# Project Rules

## Overview
Express.js REST API for user management. PostgreSQL + TypeORM.
Main entry: src/app.ts. Test: npm test (Jest).

## Stack
- Node.js 20+, TypeScript 5.4 strict
- Express.js 4.18, TypeORM 0.3
- PostgreSQL 16
- Jest 29 for testing

## Code Standards
- ESLint + Prettier enforced (run: npm run lint)
- Functions < 40 lines
- No any type unless absolutely necessary — use unknown + type guards
- Repository pattern for database access (src/repositories/)

## Testing
- Unit: Jest with jest.mock() for external deps
- Integration: supertest against real test DB
- Run before commit: npm test
- No console.log in tests

## Common Mistakes to Avoid
- Don't import directly from TypeORM in controllers — use repositories
- Don't use req.body directly — validate with Zod schemas first
- Don't catch and swallow errors — let them propagate to error middleware

AGENTS.md를 얼마나 자세히 써야 하는가? [Osmani, 2026]의 조언: "AI가 생성한 AGENTS.md는 실패한다. 사람이 직접 쓴 것만이 실제로 작동한다." 에이전트가 자꾸 틀리는 것을 발견할 때마다 그 항목을 추가한다 — 이것이 살아있는 문서가 되는 방식이다.

단, 이와 반대 주장도 있다 [Jagtap, 2026]: GEPA(Generalized Evolutionary Prompt Automation) 방식으로 에이전트 실행 결과를 피드백으로 AGENTS.md/SKILL.md를 자동 튜닝하면 수작업보다 성능이 좋아진다. 두 접근법의 중간점 — 초기 초안은 사람이 쓰고, 반복적인 실패 패턴은 자동화로 보완한다.

5.4 ~/.codex/config.toml — 실전 설정


# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"  # minimal / low / medium / high / xhigh
sandbox_mode = "workspace-write"   # 권장 시작점 (read-only / workspace-write / danger-full-access)
approval_policy = "on-request"     # 요청 시 확인 (untrusted / on-request / never; on-failure는 deprecated)

# 선택 사항
[providers]
  [providers.openai]
  api_key_env = "OPENAI_API_KEY"   # 환경변수에서 읽기

approval_policy 옵션 [OpenAI, 2026]:

  • untrusted: 신뢰하지 않는 명령 실행 시 매번 확인 (가장 보수적)
  • on-request: 모델이 요청할 때 확인 (interactive 작업의 권장 default; 이전의 on-failure를 대체)
  • never: 자동 승인 (CI/CD 등 non-interactive 실행에 적합)

프로덕션 코드를 건드리는 태스크엔 untrusted, 개인 프로젝트나 테스트 작성엔 on-request가 적당하다.

config 파일에 대한 솔직한 주의. config 파일이 항상 권위를 갖는 것은 아니다. Codex GitHub issue #11354 [contributors, 2026]는 config에 subagents = false를 설정해도 /review 명령이 서브에이전트를 다시 활성화한 사례를 기록한다 — config가 조용히 덮어쓰였다. config가 쓸모없다는 뜻이 아니라, config는 기본값을 설정하지만 특정 명령이 그것을 override할 수 있다는 뜻이다. 특히 안전 게이트 역할을 하는 approval_policy 설정이 실제로 의도한 동작을 통제하는지 반드시 테스트하라.

Figure 5.2: config.toml 실전 설정 — model·effort·sandbox_mode·approval_policy 4개 키가 Codex 동작의 대부분을 결정한다. illustration by author Gemini assisted
Figure 5.2: config.toml 실전 설정 — model·effort·sandbox_mode·approval_policy 4개 키가 Codex 동작의 대부분을 결정한다. illustration by author Gemini assisted

5.5 첫 서브에이전트 — .codex/agents/reviewer.toml

Figure 5.3: TOML 기반 서브에이전트 정의 — name·description·developer_instructions 3개 필드만으로 전문 역할을 분리한다. illustration by author Gemini assisted
Figure 5.3: TOML 기반 서브에이전트 정의 — name·description·developer_instructions 3개 필드만으로 전문 역할을 분리한다. illustration by author Gemini assisted

서브에이전트는 특정 역할에 집중하는 전문 에이전트다. 첫 서브에이전트로 코드 리뷰어를 만들어보자 [OpenAI, 2026]:


# .codex/agents/reviewer.toml
name = "reviewer"
description = "Code reviewer focused on security and performance"
developer_instructions = """
You are a code reviewer. When called:
1. Check for SQL injection vulnerabilities
2. Check for missing input validation
3. Check for inefficient database queries (N+1 problems)
4. Check for missing error handling
5. Report findings as a numbered list with file:line references

Be specific and actionable. Don't flag style issues — focus on correctness and security.
"""

이제 메인 에이전트가 이 서브에이전트를 호출한다:


codex exec "implement the create-user endpoint, then have the reviewer check it"

Willison이 기록한 대로, subagents는 2026-03-16에 GA됐다 [Willison, 2026]. 기본 제공 서브에이전트 세 가지: explorer(코드베이스 탐색), worker(코드 실행), default(범용). 커스텀 서브에이전트는 이 위에 추가된다.

5.6 skills — .codex/skills/test-gen/SKILL.md

Skills는 재사용 가능한 태스크 지시 모음이다 [OpenAI, 2026]. Codex가 AGENTS.md에서 skill frontmatter를 읽고, 필요할 때 전체 내용을 로드한다:


---
name: test-gen
description: Generate Jest unit tests for TypeScript functions
triggers:
  - "write tests"
  - "add unit tests"
  - "test coverage"
---

# Test Generation Rules

When generating Jest tests for this project:

1. Import from `@/` aliases (configured in tsconfig paths)
2. Mock external dependencies: `jest.mock('typeorm')` for ORM
3. Use `describe` blocks by function name
4. Test both success and error paths
5. Aim for 80%+ coverage of new code

## Example Structure
\```typescript
describe('UserService.createUser', () => {
  it('should create user with valid data', async () => { ... });
  it('should throw on duplicate email', async () => { ... });
  it('should hash password before saving', async () => { ... });
});
\```

5.7 사람이 직접 쓸 것인가, 자동화할 것인가

이 논쟁을 솔직하게 정리한다.

사람이 직접 써야 한다 (Osmani) [Osmani, 2026]: AI가 생성한 AGENTS.md는 실제 코드베이스 특성이 반영되지 않아 실패한다. 진짜 병목은 무엇인지, 진짜로 피해야 할 패턴이 무엇인지는 사람만이 안다.

자동화로 보완할 수 있다 (Jagtap) [Jagtap, 2026]: 에이전트 실행 로그에서 반복적 실패 패턴을 추출해 AGENTS.md에 자동 추가하면 인간 편향 없이 실제 실패 데이터에서 배운다.

실용적 결론: 초기 초안은 사람이 쓴다. 프로젝트가 성숙해지면 실행 로그 기반 자동 보완을 고려한다. 6장의 멀티에이전트 설계와 9장의 메타하네스가 이 자동화 방향으로 이어진다.

참고문헌

  1. OpenAI Codex repo, "AGENTS.md example," 2026. [OpenAI, 2026]
  2. AGENTS.md Open Standard, "60K+ projects," 2026. [Foundation, 2026]
  3. OpenAI, "AGENTS.md specification," 2026. [OpenAI, 2026]
  4. OpenAI, "Codex config reference," 2026. [OpenAI, 2026]
  5. OpenAI, "Codex subagents," 2026. [OpenAI, 2026]
  6. OpenAI, "Codex skills," 2026. [OpenAI, 2026]
  7. Willison, Simon, "Codex subagents GA," simonwillison.net, 2026-03-16. [Willison, 2026]
  8. Augment, "How to build a great AGENTS.md," 2026. [Code, 2026]
  9. Osmani, Addy, "Code orchestra — multi-model routing," 2026. [Osmani, 2026]
  10. Jagtap, "Codex AGENTS.md auto-optimization," 2026. [Jagtap, 2026]
  11. Vjujini, "Codex app — Korean hands-on review," 2026. [velog), 2026]