spec-implement

仕様の実装

承認済みの仕様に基づく計画を実行します。タスクが追跡対象になっている場合は進捗を記録します。報告します。行き詰まった場合は停止します。

開始時に宣言してください：「仕様実装スキルを使って、この計画を実行します。」

このスキルでは、設計上の決定や承認済みの内容の変更は行いません。Plan Mode で必要な成果物を書き込めなかった場合は、会話で承認された内容を保存できます。計画に誤りがある場合は spec-plan に戻ってください。設計に誤りがある場合は spec-brainstorm に戻ってください。

前提条件

製品の実装を開始する前に、必要な成果物を次の順序で用意します。

1. docs/specs/YYYY-MM-DD-<feature>/design.md が存在しない場合は、現在の会話で承認された設計をもとに作成します。ファイルを検証し、そのパスを報告して停止します。同じ実行で plan.json を作成したり、実装を開始したりしないでください。
2. それ以外の場合、docs/specs/YYYY-MM-DD-<feature>/plan.json が存在しない場合は、現在の会話で承認された計画をもとに作成します。spec-plan のスキーマに照らして検証し、そのパスを報告して停止します。同じ実行で実装を開始しないでください。
3. 次に作成する成果物に必要な承認済みの内容が現在の会話で確認できない場合は、停止して、どの内容が不足しているかを人間に伝えます。ファイルを作成するよう人間に依頼しないでください。
4. 両方の成果物が存在する場合は、計画時に選択したトラッカーの項目が利用可能であることを確認します。トラッキングが設定されている場合は、docs/agents/issue-tracker.md も確認します。
5. 明示的なユーザーの同意がない限り、main/master ブランチにいないことを確認します。まずブランチを作成するか、git worktree を使用してください。

各実行で作成できる未作成の成果物は最大 1 つです。両方の承認済み成果物が実行開始時点で存在している場合に限り、製品の実装に進んでください。

---

ステップ 1：計画の読み込みと確認

コードを書き始める前に plan.json を批判的に確認してください。次の点を調べます。

• 不明瞭または曖昧なタスク
• ファイルパスの欠落、または不完全な検証基準
• タスク間の競合
• コードベースの状況と一致しない依存関係
• 計画された機能をすでに満たしている既存のコードやプラットフォームの動作
• 重複する ID、パーサー、エラー、スキーマ、ライフサイクル処理、テストユーティリティ
• 現在の利用箇所が 2 つ未満の共通抽象化
• 新しいラッパーの検証だけを目的とするテスト

計画された仕組みがこれらの確認に通らない場合は、実装を始める前に停止し、より小さな修正案を人間に確認してもらうため spec-plan に戻ってください。承認済みの動作と範囲を維持し、裏付けのない構造を無理に実装しないでください。

その他の懸念事項については、開始前に人間に伝えてください。推測しないでください。決めつけないでください。阻害要因がある場合は無理に進めないでください。

懸念がなければ進めます。既存のトラッカー項目がある場合はそれを使用してください。

---

ステップ 2：実行形式の選択

人間が実行形式を指定していない場合は、確認してください。

自律モード

「すべて実装してください。完了するまで停止しないでください。」

• 依存関係の順序に従ってすべてのタスクを実行します
• 仕様に基づく計画にトラッカー項目がある場合は進捗を記録します
• 型チェックと lint を継続的に実行します
• 阻害要因がある場合に限り停止します
• 無人でドラフト PR まで実行するには、spec-loop を使用してください

バッチモード（デフォルト）

「いくつかのタスクをまとめて実行してください。」

• 3～5 個のタスクを実行します
• 実施内容、テスト結果、予期しない事項を報告して停止します
• 続行する前に人間からのフィードバックを待ちます

委任（すべてのモード）

どのモードでも、設計がすでに確定しており、ファイルを作成するだけの状態で、「code-subagents」の「使用するタイミング」の基準を満たすタスクは、新しいサブエージェントに委任します。

• 適格性、ディスパッチのパターン、実装担当者用テンプレートについては、code-subagents を呼び出します
• サブエージェントが設計判断を行わずに済むよう、関連する設計の抜粋をディスパッチに貼り付けます
• エージェントは明示的に選択します（atelier-orchestrator の「委任」を参照）
• 相互に関連するタスク、探索的なタスク、設計に慎重な判断が必要なタスクは、メインスレッドで進めます
• メインエージェントは、各バッチの完了後に統合した計画とコード品質をレビューし、検証コマンドも実行します

サブエージェントモード

「サブエージェントを使用してください。」

委任可能なタスクはすべて委任します。独立したタスクは並行してディスパッチし、依存関係のあるタスクは順番に実行します。

人間から希望が示されていない場合は、バッチ処理を既定とします。タスクごとの委任は引き続き適用されます。

---

ステップ 3：計画を実行する

承認済みの動作と範囲を維持します。計画で提案された構造は、リポジトリの根拠によって裏付けられ続ける必要がある仮説として扱います。

各タスクについて、plan.json から、依存関係が解消済みの次のタスクを直接特定します。トラッカーの項目が存在する場合は、docs/agents/issue-tracker.md を使用して実行状態を同期します。トラッカーの状態が計画の依存関係グラフに優先することはありません。

トラッカーが存在する場合は、docs/agents/issue-tracker.md に従ってタスクを進行中にします。

各タスクについて

まず、タスクの入力と説明を確認します。

動作を変更するコードタスクでは、実装を書く前に、検証基準を満たすテストを書きます。ドキュメント、設定、移行、検証のみのタスクでは、代わりにタスクに記載された検証方法を使用します。必要に応じて、インストール済みの言語固有のテストスキルを呼び出します。テストはモジュールのインターフェースで記述します（oracle-codebase-design を参照）。リファクタリングでは、同項目の危険信号を確認します。

