ワークフロー

基本ワークフロー

標準的な機能開発では、各成果物を出典と結び付け、次の流れで進めます。

/specify          → requirements.md
/generate-spec    → spec.md       → review-spec
/spec-to-design   → design.md     → review-design
/design-to-plan   → plan.md       → review-plan
/plan-to-tasks    → tasks.md      → review-tasks → analyze
/implement-tasks  → implementation and complete-feature code review

以下の例は、Claude の /codexspec: プレフィックスを使っています。 Codex では、コマンド名と引数はそのままに、$codexspec: を使ってください。

ステップ	コマンド	目的と出力
プロジェクト原則	/codexspec:constitution	constitution.md を作成・更新し、影響を受ける成果物を検証
要件	/codexspec:specify <idea>	意図を話し合い、最終サマリーを確認して requirements.md に保存
仕様書	/codexspec:generate-spec <feature-dir>	確認済み要件をもとに、出典参照付きの spec.md を作成
システム設計	/codexspec:spec-to-design <feature-dir>	コンポーネント、インターフェース、主要な設計判断を記した design.md を作成
実装計画	/codexspec:design-to-plan <feature-dir>	フェーズ、実行順序、検証方法を記した plan.md を作成
タスク	/codexspec:plan-to-tasks <feature-dir>	追跡・検証可能な tasks.md を作成し、成果物間の分析を実行
実装	/codexspec:implement-tasks <feature-dir>	タスクを実行し、結果を検証して、独立した検証を経たレビュー指摘を修正

<feature-dir> は、要件の検討時に返された機能ディレクトリに置き換えてください。 その worktree で作業を続けるか、明示的なパスを渡すことで、コマンドやセッションが変わっても同じ機能として扱われます。

specify、clarify、analyze

• specify は要件の検討を開始、または再開します。要件サマリーが正式な判断基準になるのは、明示的な確認を得た場合だけです。
• clarify は既存の要件や仕様の曖昧さを解消します。1 回の実行で 4 つのカテゴリにわたり、最大 5 つの質問をします。 まず requirements.md を更新し、その後 spec.md を同期します。
• analyze は要件 → 仕様 → 設計 → 計画 → タスクの流れ全体を確認します。 上位の判断基準から修正内容が一意に決まる場合は、下位成果物を自動で修正します。requirements.md は一切編集しません。 未解決の指摘は報告します。タスクレビューの合格後に自動実行されますが、情報提供を目的としており、実装の合否は判定しません。

/codexspec:clarify <feature-dir>
/codexspec:analyze <feature-dir>

Quick による小さな変更

局所的な修正など、範囲が明確で小さな変更には quick を使います。

/codexspec:quick Fix the empty-state message on the task list

Quick は簡潔な要件サマリーを確認して保存した後、仕様作成、計画、タスク化、実装を順に進めます。 各生成コマンドによるレビューも行います。広範な変更や、製品・設計上の選択が未解決の場合は、標準ワークフローを使ってください。 Quick は新しい判断が必要になると一時停止します。

ワークフローの自動化

workflow.auto_next のデフォルトは false です。 作業中のワークスペースの設定で true にすると、最終的な要件確認後に仕様作成へ進みます。 各生成ステージは PASS または PASS_WITH_WARNINGS で次へ進み、NEEDS_REVISION または BLOCKED で停止します。 implement-tasks が最終ステージです。

成果物の自動修正は、検証済みの欠陥のうち、上位の根拠から修正内容を導けるものに限られます。 修正とレビューは最大 2 ラウンドまで行います。助言は別に扱います。 実装のレビュー・修正ループには、後述する独自の完了条件があります。

共有ブループリントと自律開発

開発前に複数の確認済み要件を準備するには blueprint、そのキューを開発するには auto-dev を使います。

/codexspec:blueprint Add a confirmed requirement for task reminders
/codexspec:auto-dev

ブループリントの要件検討では、ユーザーが決めるべき方向性、選択、制約を解決してから要件をキューに入れます。 共有の .codexspec/blueprint.md では、pending、in_progress、completed の状態を使います。 保留中の要件は追加、置換、削除、並べ替えができます。進行中と完了済みの項目は、ブループリントの管理操作では読み取り専用です。

