spec-flow · skill guide

claude-to-codex

Claude 가 쓴 phase 구현 문서를 Codex 실행에 최적화된 명령형 문서로 다시 쓴다.

/spec-flow:claude-to-codex CLI 플래그 없음 원본 phase 문서 read-only docs/ai/phases/codex/

한 줄 요약

Claude 가 쓴 phase 구현 문서를 Codex 가 그대로 실행할 수 있는 명령형 문서로 다시 쓴다. 산출물은 docs/ai/phases/codex/<base>-codex-NN.md 이고, 원본 phase 문서는 절대 건드리지 않는다.

왜 필요한가

Claude 와 설계 대화를 하며 쓴 phase 문서는 서술형이고 여지가 많다. "이렇게 하는 게 무난해 보인다", "필요하면 나중에", "고려해 볼 만하다" 같은 표현이 섞인다. 사람이 읽기에는 자연스럽지만 Codex 에 그대로 주면 판단을 요구받는 지점마다 결과가 흔들린다.

이 스킬은 그 서술을 명령으로 바꾸고, 모호하거나 미뤄 둔 표현을 제거해, 원본 긴 설계 문서를 옆에 띄워 두지 않고도 생성된 문서 하나만으로 Codex 가 작업을 마칠 수 있게 만든다.

무엇을 만드는가

대상결과
docs/ai/phases/codex/<base>-codex-01.md 변환된 명령형 문서. 분할 없으면 이 한 개
-codex-02, -codex-03, ... 분할 조건이 실제로 걸렸을 때만 추가 생성
AGENTS.md @CLAUDE.md 한 줄 기준으로 생성/보완/무변경

원본 base 파일명은 항상 보존하고 -codex-NN 을 붙인다. 번호는 01 부터 0-패딩한다.

언제 쓰고 언제 안 쓰는가

쓴다

Claude 로 설계를 마쳤고, 실제 구현은 Codex 에 넘기려 할 때.

안 쓴다

  • 분해가 필요할 때. 이 스킬은 아무것도 분해하지 않는다. 같은 내용을 다른 실행자를 위해 다시 쓸 뿐이다. PRD → TRD 는 prd-to-trd, TRD → 이슈는 trd-to-issues 다.
  • 요약본이 필요할 때. 결과물은 요약이 아니라 실무용 구현 문서이며 원본 의도에 충실해야 한다.
  • CLAUDE.md 자체를 다시 쓰고 싶을 때. 명시적으로 요청하지 않는 한 건드리지 않는다.

호출 형식

CLI 플래그가 없다. 참조 문서들과 대상 phase 문서를 자연어로 지목하면 발동한다.

docs/ai/architecture.md, docs/ai/backend.md, docs/ai/phases/phase-02-x.md 를
참조해서 phase-02-x 문서를 codex 에서 작업하기 최적화된 설계문서로 변경해줘

phase-03 문서를 codex용으로 재구성해줘

이 phase 문서를 codex-friendly task 문서로 필요하면 분할해서 만들어줘

동작 단계

  1. 입력 읽기 — 지목된 참조 문서 전부와 대상 phase 문서를 한 번에 읽고, AGENTS.md / CLAUDE.md 로 repo 맥락을 파악한다.
  2. 단일 vs 분할 판단 — 기본은 단일이다. 아래 조건이 실제로 걸릴 때만 나눈다.
  3. 출력 작성 — 서술을 명령형으로 바꾸고 모호/유예 표현을 제거해 정해진 템플릿 구조로 쓴다.
  4. AGENTS.md 동기화 — 없으면 @CLAUDE.md 한 줄로 생성, 이미 있으면 그대로, 있는데 그 줄이 없으면 최소 침습적으로 추가한다.
  5. 보고 — 생성 문서 경로, 단일/분할 여부, AGENTS.md 처리 결과.

분할 조건

기본값은 분할하지 않는 것이다. 다음 중 하나가 실제로 성립할 때만 나눈다.

  • 범위가 서로 다른 책임 도메인에 걸쳐 있어(backend/frontend/shared, infra/UX, 단계별 구현 슬라이스) Codex 가 한 번에 무관한 파일을 너무 많이 만져야 하는 경우
  • phase 가 검증되지 않은 외부 인터페이스에 의존하는 경우

나눌 때는 기계적으로 균등 분할하지 않고 구현 경계를 따른다. 좋은 축은 backend / frontend / shared, transport / state / UI, infrastructure / integration / UX refinement, 확정된 구현 먼저 / 불확실한 통합 나중. 불필요한 파편화를 피하고 최소 개수를 쓴다.

품질 기준

  • 생성된 문서만으로 Codex 가 실행 가능할 것
  • 구현 범위와 파일 목록이 모호하지 않을 것
  • 원본의 Claude 작성 의도에 충실할 것

주의사항 / 제약

  • 원본 phase 문서를 수정하지 않는다.
  • CLAUDE.md 를 다시 쓰지 않는다. SSOT 는 CLAUDE.md 이고 AGENTS.md 는 Codex 를 위한 얇은 다리 역할만 한다.
  • AGENTS.md 에 Codex 정책 문구를 임의로 덧붙이지 않는다. 사용자가 명시적으로 요청할 때만 추가한다.
  • AGENTS.md 가 이미 구조화된 파일이어서 @CLAUDE.md 를 맨 위에 넣으면 깨지는 경우에는, 가장 덜 침습적인 위치에 넣고 기존 내용을 보존한다.
  • 출력 디렉터리는 docs/ai/phases/codex/ 고정이다.