OpenSpecのOpsXワークフローを調べる

AIへ実装を依頼すると、会話の勢いでコードを書き始めやすいです。

OpenSpecを調べた目的は、実装前の判断をファイルへ外部化し、後から仕様と実装を照合できるようにすることです。

現行資料では、OpsXの標準表記として/opsx:*を使います。

ただし、実際の呼び出し名は利用するAIツールの統合によって変わります。

コマンドやSkillは、導入時に生成されたものと、インストール済みバージョンのドキュメントを正とします。

成果物の流れを先に確認する

段階	標準表記	主な成果物
Explore	`/opsx:explore`	問題、制約、選択肢の整理
Propose	`/opsx:propose <change>`	proposal、specs、design、tasks
Apply	`/opsx:apply`	タスクに対応するコード変更
Archive	`/opsx:archive`	完了した変更と仕様の統合

現行のOpenSpec Getting StartedとCommandsを読むと、実装は成果物を作る工程の一部だと分かります。

Exploreは、Exploreの説明によると、考えを整理するための対話であり、必ずしもコードや成果物を作りません。

変更の曖昧さが小さければ省略できます。

1. exploreで問題の境界を調べる

探索では、解決策を先に決めません。

次の問いへ答えます。

現在の問題は何か
誰に影響するか
変えてはいけない挙動は何か
関係する既存実装はどこか
選択肢の利点と欠点は何か
未確認の前提は何か

ここで残した未確認事項が、次の調査と受け入れ条件の入力になります。

調査で問題設定が変わったら、最初の結論に合わせて実装を進めず、前提を更新します。

2. proposeでレビュー可能な差分を作る

/opsx:proposeでは、提案、仕様差分、設計、実装タスクをまとめます。

レビュー前に確認する項目は次です。

目的と非目的が分かれているか
正常系だけでなく失敗時の挙動が書かれているか
互換性と移行条件が定義されているか
受け入れ条件を検証できるか
タスクが仕様項目へ対応しているか

この確認をapplyより前に行うと、実装後に説明を合わせる作業を減らせます。

proposalやdesignへ、コードへ書けない判断理由と却下した案も残します。

3. applyをタスクと検証の単位で進める

/opsx:applyでは、合意済みのタスクを1つずつ実装して検証します。

タスクの完了条件は、コードが書けたことではありません。

テスト、型検査、lint、build、必要なドキュメント更新までを含めます。

実装中に前提が崩れた場合は、タスクを無理に消化せず、proposal、spec、designの内容を更新します。

現行ワークフローに更新用のコマンドやSkillがある場合は、生成された名前を確認して使います。

AI sessionを切り替えても、成果物がリポジトリへ残っていれば再開しやすいです。

会話履歴よりファイルを正本にします。

4. archiveで仕様へ戻す

/opsx:archiveは、完了した変更を保管し、必要な仕様差分を本体へ統合する工程です。

コードだけをマージしてproposalを放置すると、次の作業で過去の判断を再発見できません。

アーカイブ前に次を確認します。

すべてのタスクが完了または明示的に延期されている
受け入れ条件を満たす検証結果がある
実装と仕様の差が解消されている
破壊的変更と運用手順が文書化されている
不要な中間成果物の扱いを決めている

「完了」はコードの存在ではなく、仕様、実装、検証、保管が揃った状態とします。

小さな変更へ無理に適用しない

すべての変更へ同じ量の成果物を要求すると、文書作成が目的になります。

最初は、複数ファイルへまたがる変更、仕様の解釈が分かれやすい変更、移行を伴う変更へ適用します。

小さなバグ修正では、目的、受け入れ条件、タスクだけで十分な場合があります。

OpenSpecのOverviewとFAQを基準資料にします。

コマンド名、プロファイル、成果物の配置は、導入したバージョンとAIツールへ合わせて固定します。