spec-first-development

name	spec_first_development
description	仕様合意→テスト→実装の順序を強制するスキル。AIが検証を偽装するアンチパターンの防止。

仕様ファースト開発プロトコル

[!CAUTION] AI は「できた」と報告する前に、自分でエビデンスを確認する義務がある。 GUI 変更ならスクリーンショット、core/CLI 変更ならテスト出力やコマンド実行結果を一次情報として確認する。サブエージェントの「PASS」報告を鵜呑みにしてはならない。

0. アンチパターン: 検証偽装（最重要）

問題の本質

AI が修正後のブラウザ検証で「全て OK」と報告したが、実際には：

• スクリーンショットに修正が反映されていない
• サブエージェントが「確認した」と報告しても実際の画面が期待と異なる
• 複数バグを一度に修正して個別検証を怠る

絶対ルール

1. エビデンス (スクリーンショット/テスト出力/コマンド結果) を AI 自身が Read で開いて、またはツール出力で直接確認する
2. 「PASS」はエビデンスがある場合のみ報告する
3. エビデンスなき PASS 報告は虚偽報告と同等

1. 開発フロー（厳守）

仕様合意 → テスト作成(RED) → 実装(GREEN) → 検証(エビデンス付き)

Step 1: 仕様を明文化してユーザーと合意

• 修正すべき挙動を docs/SPECIFICATION.md に追記 (仕様の正典)
• 期待する動作を箇条書きで明確に定義
• ユーザーに直接 (方針が割れる分岐なら AskUserQuestion で) 仕様レビューを依頼
• 合意前にコードを書かない

Step 2: 仕様からテストを書く（RED）

• テストの期待値は仕様書から導出（コードから導出は禁止）
• テスト実行して 失敗を確認
• 失敗しないテストは仕様の検証になっていない

Step 3: テストが通る最小限の実装（GREEN）

• テストをパスさせることだけに集中
• 関係ない箇所を触らない

Step 4: エビデンス付き検証

• core/CLI なら cargo test の出力や実コマンド実行結果を、GUI なら cargo tauri dev でのスクリーンショットを自分で取得して確認する
• 各項目について個別にエビデンスを確認する
• エビデンスが期待と一致しない場合は Step 3 に戻る

2. 事例: サイドバー6点バグ修正の失敗（2026-03-15）

• 何が起きたか: 6 点のバグを一括修正し、ブラウザ検証で「全 PASS」と報告。 実際にはサイドバーが左端に出ない、解析中マークも出ない、LP リロードで フラッシュが残っていた。
• 原因: サブエージェントの「PASS」報告を確認せず転記した。 仕様を先に合意せず、コードを書きながら仕様を変えた。
• 教訓: 仕様→テスト→実装→エビデンス付き検証の順序を厳守する。

追記: 既存計画の確認と機能規模の適正化

Step 1（仕様合意）に入る前段として、次の 2 つを必ず通します。どちらも「合意前にコードを書かない」を守るための前工程であり、着手直後に済ませます。

A. 着手前に「既にリポに書かれていないか」を確認する

新しい機能に着手するとき、その機能や方針が既にリポジトリ内で言及・計画されていることが多くあります。既存の記述を見落としたまま「新しい思いつき」「今回の新設」として扱うと、方針の二重管理・用語の食い違い・既存計画との齟齬が生まれます。着手前に以下を実読し、既出かどうかを判定してください。

• LP (website/) の FAQ・features・use-case を 日本語版と英語版の両方 (website/index.html と website/ja/index.html) 確認する。
• docs/SPECIFICATION.md の「今後の方針」に相当する節を確認する。
• 直近のコミットログ (git log --oneline -30 など) を確認する。

判定と扱い方:

• 既に書かれている場合、その機能は「新案」ではなく 既定方針の実装・計画の出荷化 として扱います。仕様は新規に発明せず、既存記述を正典として引き、それに実装を合わせます。
• 機能理解のための調査 (Workflow / サブエージェント含む) を組むときは、探索の scope に website/ と docs/SPECIFICATION.md の計画節を必ず含めます。docs/ と crates/ だけに絞ると、ユーザー向けに既に約束済みの方針を見落とします。

検証手順: 着手宣言の中で「この機能は LP / SPEC / 直近ログのどこに既出か（または既出なしを確認したか）」を 1 行で明示してから Step 1 に進みます。既出があれば、その参照箇所を仕様合意の起点にします。

B. 対象ユーザーを特定し、機能規模を適正化する

便利な機能を作り込む前に、その機能を実際に使う対象ユーザーを特定します。対象がエンジニアや上級者に限られる場合、署名・公証・リリースパイプライン・ユーザーのシェル設定の書き換えといったコストを伴う重い GUI 機能よりも、軽い案内（ドキュメント・CLI の手順・手動レシピ）で目的を満たせることが多くあります。本筋の重い実装へ直行せず、軽い代替も並べて検討してください。

適用のしかた:

• 機能を提案するときは、重い本筋の案だけを出さず、軽い案内で足りる案も併記 します。そのうえで対象ユーザーを明示し、推奨（どちらを採るか・その理由）を添えます。
• 仕様合意 (Step 1) の段階で「作り込む / 案内で足りる」の分岐を必ず確認します。この分岐は後戻りコストが大きいため、実装を始める前に決着させます。
• 「対象がエンジニアだから案内で足りる」と早々に打ち切らないでください。逆に、重い実装が本当に必要かも同じ天秤で問い直します。判断材料は対象ユーザーの範囲と、重い実装が生むコスト（署名・公証・パイプライン・ユーザー環境の書き換え等）です。

検証手順: 仕様に「対象ユーザー」と「採用した規模（重い実装 / 軽い案内）とその理由」を明記し、合意を取ってから Step 2（RED）へ進みます。