Codex Port Log

Claude Code Harness
Codex/OMX Migration

Claude Code에서 5개월간 다듬어 온 운영 틀(하네스 — AI에게 규칙과 검증 절차를 강제로 씌우는 장치)을, 오픈AI의 코딩 에이전트 Codex의 방식에 맞춰 그대로 옮긴 기록입니다. 두 개의 명령이 중심입니다. $init-project은 프로젝트를 처음 분석해, 그 코드의 고유 특성(DNA)과 반드시 지켜야 할 작업 규칙(계약)을 만듭니다. $team은 여러 AI 일꾼을 동시에 굴리는 명령입니다. 요구사항이 실제로 충족됐는지 검사하는 QA와, 작업 성격에 맞춰 실행 방식을 바꾸는 판단으로 전체를 조율합니다. 미리 만들어 둔 일반 템플릿은 하나도 쓰지 않았고(0개), 모든 규칙은 실제 코드에서 뽑아냅니다.

2
Core Skills
6
Agent Roles
5
Runtime Planes
0
Generic Templates
2026-06 Parity Sync

Claude Code에 새로 들어온 기능을 Codex에도 똑같이 맞춰 넣은 지점

Source Evidence

  • ~/.claude/skills/init-project/SKILL.md — 2026-06-11
  • ~/.claude/skills/team/SKILL.md — 2026-06-11
  • ~/.claude/commands/team.md — 2026-06-10
  • ~/.claude/agents/team-orchestrator.md — 2026-06-10

Codex Port

  • ~/.codex/skills/init-project/SKILL.md — 여러 단계(분석→팀 실행→QA)를 하나로 잇는 작업 흐름을 명시하도록 보강
  • ~/.codex/skills/team/SKILL.md — 요구사항 충족 여부를 검사하는 QA와, 작업 종류를 먼저 분류해 알맞게 처리하는 방식을 반영
  • ~/.codex/skills/harness-report/SKILL.md / harness-scorecard — 실제 실행 증거와 업그레이드 점검을 서로 연결
  • ~/.codex/prompts/team-orchestrator.md — 실행 전 반드시 통과해야 하는 사전 점검을 주입
  • ~/.codex/agents/team-orchestrator.toml — Claude에서만 돌도록 묶여 있던 설정을 제거

Behavioral Delta

  • 반드시 지켜야 할 작업 계약(hard contract)이 없으면 $team 은 구현 단계로 들어가지 못하고 막힘
  • 목표 수집·성공 기준·결과 검증·중단 조건 — 이 네 가지 경계를 '어기면 막히는' 강제 규칙으로 못박음
  • .qa-evidence.json라는 증거 파일 속 acceptance_verified[] 목록이 '통과(PASS)'의 진짜 기준 — 요구사항을 실제로 충족했다는 증거만 인정
  • harness-report → harness-scorecard → harness-upgrade-audit → $team preflight hard edge
  • 작업 성격에 따라 실행 방식을 자동 분류: 직접 처리 / 역할별 AI 일꾼에게 위임 / 여러 단계를 묶은 워크플로우
Port Principle
Claude Code의 기능을 Codex에 글자 그대로 베끼지는 않았다. Claude의 모델 3종(Fable·Sonnet·Haiku), 팀 생성 도구(TeamCreate), 워크플로우 도구는 그대로 옮기지 않았다. 대신 Codex에서는 역할별 AI 일꾼, 상위 설정을 물려받는 모델 지정, .codex/.omx 형식의 저장 파일, 그리고 '통과 못 하면 막는' 검증 명령으로 같은 목적을 지켰다.
Harness Strength

두 하네스 중 어느 쪽이 더 강력한가

Claude Code
15
HARD hooks
13
Agents
7
MCP servers
Plugin marketplace · in-memory state
User approval required
VS
Codex / OMX  WINNER
31
HARD hooks
29
Agents
11
MCP servers
0
SOFT rules
Autonomous execution · cross-session state
approval_policy=never
Verdict
결론부터 말하면 Codex 쪽이 더 강력하다. 작업을 강제로 막는 장치(HARD 훅)가 2배 많고(31개 대 15개), 파일 쓰기(Write)와 수정(Edit)을 따로 감시해 정밀하게 막는다. 역할을 맡은 AI 일꾼 29개마다 설정 파일(TOML)에 '무엇까지 해도 되는지' 제약이 박혀 있다. 사람 승인 없이 스스로 실행하되, 핵심 지점은 실제로 막는 방식이다. 말로만 권고하는 규칙(SOFT)은 0개 — 어기면 프로그램이 실패 신호(종료 코드 2)를 내며 작업을 막는 장치만 남겼다.

