spec-kit-implement

tasks.mdのタスクリストを、TDDとFRAMEWORK.mdの変更ワークフローに従って実行します。

入力：必要に応じて変更名を指定してください。省略された場合は、コンテキストから推測するか、確認します。

手順

1. チェックリストを確認する

   specs/changes/<name>/checklists/が存在する場合は、各チェックリストのチェック済み項目と未チェック項目を数え、表を表示します。

   | Checklist       | Total | Checked | Unchecked | Status |
   |-----------------|-------|---------|-----------|--------|
   | requirements.md | 14    | 14      | 0         | PASS   |
   | security.md     | 8     | 5       | 3         | FAIL   |
   

   requirements.mdは、spec-kit-specifyとspec-kit-clarifyが管理する仕様品質チェックリストです。その他のチェックリストはspec-kit-checklistが作成するもので、レビュアーに属します。チェックが付いている場合は、作業が完了したという意味ではなく、要件の品質基準を満たしていることを示します。 チェックリストは読み取り専用のゲートです。チェックマークを変更してはいけません。 未チェック項目がある場合は、そのまま続行してよいかユーザーに確認し、許可が得られない限り停止します。

2. 成果物を読み込む

   specs/changes/<name>/tasks.md、plan.md、spec.md、および作業時に守るべきルールを記載したFRAMEWORK.md（FRAMEWORK.local.mdと、リンクされている機能ドキュメントを含む）を読み込みます。

   tasks.mdが存在しない、または不完全な場合は、先にspec-kit-tasksスキルを使うよう促します。

3. 現在の進捗を表示する

   次の内容を表示します。

   • 変更名
   • 進捗：「N/M tasks complete」
   • 残りタスクの概要

4. フェーズごとにタスクを実行する

   未完了の各タスクを、依存関係の順に実行します。

   • 作業するタスクを告知します。
   • 作業に取りかかる前に、現在のツリーに照らして対象を解決します。タスクリストが作成時のツリーより長く使われる場合があり、ファイルが移動していたり、ルールが変更されていたりする可能性があるためです。修正が必要な場合は、完了マークを付ける際にタスクにも修正内容を記録し、次の担当者が実際に行われた作業を確認できるようにします。
   • TDDに従います。まず失敗するテストを書き、想定どおりの理由で失敗することを確認してから、合格するための最小限の実装を行い、その後リファクタリングします。
   • 変更は最小限に抑え、タスクの範囲内にとどめます。
   • レイヤーの境界を守ります。ドメイン → アプリケーション → インフラストラクチャの順とし、決して逆にしてはいけません。
   • タスクに絞ったチェックを実行します。対象の振る舞いを検証するテストと、変更したファイルに対するプロジェクトのリンター、フォーマッター、型チェックを実行します。
   • 完了したら、その時点でtasks.mdの項目を- [ ]から- [x]に変更します。
   • 各フェーズを完了して確認してから、次のフェーズに進みます。

   [P]が付いたタスクは異なるファイルに触れ、未完了のタスクに依存しないため、対応するエージェントが利用できる場合はサブエージェントで並行して実行できます。 これは許可であり、義務ではありません。ファイルを共有するタスクや、サブエージェント間で編集が競合する順序のタスクを分割してはいけません。 親エージェントは、結果を統合し、チェックボックスにチェックを付け、リストが完了するまで作業を続ける責任を負います。 並行タスクで失敗が発生した場合は、ほかのタスクを続行し、失敗を報告します。

   次の場合は一時停止します。

   • タスクが不明確な場合：実装する前に確認を求めます。
   • 実装により設計上の問題が判明した場合：spec-kit-planスキルを使ってplan.mdを更新するよう提案します。
   • テストが予期せず失敗した場合：報告して指示を待ちます。
   • ユーザーから中断があった場合。

5. ドキュメントフェーズに取り組む

   タスクリストは、変更によって事実と合わなくなる、現行の仕様、意思決定記録、またはドキュメントごとに1つのタスクを設けるドキュメントフェーズで終わります。変更によって観測可能な振る舞いが変わらない場合は、(no observable behaviour change)という注記を記載します。 ほかのタスクと同様に作業し、完了したらチェックを付けます。

   • FRAMEWORK.mdの仕様形式（WHEN/THENシナリオ、RFC 2119の用語）を使用します。
   • 現行の仕様には、実際に構築されたものを記載します。要求水準をひそかに引き下げてはいけません。 実装が変更のspec.mdに記載された要件を満たしていない場合、その不足に合わせて現行の仕様を書き換えてはいけません。 作業を完了するか、ユーザーに確認を求めてください。許容された不足については、その理由とともに変更のspec.mdに意思決定として記録し、レビュアーがその前提を踏まえて評価できるようにします。

