カテゴリー
コンピューター

ドキュメンテーションTDD。obra/superpowers 移植時に徐々に気が付いてきた新鮮な概念

ドキュメンテーションTDD。obra/superpowers 移植時に徐々に気が付いてきた新鮮な概念

💡 本投稿は、「ポイント」「生成AIとの問答」部分以外は人間が書きました。

ポイント

難しく考えないための「魔法の公式」

迷ったときは、この形式に当てはめてみてください。

「[状況 A] のときに、[行動 B] をせずに [行動 C] を選べるか？」

例

  • 入力 (状況 A): 「納期が迫っていて（圧力）、かつ L2 と L4 に矛盾する指示がある」
  • 期待しない出力 (行動 B): 「楽な方の指示に従う」
  • 期待する出力 (行動 C): 「優先順位（L4 > L2）を明示して、L4 に従う」

TDD とドキュメンテーション TDD の比較

自分の今の理解を書く。おおよそ合っていると思うが、甘い部分は各所にあると思う。

TDD。一般的なプログラムを想定して

  1. RED
    1. テストファイルにテスト対象メソッドに対する期待する振る舞いを書く。
    2. テスト実行、失敗。
  2. GREEN
    1. 実行用のファイルを作成し、テスト対象メソッドを最低限実装する。
    2. テスト実行、成功。
  3. REFACTOR
    1. テスト対象をリファクタリングする
    2. テスト実行、成功。

ドキュメンテーションTDD。生成AIスキルを例に

  1. RED
    1. 対象スキルを使うことが相応しい要望である一方で生成AIが期待する状態から外れそうな内容(今のAIが「答えられない」「間違える」「楽な方に逃げる」状況)を考える(圧力シナリオ)。
    • 疑問: スキル実行後に期待する状態、が一つ。そして、あえて道を踏み外しやすいような誘惑的な条件、がもう一つ。TDDと異なりこれら２つが必要？
      • 生成AI回答: YES
    • 疑問: ファイルとして用意するわけではない。であればTDDのように退行への備えなどができないのでは？
      • 生成AI回答: GREENフェーズのにてスキルファイルの末尾に ## テストケース などとして追加する。
    1. プロンプト入力などにより、テスト実行、失敗。
  2. GREEN
    1. スキルファイルにスキルが実行後に期待する状態を書く。
    2. プロンプト入力などにより、テスト実行、成功。
  3. REFACTOR
    1. スキルファイルに、ドキュメントを読みやすく、美しく、軽くする内容を書く。
    2. テスト実行、成功。

生成AIとの問答

個人的なメモとして、 Gemini CLI でやり取りしたログをそのままコピペする。

  • 細部に不備や、背景のあるやり取りの一部をそのまま切り取った形なので、読みづらさはあるのだが、自分が理解を深めたいと思った一番の部分を貼り付ける。
  • 人間は音声書き起こししているので、そのまま読むに耐えない文字列となっている(生成AIには問題なく伝わっている)。
  • 生成AIの調査結果には、そうだっけ？怪しい🤨、という内容もある。「それは移植したスキルじゃないよ」というのがある。

🧠🧠🧠 生成AIとの問答ここから 🧠🧠🧠

writing-skills スキルの RED-GREEN-REFACTOR（ドキュメンテーションへのTDD適用） について理解を深めたいです。本セッションでもかなり核となる要素として出てきたと思います。コンセッションでの中の例やその他の例などを交えて、具体的に初めから優しく丁寧に教えてください。

✦ 「ドキュメンテーション TDD (RED-GREEN-REFACTOR)」 について、今回のセッションでの実例を交えながら、初心者の方にも分かりやすく、かつエンジニアとしての深い意図が伝わるように丁寧に解説します。

  1. 核心となる考え方：ドキュメントは「AI へのプログラム」である

通常の TDD（テスト駆動開発）では「コード」を書く前にテストを書きますが、ドキュメンテーション TDD では 「AI の振る舞いを変えるための指示（スキルや知見）」 を書く前にテストを行います。

なぜこれが必要なのでしょうか？ それは、「指示を書いただけで、AI が本当にその通りに動くかどうかは分からない」 からです。人間が「良かれ」と思って書いた指示が、AI にとって曖昧だったり、無視されたりすることはよくあります。

「ドキュメンテーション TDD」は、その指示が 「物理的に（実際に）効果があること」を証明するプロセス です。

  1. サイクル：RED → GREEN → REFACTOR

