j-token/codex-workflow

사용자가 기술 스펙의 독립 감사를 명시적으로 요청했거나, 보안·데이터·호환성·배포처럼 실패 비용이 큰 계획에서 독립 검토가 실질적으로 필요한 경우 사용합니다. 승인된 기술 스펙을 저장소와 공식 자료에 대조해 사실 불일치와 구현 블로커를 찾습니다. 일반 저위험 작업의 필수 게이트로 사용하지 않습니다.

Git 브랜치를 생성하거나 분기하거나 이름을 정하기 전에 적용합니다. 사용자가 브랜치 생성, 분기 또는 이름 결정을 요청할 때 의미가 분명한 접두사 규칙을 제공합니다.

사용자가 버그, 불명확한 증상, 스크린샷, 로그 또는 재현 정보를 주고 진단이나 수정을 요청할 때 사용합니다. 사실과 추정을 분리해 재현·원인을 먼저 조사하고, 요청 증상과 직접 관련된 원인 및 필수 변경 범위를 제시해 별도 승인받은 뒤 수정·검증합니다. 조사 중 발견한 별도 버그, 독립 리팩터링과 새 동작은 별도 범위로 분리합니다.

독자의 인지 부하를 최소화하도록 글을 구조화하는 공통 규칙입니다. 인지부하론(내재적/외재적/본유적 부하, 작업기억 보호) 4원칙, GitHub-flavored Markdown 작성 규칙, Codex Desktop의 Mermaid와 Codex CLI의 코드 블록 ASCII 다이어그램 규칙, 공통 자가 점검 체크리스트를 제공합니다. PR·plan·기획서·기술 문서·이슈 코멘트 등 "타인이 읽고 판단해야 할 모든 글"에 적용합니다. 사용자가 "글 정리해줘", "문서 다듬어줘", "리뷰어 부담 줄여줘", "마크다운 양식 점검", "인지 부하 줄여서 작성" 같은 요청을 하거나, pr-rule·plan-rule 같은 파생 스킬이 공통 원칙을 참조할 때 사용합니다.

사용자가 현재 요청에서 Git 커밋 생성을 명시적으로 요청했을 때 적용합니다. 모든 커밋마다 명시적 허락을 요구하고 작업별 커밋과 메시지 규칙을 제공합니다.

사용자가 Figma 링크, 스크린샷, 시각 자료를 제공하거나 UI/화면 구현을 요청할 때 사용합니다. 시각 자료와 기존 앱을 조사해 화면 역할·전이·에셋을 파악하고 단일 UI 스펙/구현 문서를 제시한 뒤, 별도 사용자 메시지에서 구현 승인을 받으면 새 Codex 작업으로 인계합니다.

의도하지 않은 브랜치나 보호 브랜치에 push하는 사고를 막기 위한 안전 워크플로우입니다. Codex가 git push 실행, 준비, 검토, 설명, force push, upstream 설정, 브랜치 게시, PR 준비를 요청받았을 때 사용합니다. 사용자가 매번 명시적으로 push를 요청하거나 승인하지 않으면 push는 금지됩니다.

모든 사용자 명령에서 실질적인 작업보다 먼저 사용자의 실제 의도를 판별하고, 불명확한 부분을 조사할지 가정할지 질문할지 의식적으로 결정합니다. 짧거나 추상적이거나 여러 해석이 가능한 요청, 범위가 크거나 되돌리기 어려운 작업에서는 특히 엄격히 적용합니다. 명확한 한 줄 변경도 이 라우팅 자체는 생략하지 않습니다.

사용자에게 작업 결과, 지식, 개념, 기술, 수치 또는 판단 근거를 설명할 때 적용합니다. 개념 설명에서는 청자가 아는 기준점에서 출발해 차이와 문제를 세우고, 한 단계 질문과 상태 변화를 따라 핵심 메커니즘에 도달한 뒤 필요성과 행동으로 되돌아옵니다. 작업 결과 보고에서는 결과, 변경, 증거와 남은 범위만 간결하게 전달합니다.

