Codex/OMX Port Log · Team x Init-Project

5개월 다듬은 Claude Code 운영 틀을
Codex에 옮겼더니 강제 훅이 2배가 됐다

Claude Code에서 5개월간 다듬어 온 운영 틀(하네스, harness — AI가 규칙을 건너뛰거나 '다 했다'고 거짓 보고를 못 하게 검증 절차를 강제로 씌우는 장치)은 Claude Code 안에서만 돌았다. 그래서 이 틀을 오픈AI의 코딩 에이전트 Codex와, Codex 위에 얹어 쓰는 플러그인 실행기 omx의 방식에 맞춰 그대로 옮겼다. omx는 명령 이름이라 소문자로 쓴다. 이 글의 제목 위 표시와 표에서 대문자로 적은 것도 같은 도구다. 이 글은 그 이식 기록이다. 결과부터 말하면 옮긴 쪽이 더 강해졌다. 어기면 작업이 막히는 훅(hook — 정해진 순간마다 자동으로 끼어들어 검사하는 작은 프로그램)이 Claude Code 쪽은 15개인데 Codex 쪽은 31개다. 중심은 두 개의 명령이다. $init-project은 프로젝트를 처음 분석해 그 코드에만 있는 고유한 성질과 반드시 지켜야 할 작업 규칙(계약, contract)을 만든다. 이 고유한 성질(코드마다 다른 특성을 생물의 유전자에 빗댄 말)을 이 글에서 부르는 이름이 프로젝트 DNA. $team은 여러 AI 일꾼(에이전트, agent — 역할 하나를 맡아 스스로 도구를 쓰며 일하는 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 — 실행 전 반드시 통과해야 하는 사전 점검(preflight)을 주입했다
  • ~/.codex/agents/team-orchestrator.toml — Claude에서만 돌도록 묶여 있던 설정을 제거했다

Behavioral Delta

  • 반드시 지켜야 할 작업 계약(hard contract — 목표·기준·검증·중단 조건을 적은 문서)이 없으면 $team 은 구현 단계로 들어가지 못하고 막힌다
  • 목표 수집·성공 기준·결과 검증·중단 조건, 이 네 가지 경계를 '어기면 막히는' 강제 규칙으로 못박았다
  • .qa-evidence.json이라는 증거 파일(QA 결과를 기록하는 파일) 속 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 · HTTP hooks
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 hook — 어기면 프로그램이 실패 신호를 내고 멈추는 강제 등급의 훅)이 2배 많다(31개 대 15개). 파일 쓰기(Write)와 수정(Edit)을 따로 감시해 정밀하게 막는다. 역할을 맡은 AI 일꾼 29개마다 toml 형식의 설정 파일에 '무엇까지 해도 되는지' 제약이 박혀 있다. 사람 승인을 묻지 않고 스스로 실행하되(승인 정책을 '묻지 않음'으로 고정), 핵심 지점은 실제로 막는 방식이다. 말로만 권고하는 규칙(soft rule)은 0개다. 어기면 프로그램이 실패 신호(종료 코드 2 — 프로그램이 끝나며 돌려주는 숫자로, 0은 정상이고 2는 '막았다'는 뜻으로 쓴다)를 내며 작업을 막는 장치만 남겼다.

Codex가 앞서는 점

  • 작업을 강제로 막는 훅(hard hook)이 31개라서 막을 수 있는 범위가 2배다
  • 파일 쓰기와 수정을 따로 감시해 더 정밀하게 차단한다
  • 스스로 실행하면서도 핵심 지점은 강제로 막는 혼합 방식이다
  • .omx/state/ 폴더에 작업 상태를 저장해 세션(대화 한 번의 단위)이 바뀌어도 이어간다
  • 역할별 AI 일꾼 29개, 각각의 toml 형식 설정 파일에 쓸 모델과 사고 강도까지 지정한다
  • 외부 도구 연결 통로(MCP 서버 — AI가 바깥 프로그램을 표준 방식으로 부르게 해 주는 접점) 11개로 상태·기억·코드 분석·추적·위키를 붙였다

Claude Code가 앞서는 점

  • 감지할 수 있는 이벤트(훅이 끼어드는 순간의 종류)가 16가지로, 하위 일꾼의 시작·종료까지 포함한다
  • 플러그인 장터(marketplace)가 있어 자동으로 설치·업데이트한다
  • ${CLAUDE_PLUGIN_ROOT} 변수(플러그인이 설치된 폴더 경로를 담는 환경 변수)가 플러그인 설치 위치를 자동으로 찾아준다
  • 웹 주소로 호출하는 방식(http 요청)의 훅도 지원한다

밑바탕이 된 원칙

  • 말로만 권고하는 규칙(soft rule)은 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 hook)으로 연결한다. 같은 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)·공유 기억으로 옮겼다. 그중 기억 저장소는 강제 훅으로 붙였다. 말로만 지시하는 방식은 쓰지 않았다. 사용자가 프롬프트(AI에게 보내는 입력 문장)를 넣을 때마다 관련 기억을 자동으로 끌어와 강제로 실행한다. 이 순간에 끼어드는 훅의 이름이 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에는 그런 플러그인 시스템이 없다. 그래서 똑같은 스크립트를 Codex의 훅 등록 파일(홈 폴더 아래 .codex/hooks.json)에 직접 연결하고, 버전이 바뀌어도 맞는 경로를 찾도록 짧은 감싸기 스크립트(wrapper — 실제 스크립트를 대신 불러 주는 얇은 껍데기)로 감쌌다. 실제로 돌아가는 코드는 같고 데이터베이스도 함께 쓴다. 연결하는 방식만 다르다.
Core Skills

이 하네스를 이루는 핵심 스킬(skill — 명령 하나로 불러 쓰는 작업 절차 묶음)

$init-project

  • real repo scan (package, config, source) → project DNA
  • 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
  • role config: one TOML file per agent (model + reasoning effort)
raground@gmail.com 복사됨