Auto-dev はドキュメントに記載された順に開発し、進行中の機能があれば、別の機能を始める前に再開します。 機能が完了するたびにキューを読み直すため、新たに追加された保留中の作業もその実行で処理できます。 確認済み要件の範囲内で SDD の各ステージ、実装、検証、レビュー、修正を行います。 auto-dev を呼び出すと、workflow.auto_next の値にかかわらず自動化が有効になります。この設定自体は変更しません。

両コマンドは、ブランチ codexspec/auto-dev の worktree-for-codexspec-auto-dev を共有します。 共通の所有権管理と書き込み保護のもとで同時に操作できますが、要件の開発はそのワークスペースで順次行います。 確認済み要件から決められない製品上の判断が必要になると、通常の自律実行中には質問せず、根拠を示して停止します。

現在の共有ブループリントを変更せずに確認するには、次を実行します。

codexspec show-blueprint

worktree での開発

Git worktree は、同じリポジトリの別の作業ディレクトリで、それぞれにブランチをチェックアウトできます。 CodexSpec はデフォルトで通常の機能ごとに 1 つ作成します。作成は最初の要件を書き込む前に行い、 その機能のドキュメント、実装、テスト、修正を同じ場所にまとめます。

projects/
├── my-project/
└── my-project-codexspec-worktrees/
    ├── <feature-id>-task-reminders/
    ├── <feature-id>-search/
    ├── worktree-for-codexspec-maintenance/
    └── worktree-for-codexspec-auto-dev/

機能の作業を再開するときは、同じワークスペースを再利用します。 独立した設定、プロジェクト憲法、プロファイルの変更には保守用 worktree を使い、開発中の機能における変更はそのワークスペース内で行います。 設定はチェックアウトごとに適用されます。作業先となる worktree で変更した設定は、まずその場所で有効になり、 Git での統合を通じて他のチェックアウトに反映されます。CLI コマンドとチェックは、返されたワークスペースで実行してください。

新機能の開発開始時には、コミット済みのローカル main ブランチの履歴と、fetch したリモート main ブランチの履歴を Git の祖先関係で比較し、基準を決めます。 履歴が分岐している場合は、新しい worktree 内でマージして検証する必要があります。 fetch に失敗した場合は警告を出し、ローカルにある参照での続行を認めます。 worktree の作成に失敗しても、main チェックアウトへの書き込みには切り替えません。

workflow.worktrees のデフォルトは true です。通常の機能と保守作業の分離を無効にするのは、YAML のリテラル false だけです。 この設定にかかわらず、blueprint/auto-dev は固定の共有 worktree を使います。 初期化とインストールの更新は、明示的に選択したチェックアウトで行います。 完了した worktree は保持され、完了時に自動でマージや削除は行われません。

worktree での開発と設定を参照してください。

既存コードでの作業

既存コードに対しては、目的に応じて 2 つのコマンドを使い分けます。

コマンド	用途	出力と操作範囲
onboard [path]	既存のコードベースから再利用可能なプロジェクト知識を初期登録	慣行の候補と、根拠に基づいて範囲を絞った制約をプロファイルに記録。コードは読み取り専用
reverse-spec [path]	既存アーキテクチャの理解、または確認済みの意図とコードの比較	成果物の草案または差異レポート。コードは読み取り専用

/codexspec:onboard src/
/codexspec:reverse-spec
/codexspec:reverse-spec src/auth

Onboard は観察できるコードから慣行を推論し、明示的な禁止事項がある場合にだけ制約を提案します。 慣行の候補はローカルで直ちに有効になります。制約の候補は、セッション内で保存・編集・破棄を決める必要があります。 既存の知識は保持します。初回のコードスキャンをもとに、過去の判断理由や、実際に経験したかどうか分からない落とし穴を作り出すことはありません。

Reverse-spec には 3 つのモードがあります。

• 概要：パス未指定、またはリポジトリルートを指定した場合。調査するモジュールを選ぶために、アーキテクチャの要点を記した design.md と slices.md を作成します。
• 生成：確認済みの基準がないモジュールパスを指定した場合。spec.md、design.md、未確定・推論段階の要件を草案として作成します。
• 照合：確認済みの基準があるモジュールを指定した場合。reconcile.md を作成し、 確認済みの仕様・設計に照らして、文書化されていない動作、未実装の仕様、意味の不一致を報告します。意図については要件を判断基準にします。

