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

5.1 이 장의 질문: 새로 시작인가, 이어받기인가

Codex에서 하네스를 짓는다고 하면 파일 이름부터 떠오른다. AGENTS.md, ~/.codex/config.toml, .codex/agents/, .codex/skills/. 하지만 실제 사용자가 처음 막히는 지점은 파일 형식이 아니다. 더 현실적인 질문은 이것이다.

"빈 프로젝트에서는 Codex에게 뭐라고 말해야 첫 하네스가 생기는가?"

"이미 Claude Code로 만든 repo에서는 무엇을 남기고, 무엇을 Codex 쪽으로 옮겨야 하는가?"

이 두 경우는 출발점이 다르다. 빈 프로젝트에서는 규칙을 처음부터 함께 만든다. 기존 Claude Code 프로젝트에서는 이미 존재하는 CLAUDE.md, .claude/agents/, hooks, skills, slash command를 해석하고, 그중 도구 독립 지식만 Codex가 읽을 수 있는 형태로 빼낸다.

따라서 이 장은 예시 파일을 복사하라는 장이 아니다. 예시처럼 좋은 파일이 나오도록 어떤 프롬프트를 주고, 어떤 결과를 검토해야 하는지를 설명하는 장이다.

5.2 두 경로의 전체 순서

먼저 결론부터 보자.

빈 프로젝트의 순서는 간단하다.

1. 프로젝트 목적과 품질 기준을 말한다.
2. Codex에게 AGENTS.md 초안을 만들게 한다.
3. config는 전역 기본값으로 보수적으로 설정한다.
4. 반복되는 작업이 실제로 생긴 뒤에 skill이나 subagent를 만든다.

기존 Claude Code repo의 순서는 더 조심스럽다.

1. Read Only로 CLAUDE.md와 .claude/를 읽게 한다.
2. 현재 상태를 HANDOFF.md로 압축한다.
3. CLAUDE.md의 범용 규칙만 AGENTS.md로 복사한다.
4. Claude 전용 agent/skill/hook은 남겨둔다.
5. 반복 workflow만 Codex skill, subagent, wrapper script로 재구성한다.

5.3 빈 프로젝트: 첫 AGENTS.md는 프롬프트로 만든다

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

AGENTS.md 표준은 현재 60,000+ 오픈소스 프로젝트에서 채택됐다 ^[2]. 정확히 말하면, 60,000+ 프로젝트가 아래 구조를 그대로 쓴다는 뜻은 아니다. 널리 채택된 것은 repo 안에 AGENTS.md라는 에이전트용 지시 파일을 두는 관습과 discovery 규칙이다. 아래 구조는 그 관습을 처음 적용할 때 쓰기 좋은 템플릿이다.

빈 프로젝트에서 바로 쓸 수 있는 첫 프롬프트:

이 repo는 새 프로젝트다. 아래 목표를 바탕으로 AGENTS.md 초안을 만들어라.

프로젝트 목표:
- <무엇을 만드는지 2-3문장>

기술 스택:
- <언어/프레임워크/DB/테스트 도구. 아직 미정이면 "미정"이라고 쓴다>

내가 중요하게 보는 기준:
- <예: 작은 diff, 테스트 우선, 배포 안전성, 논문 인용 정확성>

출력 조건:
- AGENTS.md 파일 하나만 제안하라
- 100줄 이하
- 확인하지 못한 명령은 추측하지 말고 TODO로 표시하라
- 처음부터 subagent나 skill은 만들지 마라
- Common Mistakes는 지금 아는 것만 3개 이하로 적어라

이 프롬프트의 핵심은 "표준으로 만들어줘"가 아니다. 표준은 파일 이름과 discovery 방식에 가깝다. 실제 내용은 프로젝트 목적, 기술 스택, 품질 기준에서 나온다. 따라서 "AGENTS.md 표준에 맞게 만들어줘"라고만 하면 너무 일반적인 문서가 나온다. 반드시 프로젝트 목표와 금지 사항을 같이 줘야 한다.

