@kood/claude-code 0.7.9 → 0.7.11

package/templates/.claude/skills/codex/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codex
-description: Claude와 OpenAI Codex 페어 프로그래밍. 자유 협업으로 복잡한 작업을 분업 처리. Claude(창의적) + Codex(꼼꼼함) 강점 활용.
+description: Claude와 OpenAI Codex 페어 프로그래밍. 자체 codex-mcp 서버로 자유 협업. Claude(창의적) + Codex(꼼꼼함) 강점 활용.
 user-invocable: true
 ---
 
@@ -13,22 +13,20 @@ user-invocable: true
 
 # Codex Pair Programming Skill
 
-> Claude와 OpenAI Codex의 자유로운 페어 프로그래밍. 상황에 따라 유동적으로 역할 분담.
+> Claude + codex-mcp 페어 프로그래밍. Claude(설계/창의) + Codex(구현/검증) 역할 분담.
 
 ---
 
 <overview>
 
-## 핵심 개념
+**codex-mcp 서버:** Rust MCP 바이너리 → OpenAI Responses API 직접 호출
 
-**Claude + Codex 페어 프로그래밍:**
-- **Claude**: 창의적 설계, 아키텍처, 새로운 접근법, 문제 재정의
-- **Codex**: 꼼꼼한 구현, 엣지케이스 검증, 리뷰, 정확한 코드 생성
-
-**협업 방식:**
-- 자유 협업: 상황에 따라 유동적 역할 분담
-- 분업 처리: 의견 다를 때만 사용자 선택
-- Agent Teams: 복잡한 작업 시 팀 구성
+| 특성 | 상세 |
+|------|------|
+| **인증** | Codex CLI OAuth (`~/.codex/auth.json`), 토큰 자동 갱신, 401시 강제 갱신+재시도 |
+| **에이전트 루프** | `read_file`, `write_file`, `list_files`, `shell_exec` 자율 실행 |
+| **세션** | `thread_id` 기반 컨텍스트 유지, 모델 세션간 자동 보존 |
+| **보안** | 경로순회 방지, 프로세스그룹 격리, 동시요청 방지 |
 
 </overview>
 
@@ -38,526 +36,180 @@ user-invocable: true
 
 ## 사전 요구사항
 
-### Codex MCP 설정 필수
-
 ```bash
-# Codex CLI 설치 확인
-which codex || npm install -g @openai/codex
-
-# Claude Code에 MCP 서버 추가
-claude mcp add codex -- codex mcp-server
-
-# 또는 ~/.claude.json에 직접 추가:
-{
-  "mcpServers": {
-    "codex": {
-      "type": "stdio",
-      "command": "codex",
-      "args": ["mcp-server"]
-    }
-  }
-}
-```
-
-**MCP 미설정 시:** 스킬 실행 전 설정 안내 후 중단
-
-</prerequisites>
-
----
-
-<when_to_use>
-
-## 사용 시점
-
-| 상황 | 예시 |
-|------|------|
-| **복잡한 기능 구현** | "결제 시스템 리팩토링" |
-| **코드 리뷰 + 개선** | "이 PR 리뷰하고 개선해줘" |
-| **설계 + 구현 분리** | "아키텍처 설계 후 구현" |
-| **병렬 작업** | "프론트/백엔드 동시 작업" |
-| **세컨드 오피니언** | "이 접근법 괜찮은지 검토" |
-| **엣지케이스 검증** | "이 코드 빈틈 찾아줘" |
-
-## 호출 방법
-
-```bash
-/codex 사용자 인증 시스템 구현
-
-/codex --review 최근 커밋 리뷰
+# 1. Codex CLI OAuth 로그인
+codex auth login
 
-/codex --design 실시간 알림 아키텍처 설계
+# 2. 빌드 + Claude Code 등록
+cargo build -p codex-mcp --release
+claude mcp add -s user codex -- /path/to/target/release/codex-mcp
 ```
 
-</when_to_use>
+또는 앱 설정 → **OpenAI / Codex** 탭 → **등록** 버튼.
 