Codex가 앞서는 점

  • 작업을 강제로 막는 장치(HARD 훅) 31개 — 막을 수 있는 범위가 2배
  • 파일 쓰기와 수정을 따로 감시해 더 정밀하게 차단
  • 스스로 실행하면서도 핵심 지점은 강제로 막는 혼합 방식
  • .omx/state/ 폴더에 작업 상태를 저장해, 세션이 바뀌어도 이어감
  • 역할별 AI 일꾼 29개, 각 설정 파일(TOML)에 쓸 모델과 사고 강도까지 지정
  • 외부 도구 연결 통로(MCP 서버) 11개 — 상태·기억·코드 분석·추적·위키

Claude Code가 앞서는 점

  • 감지할 수 있는 이벤트(훅) 종류 16가지 — 하위 일꾼의 시작·종료까지 포함
  • 플러그인 장터가 있어 자동으로 설치·업데이트
  • ${CLAUDE_PLUGIN_ROOT} 변수가 플러그인 설치 위치를 자동으로 찾아줌
  • 웹 요청(HTTP) 방식의 훅도 지원

밑바탕이 된 원칙

  • 말로만 권고하는 규칙(SOFT)은 0개 — 강제할 수 있는 규칙은 전부 '어기면 막히는'(HARD) 방식
  • 종료 코드 2 = 작업을 실제로 막음 (AI가 임의로 건너뛸 수 없음)
  • 참고 문서 61개는 강제 규칙이 아니라 안내용 지침일 뿐
  • "평소엔 자유롭게 실행하되, 핵심만 실제로 막는다"
Architecture Overview

Codex 하네스의 전체 구조

Claude Code를 이루는 세 가지 — commands + hooks + agents를, Codex에서는 skills + native agents + OMX plugin runtime + project hooks라는 네 가지로 바꿔 옮긴 전체 그림입니다. 이름만 다를 뿐 하는 일은 같습니다.

rules feed User Request AGENTS.md Operational Contract $init-project Project DNA Extraction $team Parallel tmux Runtime OUTPUTS CODEX.md .codex/rules .codex/skills Project Hooks QA Contracts: .qa-inventory / qa-test-plan / qa-scenarios TMX RUNTIME Leader control plane Worker 1 executor Worker N executor .omx/state + mailbox + tasks + dispatch heartbeat: 30s | manifest.v2.json | config.json Memory Bank — HARD hook: UserPromptSubmit inject + Stop fact-extract — shared SQLite (69K exchanges, 3.7K facts) QA Evidence Gate
scroll horizontally on mobile →
Migration Map

Claude Code의 각 부분이 Codex/OMX에서 무엇에 대응하는가

Layer
Claude Code
Codex / OMX
Command Surface
/team, /init-project, slash commands
$team, $init-project, skill routing, keyword hooks
State
filesystem tasks, hook state, QA evidence
.omx/state, manifests, mailbox, dispatch queue, MCP state tools
Project Memory
CLAUDE.md, custom commands, learned rules
CODEX.md, .codex/rules, project-local skills, wiki/notepad memory
Hard Gates
pre-commit, completion, deploy hooks
project-scope Codex hooks, hard process contract, acceptance evidence, no-bypass
Memory Bank
memory-bank plugin (auto inject via UserPromptSubmit hook)
Codex hooks.json 강제 훅(HARD)으로 연결 → 같은 SQLite 데이터베이스를 공유하고, 버전이 바뀌어도 맞는 경로를 자동으로 찾음
Operator UI
Claude sessions, manual panes
tmux runtime, HUD, team status, question renderer
Core Insight
Claude Code의 네 기둥 — 명령(commands)·훅(hooks)·에이전트(agents)·기억 저장소(memory-bank) — 를 Codex의 다섯 가지(skills + native agents + OMX plugin runtime + project hooks + 공유 기억)로 옮겼다. 그중 기억 저장소는 말뿐인 지시가 아니라 강제 훅으로 붙였다. 사용자가 프롬프트를 넣을 때마다(UserPromptSubmit 훅) 관련 기억을 자동으로 끌어와 강제로 실행한다.
Memory Bank Hook Pipeline

Claude Code와 Codex는 훅을 어떻게 연결하나 — 그 차이