推論から作成された草案は、人による確認を経て初めて基準として使えます。 照合では、コードの修正、ドキュメントの更新、意図の判断のいずれを進めるべきかを提案しますが、自動では適用しません。

レビューとデバッグ

4 つの成果物レビュアー review-spec、review-design、review-plan、review-tasks は、忠実度、網羅性、実現可能性、内部品質を確認します。 生成後に自動実行され、手動でも呼び出せます。レポートでは、検証済みの欠陥と、合否に影響しないリスクの助言や設計上の改善案を分けて報告し、適合度スコアも示します。

review-code は、選択した変更を対象とする独立した欠陥ゲートと、コード全体の明示的な品質評価を提供します。

/codexspec:review-code --feature <feature-dir>
/codexspec:review-code --uncommitted
/codexspec:review-code --audit src/

デフォルトでは機能ブランチの差分全体をレビューします。コミット済み、ステージ済み、未ステージ、Git の無視対象でない未追跡の変更がすべて含まれます。 コミット済み、未コミット、単一コミットのいずれかを明示的に選ぶこともできます。 --feature は要件の文脈を追加しますが、Git の対象範囲は狭めません。 --audit は指定されたパスを評価し、完了判定ではなく、助言としての評価表を作成します。

レビューでは .codexspec/review-code/ から共通基準を読み込み、関連する動作の観点や、言語・フレームワークごとのチェックを選びます。 指摘には、具体的な根拠、実際に発生し得る条件、選択した変更に起因すること、影響の説明が必要です。 レビュアーはファイルを編集せず、欠陥と根拠のある保守提案を報告します。修正を行う呼び出し元は、それらを独立して検証します。

実装では、コードのタスクはテストを先に書いて進め、ドキュメントや設定は直接変更して適切なチェックを行います。 修正後の差分レビューでは、影響を受けていない範囲の確認結果を再利用できます。 最終的な受け入れには、新たに行う機能全体のレビューで PASS を得ること、対象範囲の確認と検証が完了すること、 認定された P0–P3 の欠陥が 1 件も残っていないことが必要です。根拠のある保守提案は別に報告します。

workflow.auto_maintenance のデフォルトは true です。 修正を行う呼び出し元が、検証済みで互換性を保つ保守改善も適用するかを、この設定で制御します。 無効にしても提案は報告され、欠陥の修正や必須チェックは免除されません。 ステージの自動進行とは独立した設定で、implement-tasks の引数ではありません。

根本原因を先に調べるデバッグには、次のコマンドを使います。

/codexspec:debug Investigate intermittent failures when saving a task

Debug は、調査 → パターン分析 → 単一仮説の検証 → 失敗するテストを先に書いて修正、の順に進みます。 実装中の修正が行き詰まった場合、単純ではない動作上の欠陥について原因を追う必要がある場合、 同じ種類の根本原因がレビューの複数ラウンドで再発した場合に、この手順へ移ります。 修正が 3 回失敗したら、アーキテクチャを再検討します。

要件の明確さ、完全性、一貫性を評価するには、checklist を使います。

/codexspec:checklist Check the authentication requirements for completeness

レビュー対象の選び方、引数、詳しい手順は、コマンドリファレンスを参照してください。

プロジェクト知識

プロジェクトプロファイルには、再利用できる知識を .codexspec/profile/ に保存します。

カテゴリ	内容
constraints/	明示的な禁止事項と厳守すべき境界。最初に読む
conventions/	パターン、命名、機能をまたぐ指針
pitfalls/	実際に経験した落とし穴、その原因、回避策、教訓
decisions/	再利用可能なアーキテクチャ上の判断や、機能をまたぐ判断
strategies/	作業方法を変えるべき兆候
runbooks/	順序に沿った作業手順と、失敗時の復旧方法

distill は作業から再利用可能な知識を抽出します。機能固有の意図は、その機能の要件・設計・計画に残します。 初期化時に CLAUDE.md または AGENTS.md、あるいは両方へガイダンスを追加し、本格的な作業の前にすべての制約と関連知識を読むよう指示します。 後から追加した知識も、再初期化せずに有効になります。候補の記録は慎重に扱い、承認済みの記録には、結果の検証と人による承認が必要です。

/codexspec:distill Capture the reusable lessons from this work
/codexspec:distill review
/codexspec:evolve