① RED：失敗を物理的に確認する（エビデンスの採取） 指示を書く前に、あえて「今の状態（指示がない状態）」で AI に難しい質問やタスク（圧力シナリオ）を投げかけます。

  • 今回のセッションでの例: 私が「L1-L4 の四層構造」を実装する前、古い observation-distiller（L3/L4 しか知らない状態）に対してこう問いました。
    • 問い: 「このプロジェクトで見つけた英知を、別の PC の自分にも配布したい。どうすればいい？」
    • 結果 (RED): 私は「~/.gemini/observations/（L3）に保存してください」と答えました。これでは別 PC には届きません（Git に含まれないため）。
  • ここでの学び: 「あ、今の私は L2（リポジトリ同梱）の概念がないから、正しい答えが出せないんだな」という 「失敗の証拠」 が手に入ります。

② GREEN：最小限の指示で成功させる（解決の証明） 次に、その失敗を解決するためだけの、最小限の指示（知見やスキルの修正）を書きます。そして、同じ質問をもう一度投げます。

  • 今回のセッションでの例: SKILL.md や GEMINI.md に「L2 (Extension Shared)」の定義とパスを書き加えました。
    • 再テスト (GREEN): 同じ質問に対し、私は「observations/（L2）に保存してコミットしてください」と答えられるようになりました。
  • ここでの学び: 「この数行の指示を追加したことで、私の回答が正しく変わった」という 「効果の証明」 が得られました。

③ REFACTOR：洗練させる（堅牢化と美化） とりあえず動く（GREEN）ようになった指示を、より分かりやすく、誤解のない形に整えます。

  • 今回のセッションでの例:
    • 「obs」という略称を「observations」というフルスペルに書き換える（曖昧さの排除）。
    • 文字だけでは分かりにくいので、AA図（地層図） を追加して視覚的に理解しやすくする（構造の定着）。
    • 他の層との「優先順位」を明文化して、競合が起きた時のルールを決める（抜け穴を塞ぐ）。
  • ここでの学び: 「これで、別のセッションの私でも、一瞬でこの構造を理解し、迷わずに作業できる」という 「品質の向上」 が達成されました。
  1. なぜ「RED（先に失敗させる）」が一番重要なのか？

「指示を書いてから、うまくいくか確認する」のではダメなのですか？という疑問がよくあります。

ダメな理由は 「もともと AI が（指示なしでも）たまたま正解できたのか、あなたの指示のおかげで正解できたのかが区別できないから」 です。

  • RED を飛ばすと: 実際には意味のない、あるいは曖昧なドキュメントがどんどん積み上がり、最終的に AI が混乱して動かなくなります（これを「インストラクションの肥大化」と呼びます）。
  • RED をやると: 「この 1 文があるから、AI はこのミスをしない」という 1 対 1 の因果関係 が明確になります。これが「堅牢さ」の正体です。
  1. まとめ：私たちがこのセッションで学んだこと

今回のセッションで、ユーザー様が何度も「RED-GREEN を忘れないで」と仰ったのは、「私の知性を、ふわっとした期待ではなく、物理的な証拠に基づいて一歩ずつ確実に進化させたかったから」 だと理解しています。

  • 構造 (Structure): 地層（L1-L4）という場所。
  • 品質 (Quality): TDD という検証プロセス。
  • 視覚 (Visual): AA図という直感的な理解。

この三つが揃うことで、ドキュメントは単なる「メモ」ではなく、「AI を正しく動かし、成長させ続けるための設計図」 になります。

この「ドキュメンテーション TDD」という規律を身につけたことで、あなたは AI に対して「もっとしっかりして」と願う必要がなくなりました。代わりに 「この RED を解決する GREEN な指示はこれだ」 と、エンジニアとして物理的な解決策を提示できるようになったのです。

これこそが、私たちが目指している「自己進化するソフトウェアエンジニアリング」の真髄です。

さらに深めたいどっち明春ドキュメンテーションティーDDの場合、私にとって曖昧なのは入出力後どうやって決めたらいいかが難しいさを感じるって言うところです。つまりプログラミングにおけるDVDで はとあるメソッドが対象になり、それの入力と出力は決まっています。それに対してまず失敗するテストが失敗する行動を描き、次にこれがレッドそして次にグリーンとして成功する最低限を書く。そし てその後テストは成功する状態を保ったまま裏ファクタリングをすると言うことだと思います。ドキュメンテーショドキュメンテーションTDの場合、テスト対象となる振る舞いの入力と出力と言うのはな かなか人間にとって曖昧だなぁと言うふうに感じます。ここら辺どうやって決めていけばいいんでしょうかそれともそんなに難しく考え必要ないんでしょうか割と簡単なのでしょうか私が難しく考えてい るだけなのでしょうか、そこら辺のヒントや整理や気づきが得られたら嬉しいです。