처음 AGENTS.md는 60-120줄 정도가 가장 다루기 쉽다. 150-200줄을 넘기면 에이전트가 핵심을 놓치거나 오래된 규칙이 실제 코드와 어긋나기 쉽다. 길어지기 시작하면 하나의 거대한 파일로 만들지 말고 서브디렉토리별 AGENTS.md, skill, HANDOFF.md, TASKS.md로 분리한다.

좋은 초안의 기본 구조는 이 정도면 충분하다 ^[8].

# Project Rules

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

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

## Code Standards
<린터, 포맷터, 네이밍, 함수 크기, 타입 규칙>

## Testing
<테스트 명령, 반드시 돌려야 할 검증, 아직 없으면 TODO>

## Git Workflow
<브랜치/커밋/PR 규칙. 필요 없으면 생략>

## Common Mistakes to Avoid
<에이전트가 틀리기 쉬운 것. 실제 경험이 쌓이면 갱신>

5.4 config.toml은 복붙보다 "프로필 선택"이다

~/.codex/config.toml은 프로젝트 파일이 아니라 사용자 전역 설정이다. 그래서 책에 있는 예시를 그대로 복사하기 전에, 자신이 원하는 기본 동작을 먼저 정해야 한다. 처음에는 보수적인 설정이 좋다.

빈 프로젝트용 첫 설정:

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
project_doc_max_bytes = 65536

기존 Claude Code repo를 함께 다룰 때만 임시 bridge를 추가한다.

project_doc_fallback_filenames = ["CLAUDE.md"]

이 줄은 CLAUDE.md를 지우거나 AGENTS.md로 rename하라는 뜻이 아니다. Codex는 AGENTS.override.md, AGENTS.md, fallback 파일 순서로 instruction을 찾는다 ^[15]. 아직 AGENTS.md가 없는 repo에서 CLAUDE.md를 참고할 수 있게 하는 임시 안전장치일 뿐이다.

2026년 6월 현재는 sandbox_mode만으로 끝내지 말고 permission profile과 rules를 함께 이해해야 한다. 기본 작업은 workspace-write로 충분하지만, 반복적으로 sandbox 밖 실행이 필요한 명령은 .rules의 prefix_rule로 allow/prompt/forbid를 명시한다 ^[15]. 반대로 .env, private key, production credential은 permission profile에서 deny로 막는다. "프롬프트로 읽지 말라"고 쓰는 것보다, 파일시스템 권한으로 읽지 못하게 하는 편이 더 안정적이다.

Codex에게 config 초안을 요청할 때는 이렇게 말한다.

내 Codex 전역 config.toml 초안을 제안해라.
목표는 안전한 로컬 개발이다.

조건:
- sandbox는 workspace-write를 기본으로 한다
- approval은 interactive 작업에 맞게 on-request를 쓴다
- 기존 Claude Code repo도 읽을 수 있게 할지 여부를 별도 옵션으로 설명한다
- 파일을 직접 수정하지 말고, 먼저 TOML 블록과 각 줄의 의미를 설명하라

config는 기본값을 정하는 파일이지 모든 상황을 강제로 통제하는 절대 규칙은 아니다. 특정 명령이나 제품 표면이 config를 override할 수 있으므로, 안전 게이트로 쓰는 approval_policy와 sandbox_mode는 실제 세션에서 /status로 확인한다 ^[15].

5.5 기존 Claude Code repo: 먼저 변환하지 말고 해석시켜라

Claude Code로 오래 작업한 repo에는 코드만 있는 것이 아니다. CLAUDE.md, .claude/agents/, hooks, skills, slash command, 메모리 규칙, 반복 workflow가 함께 들어 있다. Codex로 넘어갈 때 가장 위험한 실수는 이 파일들을 Codex 형식으로 바로 변환하려는 것이다.

처음 프롬프트는 변환이 아니라 해석이어야 한다.

