Codex의 하네스 설계: 저장소가 사실의 원천, AGENTS.md는 디렉터리 페이지

왕초보 설명

  • 이게 뭐야? OpenAI의 터미널 AI 코딩 도구 Codex를 하네스 관점에서 뜯어본 코스 글이다. Codex는 기능을 잔뜩 넣기보다 **규칙(규약)**으로 승부한다: 프로젝트 지식은 저장소 문서에 두고, AGENTS.md는 그 문서들의 목차로만 쓴다.
  • 비유: 두꺼운 백과사전 한 권 대신, 도서관 입구의 안내도 한 장. 안내도가 각 서가(docs/)를 가리킨다.
  • 나는 뭘 하면 돼? AGENTS.md를 100줄 안팎으로 짧게 쓰고 “절대 어기면 안 되는 규칙 + 확인 명령(테스트·린트)“만 적는다. 자세한 설명은 docs/에 나눠 두고 링크한다. 작업마다 따로 작업 폴더(git worktree)를 쓰면 서로 엉키지 않는다.

구조 요약

한 문장(원문): 저장소가 사실의 원천(repository as the system of record)이고, AGENTS.md는 디렉터리 페이지일 뿐이며, 엔지니어링의 가치는 환경을 설계하고 의도를 표현하며 피드백 루프를 구축하는 데 있다. 이 분야의 이름을 붙인 OpenAI 《Harness Engineering》 글이 Codex로 제품을 만든 경험을 정리한 것이라, Codex 분석은 곧 그 글의 배경 실천 분석이다. Codex CLI 자체는 Rust로 만든 오픈소스 단일 바이너리다.

다섯 하위 시스템으로 보기(원문 매핑 표)

하위 시스템Codex의 구현원문 평가
지시AGENTS.md 디렉터리 페이지 + docs/ 분할 + 불변 조건”지도를 줘라”를 정의한 교과서적 구현
도구worktree 격리 + spawn_agent subagent환경으로 경계를 강제
환경독립 worktree + 관찰 가능성 스택worktree 격리가 대표 특징
상태Write 전략(상태를 파일·문서에)내장 메모리가 아니라 규약에 의존
피드백검증 명령을 규약에 + 승인 정책 + plan mode피드백 경로를 기본값으로

지시: 디렉터리 페이지. 거대한 지시 파일은 커버리지·최신성·소유권·교차 링크를 기계적으로 검사하기 어렵고 현실과 어긋난다. 그래서 AGENTS.md를 약 100줄로 제한하고, 넘치면 docs/로 나눠 필요할 때 읽게 한다(map-not-manual, lecture-04). 함께 쓰는 원칙: 구현을 세세하게 관리하지 말고 불변 조건을 강제하라(강제 제약 + 검증 명령만, 방법은 모델에게, lecture-02).

컨텍스트: Write-Select-Compress-Isolate(커뮤니티가 Codex에 매핑한 틀)

전략뜻Codex에서
Write컨텍스트를 창 밖에 영속화결론은 문서, 상태는 파일(repo-system-of-record)
Select필요한 token만 창으로AGENTS.md가 길 안내, 파일은 필요할 때
Compress중요한 것만 남김자동 compaction + 수동 /compact, compact_prompt 설정
Isolate경계별로 나눔subagent마다 다른 컨텍스트

세부: 커뮤니티 소스 분석에 따르면 build_environment_update_item은 매번 전체 시스템 컨텍스트를 다시 붙이지 않고 CWD·git 브랜치·파일 시스템 중 바뀐 필드만 낸다.

