Codex 하네스 설계와 서브에이전트 지침 - OpenAI

OpenAI가 2026년 1월부터 9월까지 낸 글과 문서를 모았다. Codex 하네스, 장기 작업, 서브에이전트, 샌드박스, 모델별 프롬프트를 다룬다. openai.com/index 글 네 건은 Cloudflare 403으로 본문을 읽지 못했다. 이 네 건은 검색 발췌만 확인했다. 나머지 문서는 전문을 확인했다.

에이전트 루프와 플랫폼

  • Unrolling the Codex agent loop (2026-01-23, 발췌만 확인): 모델이 도구를 요청하면 Codex가 실행하고 결과를 돌려준다. 모델이 응답할 때까지 이를 반복한다.
  • Introducing the Codex app (2026-02-02, 발췌만 확인): 병렬 에이전트, 격리된 worktree, 스킬을 소개한다.
  • Unlocking the Codex harness (2026-02-04, 발췌만 확인): App Server를 다룬다. 발췌 외 세부는 확인하지 못했다.
  • Harness engineering (2026-02-11, 발췌만 확인): 발췌 외 세부는 확인하지 못했다.
  • Codex as a platform (2026-08-19): 루프, 컨텍스트, 도구, 샌드박스·승인 정책을 공유 기반으로 둔다. 작업 흐름의 컨텍스트와 경계는 애플리케이션이 정한다.

장기 작업: 지속 프로젝트 파일

Run long horizon tasks with Codex (2026-02-23)

  • 명세, 계획, 런북, 상태, 결정을 프로젝트 파일로 남긴다.
  • 마일스톤마다 검증한다.
  • 문제가 있으면 고친 뒤 다음으로 넘어간다.

지침 파일: AGENTS.md

AGENTS.md 문서

  • 전역 파일 하나를 먼저 읽는다.
  • 이어 루트부터 작업 디렉터리까지 프로젝트 파일을 읽는다. 작업 위치에 가까운 파일이 나중에 온다.
  • 합친 크기는 기본 32 KiB까지다.

서브에이전트

Subagents 문서

  • 독립적이고 범위가 정해진 작업에 쓴다.
  • 서브에이전트는 별도 컨텍스트에서 일하고 조율자에게 간결한 요약을 돌려준다.
  • 읽기 위주의 병렬 작업부터 시작한다. 쓰기 위주의 병렬 작업은 서로 충돌한다.
  • Luna는 빠르고 범위가 좁은 작업에 맞다.

샌드박스와 승인

Sandbox 문서는 workspace-write와 on-request 조합을 위험이 낮은 기본값으로 둔다. danger-full-access와 never 조합을 그 반대편으로 대비한다.

오케스트레이션과 가드레일

  • Agents SDK orchestration: 전문 에이전트가 한 갈래의 최종 응답을 맡으면 handoff를 쓴다. 관리자가 책임을 유지하면 “agents as tools”를 쓴다. 전문 에이전트는 계약이 달라질 때만 추가한다.
  • Guardrails and approvals: 자동 검사와, 사람이 검토하도록 멈추는 지점을 구분한다.

모델별 프롬프트

  • Rethinking skills and prompts for GPT-6 Astra (2026-09-11): 스킬 설명은 짧게 쓰고 점진적으로 공개한다. “문서를 모두 읽어라” 같은 일괄 지시는 피한다. Astra는 일찍 멈출 수 있으므로 완료 조건을 분명히 쓴다.
  • Codex Prompting Guide: GPT-5.3-Codex를 대상으로 한다. 압축(compaction)을 다룬다.

Anthropic 원천과 다른 점

두 원천의 차이를 합치지 않고 그대로 기록한다.

  • 지침 파일: Codex는 AGENTS.md를 루트에서 작업 경로까지 자동으로 합친다. Claude Code 메모리 문서에 따르면 Claude Code는 상위에 CLAUDE.md가 있으면 AGENTS.md를 건너뛸 수 있다.
  • 장기 작업: OpenAI는 압축과 재개할 수 있는 세션을 강조한다. Anthropic은 재시작과 진행 파일을 강조한다.
  • Claude Code best practices는 모델이 따르는 지침과 결정적으로 작동하는 강제를 구분한다. 강제 쪽에는 hook·deny 규칙과 샌드박스가 있다.

검증 상태

Researcher가 developers.openai.com과 learn.chatgpt.com 문서는 전문을 확인했다. openai.com/index 글 네 건은 검색 발췌만 확인했다. 메인은 직접 대조하지 않았다.

적용 해석

아래는 원문의 주장이 아니라 우리의 해석이다.

  • 두 회사의 장기 작업 방식은 다르다. 공통 불변식은 프로젝트 안에 남는 지속 상태다.
  • 서브에이전트 문서의 “읽기 위주부터, 쓰기 병렬은 충돌” 원칙은 위임 방식 문구에서 병렬을 절제한 근거다.
  • 모델별 지침은 참고로만 읽는다. 모델별 지침을 따로 두는 방식은 채택하지 않았다.

연결

백링크

그래프 뷰

이 문서로 이어지는 주제