手動の distill review、または新たに抽出する内容がない状態で直接呼び出した distill は、ローカルで動作するオフラインのブラウザーワークスペースを開きます。 記録を修正、承認、破棄、保留、統合し、最終的な Markdown をプレビューしてから すべて適用を選択できます。 適用するまでは、判断が復旧可能な草案として保存されます。競合チェックにより、一部だけの適用や、通知なしの上書きを防ぎます。 ブラウザーを使えない環境では、明示的にテキスト方式へ切り替えることもできます。

workflow.auto_distill のデフォルトは true で、3 つの完了時フックを制御します。 implement-tasks の成功時、commit-staged でコミットを実行したとき、pr の生成時です。 コミットのプレビューでは知識を抽出しません。

インストールされたプロジェクトガイダンスは、通常の会話、SDD 外の修正、長時間の implement-tasks 実行中にも、 再利用できる知識が得られた時点で記録するようエージェントに求めます。 この指示は完了時の設定とは独立して適用されます。タスク終了時の抽出は、取りこぼしを防ぐ最後の機会です。

同じセッションで繰り返し呼び出された場合は、新しい内容だけを処理します。 セッションが変わった場合は、distill がプロファイルを読み、すでに記録されている知識を省きます。 再利用できる内容が残っていなければ、書き込まずに終了します。 自動抽出では、手動レビューを開いたり、人の応答を待ったり、呼び出し元のワークフローを止めたりすることはありません。

evolve は、承認済み知識のうちプロジェクト外でも役立つものだけを選び、コマンド・スキルの草案を作成します。 push や、人によるレビューを受けるための貢献 PR の作成前に、明示的な承認を得ます。

詳しい手順は、プロジェクト知識を参照してください。

過去の判断の再利用

変更についてユーザーに質問する前に、エージェントは .codexspec/specs/ にある関連機能の開発履歴を確認します。 requirements.md に記録された確認済みの判断を読み、後から追加された内容や明示的に置き換えられた判断をたどります。 必要に応じて、設計の理由や実装の裏付けも確認します。こうした準備は、設計、実装、デバッグ、レビューについて本格的に判断する前にも必要です。通常の会話と SDD ワークフローの両方に適用されます。

機能ディレクトリのタイムスタンプは、開発の経緯を時系列で整理するために使います。新しい文書があるだけで、過去の判断が無効になるわけではありません。 以前に確認され、変更されていない要件は引き続き適用されます。未確定の提案を確認済みの意図として扱うこともありません。 調査は現在のタスクに関連する範囲に絞り、判断に十分な背景情報がそろった時点で止めます。その情報は後続のステージでも再利用します。

たとえば、インターフェースを変更する際、過去の経緯を確認していなければ、次のような質問になりがちです。

「この機能では、後方互換性をどのように扱いますか？」

関連する判断と現在の実装を確認すれば、質問を具体的な選択に絞れます。

「以前、旧インターフェースを残すと確認されており、現在の実装でもサポートされています。今回も維持する方針を提案しますが、いかがでしょうか？」

確定済みの情報が現在も明らかに適用できる場合は、同じことを聞き直さずに再利用します。 ユーザーがすでに「今回は旧インターフェースを削除する」と明言していれば、その判断に従って進め、移行への影響を説明します。 ユーザーが最後に明示した判断が常に優先されます。 過去の履歴は、質問をより的確にし、同じ質問を繰り返さないために使います。

このガイダンスを受け取るには、既存プロジェクトのインストールを更新してください。

Git ワークフロー

/codexspec:commit-staged -p
/codexspec:pr --spec <feature-dir>/spec.md
/codexspec:release-notes --from <ref> --to HEAD
/codexspec:tasks-to-issues <feature-dir>

• commit-staged はステージング領域の内容そのものを分析し、Conventional Commits のメッセージを生成します。 -p では、コミットせずにプレビューできます。ファイルの選択とステージングは、呼び出し元のワークフローが行います。 許可を得て実行する場合は、保護された実行環境で、コミットする内容が分析対象と一致することを再確認します。 エージェントのコミットガイダンスは通常の会話、SDD、blueprint、auto-dev にも適用されます。 コマンドが利用可能であるだけでは、その呼び出しにも、コミットの許可にもなりません。
• pr は差分をもとに、構造化された GitHub PR または GitLab MR の説明を生成します。 --spec を指定すると、spec.md のファイルパス、またはそのファイルを指す機能ディレクトリ名やプレフィックスから、機能の文脈を追加できます。 デフォルトでは、ホスティングプラットフォームで使うためのテキストを出力します。
• release-notes は Git 履歴から、Keep a Changelog のエントリとリリース本文を作成します。 デフォルトのセクションは [Unreleased] で、--version を指定すると、そのラベルを使います。 ステージング、コミット、バージョン更新、タグ付け、公開、リリース作成は行いません。
• tasks-to-issues は既存のタスクから、依存関係と受け入れ基準を含む GitHub Issue を作成します。 認証済みの GitHub CLI が必要です。Issue のリポジトリが、設定済みのリモートと一致することも検証します。