이 repo는 Claude Code 하네스를 이미 사용한다.
절대 CLAUDE.md, .claude/, hooks, skills, subagents를 삭제하거나 rename하지 마라.

Read Only로 다음을 분석해라:
- CLAUDE.md의 도구 독립 규칙
- Claude 전용 규칙
- .claude/agents의 역할
- hooks/skills/slash command가 실제로 해결하는 workflow

출력:
- AGENTS.md로 옮길 항목
- HANDOFF.md에 기록할 현재 상태
- Codex skill로 재구성할 후보
- Codex subagent로 재구성할 후보
- 그대로 Claude Code에 남겨야 할 항목

파일 수정은 아직 하지 마라.

이 요청의 결과는 보통 다음과 같은 분류표가 되어야 한다.

그 다음에야 작은 파일 하나를 만들게 한다.

방금 분류표를 바탕으로 1단계만 수행해라.
AGENTS.md 초안만 추가하라.
CLAUDE.md와 .claude/ 아래 파일은 수정하지 마라.
AGENTS.md에는 도구 독립 규칙만 넣고, Claude 전용 지시는 넣지 마라.
변경 후 diff 요약을 제공하라.

5.6 agents와 skills는 언제 만들까

처음부터 .codex/agents/와 .codex/skills/를 가득 채우면 안 된다. AGENTS.md만으로도 대부분의 첫 작업은 충분하다. agent와 skill은 반복되는 문제가 보일 때 만든다.

구분은 이렇게 하면 된다.

Claude Code agent를 Codex subagent로 바꿀 때의 프롬프트:

.claude/agents/reviewer.md를 읽고 Codex subagent 초안을 제안해라.

조건:
- 목적과 판단 기준만 옮긴다
- Claude Code 전용 호출 방식이나 tool 이름은 제거한다
- .codex/agents/reviewer.toml 형식으로 제안한다
- name, description, developer_instructions만 사용한다
- 파일 수정은 하지 말고 먼저 초안을 보여준다

예상되는 Codex subagent 형식:

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness, security, and maintainability"
developer_instructions = """
When called, review the current diff only.
Prioritize correctness, security, data loss, and missing tests.
Report findings with file:line references.
Do not comment on style unless it affects behavior.
"""

Claude Code skill이나 slash command를 Codex skill로 바꿀 때의 프롬프트:

.claude/skills/test-gen 또는 관련 slash command를 읽고 Codex skill 초안을 제안해라.

조건:
- 반복되는 작업 지시만 SKILL.md에 넣는다
- shell 실행, 파일 이동, publish 같은 운영 절차는 skill에 넣지 말고 wrapper script 후보로 분리한다
- .codex/skills/test-gen/SKILL.md 형식으로 제안한다
- 트리거 문구와 사용 예시를 포함한다
- 파일 수정은 하지 말고 먼저 초안을 보여준다