현재 작업 안에서 서로 독립적인 조사·구현·검토를 병렬화할 실질적 이점이 있거나 사용자가 하위 에이전트를 명시적으로 요청했을 때 사용합니다. 역할, 최소 컨텍스트, 파일 소유권과 결과 검증을 조율합니다. 간단한 수정과 일반 작업에 하위 에이전트나 독립 리뷰를 필수 게이트로 강제하지 않습니다.

사용자가 pull request 생성을 명시적으로 요청했을 때 적용합니다. draft PR을 만들고 대상 브랜치를 사용자에게 확인하며 제목과 본문 양식을 강제합니다.

사용자가 PRD, 제품 요구사항 문서, 기술 제품 기획서 또는 제품·기능 구현을 요청했을 때 작성하거나 다듬습니다. 요구사항 조사 결과를 제품 범위와 수용 기준으로 정리해 제시하고, 별도 사용자 메시지에서 기술 스펙 작성 승인을 기다립니다.

디자인이나 흐름이 확정되기 전에 가벼운 시각적 웹 프로토타입을 만들고 반복합니다. 사용자가 아이디어, 거친 제품 요청, 불명확한 화면 흐름을 제시하거나 앱 내 브라우저에서 클릭 가능한 콘셉트를 보고 싶어 할 때 사용합니다. .codex/temp/prototype 아래에 날짜별 작업 공간을 만들고 Mermaid 설계 문서, HTML/CSS/JS 소스, Python 정적 서버와 의미 있는 각 페이지 또는 상태의 스크린샷을 작성합니다. Figma를 사용하거나 확정된 디자인을 요구하지 않습니다.

사용자가 거친 요구사항, 배경, 불확실한 질문을 가져오거나 제품·기능 문서 작성을 요청할 때 사용합니다. 저장소와 필요한 외부 사실을 조사한 뒤 PRD를 먼저 제시하고, 별도 사용자 메시지의 승인 후 기술 스펙을 작성하며, 다시 별도 승인 후 구현 작업으로 인계합니다.

연구 가설, 모델·전략·알고리즘 비교, benchmark, ablation, feasibility test, 학습 실험, 평가 계획과 실험 결과 문서화를 요청했을 때 사용합니다. 저장소와 기존 실험 근거를 조사해 검증 가능한 사전등록 계획을 작성하고, 별도 승인 후 실행 단위로 인계하며, 완료된 산출물에서 결과와 재사용 교훈을 기록합니다. 제품 PRD·기술 스펙 작성이나 일반 버그 수정에는 사용하지 않습니다.

Codex 워크플로우로 작성한 기술 스펙 또는 UI 구현 문서를 제시한 뒤, 사용자가 별도 메시지에서 해당 문서의 구현 시작을 승인했을 때 사용합니다. 승인된 문서를 다시 읽고 모델과 추론 강도를 확인한 뒤 새 Codex 작업으로 구현을 넘깁니다. 관련 버그를 현재 작업에서 바로 수정하는 흐름에는 사용하지 않습니다.

사용자가 기술 스펙, 구현 스펙, 아키텍처 스펙 또는 IPC/API/SDK/CLI/FFI/JNI/native shell/런타임/빌드/테스트 계약 문서를 요청했을 때 작성하거나 다듬습니다. 제품·기능 워크플로우에서는 별도 메시지로 승인된 PRD를 입력으로 기술 스펙을 작성하고, 문서를 제시한 뒤 별도 구현 승인을 기다립니다.

요구사항 발견, 연구·실험, 디버깅, UI/Figma 구현이 한 요청에 섞여 있을 때 사용합니다. 단일 분류를 강제하지 않고 모듈을 조합하되, 제품·기능은 PRD·기술 스펙 승인 흐름으로, 연구 가설은 별도 사전등록 실험 흐름으로 보내며, 버그는 요청 증상과 직접 관련된 변경 범위를 별도 승인받은 뒤 수정합니다.