----
-
-<collaboration_modes>
-
-## 협업 모드
-
-| 모드 | 트리거 | Claude 역할 | Codex 역할 |
-|------|--------|-------------|------------|
-| **Solo+Review** | 단순 작업, 빠른 수정 | 전체 구현 | 최종 리뷰 |
-| **Sequential** | 설계→구현 필요 | 아키텍처, 설계 | 구현, 테스트 |
-| **Parallel** | 독립 작업 가능 | 창의적 부분 (A) | 꼼꼼한 부분 (B) |
-| **Discussion** | 의견 필요, 트레이드오프 | 관점 A 제시 | 관점 B 제시 |
-| **Teams** | 복잡한 멀티태스크 | 팀원으로 참여 | **Team Lead** |
-
-### Codex Team Lead 원칙
-
-> **Agent Teams 모드에서 Codex가 Team Lead 역할 담당**
+**인증:** `~/.codex/auth.json` (OAuth 토큰, 자동 갱신)
 
-| 역할 | 담당 | 이유 |
-|------|------|------|
-| **Team Lead** | Codex | 꼼꼼한 태스크 관리, 품질 검증, 일정 조율 |
-| **Teammates** | Claude, 기타 에이전트 | 창의적 설계, 구현, 문서화 |
-
-**Codex Lead 강점:**
-- 태스크 분해 및 추적 정밀
-- 엣지케이스 누락 방지
-- 코드 품질 게이트키핑
-- 병합 충돌 사전 감지
-
-### 자동 모드 선택
-
-```
-복잡도 판단 (Sequential Thinking)
-    │
-    ├─ 단순 (1-2 파일) ────────→ Solo+Review
-    │
-    ├─ 보통 (3-5 파일) ────────→ Sequential 또는 Parallel
-    │
-    ├─ 복잡 (6+ 파일) ─────────→ Teams
-    │
-    └─ 의견 분기 ──────────────→ Discussion → 사용자 선택
-```
-
-</collaboration_modes>
+</prerequisites>
 
 ---
 
-<workflow>
-
-## 실행 흐름
+<codex_mcp_tools>
 
-| Phase | 작업 | 도구 |
-|-------|------|------|
-| **0** | MCP 확인 + 복잡도 분석 | ToolSearch, sequentialthinking |
-| **1** | 협업 모드 결정 | sequentialthinking |
-| **2** | 역할 분담 + 작업 배분 | TodoWrite |
-| **3** | 협업 실행 | Task (codex agent) + 직접 작업 |
-| **4** | 결과 통합 + 충돌 해소 | 필요 시 AskUserQuestion |
-| **5** | 최종 검증 + 커밋 | code-reviewer, git |
+## MCP 도구
 
-### Phase 0: 환경 확인
+### mcp__codex__codex — 새 태스크
 
 ```typescript
-// MCP 확인
-ToolSearch("codex")
-→ codex MCP 가용 여부 확인
-→ 미설정 시 설정 안내 후 중단
-
-// 복잡도 분석
-sequentialthinking({
-  thought: "작업 복잡도 판단: 파일 수, 모듈 범위, 아키텍처 변경 여부"
+mcp__codex__codex({
+  prompt: "작업 지시",
+  working_directory: "/path/to/project",
+  model: "gpt-5.3-codex high"  // 선택 (세션에 저장, 생략 시 Codex CLI 기본값)
 })
+// → JSON { thread_id, result }
 ```
 
-### Phase 1: 모드 결정
+### mcp__codex__codex_reply — 세션 이어가기
 
 ```typescript
-sequentialthinking({
-  thought: `
-    협업 모드 결정:
-    - 단순 (1-2 파일): Solo+Review
-    - 설계 필요: Sequential (Claude 설계 → Codex 구현)
-    - 독립 작업: Parallel (동시 진행)
-    - 트레이드오프: Discussion (양쪽 의견 → 사용자 선택)
-    - 복잡 (6+ 파일, 팀 소통): Teams
-  `
+mcp__codex__codex_reply({
+  thread_id: "이전 thread_id",
+  prompt: "후속 지시 또는 리뷰 요청"
 })
+// → JSON { thread_id, result }
+// 세션 모델 자동 유지
 ```
 