Skills는 재사용 가능한 태스크 지시 모음이다 ^[15]. Claude Code의 slash command를 그대로 옮기는 것이 아니라, "모델이 어떤 방식으로 일을 해야 하는가"만 skill에 남기는 편이 안전하다. 실행 절차는 bin/* wrapper나 make 명령으로 고정한다.

5.7 공식 import를 써도 검토는 사람이 한다

OpenAI의 Codex app은 Import other agent setup 흐름을 제공한다. Settings의 General 페이지에서 import를 실행하면 Codex가 사용자 수준 설정과 현재 프로젝트 설정을 감지하고, 직접 가져올 수 있는 항목을 가져온 뒤, 남은 항목은 새 thread에서 follow-up migration 작업으로 이어갈 수 있다 ^[15].

공식 import가 다루는 범위는 다음과 같다 ^[15].

하지만 이 표를 "그대로 가져오면 끝"으로 읽으면 안 된다. import는 초안 생성 도구다. 특히 hook, slash command, subagent는 형식보다 목적이 중요하다. 예를 들어 /post 는 Codex slash command로 억지 이식하기보다 다음 두 층으로 나누는 편이 안전하다.

codex-native skill: .codex/skills/post/SKILL.md
stable wrapper:     bin/post <url>

wrapper는 shell 인자 처리, draft 기본값, publish 금지, HANDOFF.md 업데이트 같은 운영 정책을 코드로 고정한다. skill은 "좋은 글로 바꾸는 방법" 같은 모델 지시를 담는다. 이렇게 나누면 Claude Code가 계속 돌아가는 동안에도 Codex가 같은 workflow를 작은 diff 단위로 재현할 수 있다.

import 후에는 이렇게 검토시킨다.

방금 import 또는 변환된 Codex 하네스를 리뷰해라.

확인할 것:
- CLAUDE.md와 .claude/가 삭제되거나 rename되지 않았는가
- AGENTS.md에 Claude 전용 지시가 섞이지 않았는가
- skills에 위험한 shell 실행 절차가 들어가지 않았는가
- subagent가 너무 넓은 역할을 갖지 않는가
- MCP 인증, secret, 배포 명령이 자동 실행되지 않는가

수정하지 말고 위험 목록과 권장 diff만 제안해라.

2026-06-09 업데이트에서 Codex는 Claude Code와 Claude Cowork 계열 setup을 가져오는 onboarding flow를 더 전면에 배치했다 ^[15]. 이 기능이 유용한 이유는 "자동 이식"이 아니라 누락 목록을 드러내기 때문이다. Codex가 직접 가져오지 못한 hook, MCP auth, prompt template, path placeholder는 새 thread에서 migrate-to-codex skill로 이어받을 수 있다. 실무에서는 import 결과보다 "남은 항목 목록"이 더 중요하다. 바로 그 목록이 사람이 검토해야 할 migration risk register다.

5.8 실용적 결론: 초안은 만들게 하되, 소유권은 사람이 가진다

AGENTS.md와 하네스를 사람이 직접 써야 하는지, 자동화로 만들 수 있는지는 논쟁적이다.

사람이 직접 써야 한다 (Osmani) ^[9]: AI가 생성한 AGENTS.md는 실제 코드베이스 특성이 반영되지 않아 실패한다. 진짜 병목과 피해야 할 패턴은 사람의 경험에서 나온다.

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

이 책의 결론은 중간이다. 초안은 Codex에게 만들게 해도 된다. 하지만 무엇을 규칙으로 채택할지는 사람이 결정한다. 빈 프로젝트에서는 목적과 제약을 주고 AGENTS.md 초안을 만들게 한다. 기존 Claude Code repo에서는 먼저 해석과 분류를 시킨 뒤, 작은 diff로 AGENTS.md, HANDOFF.md, skill, subagent를 하나씩 추가한다.

즉 이 장의 실행 순서는 이렇게 요약된다.

1. 빈 프로젝트라면 목적을 설명하고 AGENTS.md 초안을 요청한다.
2. 기존 Claude Code repo라면 먼저 CLAUDE.md와 .claude/를 Read Only로 분석시킨다.
3. config는 복붙하지 말고 자신의 안전 프로필에 맞게 선택한다.
4. agent와 skill은 처음부터 만들지 말고 반복 패턴이 생긴 뒤 만든다.
5. import나 자동 변환 결과는 반드시 사람이 리뷰한다.

다음 장에서는 이렇게 만든 하네스를 실제 작업 루프에 넣는다. 작은 diff를 만들고, reviewer를 붙이고, 테스트로 검증하는 "검증 가능한 바이브 코딩"이 그 다음 단계다.

참고문헌

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]
12. OpenAI, "Migrate to Codex," 2026. [OpenAI, 2026]
13. OpenAI, "Migrate to Codex," Codex manual, 2026. [OpenAI, 2026]
14. OpenAI, "Codex rules," Codex manual, 2026. [OpenAI, 2026]
15. OpenAI, "Codex permissions," Codex manual, 2026. [OpenAI, 2026]