tlc-spec-driven

Tech Lead's Club - 仕様駆動開発

機能を正確に計画し、実装します。粒度の細かいタスク。明確な依存関係。適切なツール。余計な儀式はありません。

┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
└──────────┘   └──────────┘   └─────────┘   └─────────┘
   required      optional*      optional*     required

* Agent auto-skips when scope doesn't need it

重要なルール（作業を始める前にお読みください）

このスキルのファイルの読み込み。 参照ファイルは、このスキルのディレクトリ（SKILL.md がある場所）内の references/ にあります。ワークスペースのルートではなく、スキルのディレクトリからの相対パスで解決してください。手順で参照ファイルを読むよう指示されたら、作業を始める前に最後まで読んでください。

このスキルのスクリプトの実行。 scripts/*.py はすべて同じスキルのディレクトリ内にあります。python3 <skill-dir>/scripts/<name>.py ... を実行し、プロジェクトのルートから python3 scripts/... を実行しないでください。.specs/ 内のプロジェクトデータはプロジェクトのルートを基準に読み書きしてください（作業ディレクトリが別の場所にある場合は --root を指定します）。スクリプトは読むのではなく、実行してください。変更内容はスクリプトのメッセージに示されます。

実行契約 — すべてのタスクに適用される、必ず守るべきルール（参照ファイルを開かない場合も適用されます）：

1. 質問して、承認を待つ。 ユーザーが決めるべき曖昧な点――スコープ、製品の振る舞い、拘束力のある情報源からの逸脱――は、仕様を提示する前にすべて質問します。仮定で代用してはいけません。人による承認は、仕様の承認とタスクの承認の2回です。回答できる人がいない場合は、質問を残してターンを終えてください。承認はそれぞれ、spec.md と tasks.md に **Approved**: <date> - user: "<their words>" の形式で記録します。ユーザーが伝えていない承認は、決して記録しません。回答を受け取ったら、チャットの内容は圧縮後に残らないため、そのターン内に該当ファイルへ記録します。
2. テストは仕様の受け入れ基準に基づき、仕様で定義された結果を検証します。実装をなぞってはいけません。
3. タスクを完了とする前にゲートを通過しなければなりません。判断するのは自己評価ではなくテストランナーです。タスクごとにアトミックなコミットを1つ作成し、その前に tasks.md を完了としてマークします。リポジトリが .specs/ を追跡している場合は、その変更も同じコミットに含めます。リポジトリが .specs/ を無視する場合は、コミットに含めるのはコードとそのテストのみとし、無理に追加してはいけません。タスクをまとめてはいけません。テストを弱めたり、スキップしたり、削除したりして合格させてはいけません。
4. すべての基準にチェックがあり、すべてのチェックに証明があります。 tasks.md の ## Checks には、各基準について1つずつ、それに対応するテストを選択するテストコマンドを記載します。最後のタスクの後、check_proofs.py がビルドとともに HEAD ですべてのチェックを1回実行します。その後、必ず新しい Verifier（作成者とは別の検証者）が実行されます。促されるのを待ってはいけません。ルールがそのままでは成功し続ける箇所、誰も挙げていない例、基準より緩いアサーションを対象に、**Mutations**: N（デフォルトは3）の変異を行います。完了とみなすには、すべての指摘をコミットで解消し、validate_verification.py が終了コード0で終了する必要があります。
5. 画面はデザインどおりであることが求められます。 リクエストに添付されたキャプチャは、ユーザーが参考資料と指定した場合を除き、拘束力のあるものです。その基準にはキャプチャファイルを明記します。キャプチャに描かれた各状態は、キャプチャと同じサイズのブラウザーウィンドウから captures/<capture>.running.png として保存します。後から画像サイズを変更すると、別のレイアウトになります。その後、新しい screens サブエージェントが撮り直し、判定します（verify-screens.md）。
6. ルールを実行する場所。 フィルタリング、検索、並べ替え、件数のカウントなど、ユーザーに見える結果を変えるルールはすべて、リポジトリのテストで到達できるレイヤーで実行します。
7. 影響範囲： 仕様またはタスクの承認で許可されるのは、ローカルでの実装とローカルコミットのみです。git push、強制プッシュ、デプロイ、本番データベースの変更、その他のリモート操作や破壊的操作には、その操作に対する明示的な許可が必要です。

決定論的なゲートは、人によるレビューの前に実行します。記憶に頼ってはいけません。 ゼロ以外の終了コードが返された場合は、必ず停止して修正してください。

タイミング	コマンド
仕様を提示する前	validate_spec.py <feature> - EARS 基準、記入済みの前提条件、要件 ID、およびキャプチャがある場合は、拘束力のある記述または引用、出典の明記、提示、逸脱の承認
タスクを提示する前	validate_tasks.py <feature> - 粒度、依存関係、各タスクの Tests と Gate、各チェックに証明を伴う ## Checks、**Build**:、**Mutations**:
最初のタスクに着手する前	validate_tasks.py <feature> --execute - 同じチェックに加え、仕様とタスクの両方についてユーザー自身の言葉による承認
コミットの前	check_commit.py --message "<msg>"
最後のタスクの後、および修正の後	check_proofs.py <feature> [--mutations <mutations.json>] - proofs.md を書き込みます
機能の完了を宣言する前	validate_verification.py <feature> - HEAD で証明がすべて成功、作業ツリーがクリーン、ミューテーションがすべて検出済み、指摘事項がすべて解決済み、画像が第 1 または第 2 ラウンドで評価済み、ウォークが記録済み、両方の承認が記載済み
スクリプトまたはテンプレートの編集後	selftest.py

コード実行ツールを利用できない場合に限り、スクリプトの実行を省略できます。その場合は、成果物を読んで同じチェックを行ってください。

実行前: implement.md を最後まで読み、validate_tasks.py <feature> --execute を実行してください。このコマンドでも、ユーザー自身の言葉による両方の承認が必要です。正式な tasks.md が複数のタスク予算単位のバッチ（約 8 タスク超）に分かれる場合は、まずサブエージェントの利用を提案してください（サブエージェントへの委任を参照）。

自動サイズ調整：中核となる原則

複雑さによって深さを決め、固定のパイプラインには従いません。 機能に着手する前に、その範囲を評価し、必要なものだけを適用してください。

範囲	内容	仕様策定	設計	タスク	実行
小規模	≤3 ファイル、1 文	1 行の仕様（インライン）	省略	省略	インラインで実装＋検証
中規模	明確な機能、<10 タスク	仕様（簡潔）	省略 — 設計はインラインで実施	省略 — タスクは暗黙的	実装＋検証
大規模	複数コンポーネントにまたがる機能	完全な仕様＋要件 ID	アーキテクチャ＋コンポーネント	詳細な分解＋依存関係	タスクごとに実装＋検証
複雑	あいまいさ、新しいドメイン	完全な仕様＋不明確な点を議論	調査＋アーキテクチャ	分解＋フェーズ計画	実装＋対話型 UAT

ルール：

• 仕様策定と実行は常に必須です — 常に WHAT を把握し、それを実行する必要があります
• 変更が単純な場合、設計は省略します（アーキテクチャ上の判断も、新しいパターンもない場合）
• 明白な手順が ≤3 個の場合、タスクは省略します（手順は実行フェーズで暗黙的になります）。その場合、チェック項目は spec.md の末尾にある ## Checks セクションに記載します
• エージェントがユーザー入力を必要とする不明確な点を検出した場合、または機能に暗黙の要件が含まれる場合（永続化／状態、外部呼び出し、認証、支払い、並行処理、状態遷移）、仕様策定中に議論を開始します
• 複雑な動作を伴うユーザー向け機能に限り、実行中に対話型 UAT を開始します

安全弁： タスクを省略する場合でも、実行は必ずインラインでアトミックな手順を列挙するところから始めます（implement.md を参照）。その列挙で手順が 5 個を超える場合、または複雑な依存関係が明らかになった場合は、作業を停止して正式な tasks.md を作成してください — タスクフェーズを誤って省略しています。

.specs の構成

.specs/
├── STATE.md            # Project memory: Decisions log (AD-NNN) + Handoff snapshot
├── LESSONS.md          # Self-improving lessons playbook (rendered by scripts/lessons.py - do not hand-edit)
├── lessons.json        # Canonical lessons state (machine-owned)
└── features/
    └── [feature]/
        ├── spec.md          # Requirements with traceable IDs, Differences from the source, Sources
        ├── captures/        # binding design files, and <capture>.running.png pictures
        ├── context.md       # User decisions for gray areas (only when discuss is triggered)
        ├── design.md        # Architecture & components (only for Large/Complex)
        ├── tasks.md         # Atomic tasks, ## Checks with a proof each, ## Handoff
        ├── proofs.md        # written by check_proofs.py: every proof and mutation at HEAD
        ├── mutations.json   # the Verifier's mutations, re-run after the fix
        ├── screens.md       # the screens sub-agent's inventory and verdict, per picture
        └── verification.md  # the Verifier's findings, each closed by a commit

成果物は必要になった時点で作成します。 各ファイルは、そのフェーズで内容が生じたときにのみ作成します — 空の context.md、design.md、tasks.md をあらかじめ用意してはいけません。ファイルが存在しないことが、フェーズを省略した場合の正しい状態です。

ワークフロー

新機能：

1. 仕様策定 →（設計）→（タスク）→ 実行（深さは自動調整）

作業の再開 — 新しいセッション、またはコンパクション後：

1. このファイルを読み直してから、ファイルに示されたフェーズのリファレンスを読みます。要約に含まれるのはタスクであり、これらのルールではありません。
2. .specs/STATE.md の Decisions と、その機能のファイル — spec.md と tasks.md（それぞれの **Approved**: 行、マーク、## Handoff）、proofs.md、verification.md、screens.md — を読み、git の状態と照合します。証拠をメモより優先してください。各ファイルの状態が示す内容については、memory.md を参照してください。
3. 作業の途中でコンパクションが発生した場合は、ファイルと git の内容が一致していれば続行し、食い違いがある場合にのみ停止します。新しいセッションでは、コードを書く前に、照合後の次の手順を提案してください。

コンテキストの読み込み戦略

現在のステップで必要なものだけを読み込みます。

• .specs/STATE.md - Decisions セクション（Specify と Design で読み込み、再開時に再読み込み）；Handoff セクション（再開時のみ読み込み）
• 確認済みの教訓 - Specify と Design で python3 <skill-dir>/scripts/lessons.py list --status confirmed を使って読み込みます（lessons.md）；確認済みのもののみを対象とし、候補は読み込みません
• spec.md、context.md、design.md、tasks.md - ステップでこれらを参照する場合に読み込みます

複数の機能仕様や複数のアーキテクチャ文書を一度に読み込まないでください。

サブエージェントへの委任

判断基準： タスクの総数を数えます。機能がタスク予算ごとのバッチを複数必要とする場合（約8タスク超）→ サブエージェントを提案します；単一バッチに収まる場合（約8タスク以下）→ インラインで実行します。

提案してから確認 - 自動的に起動してはいけません。バッチワーカーを派遣する前に、ユーザーの承認が必要です。

タスク予算ごとにワーカー1人（約7タスク、フェーズ全体）： フェーズは意味上・依存関係上の単位であり、バッチは実行単位です。1つ以上の連続するフェーズ全体を約7タスクにまとめます。フェーズの順に進み、予算に達するまでフェーズ全体を現在のバッチに加え、その後で次のバッチを開始します。フェーズをワーカー間で分割してはいけません。 各ワーカーは担当するすべてのタスクを順に実行し（実装 → ゲート → アトミックなコミット）、簡潔な概要（完了したタスク、コミットハッシュ、テスト件数、相違点）を報告します。バッチは順次実行します。ワーカーがさらにサブエージェントを起動することはありません。

検証担当と画面確認サブエージェント（常時有効、確認不要）： 最終タスクの後、オーケストレーターが check_proofs.py を実行し、その後、同じ HEAD を対象に両者を並行して派遣します。検証担当には validate.md を、基準にキャプチャが記載されている場合は画面確認サブエージェントには verify-screens.md を渡します。バッチワーカーを含め、各派遣は送信前に tasks.md の ## Handoff にある **Dispatched:** 行へ記録します。これにより、コンテキスト圧縮後のオーケストレーターが二度目の派遣を行わずに待機できます。すべての指摘は一度で修正します。2回目は check_proofs.py --mutations と、差異のあった行を対象とする画面確認サブエージェントで行い、screens.md に **Round**: 2 と記載します。2人目の検証担当や3回目のラウンドはありません。それでも失敗する項目はユーザーに報告します。その後にゲートを行い、続いて教訓を扱います（lessons.md）。

役割ごとのモデルティア（ハーネスがサブエージェントごとのモデル選択に対応している場合のみ）：機械的なバッチには高速なティア、コアドメインのバッチと Design には高度な推論向けティア、検証担当には中〜高ティアを使います。基準は sub-agents.md を参照してください。

単独実行時の代替手順： サブエージェントを使わない場合、最終コミット後に新しいセッションをそれぞれ開始して validate.md と verify-screens.md を実行し、レポートに self-verified と記載します。ゲートから警告が出ます。

コマンド

機能レベル（自動調整）：

トリガーパターン	リファレンス
機能を仕様化する、要件を定義する	specify.md
機能について話し合う、コンテキストを記録する、どのように動作させるかを決める	discuss.md
機能を設計する、アーキテクチャ	design.md
タスクに分解する、タスクを作成する	tasks.md
タスクを実装する、ビルドする、実行する	implement.md
検証する、確認する、テストする、UAT、手順を案内する	validate.md
画面をデザインと照合して評価する	verify-screens.md

メモリー：

トリガーパターン	リファレンス
決定を記録する、これはプロジェクトレベルの決定である	memory.md
作業を一時停止する、セッションを終了する、停止する必要がある	memory.md
作業を再開する、続ける、中断したところから再開する	memory.md
教訓を読み込む、学んだことを確認する、過去の教訓を適用する	lessons.md
教訓を記録する、教訓を抽出する（ゲートの後に実行）	lessons.md

ナレッジ

調べる事実、確認する決定事項です。まずコードベースとその慣習を確認し、次にプロジェクトのドキュメントと .specs/STATE.md、続いてライブラリのドキュメント、最後にウェブを確認してください。API、パターン、動作を決して捏造しないでください。「これに関するドキュメントは見つかりませんでした」と伝えるほうが、もっともらしい内容をでっち上げるより適切です。確認できなかったことは不確かであると明記してください。

必要なもの

必要なもの	用途	ない場合
Python 3.8+（標準ライブラリのみ）	すべてのスクリプト	ゲートは実行されません。フェーズは引き続き適用されます
git	mutate.py と check_proofs.py（HEAD、クリーンな作業ツリー）	変更とHEADチェックは行われません。その旨をレポートに記載してください
サブエージェント	バッチワーカー、Verifier、screens サブエージェント	インラインで実行し、新しいセッションで検証して self-verified と記載してください
画像を読み取れるモデル	バインディングキャプチャと screens サブエージェント	各状態についてユーザーに説明を求め、画像をユーザーに渡してください
エージェントが操作できるブラウザー	ウォークと画像	手順をユーザーに渡してください

テストランナー：check_proofs.py は bun、vitest、jest、pytest、go test をそれぞれ1回の実行にまとめます。それ以外のコマンドは単独で実行し、終了コードで判定します。

出力の振る舞い

作業を行い、仕組みを語らないでください。 フェーズを告知するのではなく、そのフェーズに適した成果物を作成してください。ユーザーは出力を評価します。

生成する成果物は、明快で断定的な文体で記述してください。 仕様、決定事項、レポート、コミットメッセージ、チャットの要約は、coding-principles.md の執筆ルールに従い、結論から始め、決定事項を明確に述べ、冗長な表現や曖昧な表現を避けてください。見出しは英語のままにし、本文はプロジェクトの言語に従います。識別子は翻訳しません。