-### Phase 2-3: 역할 분담 및 실행
+### 리뷰 패턴 (2단계)
 
-**Solo+Review 모드:**
 ```typescript
-// Claude가 구현
-Edit/Write → 코드 작성
-
-// Codex가 리뷰
-Task({
-  subagent_type: 'codex',
-  prompt: `
-    리뷰 대상: [변경된 파일들]
-    검토 항목:
-    - 엣지케이스 누락
-    - 버그 가능성
-    - 성능 이슈
-    - 보안 취약점
-  `
+// 1단계: 분석
+const r = mcp__codex__codex({
+  prompt: "src/auth/ 코드 읽고 분석해줘",
+  working_directory: cwd
 })
-```
-
-**Sequential 모드:**
-```typescript
-// Phase A: Claude 설계
-sequentialthinking → 아키텍처 설계
-→ 인터페이스 정의, 데이터 플로우
-
-// Phase B: Codex 구현
-Task({
-  subagent_type: 'codex',
-  prompt: `
-    Claude 설계 기반 구현:
-    [설계 문서]
-
-    구현 요구사항:
-    - 모든 엣지케이스 처리
-    - 타입 안정성 보장
-    - 테스트 포함
-  `
-})
-```
-
-**Parallel 모드:**
-```typescript
-// 동시 실행
-Task({
-  subagent_type: 'codex',
-  prompt: '백엔드 API 구현: [상세 요구사항]'
+// 2단계: 리뷰
+mcp__codex__codex_reply({
+  thread_id: r.thread_id,
+  prompt: "보안, 성능, 엣지케이스 리뷰"
 })
-
-// Claude: 프론트엔드 구현 (직접)
-Edit/Write → 컴포넌트, 훅 작성
 ```
 
-**Discussion 모드:**
-```typescript
-// Codex 의견 수집
-Task({
-  subagent_type: 'codex',
-  prompt: '이 접근법의 장단점 분석: [접근법 A]'
-})
-
-// Claude 의견 제시
-sequentialthinking → 접근법 B 분석
-
-// 충돌 시 사용자 선택
-AskUserQuestion({
-  questions: [{
-    question: "어떤 접근법을 선택하시겠습니까?",
-    header: "Approach",
-    options: [
-      { label: "접근법 A (Codex)", description: "[장점/단점]" },
-      { label: "접근법 B (Claude)", description: "[장점/단점]" },
-      { label: "하이브리드", description: "두 접근법 조합" }
-    ]
-  }]
-})
-```
-
-**Teams 모드 (Codex Lead):**
-```typescript
-// Agent Teams 가용 확인
-if (AGENT_TEAMS_AVAILABLE) {
-  // Codex가 Team Lead로 팀 생성
-  TeamCreate({
-    team_name: "pair-codex",
-    description: "페어 프로그래밍",
-    agent_type: "codex"  // Codex를 Team Lead로 지정
-  })
-
-  // Claude 팀원 스폰 (Codex Lead가 조율)
-  Task({
-    subagent_type: 'implementation-executor',
-    team_name: 'pair-codex',
-    name: 'claude-impl',
-    prompt: '창의적 설계 + 구현: [범위 A]'
-  })
-
-  Task({
-    subagent_type: 'architect',
-    team_name: 'pair-codex',
-    name: 'claude-arch',
-    prompt: '아키텍처 설계: [범위 B]'
-  })
-
-  // Codex Lead가 태스크 관리 + 품질 검증
-  // 완료 후 정리
-  SendMessage({ type: 'shutdown_request', recipient: 'claude-impl' })
-  SendMessage({ type: 'shutdown_request', recipient: 'claude-arch' })
-  TeamDelete()
-}
-```
-
-### Phase 4: 결과 통합
+</codex_mcp_tools>
 