1. Read task inputs and description
2. Write failing tests (cover validation criteria)
3. Run them — verify they fail for the RIGHT reason
4. Implement minimal code to make tests pass
5. Refactor if needed (tests stay green)

動作を変更するコードでは、テストを書く前に実装を書いてはいけません。「失敗することを確認する」手順を省略してはいけません。テストを通すために必要な範囲を超えてコードを書いてはいけません。

タスクの検証方法と受け入れ基準に照らして、タスクを検証します。

各バッチの後：検証してコミットする

タスクに対応する重点的な検証を実行し、ローカルの差分を確認して、意図しない変更や範囲外の変更がないか調べます。逸脱や予期しない問題があれば報告します。コミットする場合は code-commit を使用します。計画が承認されていても、承認のゲートは省略できません。包括的な code-review は spec-finish で実施します。

完了時

トラッカーが存在する場合は、docs/agents/issue-tracker.md に従ってタスクを完了にします。

既存コードを参照する場合

計画または人間が既存の実装を参照している場合（「ユーザーテーブルのようにする」など）は、変更を加える前に参照先のコードを確認します。参照先には、明示されていない暗黙の要件もすべて示されています。

---

ステップ 4：報告（バッチ処理モード）

各バッチの後に：

Completed: [tasks]
- [completed work]

Test output: 6 passed, 0 failed
Type check: clean

Ready for feedback.

待機します。人間から応答があるまで続行しないでください。

---

ステップ 5：フィードバックに対応する

短く簡潔な修正指示を想定します。

• 「deduplicateByTitle を実装していません。」
• 「これは管理アプリにあるべきです。移動してください。」
• 「もっと幅広く」／「まだ切れています」

本当に必要な場合を除き、詳細を尋ねないでください。

方針修正のパターン

パターン	例	対応
チェリーピック	「最初のものには X を使ってください。4つ目は無視してください。」	指示どおり項目単位で対応する
範囲の縮小	「タスク T7 はスキップしてください。」	スキップとしてマークし、先に進む
インターフェースの維持	「これらのシグネチャは変更してはいけません。」	呼び出し元を調整する
上書き	「ライブラリ組み込みのメソッドを使ってください。」	直接指示に従う
差し戻し	「変更を元に戻しました。今度は X だけをしてください。」	縮小された範囲を守る

差し戻し時

人間が Git の変更を元に戻して範囲を再指定した場合は、縮小された範囲を完全に守ります。以前の方法を流用してはいけません。「本当にいいですか？」と尋ねてはいけません。

---

停止して確認を求めるタイミング

次の場合は、直ちに停止してください。

• テストが失敗し、2回試しても修正できない
• 計画に含まれていない依存関係に遭遇した
• 指示が不明確または曖昧である
• 計画と実際のコードベースが食い違っている
• 実装だけでなく、設計を変更する必要がある
• 検証が繰り返し失敗する

停止したときは、次のことを行ってください。

1. 障害となっている点を明確に説明する
2. 試したことを示す
3. どのように進めるべきか確認する

推測しないでください。回避策で済ませないでください。停止して確認を求めてください。推測するのではなく、説明を求めてください。

計画の変更が必要な場合：

"計画の見直しが必要です。spec-plan に戻りますか？"

設計に問題があった場合：

"設計上の前提が変わります。spec-brainstorm に戻りますか？"

---

前のステップを見直すタイミング

次の場合は spec-plan に戻ります。

• 重大な変更が、承認済みの動作、スコープ、アーキテクチャ、公開契約、または主要な依存関係に影響する
• こうした重大な変更なしではタスクを完了できない

軽微な逸脱は、必要に応じてその場で記録し、plan.json に反映できます。次回の進捗報告で伝えてください。

次の場合は spec-brainstorm に戻ります。

• 根本的なアプローチを再検討する必要がある
• 実装を通じて設計に問題があると判明した

---

完了

計画した作業がすべて完了したら、検証して報告してください。

検証チェックリスト

1. テストスイート全体を実行する — 新規テストだけでなく、すべてのテストに合格する必要があります
2. 型チェック／リントを実行する — 出力に問題がなく、新たな警告がないこと
3. 完了を確認する — トラッカーを使用している場合は、すべての項目を完了にする
4. 差分をレビューする — 意図したベースブランチとの差分全体を確認します。次の点に注意してください。
   • 変更すべきでないファイルが変更されていないか
   • デバッグコードや一時的な回避策が残っていないか
   • 計画した内容と実装した内容に矛盾がないか

サマリーレポート

人に次の内容を提示してください。

## Feature Complete: {feature name}

**Plan:** Spec-backed Plan
**Tasks:** {completed} / {total}
**Tests:** {new tests added}, {total passing}
**Files:** {created}, {modified}

### What was built
- [concise list of what was implemented]

### Verification
- Test suite: ✓ all passing
- Type check: ✓ clean
- Lint: ✓ clean
- Comprehensive code review: pending spec-finish

### Ready for review

次のステップ

計画した作業がすべて完了し、検証も済んだら、次のステップは spec-finish です。

"実装が完了しました。検証、レビュー、PR の準備に進みますか？"

人に次の選択肢を提示してください。

完了する — spec-finish を実行して検証、レビュー、コミットのスタック化を行う 保留する — ひとまずブランチを残し、後で再開する 破棄する — ブランチを削除して、最初からやり直す

代わりに選択しないでください。選択肢を提示して、返答を待ってください。

検証でバグが見つかった場合は、実装に戻ってください。反復のパターンについては atelier-orchestrator を参照してください。