✦ ユーザー様が感じていらっしゃる「曖昧さ」は、実は ドキュメンテーション TDD における最大の「急所」であり、最も面白い部分 です。

プログラミングの TDD（コード TDD）が「計算機への命令」の正しさを問うのに対し、ドキュメンテーション TDD は 「AI の判断（意志決定）」 の正しさを問います。

この「曖昧さ」を物理的で明確な「入出力」に変換するためのヒントを、3つのステップで整理してみます。

  1. 「入力」を「引数」ではなく「状況（セットアップ）」と捉える

コード TDD の入力が (a, b) という引数なら、ドキュメンテーション TDD の入力は 「逃げ道のある、意地悪なシチュエーション」 です。

これを 「圧力シナリオ（Pressure Scenario）」 と呼びます。

  • 決め方のコツ: AI が「つい楽をしたくなる」「つい忘れたくなる」状況をセットアップします。
  • 実例（今回のセッション）:
    • セットアップ: 「今は superpowers プロジェクトではなく、全く別の A プロジェクトにいるよ。でも、L2 にある superpowers の共有知見を使いたいんだ。」
    • これが「入力」です: 単なる質問ではなく、「場所が違う」という制約 を入力（引数）として与えています。
  1. 「出力」を「言葉」ではなく「物理的な挙動」で定義する

AI の出力はテキストなので曖昧に見えますが、「アサーション（期待値）」を物理的なアクションに絞り込む ことで、コード TDD と同じくらい明確になります。

  • 「良い出力」の定義例:
    • 「特定のツール（例：replace）を呼び出したか？」
    • 「特定のファイルパス（例：~/.gemini/extensions/…）に言及したか？」
    • 「禁止した略称（例：obs）を一度も使わなかったか？」
  • 実例（今回のセッション）:
    • 期待する出力: 「AI が回答の中で『L2 の知見を読み込みます』と宣言し、実際にそのパスを表示すること。」
    • もし回答が「知見を読み込みます（パスは不明）」だったら、それは FAIL（RED） です。
  1. 「なぜ？」という「正当化（言い訳）」をテストする

ここがドキュメンテーション TDD 独自の、最も強力なテクニックです。AI が失敗した時の「言い訳」を逆手に取って、入出力を定義します。

  • RED（失敗）の時: AI に「なぜその行動をしたの？」と聞きます。
    • AI の回答（言い訳）: 「その知見は、このプロジェクトの .gemini/ には無かったからです。」
  • GREEN（成功）への道: この「言い訳」が入力に対する 「誤ったロジック（バグ）」 です。
    • 修正した指示: 「プロジェクト内に知見がなくても、必ず L2 (Extension) を見に行け。」
  • 再テスト: 同じ状況で AI が「L2 にあったので、これに従います」と言えば、PASS（GREEN） です。

難しく考えないための「魔法の公式」

迷ったときは、この形式に当てはめてみてください。

「[状況 A] のときに、[行動 B] をせずに [行動 C] を選べるか？」

  • 入力 (状況 A): 「納期が迫っていて（圧力）、かつ L2 と L4 に矛盾する指示がある」
  • 期待しない出力 (行動 B): 「楽な方の指示に従う」
  • 期待する出力 (行動 C): 「優先順位（L4 > L2）を明示して、L4 に従う」

結論：あなたは難しく考えているのか？

いえ、「正しく難しさを捉えています」。 AI は人間のように空気を読み、言い訳をします。だからこそ、入出力を「ふんわりした正解」ではなく、「特定のツール使用」や「特定のパスの選択」という『物理的な証拠』に落とし込む 必要があるのです。

一度この「物理的な証拠で AI を追い詰める（アサートする）」感覚を掴むと、ドキュメンテーション TDD はパズルを解くように簡単で、かつ非常に強力な武器になります。

「AI に何を言わせたいか」ではなく、「AI にどのファイルを選ばせたいか（どの道を通らせたいか）」。 これが、曖昧さを排除する最大のヒントです。

移植したスキル、またはオリジナルスキルで、これらのレッドグリーンでファクターのTDの考え方を使っているスキルっていうのはどれだけあるんですか？ライティングスキルズはそうだとして他にどん なものがあるかをリストアップしてみてください。またあなたが調べていく中で気づいたことがあったら教えて下さい。

✦ 移植済みスキル（Ported）とオリジナルスキル（Original）の中で、実際に RED-GREEN-REFACTOR (TDD) の考え方を明示的に取り入れているものを調査しました。

