OMX - Prompt Agent System

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편 (본문)	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• Prompt & Agent System은 OMX의 33개 에이전트 역할 정의와 모델 라우팅 체계
• prompts/*.md로 정의되는 XML 태그 기반 역할 프롬프트와, definitions.ts로 중앙 관리되는 에이전트 메타데이터(reasoningEffort, posture, modelClass)를 분리한 2파일 아키텍처
• /prompts:name으로 호출되며, 빌드 타임에 프롬프트 + 메타데이터 + posture overlay가 합성되어 .toml 에이전트 설정 파일로 설치되는 구조

해당 개념이 필요한 이유

• 3편에서 Skill이 “에이전트를 활용하여 병렬로 실행하라”고 지시하는 구조를 이해했음
• 하지만 **“어떤 에이전트가 있고, 각각 뭘 할 수 있고, 어떤 모델을 쓰는지”**가 빠져 있음
• 이 파트는 에이전트의 정의(prompts/*.md), 메타데이터(definitions.ts), 모델 라우팅(3-Tier), 위임 프로토콜을 다루어 그 간극을 메움

AS-IS (OMC Agent — Claude Code 방식)

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    participant AD as agents/executor.md
    participant SA as Subagent

    U->>CC: Task(subagent_type="omc:executor")
    CC->>AD: YAML frontmatter에서 model 필드 읽기
    Note over AD: model, disallowedTools 등 메타데이터가<br/>프롬프트 파일 자체에 내장
    CC->>SA: subagent spawn (model 지정)
    SA-->>CC: 결과 반환

TO-BE (OMX Agent — Codex CLI 방식)

sequenceDiagram
    autonumber
    participant U as User
    participant CX as Codex CLI
    participant PM as prompts/executor.md
    participant DF as definitions.ts
    participant NC as native-config.ts
    participant TM as ~/.omx/agents/executor.toml

    Note over NC,TM: omx setup 시 (빌드 타임)
    NC->>PM: ① prompts/*.md 로드 + frontmatter 제거
    NC->>DF: ② 메타데이터 확인 (posture, modelClass)
    NC->>NC: ③ 프롬프트 + posture overlay + modelClass overlay 합성
    NC->>TM: ④ .toml 파일 생성·설치

    Note over U,CX: 세션 시 (런타임)
    U->>CX: "/prompts:executor refactor API"
    CX->>TM: executor.toml 로드 (developer_instructions)
    CX->>CX: 지침에 따라 작업 수행

핵심 차이: OMC는 프롬프트 파일 내 frontmatter에 모든 메타데이터를 넣지만, OMX는 프롬프트(prompts/*.md)와 메타데이터(definitions.ts)를 분리하고 빌드 타임에 합성한다.

Agent Prompt 구조 — prompts/*.md 해부

XML 태그 구조

모든 에이전트 프롬프트는 YAML frontmatter + XML 태그 섹션으로 구성된다. 3편의 SKILL.md와 같은 패턴이지만 다른 태그 세트를 사용한다.

---
description: "역할 설명 (complexity tier)"
argument-hint: "task description"
---
 
<identity>         # 에이전트의 정체성과 미션 (1-2문장)
<constraints>      # 행동 제약
  <reasoning_effort>   # 추론 노력 수준 지침
  <scope_guard>        # 범위 제한 규칙
  <ask_gate>           # 질문 vs 직접 탐색 판단 기준
<execution_loop>   # 단계별 실행 절차
  <success_criteria>   # 완료 조건
  <verification_loop>  # 검증 절차
<tools>            # 사용 가능 도구 목록
<style>            # 출력 형식
  <output_contract>    # 응답 구조 템플릿

SKILL.md vs prompts/*.md — 태그 비교

구분	SKILL.md (워크플로우)	prompts/*.md (에이전트)
역할	무엇을 할지 (워크플로우 절차)	누가 할지 (에이전트 행동)
정체성	<Purpose>	<identity>
사용 조건	<Use_When> / <Do_Not_Use_When>	<constraints> / <scope_guard>
실행 절차	<Steps>	<execution_loop>
완료 확인	<Final_Checklist>	<success_criteria> + <verification_loop>
도구 계약	<Tool_Usage>	<tools>
출력 형식	(없음)	<style> / <output_contract>

대표 프롬프트 비교 — complexity 별 차이

항목	explore.md (Low)	executor.md (Standard)	architect.md (High)
identity	”find files, code patterns"	"implement, verify, finish"	"diagnose, analyze, recommend”
scope_guard	읽기 전용, 파일 수정 금지	최소 viable diff 선호	파일 쓰기/수정 금지 (read-only)
ask_gate	”search first, ask never"	"explore first, ask last"	"ask only when scope changes”
검증	모든 경로 절대경로, 관계 설명	diagnostics + tests + build	evidence 기반 root cause
output	files, relationships, next_steps	Changes, Verification, Summary	Summary, Analysis, Root Cause, Recommendations, Trade-offs

33개 에이전트 분류

prompts/ 디렉토리에 33개 .md 파일이 존재하며, 이 중 definitions.ts에 메타데이터가 등재된 것은 30개다. 나머지 3개(team-orchestrator, sisyphus-lite, explore-harness)는 특수 목적으로 별도 관리된다.

Build Lane (7개)

에이전트	역할	reasoning	posture	modelClass
explore	빠른 코드베이스 탐색 (읽기 전용)	low	fast-lane	fast
analyst	요구사항 명확화, 수용 기준	medium	frontier-orchestrator	frontier
planner	작업 분해, 실행 계획	medium	frontier-orchestrator	frontier
architect	시스템 설계, 인터페이스 (읽기 전용)	high	frontier-orchestrator	frontier
debugger	근본 원인 분석, 회귀 격리	medium	deep-worker	standard
executor	코드 구현, 리팩터 (기본 구현 역할)	medium	deep-worker	standard
verifier	완료 증거 검증, 테스트 적정성	medium	frontier-orchestrator	standard

Review Lane (6개)

에이전트	역할	reasoning	posture	modelClass
style-reviewer	포맷팅, 네이밍, lint 컨벤션	low	fast-lane	fast
quality-reviewer	로직 결함, 유지보수성	medium	frontier-orchestrator	standard
api-reviewer	API 계약, 하위 호환성	medium	frontier-orchestrator	standard
security-reviewer	취약점, 신뢰 경계, 인증	medium	frontier-orchestrator	standard
performance-reviewer	핫스팟, 메모리/지연 최적화	medium	frontier-orchestrator	standard
code-reviewer	전체 관심사 통합 리뷰	high	frontier-orchestrator	frontier

Domain Specialists (11개)

에이전트	역할	reasoning	posture	modelClass
dependency-expert	외부 SDK/API/패키지 평가	medium	frontier-orchestrator	standard
test-engineer	테스트 전략, 커버리지	medium	deep-worker	standard
build-fixer	빌드/타입 오류 수정	medium	deep-worker	standard
designer	UX/UI 아키텍처, 인터랙션 설계	medium	deep-worker	standard
writer	문서, 마이그레이션 노트	low	fast-lane	fast
qa-tester	CLI/서비스 런타임 검증	low	deep-worker	standard
git-master	커밋 전략, 히스토리 관리	medium	deep-worker	standard
code-simplifier	코드 단순화, 일관성 개선	high	deep-worker	frontier
researcher	외부 문서, 레퍼런스 리서치	low	fast-lane	standard
quality-strategist	품질 전략, 릴리스 준비	medium	frontier-orchestrator	standard
team-executor	감독된 Team 실행	medium	deep-worker	standard

Product Lane (4개)

에이전트	역할	reasoning	posture	modelClass
product-manager	문제 프레이밍, 페르소나, PRD	medium	frontier-orchestrator	standard
ux-researcher	휴리스틱 감사, 사용성, 접근성	medium	frontier-orchestrator	standard
information-architect	분류 체계, 내비게이션, 탐색성	low	frontier-orchestrator	standard
product-analyst	프로덕트 메트릭, 퍼널 분석	low	frontier-orchestrator	standard

Coordination (2개)

에이전트	역할	reasoning	posture	modelClass
critic	계획/설계 비판적 리뷰	high	frontier-orchestrator	frontier
vision	이미지/스크린샷/다이어그램 분석	low	fast-lane	standard

definitions.ts 미등재 (3개)

에이전트	역할	비고
team-orchestrator	Team Worker 조율	team 스킬이 직접 처리
sisyphus-lite	경량 추론/라우팅	specialized prompt contract로 별도 검증
explore-harness	제한된 탐색 하네스	explore의 제한 변형

Agent Metadata — definitions.ts 심층 분석

AgentDefinition 인터페이스

export interface AgentDefinition {
  name: string;
  description: string;
  reasoningEffort: 'low' | 'medium' | 'high';
  posture: 'frontier-orchestrator' | 'deep-worker' | 'fast-lane';
  modelClass: 'frontier' | 'standard' | 'fast';
  routingRole: 'leader' | 'specialist' | 'executor';
  tools: 'read-only' | 'analysis' | 'execution' | 'data';
  category: 'build' | 'review' | 'domain' | 'product' | 'coordination';
}

각 필드의 역할:

필드	역할	값 범위
reasoningEffort	Codex CLI의 추론 노력 수준 지정	low / medium / high
posture	행동 성향 오버레이	frontier-orchestrator / deep-worker / fast-lane
modelClass	사용할 모델 등급	frontier / standard / fast
routingRole	위임 체계에서의 역할	leader / specialist / executor
tools	허용된 도구 범위	read-only / analysis / execution / data
category	에이전트 분류	build / review / domain / product / coordination

모델 분포 요약

graph LR
    subgraph Frontier["frontier (6개)"]
        F1["architect"]
        F2["analyst"]
        F3["planner"]
        F4["code-reviewer"]
        F5["critic"]
        F6["code-simplifier"]
    end

    subgraph Standard["standard (20개)"]
        S1["executor, debugger, verifier ..."]
        S2["quality/api/security/perf-reviewer"]
        S3["dependency-expert, test-engineer ..."]
        S4["product-manager, ux-researcher ..."]
    end

    subgraph Fast["fast (4개)"]
        FA1["explore"]
        FA2["style-reviewer"]
        FA3["writer"]
        FA4["vision"]
    end

    style Frontier fill:#d4edda
    style Standard fill:#cce5ff
    style Fast fill:#fff3cd

Model Routing — 3-Tier Complexity

모델 해상도 우선순위

Frontier 모델 (기본: gpt-5.4):

1. 환경변수: OMX_DEFAULT_FRONTIER_MODEL
2. 설정 파일: .omx-config.json → env.OMX_DEFAULT_FRONTIER_MODEL
3. 모드별 설정: .omx-config.json → models.<mode-name>
4. 기본 설정: .omx-config.json → models.default
5. 하드코딩 폴백: gpt-5.4

Fast/Spark 모델 (기본: gpt-5.3-codex-spark):

1. 환경변수: OMX_DEFAULT_SPARK_MODEL
2. 레거시: OMX_SPARK_MODEL
3. 설정 파일: .omx-config.json → env.OMX_DEFAULT_SPARK_MODEL
4. Low-complexity 키: models.team_low_complexity
5. 하드코딩 폴백: gpt-5.3-codex-spark

Low-Complexity 에이전트 자동 감지

const LOW_COMPLEXITY_AGENT_TYPES = new Set([
  'explore', 'explorer', 'style-reviewer', 'writer'
]);
 
// 이름이 '-low'로 끝나는 에이전트도 자동으로 low-complexity 취급
// 예: 'executor-low' → spark 모델 사용

reasoningEffort → model_reasoning_effort 매핑

definitions.ts의 reasoningEffort는 생성된 .toml 파일의 model_reasoning_effort 키에 직접 매핑된다. 이 값은 Codex CLI가 모델에게 전달하는 추론 노력 파라미터로, LLM의 think 시간을 제어한다.

reasoningEffort	적용 에이전트 예시	효과
low	explore, writer, style-reviewer, vision	빠른 응답, 최소 추론
medium	executor, debugger, planner, designer	균형 잡힌 추론
high	architect, code-reviewer, critic, code-simplifier	깊은 추론, 느린 응답

Posture 시스템 — 행동 오버레이

Posture는 에이전트의 행동 성향을 결정하는 오버레이다. native-config.ts가 프롬프트 합성 시 posture별 행동 지침을 <posture_overlay> 태그로 삽입한다.

3가지 Posture

frontier-orchestrator — 의도 분류 + 위임 우선

“Prioritize intent classification before implementation.”

• 첫 결정을 라우팅 문제로 취급 (리서치 vs 계획 vs 구현 vs 검증)
• 전문 executor가 있으면 위임 선호
• 잘못된 사용자 가정에 실행 전 간결히 반론
• 해당 에이전트: analyst, planner, architect, code-reviewer, critic, verifier, 대부분의 reviewer, product 계열

deep-worker — 직접 실행 + 검증 필수

“Bias toward direct execution and end-to-end completion.”

• 구현 지향 태스크면 직접 실행에 편향
• 탐색 → 최소 변경 → 기존 패턴 따르기
• diagnostics·tests·build 증거 필수 (완료 선언 전)
• 에스컬레이션은 다른 접근이 실패한 후에만
• 해당 에이전트: executor, team-executor, debugger, test-engineer, build-fixer, designer, qa-tester, git-master, code-simplifier

fast-lane — 빠른 분류 + 에스컬레이션

“Optimize for fast triage, search, lightweight synthesis.”

• 빠른 검색·분류·경량 합성에 최적화
• 깊은 구현이 필요하면 에스컬레이션 (frontier-orchestrator 또는 deep-worker로)
• 모호할 때 보수적 응답
• 해당 에이전트: explore, style-reviewer, writer, vision, researcher

Posture → Model Class 매핑 다이어그램

graph TD
    subgraph Posture["Posture (행동 성향)"]
        FO["frontier-orchestrator<br/>의도 분류 + 위임"]
        DW["deep-worker<br/>직접 실행 + 검증"]
        FL["fast-lane<br/>빠른 분류 + 에스컬레이션"]
    end

    subgraph ModelClass["Model Class (모델 등급)"]
        FR["frontier<br/>gpt-5.4"]
        ST["standard<br/>기본 모델"]
        FA["fast<br/>gpt-5.3-codex-spark"]
    end

    FO --> FR
    FO --> ST
    DW --> ST
    DW --> FR
    FL --> FA
    FL --> ST

    style FO fill:#d4edda
    style DW fill:#cce5ff
    style FL fill:#fff3cd

Posture와 ModelClass는 독립적인 축이다. frontier-orchestrator posture라고 반드시 frontier 모델을 쓰는 것이 아니며 (예: verifier는 frontier-orchestrator이지만 standard 모델), deep-worker라고 반드시 standard 모델을 쓰는 것도 아니다 (예: code-simplifier는 deep-worker이지만 frontier 모델).

Delegation Protocol — 위임 판단과 Child Agent 규칙

기본 자세: 직접 작업

“Default posture: work directly. Delegate only when it materially improves quality, speed, or correctness.”

AGENTS.md <delegation_rules>에 명시된 원칙이다. 에이전트는 항상 직접 작업을 먼저 시도하고, 실질적 이점이 있을 때만 위임한다.

위임 조건 4가지

조건	예시
multi-file	여러 파일에 걸친 변경이 필요할 때
specialist-heavy	전문 SDK/API/프레임워크 사용 → dependency-expert
highly parallel	독립적 태스크를 동시 실행 가능할 때
안전성	전문 역할이 작업하는 것이 더 안전할 때

Child Agent Protocol

sequenceDiagram
    autonumber
    participant L as Leader Agent
    participant PM as prompts/{role}.md
    participant C1 as Child Agent 1
    participant C2 as Child Agent 2

    L->>PM: ① 역할 프롬프트 읽기
    L->>C1: ② 프롬프트 + 구체적 태스크로 spawn
    L->>C2: ② 프롬프트 + 구체적 태스크로 spawn
    Note over L: 최대 6개 동시 child agent
    C1-->>L: ③ 결과 반환 (재귀 오케스트레이션 금지)
    C2-->>L: ③ 결과 반환
    Note over C1,C2: child는 할당된 역할 내에서만 완료

핵심 규칙:

• 최대 6개 동시 child agent (AGENTS.md <child_agent_protocol>)
• child 프롬프트는 AGENTS.md 권한 하에 동작
• worker는 team 모드 전용 — 일반 위임에 사용 금지
• child agent는 할당된 역할 내에서 완료해야 함 (재귀 오케스트레이션 금지)

Child Agent vs Team Worker — 차이

항목	Child Agent (위임)	Team Worker (team 모드)
최대 동시 수	6개	20개
격리	같은 세션 내	tmux 개별 pane
역할 지정	/prompts:name	role-router.ts 자동 배정
오케스트레이션	leader agent가 직접 관리	team 스킬이 파이프라인 관리
상태 관리	없음	.omx/state/team/

Prompt Guidance Contract — 프롬프트 구조 검증

4개 핵심 행동 패턴

OMX의 모든 프롬프트 표면(AGENTS.md, prompts/.md, skills//SKILL.md)에 강제 적용되는 4가지 행동 계약이다. src/hooks/prompt-guidance-contract.ts가 regex 패턴 매칭으로 검증한다.

#	패턴	대표 문구
1	Compact output	”Default to compact, information-dense responses”
2	Automatic follow-through	”Proceed automatically on clear, low-risk, reversible next steps”
3	Scoped overrides	”Treat newer user task updates as local overrides”
4	Evidence-backed completion	”Persist with tool use when correctness depends on retrieval”

계약 카테고리와 검증 계층

graph TD
    PGC["prompt-guidance-contract.ts<br/>regex 패턴 매칭"]

    PGC --> ROOT["ROOT_TEMPLATE<br/>AGENTS.md"]
    PGC --> CORE["CORE_ROLE<br/>executor, planner, verifier"]
    PGC --> W2["WAVE_TWO<br/>architect, critic, debugger ..."]
    PGC --> CAT["CATALOG<br/>analyst, api-reviewer, designer ..."]
    PGC --> SPEC["SPECIALIZED<br/>sisyphus-lite"]
    PGC --> SKILL["SKILL<br/>skills/*.md"]

    style PGC fill:#e8f0fe

각 카테고리별로 required regex patterns가 정의되어 있으며, 테스트(prompt-guidance-contract.test.ts)가 모든 프롬프트 파일에 대해 패턴 존재를 자동 검증한다. 패턴이 누락된 프롬프트는 CI에서 실패한다.

Guidance Schema — 6개 표준 섹션

docs/guidance-schema.md에 정의된 모든 프롬프트 표면의 표준 구조:

섹션	역할
Role & Intent	에이전트의 정체성과 성공 기준
Operating Principles	고수준 판단 규칙 (품질, 속도, 안전, 검증)
Execution Protocol	태스크 실행 워크플로우
Constraints & Safety	금지 행동, 호환성 제약
Verification & Completion	완료 선언 전 필요한 증거
Recovery & Lifecycle	취소/정리/재개 행동

OMC Agent와의 비교

항목	OMC (19개)	OMX (33개)
정의 파일	agents/*.md + definitions.ts	prompts/*.md + definitions.ts
호출 방식	Task(subagent_type="omc:name")	/prompts:name
모델 지정	YAML frontmatter에 model 필드	definitions.ts의 modelClass
메타데이터 위치	프롬프트 파일에 내장	분리 (프롬프트 / 메타데이터 / overlay)
리뷰어	code-reviewer 1개	6개 세분화 (code/security/quality/style/perf/api)
도메인 전문가	designer 1개	7개 (designer, PM, analyst, UX, IA, vision, QS)
도구 제한	disallowedTools	tools 카테고리 (read-only/analysis/execution/data)
최대 동시 agent	제한 없음	최대 6개 (child), 20개 (team)
행동 오버레이	없음	Posture 시스템 (frontier-orchestrator/deep-worker/fast-lane)
구조 검증	없음	Prompt Guidance Contract (regex 기반 CI 검증)

참고 문서

• OMX GitHub
• Codex CLI AGENTS.md Guide