AIDive

動画パック

GitでAIのspecとplanを管理する: 5つのルール、drift gate、出典、チェックリスト

11 分で読めます

TL;DR

  • AIが書いたspecとplanはcommitする。どのツールもデフォルトでそうしている。問われているのはガバナンスだ。
  • squadごとに1つのフォルダを作り、CODEOWNERSに1行置く。specを変更するとコードのオーナーにレビューが依頼される。
  • 共有specにはすべてADR形式のヘッダーを付ける: status、superseded-by、owner、対象パス、レビュー期限。acceptedになったspecを書き換えて別の決定にしてはいけない。
  • CIでdrift gateを走らせる: acceptedなspecごとに、そこに書かれたパスが存在しなくなったらビルドを失敗させる。
  • 出力先はCLAUDE.mdの太字の命令文1行で切り替え、個人のplanはCLAUDE.local.mdと.git/info/excludeに置き、書き込みは必ずブランチ上で行い、mainには書かない。
  • specを書くのは、squadの境界をまたぐ作業か、90日後にまた読まれる作業だけ。spec駆動の実行は、時間が約2倍、トークンが約3倍かかる。

資料が語ること

デフォルト: みんなcommitする

Superpowersのwriting-plansスキルは、planをdocs/superpowers/plans/YYYY-MM-DD-<feature-name>.mdに保存し、その下に、plan保存先についてのユーザーの設定がこのデフォルトより優先されるという1行を添えている s1。brainstormingスキルは承認済みの設計をdocs/superpowers/specs/YYYY-MM-DD-<topic>-design.mdに書き、「Commit the design document to git」で終わる s2。Spec Kitはspecs/[branch-name]/にspec.md、plan.md、tasks.mdを置き、001、002と番号を振り、memory/constitution.mdにconstitutionを持つ s6。Kiroは機能ごとに1フォルダの.kiro/specs/を持ち、チームに「collaborate with team members on different features simultaneously」を勧めている s8。Anthropicのplaybookははっきり書いている: 「Every stage commits an artifact the next stage can read」、「Commit the approved plan as plan.md」、「When implementation departs from the plan, update plan.md in the same commit」 s5。

これらのどの文書も、commitされたspecを誰が所有するのか、いつ正しくなくなるのかを述べていない。記録されている3つの失敗は、その空白で起きている。

失敗1: 公開への漏洩

2026-06-05に立てられたIssue 1690は、デフォルトのdocs/superpowers/がSphinxとRead the Docs経由で社内のplanを公開ドキュメントに漏らす可能性を報告している s15。影響を受けたのは、273スターのPythonライブラリokamaだ。その修正commitは5つのplanと3つのspecを再追加し、.gitignoreの1行を削除し、「track superpowers plans/specs in git, excluded from the Sphinx build」と書かれている s21。docs/conf.pyの84行目には今exclude_patterns = ["_build", "Thumbs.db", "superpowers"]がある s22。現在そのフォルダには8つのplanと6つのspecがある s15。チームは運用を続け、ビルドの側を直した。

失敗2: mainにあるplan

2026-04-22に立てられ、まだ開いているIssue 1246は、開発ブランチができる前になぜplanがcommitされるのかを問うている。あるユーザーは「I'm getting 10 to 15 commits」と報告し、別のユーザーは「Yes please, no plans and specs on main branch!」と書いている s16。プラグインはブランチのルールを強制しない。強制するのは下のチェックリストだ。

失敗3: モデルが無視するoverride

Issue 337は2026-03-10にクローズされ、メンテナーはv5.0からプラグインが自身のデフォルトよりプロジェクトのCLAUDE.mdを優先すると述べた。例の行は「Save plans to ~/.superpowers/plans/ instead of docs/plans/」 s17。v5.0.6でのIssue 939は限界を示している: CLAUDE.mdの「Output Paths」表は無視され、specはdocs/superpowers/specs/に書かれ続けた。効いた回避策は、表の下に置いた太字の命令文1行だった: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18。指示の順序を入れ替えたPull request 1020は、マージされずにクローズされた s19。overrideは設定ではなくプロンプトだ。プラグインをリリースするたびに確認し直すこと。プラグイン自身の作業ファイルについては、Issue 1780がv6.0.3でクローズされ、自分自身をignoreする.superpowers/sdd/フォルダが、*だけを書いた.gitignoreを自分で置く形になった s20。

個人用と共有

Claude Codeは分け方を文書化している: 「For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed」 s3。ディレクトリごとのCLAUDE.mdは必要に応じて読み込まれ、「Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file」とあり、claudeMdExcludes設定でモノレポ内の他チームのファイルを隠せる s4。Gitには3層のignoreがある。$XDG_CONFIG_HOME/git/ignore、$GIT_COMMON_DIR/info/exclude、.gitignoreだ s24。真ん中の層なら、共有ファイルに触れずに個人のplanフォルダを隠せる。所有の半分はCODEOWNERSが担う: 「Code owners are automatically requested for review when someone opens a pull request that modifies code that they own」 s23。

ADRのようなライフサイクル