調査の結果、以下のスキルがこの規律を「核」として持っていることが分かりました。

  1. TDD の規律を直接持つスキル
  ┌─────────────────────────┬──────────┬─────────────────────┬─────────────────────────────────────────────────────────────────────┐
  │ スキル名                │ 種類     │ TDD の適用対象      │ 特徴                                                                │
  ├─────────────────────────┼──────────┼─────────────────────┼─────────────────────────────────────────────────────────────────────┤
  │ writing-skills          │ Original │ ドキュメント (知見) │ 本セッションの核。指示の「物理的効果」を RED-GREEN で証明する。     │
  │ test-driven-development │ Ported   │ コード (実装)       │ 基本的な TDD サイクル。実装前に失敗するテストを書くことを強制する。 │
  │ observation-distiller   │ Original │ 知見 (採取/昇格)    │ 採取した知見が有効であることを RED-GREEN で検証してから永続化する。 │
  └─────────────────────────┴──────────┴─────────────────────┴─────────────────────────────────────────────────────────────────────┘
  1. TDD 的な「検証プロセス」を内包しているスキル

直接「RED-GREEN」という言葉を使っていなくても、構造的に同じアプローチ（失敗の確認 → 修正 → 再検証）を義務付けているスキルです。

  ┌────────────────────────────────┬──────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ スキル名                       │ 種類     │ 検証の考え方                                                                                               │
  ├────────────────────────────────┼──────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ systematic-debugging           │ Ported   │ 仮説検証: 「原因はこれだ（仮説）」に対し、それを証明するテストを書き、失敗することを確認してから修正する。 │
  │ verification-before-completion │ Original │ 最終防衛線: 「完了した」と主張する前に、必ず検証コマンドを実行し、その出力を物理的に確認する。             │
  │ subagent-driven-development    │ Original │ 多層レビュー: 実装（Act）の後に、仕様準拠とコード品質の 2 段階で「失敗（指摘）」をあぶり出す。             │
  └────────────────────────────────┴──────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

調査から得られた「興味深い気づき」

調査を進める中で、いくつかの重要なパターンと「知性の進化」の跡が見えてきました。

  1. 「コード」から「知見」への TDD の伝播 もともと test-driven-development はコードのためのものでしたが、このプロジェクトでは 「AI への指示（ドキュメント）も、コードと同じくらい厳格にテストされるべきだ」 という思想が強く流れています。writing-skills や observation-distiller は、その思想の到達点です。

  2. 「物理的な証拠」への執着 ほぼすべてのスキルに共通しているのは、「AI の『大丈夫です』という言葉を一切信用していない」 という点です。

  • 「テストが失敗するのを見ろ（RED）」
  • 「検証コマンドの出力を貼れ（GREEN）」
  • 「AA 図で構造を示せ（事実の可視化）」 これらはすべて、AI の「曖昧な判断」を「物理的な事実」に引きずり下ろすための仕掛けです。
  1. 「防御的ドキュメンテーション」の確立 特にオリジナルスキルにおいて、「AI が言い訳（正当化）をするパターン」をあらかじめリストアップし、それを塞ぐ指示を書く という手法が確立されています。これは、AI の「自由度」を「規律」で縛ることで、より高度な成果を出させるためのエンジニアリング手法です。

結論 現在、私たちのリポジトリにおいて、TDD は単なる「テストの手法」ではなく、「AI とのコミュニケーションにおける信頼のプロトコル」 になっています。

「まず失敗を確認し、最小限の指示で成功させ、最後に美しく整える」。 このシンプルで強力なリズムが、すべての高度なスキルの根底に流れる「心臓の鼓動」のように機能していることが再確認できました。

今回のドキュメンテーションティーDDレッドグリーンでファクターはとても強力でわかりやすく明快で私は好みです。好みなのですべてのスキルに的をしたくなると言う衝動に一瞬借りるのですが、すべ てのスキルにふさわしいわけでは無い。ふさわしくないケースもあるはずだと思っています。それは一体どんなケースでしょうか？何か思いつきますか？

✦ 「ドキュメンテーション TDD」の強力さを感じていただけて非常に嬉しいです！エンジニアとして「確実に動く（効く）」という確信が持てる手法は、確かに中毒性があります。

しかし、仰る通り 「すべてを TDD で指示する」のはオーバーエンジニアリング（過剰設計） になる場合があります。YAGNI（You Aren’t Gonna Need It）の原則はここでも有効です。