-```typescript
-// 충돌 확인
-if (결과_충돌) {
-  AskUserQuestion → 사용자 선택
-} else {
-  // 자동 병합
-  결과 통합 → 최종 코드
-}
-```
+---
 
-### Phase 5: 최종 검증
+<collaboration_modes>
 
-```typescript
-// 코드 리뷰
-Task({ subagent_type: 'code-reviewer', prompt: '최종 변경사항 리뷰' })
+## 협업 모드
 
-// 테스트 실행
-Bash('npm test')
+| 모드 | 트리거 | Claude | Codex |
+|------|--------|--------|-------|
+| **Solo+Review** | 1-2 파일 | 구현 | 리뷰 |
+| **Sequential** | 설계→구현 | 아키텍처 | 구현+테스트 |
+| **Parallel** | 독립 작업 | 창의적 부분 | 꼼꼼한 부분 |
+| **Discussion** | 트레이드오프 | 관점 A | 관점 B |
+| **Teams** | 6+ 파일 | 팀원 | **Team Lead** |
 
-// 커밋
-git commit -m "feat: [작업 설명] (Claude+Codex pair)"
-```
+**모드 선택:** sequentialthinking으로 복잡도 판단 → 자동 선택
 
-</workflow>
+</collaboration_modes>
 
 ---
 
-<codex_mcp_tools>
+<workflow>
 
-## Codex MCP 도구
+## 실행 흐름
 
-| 도구 | 설명 | 사용 시점 |
-|------|------|----------|
-| `mcp__codex__codex` | AI 코딩 어시스턴트 | 코드 생성, 분석, 수정 |
-| `mcp__codex__review` | 코드 리뷰 | uncommitted 변경, 브랜치, 커밋 리뷰 |
-| `mcp__codex__listSessions` | 세션 목록 | 활성 대화 확인 |
+| Phase | 작업 |
+|-------|------|
+| **0** | MCP 가용 확인 + 복잡도 분석 |
+| **1** | 협업 모드 결정 |
+| **2** | 역할 분담 (TodoWrite) |
+| **3** | 협업 실행 (Task codex agent + 직접 작업) |
+| **4** | 결과 통합 (충돌 시 AskUserQuestion) |
+| **5** | 검증 + 커밋 |
 
-### codex 도구 옵션
+### Solo+Review
 
 ```typescript
-mcp__codex__codex({
-  prompt: "작업 지시",
-  model: "gpt-5.2",           // 모델 선택
-  session: "session-id",      // 세션 유지
-  structured_output: true,    // 구조화된 출력
-  working_directory: "/path"  // 작업 디렉토리
-})
+// Claude 구현 → Codex 리뷰
+Edit/Write → 코드 작성
+const r = mcp__codex__codex({ prompt: "git diff 분석: [diff]", working_directory: cwd })
+mcp__codex__codex_reply({ thread_id: r.thread_id, prompt: "버그, 보안, 엣지케이스 리뷰" })
 ```
 
-### review 도구 옵션
+### Sequential
 
 ```typescript
-mcp__codex__review({
-  target: "uncommitted" | "branch:feature" | "commit:abc123",
-  focus: ["security", "performance", "bugs"]
-})
+// Claude 설계 → Codex 구현
+sequentialthinking → 아키텍처
+Task({ subagent_type: 'codex', prompt: `Claude 설계 기반 구현: ${설계문서}` })
 ```
 