도구와 경계

  1. git worktree 환경 격리: 각 작업을 독립 worktree에서 돌리고 로컬 관찰 스택(로그·메트릭·트레이스)으로 변경마다 검증. 경계를 프롬프트로 부탁하지 않고 환경으로 강제한다(lecture-07).
  2. 커널 수준 subagent: spawn_agent/wait_agent. subagent는 부모 AGENTS.md를 상속하되 자기 컨텍스트에서 돈다. 설정은 .codex/agents/*.toml(모델·지시를 따로 지정).

피드백: AGENTS.md에 검증 명령을 적어 “제대로 했는지 확인하는 방법”을 저장소의 일부로 만든다(verification-commands). 테스트·CI·문서·관찰 설정까지 Codex가 생성한다. 승인 정책과 plan mode는 고위험 작업 전에 계획과 승인을 요구한다.

원문이 꼽는 참고할 설계: ① AGENTS.md를 약 100줄 디렉터리 페이지로 ② 불변 조건만, 구현은 맡기기 ③ worktree로 환경 격리 ④ 환경 컨텍스트는 변경분만 ⑤ subagent로 컨텍스트 격리.

다른 하네스와의 비교

항목claude-codecodex (이 페이지)deepseekpioh-my-claudecodegajae-code
정체Anthropic의 공식 CLI. 단순한 while 루프 + 루프를 둘러싼 시스템OpenAI의 오픈소스 Rust 단일 바이너리 CLI. 《Harness Engineering》 글의 배경dsh, 2026-08 Developer Preview. Agent = Model + Environment + Tools + State, 모든 것이 plugin(Cordis 커널)“minimal agent harness”. npm @earendil-works/pi-coding-agent. 작은 커널 + 프로그래밍 가능한 확장Claude Code 위에 얹는 플러그인독립 실행 CLI 하네스(oh-my-pi 계열)
지시CLAUDE.md 4범위(조직/사용자/프로젝트/로컬) + 하위 디렉터리 필요 시 로드 + auto memory(첫 200줄 또는 25KB)AGENTS.md = 약 100줄 디렉터리 페이지 + docs/ 분할, 불변 조건과 검증 명령만규칙·스킬을 plugin으로 주입. CLAUDE.md 같은 내장 규약 없음AGENTS.md 계층 로드(전역 → 상위 디렉터리 → 현재, CLAUDE.md 호환) + SYSTEM.md replace/append스킬 48개, 에이전트 19개 + 키워드 자동 감지번들 스킬 4개 + 역할 4개만, 명시적으로 부를 때만
계획 단계원문(분석 글)에 서술 없음plan mode(고위험 작업 전 계획 작성·승인 요청)원문(분석 글)에 서술 없음원문(분석 글)에 서술 없음deep-interview(모호함 ≤20%) → ralplandeep-interview(기본 기준 5%) → ralplan(최대 5회, 코드로 수정 차단)
실행 루프모델 호출 → 도구 실행 → 관찰 반복. lecture-13: /goal, /loop, Routines원문(분석 글)에 서술 없음. lecture-13: /goal(수동 활성화), Automations, codex exec + cron이벤트 파이프라인(turn/start → … → step/end). agent 루프 자체도 교체 가능한 pluginwhile 루프. TUI 외에 print/JSON 모드·RPC·SDK로 외부 프로그램이 구동ralph(prd.json 이야기별 반복), autopilot, team 5단계ultragoal(goals.json 목표별 반복 + goal 모드)
계속 돌게 하는 장치Stop hook이 완료 선언 시점에 개입 가능(OMC가 이 지점을 사용)원문(분석 글)에 서술 없음. lecture-13: 스레드 자동화·독립 실행형 자동화agent/turn-stopping 이벤트를 받아 추론 계속 여부 결정hooks로 외부(파일 감시·Webhook·CI)에서 메시지를 넣어 agent를 깨움Stop 훅(persistent-mode)이 턴 종료를 막음, 안전 상한 기본 500회goal 모드 연속 실행 + nudgeBudget(목표당 기본 10회)
상태append-only history.jsonl + /resume·fork + 5단계 compactionWrite 전략(상태를 파일·문서에) + 자동·수동 /compact(compact_prompt 설정)append-only Session Event Logsession 트리(/tree, 한 파일에 모든 브랜치) + 교체 가능한 compaction(최근 약 2만 token 유지).omc/state/sessions/<id>/prd.json, progress.txt.gjc/_session-<id>/ultragoal/goals.json, ledger.jsonl
피드백permissions 7모드 + ML 분류기, PostToolUse hook 강제 검사검증 명령을 AGENTS.md 규약에, 작업마다 git worktree + 로그·메트릭·트레이스로 검증tools/pre-execute의 permission·guard·policy·hook + “Model-visible means logged” 런타임 불변 조건강제 테스트 gate 없음. 검증 명령은 사용자가 AGENTS.md에. 커뮤니티 확장 session-summary·extract-patterns·telemetryomc ralph verify가 기준선 대비 새 실패만 판정, 리뷰어 검증목표별 quality-gate + 마지막 경계 검토 + 종료 critic OKAY
역할 분리subagent 대화를 별도 sidechain 파일로 격리spawn_agent/wait_agent subagent, .codex/agents/*.toml로 모델·지시 지정SubAgent도 교체 가능한 능력 접합부(capability seam)원문(분석 글)에 서술 없음단계별로 다른 에이전트·모델 등급(haiku/sonnet/opus)읽기 전용 planner·architect·critic vs 쓰기 가능한 executor
사람 개입permissions 정책에 따라 고위험 작업은 질문 또는 거부승인 정책(approval policies) + plan mode원문(분석 글)에 서술 없음hooks로 위험 명령 가로채기(permissions gate)·경로 보호매직 키워드만 말하면 자동 진행기본은 계획 승인 1회. autoHandoff=ultragoal이면 0회
왕초보에게기본 내장이 많아 바로 쓴다. 확장 4종(스킬·MCP·hooks·subagent)의 역할 구분은 배워야 한다기능보다 규약. 저장소를 잘 정리해 둘수록 효과가 커진다자유도가 가장 높지만 설정 비용도 가장 크다. 아직 Developer Preview가장 가볍지만 필요한 장치는 직접 만들거나 패키지로 설치해야 한다기능이 많아 강력하지만 무겁다흐름이 하나라 배우기 쉽다. 대신 git 필수
  • 원문의 대비: claude-code는 메모리·permissions·subagent를 모두 커널에 넣는 “덧셈”, Codex는 커널을 절제하고 책임을 저장소 규약과 컨텍스트 엔지니어링에 두는 “뺄셈”.
  • gajae-code 저장소 자신의 AGENTS.md는 스스로를 “아키텍처 지도 + docs/에서 유도할 수 없는 규칙”으로 정의하고 깊은 내용은 docs/로 보낸다. 디렉터리 페이지 발상은 같지만 길이는 206줄로, 이 글이 권하는 약 100줄의 두 배다. 또한 gjc는 계획·실행 워크플로(스킬 4개)를 기본으로 내장한다는 점에서 Codex보다 “덧셈” 쪽이다.

원문 경로

  • ko: raw/learn-harness-engineering/docs/ko/harness-designs/codex/index.md
  • en: raw/learn-harness-engineering/docs/en/harness-designs/codex/index.md
  • 원문이 드는 1차 출처: OpenAI 《Harness Engineering》, OpenAI 《AGENTS.md》 규약, github.com/openai/codex, 커뮤니티 글 “Context Engineering for Codex CLI”, 커뮤니티 소스 분석 codex-harness-internals. 이 위키는 외부 문서를 직접 확인하지 않았다.

원문 간 차이

  • 같은 OpenAI 사례를 이 글은 “몇 주 만에(in a matter of weeks) 100만 줄 넘게, 모든 줄을 Codex가 작성”이라고, lecture-13은 “작은 팀이 새 저장소에서 다섯 달 동안 약 100만 줄, 약 1,500 PR”이라고 쓴다. 기간이 다르다.
  • AGENTS.md 길이: 이 글과 lecture-02는 약 100줄, lecture-04는 50~200줄을 권한다(map-not-manual의 열린 질문).