Layer
Claude Code
Codex
훅 등록 방법
플러그인 안의 hooks/hooks.json — 플러그인 시스템이 알아서 불러옴
~/.codex/hooks.json에 직접 손으로 등록 — Codex에는 플러그인 시스템이 없기 때문
설치 경로 찾기
${CLAUDE_PLUGIN_ROOT} 변수가 플러그인 위치를 자동으로 찾아줌
sort -V | tail -1 명령으로 가장 최신 버전 폴더를 자동으로 찾음
외부 도구 연결(MCP)
플러그인이 외부 도구(MCP)를 자동 등록 (mcp__plugin_memory-bank_*)
config.toml [mcp_servers.memory_bank] — 짧은 스크립트로 감싸 실행
실제 실행 스크립트
플러그인 안에 들어 있음: inject-context.sh, fact-extract-hook.js, sync-*.js
똑같은 스크립트 를 그대로 호출 — ~/.codex/hooks/memory-bank/*.sh가 감싸서 부름
데이터베이스 공유
~/.config/superpowers/conversation-index/db.sqlite
같은 데이터베이스 — Claude Code로 쌓아 둔 대화 6만 9천 건(69K)과 추출된 사실 3천 7백 건(3.7K)을 그대로 사용
버전 올릴 때
플러그인을 업데이트하면 CLAUDE_PLUGIN_ROOT 경로가 자동으로 갱신됨
ls ... | sort -V | tail -1 — 새 버전을 깔면 자동으로 최신 경로를 씀
동기화(cc-sync) 대상
플러그인 설정 전체가 settings.json 안에 들어 있음
~/.codex/hooks.json + hooks/memory-bank/*.sh + config.toml 이 세 가지가 동기화 대상
핵심 차이
Claude Code는 플러그인 시스템이 훅을 알아서 찾아 등록한다. Codex에는 그런 플러그인 시스템이 없다. 그래서 똑같은 스크립트를 hooks.json 설정 파일에 직접 연결하고, 버전이 바뀌어도 맞는 경로를 찾도록 짧은 스크립트(wrapper)로 감쌌다. 실제로 돌아가는 코드는 같고 데이터베이스도 함께 쓴다 — 연결하는 방식만 다르다.
Core Skills

이 하네스를 이루는 핵심 스킬

$init-project

  • real repo scan (package, config, source)
  • CODEX.md + .codex/rules generation
  • hard-process-contract.json + team-handoff.json
  • connected workflow skills: init → team → scenario → QA
  • project-local skills creation
  • hook install + verify
  • QA bootstrap (inventory + test-plan)

$team

  • hard contract preflight before implementation
  • acceptance criteria extraction (anti-Goodhart)
  • direct / native subagent / OMX workflow classify-and-act
  • .omx/state shared root
  • mailbox + dispatch queue
  • heartbeat monitoring (30s)
  • shutdown gate (pending=0)

QA Pipeline

  • $qa-scenario-gen (inventory → contracts)
  • $qa-cycle (build → test → evidence)
  • acceptance_verified[] required for user-facing PASS
  • .qa-cycle-passed (hash verified)
  • no-bypass evidence gate
  • auto-fix loop on failure

Worker Protocol

  • ACK → claim-task → transition-status
  • commit protocol (state-first)
  • no blind tmux send-keys
  • CLI/state > direct pane input

OMX Plugin Runtime

  • skill routing + keyword hooks
  • context snapshot + role prompt
  • HUD + question renderer
  • MCP tool integration

Memory Bank (HARD)

  • Claude Code와 같은 SQLite 데이터베이스 공유 (대화 6만 9천 건 이상(69K+), 사실 3천 7백 건 이상(3.7K+))
  • UserPromptSubmit 훅 → 프롬프트를 넣을 때마다 관련 기억을 자동으로 넣어 줌
  • SessionStart hook → sync + fact consolidation
  • Stop hook → fact extraction + export
  • MCP 9 tools: search, search_facts, explore_graph, ask_avatar
  • version-agnostic wrapper (sort -V | tail -1)

Agent Roles (6)

  • leader — control, context, verification
  • executor — implement, Read/Write/Edit/Bash
  • explore — file/symbol, Read/Grep/Glob only
  • verifier — lint/test, Read/Bash/Grep, no Write
  • planner — PRD, spec, tradeoffs
  • researcher — docs, deps, external, no Write
[email protected] 복사됨