1exploreSpark
빠른 코드베이스 검색, 파일/심볼 매핑, 현재 구현 위치 파악
📌 언제? 저장소 안에서 파일, 함수, 관계, 기존 사용 패턴을 빠르게 찾을 때
Oh My Codex 에이전트 가이드
18개 active/internal native agents + 26개 active/internal skills + native hooks + Hermes MCP
· 인터랙티브 학습 가이드
usefullabs(쓸모랩) 교육자료Build / Analysis Lane
코드베이스 탐색, 요구사항 정리, 계획, 설계, 구현, 검증까지 담당하는 OMX의 기본 실행 축입니다.
2analystFrontier
요구사항 명확화, 인수 기준, 숨은 제약과 리스크 도출
📌 언제? 요청이 구현 가능한 기준으로 쪼개지지 않았거나 비즈니스 경계가 흐릴 때
3plannerFrontier
작업 순서, 실행 계획, 리스크 플래그 설계
📌 언제? 요구사항은 보이지만 실행 순서와 검증 전략을 먼저 고정해야 할 때
4architectFrontier
시스템 경계, 인터페이스, 장기 트레이드오프 설계
📌 언제? 아키텍처 변경, 모듈 경계, 데이터 흐름, 대규모 리팩토링 판단이 필요할 때
5debuggerStandard
근본 원인 분석, 회귀 격리, 장애 진단
📌 언제? 스택 트레이스, 재현 조건, 실패 로그를 근거로 최소 수정 지점을 찾을 때
6executorStandard
코드 구현, 리팩토링, 기능 개발
📌 언제? 스펙과 검증 기준이 충분히 명확해 실제 파일을 수정해야 할 때
7team-executorFrontier
보수적인 병렬 실행 lane을 감독하는 팀 실행 역할
📌 언제? Team 런타임이 여러 실행 lane을 나눠 관리할 때
8verifierStandard
완료 증거, 주장 검증, 테스트 적절성 확인
📌 언제? 작업이 정말 끝났는지 파일, 테스트, 빌드, 로그로 증명해야 할 때
Review Lane
품질, API 계약, 보안, 성능, 종합 코드 리뷰를 담당합니다. 일부 세부 리뷰 역할은 현재 카탈로그에서 code-reviewer로 병합된 문맥 역할입니다.
1style-reviewerSpark
포맷, 네이밍, 관용구, lint convention 검토
📌 언제? 표면적 스타일 정리를 빠르게 확인할 때
2quality-reviewerStandard
논리 결함, 유지보수성, 안티패턴 검토
📌 언제? 로직이나 구조 결함을 code-reviewer의 한 축으로 확인할 때
3api-reviewerStandard
API 계약, 버전 호환성, backward compatibility 검토
📌 언제? 공개 API, SDK, 내부 모듈 계약 변경의 위험을 점검할 때
4security-reviewerFrontier
취약점, 신뢰 경계, 인증/인가 위험 검토
📌 언제? 보안 관점 리뷰가 필요하되 현재 카탈로그 상태 차이를 알아야 할 때
5performance-reviewerStandard
핫스팟, 복잡도, 메모리/지연 최적화 검토
📌 언제? 성능 리스크를 종합 리뷰의 한 축으로 다룰 때
6code-reviewerFrontier
품질, 보안, 성능, API 계약을 종합하는 최종 코드 리뷰
📌 언제? 변경 완료 전 심각도 기반 리뷰와 승인/차단 판단이 필요할 때
Domain Specialists
테스트, 의존성, UI/UX, 문서, Git, 연구 조사 등 특정 분야의 정확도를 높이는 전문 역할입니다.
1dependency-expertStandard
패키지, SDK, API 선택과 교체/업그레이드 평가
📌 언제? 새 의존성을 도입하거나 SDK 후보를 비교해야 할 때
2test-engineerFrontier
테스트 전략, 커버리지, flaky test 강화
📌 언제? 변경의 리스크가 테스트 설계나 QA 범위를 요구할 때
3quality-strategistStandard
릴리스 품질 전략, readiness, 리스크 평가
📌 언제? 릴리스 판단과 품질 게이트를 verifier 문맥으로 정리할 때
4build-fixerStandard
빌드, 툴체인, 타입 실패 해결
📌 언제? 현재 카탈로그에서는 별도 agent보다 executor/debugger/test-engineer 경로를 우선할 때
5designerStandard
UX/UI 아키텍처와 인터랙션 디자인
📌 언제? 프론트엔드 화면, 디자인 시스템, 사용자 흐름을 다룰 때
6writerStandard
문서, 마이그레이션 노트, 사용자 가이드 작성
📌 언제? 사용자 설명, 릴리스 노트, 가이드 문서가 필요할 때
7qa-testerStandard
대화형 CLI/서비스 런타임 QA 검증
📌 언제? 실행 중인 앱이나 CLI 동작을 수동 QA 관점으로 확인할 때
8git-masterStandard
커밋 전략, 히스토리 정리, 리베이스
📌 언제? 작업 단위별 커밋, Lore trailer, 히스토리 정리가 필요할 때
9code-simplifierFrontier
최근 수정 코드의 명확성, 일관성, 유지보수성 개선
📌 언제? 동작을 바꾸지 않는 cleanup pass나 Stop 후 정리가 필요할 때
10researcherStandard
공식 문서, 외부 레퍼런스, 버전별 동작 조사
📌 언제? 외부 공식 문서나 최신 API 동작 확인이 정확도에 중요할 때
Product Context Roles
제품 문제 정의, UX 리서치, 정보 구조, 지표 분석 역할입니다. 현재 카탈로그에서는 대부분 analyst 또는 designer로 병합되어 마이그레이션 문맥으로 남아 있습니다.
1product-managerStandard
문제 정의, persona/JTBD, PRD framing
📌 언제? 제품 요구사항을 analyst 경로로 정리해야 할 때
2ux-researcherStandard
휴리스틱 감사, 사용성, 접근성 검토
📌 언제? 디자인 변경의 사용자 경험 리스크를 designer 문맥으로 다룰 때
3information-architectStandard
정보 구조, 내비게이션, taxonomy, findability
📌 언제? 문서나 앱 구조를 더 찾기 쉽고 학습하기 쉽게 정리할 때
4product-analystStandard
제품 지표, funnel 분석, 실험 설계
📌 언제? 성과 지표와 실험 가설을 analyst 문맥으로 연결할 때
Coordination
계획을 비판적으로 검토하거나 이미지/스크린샷을 읽어 실행 품질을 보강하는 교차 역할입니다.
1criticFrontier
계획과 설계를 비판적으로 도전하고 약한 가정을 찾는 역할
📌 언제? 구현 전 설계의 허점, 과한 복잡도, 누락된 리스크를 찾을 때
2visionFrontier
이미지, 스크린샷, 다이어그램 분석
📌 언제? 시각 결과물, 화면 QA, 다이어그램 해석이 필요한 작업에서
Skills - Codex 행동을 바꾸는 workflow surface
카탈로그 기준 active/internal skill은 26개입니다. deprecated, merged, alias 항목은 신규 작업의 기본 경로가 아니라 마이그레이션 문맥으로 봐야 합니다.
!Agent vs Skill - 핵심 차이
| Agent | Skill | |
|---|---|---|
| 정체 | 역할 prompt와 model/reasoning metadata를 가진 Codex native subagent | 현재 Codex agent의 행동을 바꾸는 repo-local workflow instruction |
| 실행 | bounded delegation, team worker, specialist lane에 사용 | $name 호출, keyword routing, hooks/context injection으로 활성화 |
| 상태 | active/internal/merged/deprecated catalog status를 가짐 | .omx state, plans, ledgers, native hooks와 연결될 수 있음 |
| 주의점 | merged/deprecated 역할은 단독 설치 대상이 아닐 수 있음 | runtime workflows는 Codex App 밖 tmux/CLI 조건이 필요할 수 있음 |
Execution Skills - 실행 모드
| 스킬 | 호출 방법 | 기능 |
|---|---|---|
| autopilot | $autopilot | $ralplan -> $ralph -> $code-review를 묶은 엄격한 자율 루프 |
| ralph | $ralph | architect 검증을 포함해 완료될 때까지 지속하는 단일 소유자 루프 |
| team | $team | tmux 기반 공유 작업 목록에서 여러 에이전트를 조정하는 병렬 실행 모드 |
| ultrawork | $ultrawork | 고처리량 병렬 작업 완료 엔진 |
| ultraqa | $ultraqa | 적대적 시나리오, prompt injection, interrupt/cancel/resume, stale state까지 포함하는 e2e QA 루프 |
| ultragoal | $ultragoal | .omx/ultragoal 아티팩트와 Codex goal snapshot을 reconcile하는 durable multi-goal 실행 |
| autoresearch | $autoresearch | native-hook persistence를 포함한 validator-gated research loop |
| autoresearch-goal | $autoresearch-goal | Codex goal snapshot 위에서 professor/critic 연구 루프를 운영 |
| performance-goal | $performance-goal | 성능 최적화를 evaluator gate와 durable goal handoff로 관리 |
| pipeline | $pipeline | 구성 가능한 stage sequencing workflow |
Planning Skills - 명확화와 계획
| 스킬 | 호출 방법 | 기능 |
|---|---|---|
| deep-interview | $deep-interview | 수학적 ambiguity gate를 둔 소크라테스식 요구사항 인터뷰 |
| ralplan | $ralplan | $plan --consensus alias. planner, architect, critic 합의로 실행 전 계획을 고정 |
| plan | $plan | interview 옵션이 있는 전략 계획 workflow |
Agent Shortcuts - 전문 역할 호출
| 스킬 | 호출 방법 | 기능 |
|---|---|---|
| analyze | $analyze | read-only deep repository analysis. evidence와 inference를 분리해 보고 |
| ai-slop-cleaner | $ai-slop-cleaner | 변경 파일 중심 cleanup/refactor/deslop pass |
| code-review | $code-review | 종합 코드 리뷰. canonical target은 code-reviewer |
| design | $design | 공식 DESIGN.md 중심 제품/UI/UX workflow |
| visual-ralph | $visual-ralph | reference screenshot과 pixel evidence를 포함하는 frontend visual loop |
| ask | $ask | 로컬 Claude 또는 Gemini advisor CLI에 질문하고 artifact를 남김 |
| git-master | $git-master | atomic commit, rebase, history hygiene 보조 alias |
Utility Skills - 설치와 운영
| 스킬 | 호출 방법 | 기능 |
|---|---|---|
| cancel | $cancel | 활성 OMX mode를 안전하게 취소 |
| doctor | $doctor 또는 omx doctor | 설치 shape, hooks, runtime prerequisites 진단 |
| skill | $skill | local skills list/add/remove/search/edit/setup 관리 |
| hud | $hud 또는 omx hud | two-layer statusline과 HUD 상태 확인 |
| omx-setup | $omx-setup 또는 omx setup | 현재 CLI 동작 기준으로 prompts, skills, hooks, agents 설치/갱신 |
| configure-notifications | $configure-notifications | Discord, Telegram, Slack, OpenClaw 등 알림 통합 설정 |
| worker | $worker | team worker ACK/mailbox/task lifecycle용 internal protocol |
Deprecated / Merged - 신규 사용 시 주의
| 스킬 | 현재 상태 | 대체 경로 |
|---|---|---|
| frontend-ui-ux | deprecated | $design 또는 $visual-ralph 사용 |
| ecomode | deprecated | 모델 라우팅은 .omx-config.json과 기본 model tier 정책 사용 |
| swarm | deprecated | $team compatibility facade로만 이해 |
| build-fix / tdd / deepsearch | deprecated shims | executor, test-engineer, analyze/researcher 등 active 역할로 라우팅 |
| security-review / visual-verdict / web-clone | deprecated shims | $code-review, $visual-ralph, designer 경로 우선 |
| configure-discord / configure-slack / configure-openclaw | merged | $configure-notifications로 통합 |
Hooks - native Codex hooks와 runtime fallback
setup surface는 .codex/hooks.json과 .codex/config.toml을 관리합니다. native hook으로 증명한 동작과 tmux/notify fallback으로 증명한 동작은 구분해야 합니다.
!설치 surface
omx setup은 native hook registration, trust state, goal feature flag, project/user scope 설정을 맞춥니다. 다만 omx doctor가 green이어도 실제 Codex auth request가 되는지는 codex login status와 omx exec smoke test로 별도 확인해야 합니다.
Event / SurfaceSessionStart
Adapter
codex-native-hook.js -> session-start주요 기능
leader session bookkeeping, startup developer context, .omx gitignore, wiki startup context, committed project memory loading을 처리합니다.
Event / SurfaceUserPromptSubmit
Adapter
keyword-detectortriage advisory routing주요 기능
명시적 $keyword를 deterministic routing으로 처리하고, keyword가 없으면 advisory prompt-routing context를 주입할 수 있습니다. native subagent prompt는 별도 workflow activation에서 격리됩니다.
Event / SurfacePreToolUse (Bash)
Adapter
pre-tool-use native adapter주요 기능
inspectable git commit의 Lore guard, 위험 명령 경고, document-refresh warning을 다룹니다. native tool hook 범위는 Bash 중심입니다.
Event / SurfacePostToolUse (Bash)
Adapter
post-tool-use native adapter주요 기능
command-not-found, permission-denied, missing-path, MCP transport death처럼 실패 결과에서 유용한 복구 힌트를 생성합니다.
Event / SurfaceStop
Adapter
native Stop continuation주요 기능
Ralph, Autopilot, Ultrawork, UltraQA, Team, ralplan, deep-interview, auto-nudge 등 non-terminal workflow를 block/continue 계약으로 이어갑니다.
Event / SurfacePreCompact / PostCompact
Adapter
wiki compact hooks주요 기능
compact lifecycle을 기록하되 Codex가 거부하는 compact additionalContext stdout을 내지 않는 방식으로 wiki/compaction state를 보존합니다.
Event / SurfaceRuntime fallback
Adapter
omx tmux-hooknotify-hookderived watcher주요 기능
ask-user-question, session-end, session-idle, wiki session capture처럼 아직 distinct native hook이 없는 영역은 runtime fallback이 담당합니다.
빠른 선택 가이드 - 작업별 추천 surface
요구사항이 애매함$deep-interview
실행 전 계획 승인$ralplan
한 명이 끝까지 완료$ralph
병렬 실행 필요$team
여러 목표를 durable하게 관리$ultragoal
저장소 위치/심볼 탐색explore / omx explore
패키지 또는 SDK 선택dependency-expert
외부 공식 문서 조사researcher
UI/UX 결정 원천 관리$design
시각 기준에 맞춰 반복 구현$visual-ralph
적대적 e2e QA$ultraqa
최종 코드 리뷰$code-review
MModel routing
| Lane | Model / rule | 특성 | 용도 |
|---|---|---|---|
| Frontier | gpt-5.5 | 최고 품질 기본 lane | leader, frontier-class roles, planner, architect, critic, code-reviewer, team-executor, vision |
| Standard | inherits frontier unless OMX_DEFAULT_STANDARD_MODEL is set | 표준 worker/review lane | debugger, dependency-expert, writer, researcher 등. 비용 절감 시 gpt-5.4-mini로 override 가능 |
| Spark | gpt-5.3-codex-spark | 저비용/고속 탐색 lane | explore, style-reviewer, team_low_complexity, sparkshell/explore fallback |
TWorkflow compositions
| 시나리오 | 흐름 |
|---|---|
| Canonical flow 불명확한 요구사항을 명확화하고, 합의된 계획을 실행으로 넘기는 기본 흐름 | $deep-interview -> $ralplan -> $team 또는 $ralph |
| Durable launch 여러 목표를 .omx/ultragoal ledger와 Codex goal snapshot으로 추적 | $ultragoal -> get_goal/create_goal -> story checkpoint -> final review gate |
| Frontend design 제품/UI 결정 원천과 시각 검증 루프를 분리 | $design -> DESIGN.md -> $visual-ralph -> verifier/code-reviewer |
| Adversarial QA 정상 경로뿐 아니라 공격적/중단/재개/오염 상태를 함께 검증 | $ultraqa -> hostile scenarios -> test/verify/fix -> cleanup evidence |
5Team pipeline stages
기본 pipeline은 team-plan -> team-prd -> team-exec -> team-verify -> team-fix loop입니다.
| Stage | 주요 에이전트 | 선택적 에이전트 |
|---|---|---|
| team-plan | explore + planner | analyst/architect |
| team-prd | analyst | critic |
| team-exec | executor/team-executor + specialists | designer, writer, test-engineer, dependency-expert |
| team-verify | verifier | code-reviewer, security context, performance context |
| team-fix | executor/debugger/test-engineer | 결함 유형에 따라 선택 |