Michael Nygardの2011年の記事がひな形だ。決定は「'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement」となり、「If a decision is reversed, we will keep the old one around, but mark it as superseded」とある s9。Thoughtworksはspecの使い方を、spec-first(タスクのために一度書く)、spec-anchored(機能を育てるために保つ)、spec-as-source(specだけを編集する)に分け、筆者は「I'd rather review code than all these markdown files」と付け加えている s10。Superpowersはspec-firstのファイルを書き、そのまま残し続ける。つまりデフォルトでdriftする。

Driftとgate

arXivの論文はこの問題を「silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair」と呼び、「a drift gate that makes spec-code divergence a blocking merge condition」を提案している s11。Spec Kit自身のガイドも警告している: 「Do not leave a lower-level change in tasks.md or code if spec.md still says something different」 s7。TrueFoundryはガバナンスの論拠をはっきり述べる: 「forty-one specs and nine agent files aren't a tidiness problem」、それは「forty-one unversioned behavior inputs and nine competing standing policies」であり、driftは「is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable」。同じ記事は、specあたり約300行、常設の指示は150から200件の予算を勧めている s13。ある実践者は手作業の方法をこう述べる: 「I've had to have Claude compare the spec files to the codebase and see if anything is missing」 s26。

コスト

実験 結果 出典
現在の日付を表示する機能にSpec Kitを使用 8ファイル、1,300行のテキスト s14
OpenSpecの比較実験、同じ要件でspecツールとプレーンなClaude Codeを比較 OpenSpecは3つ多くギャップを見つけた。コードは50%多く、循環的複雑度も50%高い。時間は2倍、コストは3倍 s12
spec駆動開発を数か月続けたチーム 「two to three times as many tokens and take about twice as long」。コードが良くなった証拠はない s25

比較実験は1回きりで、筆者もそう述べているが、3つとも方向は同じだ。だから、アーキテクチャに関わる道筋にはspecを書き、範囲の決まった道筋は範囲のままにし、実践者が繰り返す2つの教え、「don t spec too big / read the generated specs」に従う s26。

月曜にやること

  • squadごとにdocs/specs/<squad>/を作り、フォルダごとにそのsquadのレビュアーを指すCODEOWNERSの行を1行追加する。
  • プロジェクトのCLAUDE.mdに太字の命令文を1行追加する: plans and specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/。brainstormを1回走らせ、ファイルがどこに作られたか確認する。
  • 個人のplanは.git/info/excludeに載せたフォルダへ移し、開発者ごとの設定はそれ自体もignoreされたCLAUDE.local.mdに置く。
  • 共有specすべてにヘッダーを付ける: status(proposed、accepted、superseded)、superseded-by、owner、paths、review-by。
  • drift gateを書く: status: acceptedのspecごとに、そこに書かれたパスを抽出し、1つでも存在しなければpull requestを失敗させる。シェルかPythonで15行ほど。
  • ブランチのルールを追加する: specやplanのcommitは、pull request以外ではmainに入れない。
  • リポジトリがSphinxなどでドキュメントを公開しているなら、今日のうちにspecsフォルダをexclude_patternsに追加する。
  • サイズの予算を決める: specは300行前後に収め、squadの境界をまたぐ作業か90日後にまた読まれる作業にだけ書く。

さらに読む

  • ヘッダーの方式を選ぶ前に、specの3つの使い方(spec-first、spec-anchored、spec-as-source)を読む。ライフサイクルが意味を持つのはspec-anchoredのファイルだけだ s10。
  • arXivの論文はパスのチェックを超えて、drift-enforcedなアーキテクチャ全体まで踏み込んでいる。15行のgateが粗く感じられてきたら役に立つ s11。
  • Spec Kitのガイドは3つの進化フロー(Flow-Forward、Living Spec、Flow-Back)を挙げており、同一commitのルールに対応する s7。
  • playbookはplanとdiffの同期を強制するhookを提案している。それについてのRedditのスレッドは43ポイント、27コメントで、現場の報告が集まっている s5, s27。
  • specの変更はpolicyの変更なので、実行メタデータ付きのevalゲートの後ろに置くべきだというTrueFoundryの主張は、CIでのパスチェックの次の一歩になる s13。
  • 開いている2つのIssue、1246(mainにあるplan)と939(無視されるoverride)を追う。どちらかがクローズされれば、このパックのルールの1つがプラグインのデフォルトになる s16, s18。
  • Marmelabの全文は、なぜ1,300行が生まれたのか、Spec Kitがどこで実際に効くのかを説明している s14。

出典

FAQ

最初の日から5つのルールすべてが必要ですか?

いいえ。CLAUDE.mdのリダイレクトとSphinxの除外は10分で終わります。CODEOWNERSとヘッダーは、specが初めてsquadをまたいだときに追加し、drift gateは、acceptedなspecが1スプリント経過してから追加します。

drift gateが見逃すものは?

挙動の変更です。指定されたパスがまだ存在するかどうかしか調べないので、反転した条件は通ってしまいます。同一commitのルールとレビューを組み合わせてください。

フォルダをgitignoreするだけではだめですか?

後からspecを読むエージェントがそれを必要とし、途中の成果物がバージョン管理されていなければ監査証跡が機能しないからです。okamaのチームはgitignoreを試し、ビルドからの除外を付けたcommitに戻しました。