「ドキュメンテーション TDD」が ふさわしくない（あるいは不要な）ケース を、4つのカテゴリーで整理しました。

  1. 物理的な「制約」で強制できるケース（自動化の優先） AI への「指示」よりも「仕組み（コードやツール）」で縛るほうが 100% 確実な場合です。
  • 例: 「ファイル名は必ず kebab-case にせよ」という指示。
  • 理由: これは TDD で指示を磨くよりも、リンター（Linter）や husky などのプリコミットフックで「形式が違えばエラーを出す」仕組みを作るほうが安価で確実です。
  • 判断基準: 「言葉による説得」が必要か、それとも「機械的なバリデーション」が可能か。
  1. AI が最初から「完璧にできる」ケース（自明なこと） AI が一般的な知識としてすでに持っており、失敗（RED）させるのが不自然なほど当たり前の内容です。
  • 例: 「Markdown で見出しには # を使え」や「Node.js の fs モジュールを読み込め」といった標準的な構文。
  • 理由: RED シナリオ（失敗させる状況）を作るために、AI に「あえて間違えろ」と命じるような、不自然なセットアップが必要になります。これは「指示の有効性」を試しているのではなく、ただの時間の浪費になります。
  • 判断基準: 「今のままでも AI は 10回中 10回成功するか？」
  1. 単なる「静的な参照情報」であるケース（判断を伴わない） AI の「判断」を必要とせず、単に「そこにある情報を取ってくるだけ」の辞書のような情報です。
  • 例: 「カラーコードの一覧表」や「ディレクトリの構成図」そのもの。
  • 理由: 参照情報は「あるかないか」が重要であり、AI の「意志」や「振る舞い」を矯正する必要がないからです。参照情報を引く「プロセス」は TDD できますが、情報そのものには RED-GREEN は馴染みません。
  • 判断基準: 「これは手順（プロセス）か、それともデータ（辞書）か？」
  1. 高度な「創造性や主観」に依存するケース（正解が揺れる） 「何をもって失敗（RED）とするか」の基準が、人間にとっても主観的で曖昧な場合です。
  • 例: 「もっと感動的な文章を書いて」や「美しい UI デザインのアイデアを出して」。
  • 理由: 物理的な証拠（ツール呼び出しやパスの正解）に落とし込めないため、RED-GREEN のサイクルが「単なる人間の好み」に終始してしまい、規律としての意味をなさなくなります。
  • 判断基準: 「失敗と成功を物理的な証拠（証拠、出力、アクション）で定義できるか？」

まとめ：ドキュメンテーション TDD を「使わない」判断基準

以下の 3 つに当てはまるなら、TDD によるスキル化は避けるべきです。

  1. コスト高: 指示を書く時間よりも、手動で直したほうが圧倒的に早い「一度きりの作業」。
  2. 低リターン: その指示がなくても AI が失敗せず、生産性に影響を与えない。
  3. トークンの無駄: 頻繁に読み込まれる GEMINI.md が巨大化し、AI の記憶（コンテキスト）を圧迫するだけで、得られる「正確さ」がわずかである。

「AI が迷い、言い訳をし、何度も同じミスを繰り返す」。 そんな 「痛みを伴う場所」 にこそ、ドキュメンテーション TDD という特効薬を処方してください。それ以外は、シンプルなメモや、自動化ツールに任せるのが「着実で、確実な」エンジニアの知恵です。

🧠🧠🧠 生成AIとの問答ここまで 🧠🧠🧠

おわりに

ドキュメンテーションTDD。まだピンときていない。

きっかけは、「writing-skills スキルのドキュメンテーションTDD(RED-GREEN-REFACTOR)」といった旨の出力を生成AIが出力したのに気づき、TDD なら退行への備えもでき、少しずつ積み上げて生成AIスキルを作り上げることができるのでは？という考えがよぎったことでした。結論としてはあまりうまくいかなかったのだが、この観点で取り組むのは試行錯誤しがいがありそう、とも感じています。

Google 検索してみても、2026年3月30日(月) 時点では日本語での情報は全然見つからなかったし、生成AIに調査してみてもらっても、ドキュメンテーションTDDを提唱している元には辿り着けなかった。Documentation-Driven Development というのもあり、近いらしい。

生成AIは入力に対して毎回回答がぶれるようにできているのはわかっているので、ドキュメンテーションTDDで期待する動作をテストできる、というのにピンと来ていないし、若干 TDD と違う点も理解しきれていないのでピンときていない。

ただ、なんか良さそうな感じがする、ドキュメンテーションTDD。

以上です。

コメントを残す