コミットのプレビューと、許可を得て現在のチェックアウトで行うコミットには、Python 3.11+ と Git が必要です。 実行環境は CLI で初期化したプロジェクトにインストールされ、Claude プラグインにも同梱されます。 エージェントが作成する、内容の変更を伴うマージでも、ステージ済み内容の分析を行います。 履歴だけをつなぐマージでは、ツリーと親を検証しながら Git のデフォルトメッセージを維持します。 fast-forward はコミットを作成しません。

追跡可能性と作業の再開

確認済みの requirements.md が機能の意図を定め、下流は spec.md → design.md → plan.md → tasks.md の順に続きます。適用されるプロジェクト原則と検証済みのリポジトリの事実も併せて判断します。要件は安定した ID を持ち、仕様の項目は Sources、下流の作業は Covers で対応関係を示します。下流の成果物が上流の判断を黙って変更することはできません。判断根拠の衝突や新たなプロダクト判断はユーザーが解決します。過去の要件記録がない場合は元の確認を検証できないことを明示し、設計成果物がない場合は文書化された代替経路を使います。

対象が曖昧な場合は機能のパスを明示してください。コマンドが最新ディレクトリを勝手に選ぶことはありません。worktree の親ディレクトリは主リポジトリを基準に決まり、サブディレクトリや別のリンク済み worktree から呼んでも同じです。ベアリポジトリでは隣接する <bare-repository-name>-codexspec-worktrees を使います。独立した保守作業には codexspec/maintenance ブランチを使います。

worktree の準備に失敗しても、その識別情報は再開のために保持されます。分岐した基準履歴のマージは、プロジェクトの検査に合格してから機能要件の書き込みや開発へ進みます。読み取り専用の調査は元の入力を維持し、レポートは解決済みの出力先チェックアウトに書き込みます。コミット実行は選択されたインデックスを維持し、main のステージ済み変更を他の worktree に移しません。新しい worktree に必要なインストール済みリソースがなければ、先にその出力先を初期化します。

レビューモデル

レビューは 3 種類の出力を区別します。

• 忠実性の欠陥: 権威あるソースとの競合、あるいは必要なカバレッジの欠落。
• 内在的欠陥: 成果物が内部的に矛盾している、検証不可能、実行不可能である。
• リスク助言・設計の機会: 現状の欠陥の証拠を伴わない、任意の改善。

各欠陥は、エビデンス・場所・不一致・影響・最小限の remediation を明示しなければなりません。同じ根本原因を持つ指摘はマージされます。助言はステータス・スコア・自動修正に影響しません。

レビューステータスは次のとおりです。

• PASS: critical・warning・minor のいずれの欠陥もない。
• PASS_WITH_WARNINGS: minor の欠陥のみ残っている。
• NEEDS_REVISION: 1 件以上の warning が残っている。
• BLOCKED: critical な競合があり、確実に続行できない。

互換性スコアは、固定のテンプレートセクションの減点方式ではなく、同じ分類済み指摘から導出されます。ステータスが権威であり、スコアは数値を期待する統合のために存在します。

限定された自動レビュー

生成コマンドは対応するレビューを自動実行します。これは 証拠に基づくレビュー の規律そのものであり、証拠に裏打ちされた欠陥のみを修復し、最大 2 ラウンドまで再レビューします。PASS になれば早期終了し、以下の場合にはユーザーの入力を求めて停止します。

• 権威あるソースが別のソースと競合する
• 修正が確認された意図を変えることになる
• 残っている項目が欠陥ではなく助言である
• 2 ラウンドの修復を使い切った

/codexspec:review-* コマンドは、いつでも手動で実行して新鮮なレポートを得られます。