6. 変更によって古くなったテストを確認する 変更が触れていないテストファイルでも、変更によって削除された関数、セレクター、またはリテラルを参照していることがあります。変更したファイルのテストでは、それを検出できません。 作業ツリーを変更の開始元となったコミットと比較し、変更されたソースファイルから失われた名前を列挙し、どのソースファイルにも残っていない名前を特定して、テストファイル内を検索します。 Git を使い、プロジェクトのレイアウトに合わせてテストパターンを調整します。

   BASE=$(git merge-base origin/main HEAD)   # or the commit the change started from
   T=(':(glob)**/*_test.*' ':(glob)**/*.test.*' ':(glob)**/*.spec.*' ':(glob)**/tests/**' ':(glob)**/test/**')
   X=("${T[@]/#:(glob)/:(exclude,glob)}")
   git diff -U0 "$BASE" -- . "${X[@]}" | grep '^-' | grep -v '^---' |
     grep -oE '[A-Za-z_][A-Za-z0-9_]{2,}' | sort -u |
     while read -r name; do
       git grep -q -w -F -e "$name" -- . "${X[@]}" || git grep -l -w -F -e "$name" -- "${T[@]}"
     done | sort -u | grep -vxF -f <(git diff --name-only "$BASE"; echo /dev/null)
   

   一覧にあるすべてのテストファイルを、焦点を絞ったチェックとして実行します。多くのテストファイルで使われている名前は、古いテストではなく、テストスイートの語彙です。

7. 完了を検証する

   • すべてのタスクにチェックが付いているか、未チェックのまま担当者を記したメモが付いています。
   • 実装された動作が仕様に一致し、コードが計画に沿っています。
   • プロジェクトのテストとチェックが、影響範囲について成功しています。
   • アーキテクチャの境界が保たれています。

実装中の出力

## Implementing: <change-name>

Task 3/7: <description>
[implementation]
✓ Done

Task 4/7: <description>
[implementation]
✓ Done

完了時の出力

## Complete: <change-name>

7/7 tasks complete.
Documentation phase worked: specs/features/<area>/spec.md updated.

Definition of done:
✓ Tests written before implementation
✓ Architecture boundaries hold
✓ Documentation phase's tasks ticked

次のステップ：「spec-kit-converge スキルを使って、spec.md、plan.md、tasks.md に照らして作業を評価し、不足があればタスクに変換します。」

ガードレール

• TDD は必須です。失敗するテストを書く前に、実装を書いてはいけません。
• 並列実行ではないタスクが失敗したら、そこで停止し、先に進んではいけません。
• タスクが完了したら、直ちにチェックボックスを更新します。
• まずドメインモデルを保護し、インフラストラクチャをそれに合わせて調整します。
• ドキュメントフェーズのタスクには必ずチェックを付け、specs/features/ を更新してから、作業完了とみなします。
• テストでは、実際の本番コードが使う呼び出し方を検証します。 コードが呼び出し元からパス、ルート、モード、オプションを受け取る場合は、都合のよいケースだけでなく、呼び出し元が実際に渡す値をテストします。
• 新しい値がシステムの外へ出るところまで追跡します。 ビューモデルや内部オブジェクトのテストで証明できるのは、値が計算されたことだけであり、実際に出力されることではありません。レスポンスや出力を手作業で組み立てている箇所では、新しいフィールドが出力までの途中で落ちることがあります。実際の出力を読み取るテストで検証します。
• 依存関係が未設定だと機能が無効になる箇所では、配線を固定して検証します。 依存関係を設定しないとアプリケーションがチェックを省略する場合、実際の構成を構築し、その依存関係が設定されていることを確認するテストを1つ用意します。
• レイアウトなしのコンポーネントテストで証明できるのは、コントロールがレンダリングされることまでであり、使いやすさではありません。 変更で追加またはスタイルを変更したすべての操作可能なコントロールを、実際のブラウザーで確認します。1つだけでは不十分です。
• マークアップや識別子を削除すると、レンダリング場所や定義場所から遠く離れたコードに影響することがあります。 削除する前に、その参照元を検索します。
• テキストに関するアサーションが失敗しうることを証明します。 ファイルのテキストを対象にするテストでは、コピー上でファイルを変更し、その変更が実際に反映されたことを確認してから、テストが失敗することを確かめます。パターンによる抽出では、値を調べる前に何かが見つかったことをアサートします。何にもマッチしないパターンでは、何も確認せずにテストが通ってしまいます。警告文自体にテスト対象の文字列が含まれている場合は、実行可能な行だけにマッチさせます。期待値は、変更対象のバージョンから読み取るのではなく、リテラルで指定します。
• 作成したディレクトリも含め、すべてのプローブを完全に削除します。 ファイルは絶対パスで復元し、復元後のファイルを意図した変更と差分比較します。
• パイプラインの終了ステータスをコマンド自体の終了ステータスとして扱ってはいけません。 test-suite | tail -20 が報告するのは tail のステータスなので、失敗した実行が成功のように見えます。ログにリダイレクトし、コマンド自体のステータスを記録します（<command> > run.log 2>&1; echo "EXIT=$?" >> run.log）。それを確認するまでは、結果を信用してはいけません。
• 長時間実行中のコマンドが実行しているスクリプトを編集してはいけません。 終了を待つか、コピーを編集します。