Agent Team Codex

Agent Team Codex

Codex CLI의 stable multi-agent 기능을 사용해 작업을 병렬 분배하는 운영 스킬입니다. Codex의 default/explorer/worker 역할을 기준으로 실행하며 특정 모델을 강제하지 않습니다.

Prerequisites

1. 현재 Codex에서 subagent 도구가 노출되는지 확인합니다. 현행 Codex는 [agents].enabled 기본값이 true입니다.
2. 사용자가 명시적으로 비활성화한 경우 그 선택을 존중하고 메인 컨텍스트에서 Wave를 순차 실행합니다.
3. 동시성 상한을 사용자가 조정하려는 경우에만 현재 설정명을 사용합니다:

[agents]
max_concurrent_threads_per_session = 6

사용자 정의 .toml agent는 필요하지 않습니다. 고유한 sandbox·MCP·모델 계약이 입증된 경우에만 별도 opt-in으로 추가합니다.

Source-only internal module resolution (mandatory)

code-reviewer와 조건부 orchestrator는 이 하네스가 내부 정책으로 읽는 source-only 모듈입니다. 등록된 스킬이나 slash command로 호출하지 않습니다.

각 선택된 모듈을 다음 순서로 해석하고 처음 확인된 exact SKILL.md 파일 하나를 읽습니다.

1. 현재 프로젝트의 skills/{name}/SKILL.md가 실제로 있으면 그 exact 파일.
2. 없으면 Codex active root의 ~/.codex/skills/{name}/SKILL.md exact 파일 (명시 opt-in 설치 지원).
3. 둘 다 없으면 Codex 전역 ~/.codex/SKILLS-CATALOG.md에서 정확한 모듈명 행을 찾습니다. 행이 하나일 때만 읽을 경로에 적힌 절대 SKILL.md를 그대로 읽고, 누락·중복 행은 fail-closed입니다. 기본 경로가 보통 .olympus/source-skills 아래여도 직접 조합하거나 추측하지 않습니다.
4. module_root는 읽은 SKILL.md의 부모입니다. 모듈의 references/, scripts/, commands/는 모두 이 루트에서 해석합니다.
5. Step 6 코드 리뷰에 도달했을 때만 code_reviewer_root를 만듭니다. hard file lock, 외부 ledger, 크로스-CLI 혼합이 실제로 필요해 MCP 분기를 선택한 뒤에만 orchestrator_root를 만들고 ${orchestrator_root}/commands/workpm-mcp.md를 읽습니다.

이 exact 파일 읽기는 내부 모듈 로드입니다. 런타임 Skill 목록/레지스트리를 근거로 호출하거나 모듈 이름을 slash command로 실행하지 않습니다.

code-reviewer를 읽지 못하면 codex review 1회와 explorer의 bounded 품질·보안·타입 체크만 실행하고 policy module: NOT RUN (native fallback), gate DEGRADED를 기록합니다. orchestrator/MCP를 읽지 못하면 파일 소유권을 직렬화할 수 있는 경우에만 메인 순차 경로로 축소하고 MCP: NOT RUN을 기록합니다. hard lock이 필수이면 해당 Wave는 BLOCKED입니다. 어느 누락도 PASS로 처리하지 않습니다.

Modes

1) 섹션 모드