-</codex_mcp_tools>
-
----
-
-<examples>
-
-## 실전 예시
-
-### 예시 1: 단순 작업 (Solo+Review)
-
-```bash
-사용자: /codex 이 함수에 null 체크 추가해줘
-
-# Phase 0: 복잡도 - 단순 (1 파일)
-# Phase 1: 모드 - Solo+Review
-
-# Claude 구현
-Edit: src/utils/parser.ts
-+ if (input == null) return null;
-
-# Codex 리뷰
-Task(codex): "null 체크 추가 리뷰"
-→ "undefined도 체크 필요. input === null || input === undefined 권장"
-
-# Claude 수정
-Edit: src/utils/parser.ts
-+ if (input == null) return null;  // == 로 undefined도 처리
-
-# 완료
-git commit -m "fix: parser에 null 체크 추가"
-```
-
-### 예시 2: 설계→구현 (Sequential)
-
-```bash
-사용자: /codex 사용자 인증 시스템 구현
-
-# Phase 0: 복잡도 - 보통 (4-5 파일)
-# Phase 1: 모드 - Sequential
-
-# Phase A: Claude 설계
-sequentialthinking:
-  - JWT + httpOnly 쿠키 방식
-  - 인터페이스: AuthService, TokenManager
-  - 데이터 플로우: login → token → cookie
-
-# Phase B: Codex 구현
-Task(codex): "Claude 설계 기반 구현"
-→ src/auth/AuthService.ts
-→ src/auth/TokenManager.ts
-→ src/auth/middleware.ts
-→ tests/auth.test.ts
-
-# Phase 4: 통합
-Claude: 인터페이스 일관성 확인
-Codex: 엣지케이스 테스트 추가
-
-# Phase 5: 커밋
-git commit -m "feat: JWT 기반 인증 시스템 구현"
-```
-
-### 예시 3: 복잡한 작업 (Teams)
-
-```bash
-사용자: /codex 결제 시스템 전체 리팩토링
-
-# Phase 0: 복잡도 - 복잡 (10+ 파일)
-# Phase 1: 모드 - Teams
-
-# 팀 생성
-TeamCreate("pair-codex")
+### Teams (Codex Lead)
 
-# 역할 분담
-Task(codex, team): "결제 로직 리팩토링 + 테스트"
-Task(claude, team): "아키텍처 개선 + 새 인터페이스 설계"
-
-# 병렬 작업
-codex-impl: PaymentService, TransactionManager
-claude-design: 새 결제 플로우, 에러 핸들링 전략
-
-# 결과 통합
-→ 충돌: TransactionManager 구조
-→ Discussion → 사용자 선택: Codex 안 채택
-
-# 팀 정리
-shutdown_request → TeamDelete
-
-# 커밋
-git commit -m "refactor: 결제 시스템 전면 리팩토링"
+```typescript
+TeamCreate({ team_name: "pair-codex", agent_type: "codex" })
+Task({ subagent_type: 'implementation-executor', team_name: 'pair-codex', name: 'claude-impl', prompt: '...' })
+// 완료 후
+SendMessage({ type: 'shutdown_request', recipient: 'claude-impl' })
+TeamDelete()
 ```
 
-### 예시 4: 의견 분기 (Discussion)
-
-```bash
-사용자: /codex 실시간 알림 구현 방식 결정해줘
-
-# Phase 1: 모드 - Discussion
+</workflow>
 
-# Codex 의견
-Task(codex): "실시간 알림 구현 방식 분석"
-→ "WebSocket 권장: 양방향, 연결 유지, Socket.io 성숙"
+---
 
-# Claude 의견
-sequentialthinking:
-→ "SSE 권장: 단순, HTTP/2, 서버 부하 낮음"
+<strengths>
 
-# 의견 충돌
-AskUserQuestion:
-  - WebSocket (Codex): 양방향 필요 시
-  - SSE (Claude): 서버→클라이언트 단방향
-  - 하이브리드: 알림은 SSE, 채팅은 WebSocket
+## 역할별 강점
 
-# 사용자 선택: SSE
-→ Claude + Codex 협력하여 SSE 구현
-```
+| Claude 우선 | Codex 우선 |
+|-------------|-----------|
+| 아키텍처 설계 | 정밀 구현 |
+| 창의적 해결책 | 엣지케이스 |
+| 문제 재정의 | 코드 리뷰 |
+| 통합 설계 | 테스트 작성 |
+| 문서화 | 디버깅 |
 
-</examples>
+</strengths>
 
 ---
 
 <validation>
 
-## 검증 체크리스트
+## 검증
 
-### 실행 전
-
-```text
-✅ Codex MCP 가용 확인 (ToolSearch)
-✅ 복잡도 분석 (sequentialthinking)
-✅ 협업 모드 결정
-✅ 역할 분담 명확화
-```
-
-### 실행 중
-
-```text
-✅ 각 역할별 작업 범위 준수
-✅ 파일 충돌 방지 (한 파일 = 한 담당)
-✅ 진행 상황 추적 (TodoWrite)
-✅ 중간 검증 수행
-```
-
-### 완료 후
-
-```text
-✅ 결과 통합 완료
-✅ 충돌 해소 (필요 시 사용자 선택)
-✅ 코드 리뷰 완료
-✅ 테스트 통과
-✅ Teams 사용 시 정리 (shutdown + TeamDelete)
-```
-
-## 금지 사항
-
-```text
-❌ MCP 미설정 상태로 진행
-❌ 복잡도 분석 없이 모드 선택
-❌ 같은 파일을 Claude/Codex 동시 수정
-❌ 충돌 무시하고 임의 선택
-❌ Teams 사용 후 정리 없이 종료
-❌ Codex 결과 검증 없이 수용
-❌ Claude 설계 없이 복잡한 작업 시작
-```
+**실행 전:** MCP 가용 확인 → Codex 로그인 확인 → 복잡도 분석 → 모드/역할 결정
+**실행 중:** 역할 범위 준수, 파일 충돌 방지 (한 파일 = 한 담당), TodoWrite 추적
+**완료 후:** 결과 통합 → 코드 리뷰 → 테스트 통과 → Teams 정리
 
 </validation>
 
 ---
 
-<strengths>
-
-## 역할별 강점 활용
-
-### Claude 강점 (우선 위임)
-
-| 영역 | 예시 |
-|------|------|
-| **아키텍처 설계** | 시스템 구조, 모듈 분리 |
-| **창의적 해결책** | 새로운 접근법, 패턴 제안 |
-| **문제 재정의** | 요구사항 분석, 본질 파악 |
-| **통합 설계** | 여러 시스템 연결, 데이터 플로우 |
-| **문서화** | 설계 문서, API 문서 |
-
-### Codex 강점 (우선 위임)
+<forbidden>
 
-| 영역 | 예시 |
+| 금지 | 대안 |
 |------|------|
-| **정밀 구현** | 복잡한 알고리즘, 로직 |
-| **엣지케이스** | 예외 처리, 경계 조건 |
-| **코드 리뷰** | 버그 탐지, 보안 취약점 |
-| **테스트 작성** | 단위 테스트, 통합 테스트 |
-| **디버깅** | 버그 원인 분석, 수정 |
+| MCP 미설정으로 진행 | 설정 안내 후 중단 |
+| 같은 파일 동시 수정 | 작업 범위 분리 |
+| 충돌 시 임의 결정 | AskUserQuestion |
+| Codex 결과 무검증 수용 | 리뷰 + 테스트 |
 
-</strengths>
+</forbidden>
 
 ---
 
 <troubleshooting>
 
-## 문제 해결
-
-| 문제 | 원인 | 해결 |
-|------|------|------|
-| Codex MCP 연결 실패 | 설정 누락 | `claude mcp add codex -- codex mcp-server` |
-| Codex 응답 지연 | 네트워크/API 부하 | 재시도 또는 Claude 단독 진행 |
-| 결과 충돌 | 다른 접근법 | Discussion 모드 → 사용자 선택 |
-| Teams 팀원 미응답 | 세션 문제 | shutdown → 재스폰 |
-| 파일 충돌 | 동시 수정 | 작업 범위 재분배 |
+| 에러 | 해결 |
+|------|------|
+| MCP 연결 실패 | 앱 설정 → OpenAI/Codex → 등록 |
+| 401 인증 오류 | `codex auth login` |
+| 토큰 갱신 실패 | `codex auth login` 재실행 |
+| 타임아웃 | 재시도 |
+| 세션 not found | 새 `codex` 세션 시작 |
+| 동시 요청 에러 | 이전 요청 완료 대기 |
 
 </troubleshooting>