• 입력에 docs/plan/*/sections/index.md 또는 zephermine 산출물이 있는 경우 (archive/ 경로 제외)
• 섹션 의존성을 Wave로 분리해 병렬 실행

2) 자유 모드

• 일반 작업 요청(예: "auth 리팩토링 + 테스트")
• 파일/모듈 기준으로 태스크를 직접 분해 후 병렬 실행

조건부 MCP 정책 분기

기본 경로는 Codex native agent이며, agent가 없으면 메인 컨텍스트 순차 실행입니다. hard file lock, 외부 task ledger, 크로스-CLI 혼합 중 하나가 실제 요구사항일 때만 MCP 분기를 선택하고, 그때 위 resolver로 orchestrator 모듈과 ${orchestrator_root}/commands/workpm-mcp.md를 읽습니다. 선택 전에는 모듈·서버·활동 로그 도구를 로드하지 않습니다.

Workflow

Step 0: 산출물 검토 (PM 게이트)

Claude 버전 agent-team의 Step 0과 동일한 역할. 설계 없이 구현을 시작하지 않는다.

섹션 모드에서 필수 확인:

1. plan.md — 전체 구현 방향 파악
2. sections/index.md — 의존성 그래프 → Wave 분리 기준
3. flow-diagrams/ — 공정 도면 존재 여부 (있으면 각 worker에게 담당 노드 배분)
4. 보조 문서 매핑:
   • api-spec.md → API 관련 worker에게 전달
   • db-schema.md → DB 관련 worker에게 전달
   • design-system.md → 프론트엔드 worker에게 전달
5. 각 section의 Acceptance Criteria 추출 → 마스터 체크리스트로 통합

자유 모드에서는 건너뜀.

Step 1: 작업 분해

1. 목표를 3~8개의 독립 태스크로 분할
2. 태스크별 담당 파일 범위를 고정
3. 의존성 있는 태스크는 후행 Wave로 배치

상세 규칙: references/role-mapping.md

Step 2: 역할 매칭

• explorer: 분석, 리스크 점검, 편집 금지
• worker: 구현/수정/테스트
• default: 조율, 병합 판단, 최종 보고

Step 3: 에이전트 스폰

Codex 프롬프트에서 자연어로 spawn 지시를 보냅니다. 템플릿은 references/prompt-templates.md를 사용합니다.

핵심 규칙:

• 각 worker는 파일 소유권 범위를 벗어나지 않음
• explorer는 코드 수정 금지
• 충돌 가능성이 있으면 즉시 default가 재분배
• 각 worker는 변경 파일·테스트·계획 이탈·남은 위험을 반환하고, Lead만 conversations/{YYYY-MM-DD}-team-poseidon.md와 공유 implementation-notes.md를 기록

Step 4: 모니터링

1. 진행 중 실패 태스크를 우선 확인
2. 실패 원인을 한 번에 하나씩 재시도
3. 3회 이상 반복 실패 시 아키텍처 이슈로 분류 후 사용자 보고

Step 5: Activity Log Summary

통합 전 활동 로그 요약:

1. Lead가 기록한 conversations/{YYYY-MM-DD}-team-poseidon.md 읽기
2. 에이전트별 활동 통계: 완료 보고 수, 에러 수, 파일 수
3. orchestrator source module과 MCP command를 성공적으로 읽고 실제 분기를 시작한 경우에만 orchestrator_get_activity_log로 JSONL 로그도 확인. 그 외에는 MCP: NOT SELECTED 또는 MCP: NOT RUN으로 기록
4. 요약을 최종 보고에 포함

Step 6: 코드 리뷰 게이트

구현 완료 후, 통합 전 품질 검증:

1. Step 6 진입 후 전역 카탈로그의 code-reviewer 행을 해석하고 ${code_reviewer_root}/SKILL.md의 Codex native 경로와 포세이돈 정책 레이어를 읽습니다. 등록 스킬로 호출하지 않습니다. 보안 감사 reference가 필요한 범위만 ${code_reviewer_root}/references/security-audit.md를 추가로 읽습니다.
2. native-first로 codex review --uncommitted 또는 적절한 base review를 실행하고, 필요한 보강 검토를 explorer 에이전트에게 위임합니다:
   • 각 worker가 생성한 파일의 품질, 보안, 타입 안전성 확인
   • Acceptance Criteria 대조 (Step 0에서 추출한 마스터 체크리스트)
   • flow-diagrams 노드 매핑 (있는 경우) — 담당 노드가 구현되었는지
3. source module 미가용 시 native review + 위 세 항목만 bounded fallback으로 실행하고 policy module: NOT RUN, review gate: DEGRADED를 보고합니다.
4. 미통과 항목 → 해당 worker 재spawn하여 수정 (최대 2회)
5. 2회 후에도 미통과 → 사용자 보고

Step 7: 통합 게이트 (완료 권한 — 필수)

I-1: 병렬 구현 후 "함수가 존재하는가"를 Grep/Read로 확인하는 코드-존재 검증은 자기 판단이며, 컴파일/통합되지 않는 코드도 통과시킬 수 있다. 빌드/타입체크는 선택이 아니다.

1. 파일 충돌 여부 확인
2. 사전 점검(PRE-CHECK, 완료 권한 아님): 코드-존재 / Acceptance Criteria grep 대조 — 빠뜨린 작업 식별용일 뿐, 이것만으로 완료 선언 금지. AC는 proved/weak/missing으로 채점(028 완료 계약) — 코드는 있으나 동작 증거가 약하면 weak로 분리(존재=완료 둔갑 방지). 또한 경계면 정합성 교차 비교(웹앱: API 응답 shape↔훅 타입·경로↔href·엔드포인트↔훅 1:1 / 비웹: 해당 경계 / 없으면 skip) — 빌드 통과가 숨기는 런타임 mismatch를 게이트 전에 정적으로 거른다(양쪽 동시 읽기)
3. 병합 결과에 대해 통합 게이트를 1회 실행 (이 게이트만이 완료 권한):
   1. 빌드 / 타입체크
   2. 전체 테스트 스위트 1회 실행 (병합된 결과 대상)
   3. (가능하면) 통합/E2E 1회 실행
4. 게이트 결과에 따라:
   • 전부 통과 → 완료 선언 가능
   • 실패 → 해당 worker 재spawn하여 수정 후 게이트 재실행
   • 빌드/테스트 도구가 없으면 그 사실을 명시하고 사용자에게 수동 확인을 요청 (자동 PASS 금지)
5. 남은 리스크/미해결 항목 정리

Guard: 게이트 미통과 상태로 완료 선언 금지; 빌드/테스트 도구가 없으면 명시하고 수동 확인 요청(자동 PASS 금지).

Output Format

최종 보고는 아래 포맷을 따릅니다:

Codex Agent Team 실행 결과
- 완료 태스크: N개
- 실패 태스크: N개
- 마스터 체크리스트: M/N 통과 (XX%)
- 주요 변경 파일: ...
- 테스트 결과: 통과 N / 실패 N
- 내부 모듈: code-reviewer {LOADED|NOT RUN}, orchestrator MCP {NOT SELECTED|LOADED|NOT RUN}
- 잔여 리스크: ...

👉 다음 단계 (선택):
  /argos               → 감리 (설계 대비 구현 검증, Phase 0~6)
  /aphrodite           → 디자인 정교화 (design-system.md가 있는 UI 프로젝트)
  /minos          → Playwright 자동 테스트 + Healer 루프
  /review              → 코드 리뷰
  /commit              → 변경사항 커밋

Troubleshooting

subagent 도구가 보이지 않음

• codex features list와 현재 [agents].enabled 설정을 확인합니다.
• 현행 버전인데 도구가 없으면 Codex를 갱신하고 세션을 다시 시작합니다.
• 사용자가 agents를 껐거나 갱신할 수 없으면 메인 컨텍스트 순차 실행으로 계속합니다.

에이전트 충돌(같은 파일 동시 수정)

• 파일 소유권을 다시 나눠 재스폰
• 공통 모듈은 별도 single-owner 태스크로 분리

스레드 과다로 품질 저하

• max_concurrent_threads_per_session을 줄여 재실행 (예: 6 → 4)
• explorer를 1개로 고정하고 worker 수만 조절

References

• 역할/소유권 규칙: references/role-mapping.md
• 스폰 프롬프트 템플릿: references/prompt-templates.md