【ITニュース解説】Rotten specs

ソフトウェア開発の現場では、「仕様書駆動開発」（Spec-driven development、略してSDD）という開発手法が注目を集めることがある。これは、まずシステムの「仕様書」を作成し、その仕様書に基づいて実際のプログラムを開発していくアプローチだ。しかし、このSDDを進める上で、「腐った仕様書」（Rotten specs）という問題が頻繁に発生すると筆者は指摘している。腐った仕様書とは、時間の経過とともに古くなったり、必要以上に複雑になったりして、むしろ開発の妨げになってしまうような仕様書や関連ドキュメントの総称である。

なぜこのような腐った仕様書が生まれるのか。その原因は、開発プロセスにおいて「知識ベース」を過剰に構築してしまうことにあると記事は述べている。OpenSpec、Spec-Kit、BMADといったツールは、SDDをサポートするために作られたものだが、これらが自動的に多くのドキュメントや関連ファイル、ディレクトリ構造を生み出してしまう傾向がある。例えば、OpenSpecは、提案書、設計書、タスクリスト、さらにネストされた仕様書といった様々なMarkdownファイルを大量に生成し、変更のアーカイブまで作成する。これらは一見すると整然とした知識の集積に見えるが、実際にはその多くが不要になり、管理が非常に困難になる。

同様に、Matt Pocock氏が提唱する「小さく、適応しやすく、構成可能な単位」というアプローチも、結局は多くのドキュメントを生み出し、独自の知識ベースを築いてしまうと筆者は指摘する。課題トラッカーのドキュメント、ドメインモデリングのためのコンテキストファイル、設計上の決定を記録するADR（Architectural Decision Record）、一時的な仕様書ファイル、チケット（課題）管理ファイル、そしてそれらをまとめるマップファイルなど、形は異なっても、やはり情報が多岐にわたり、それが積み重なっていく。

Scott Logicという会社が行った実験では、Spec-Kitを使ってわずか一つの機能開発を行っただけで、689行のプログラムコードに対して、2,577行ものMarkdown形式のドキュメントが生成されたという。しかも、これらのドキュメントのレビューには3.5時間も要したと報告されている。プログラムコード自体は変更が進んでいくにもかかわらず、大量に生成されたドキュメントは更新されずに残存し、やがて古くなり、誤った情報源となってしまう。これは、開発をサポートするはずのドキュメントが、むしろ足かせになってしまう典型的な例と言えるだろう。

このような状況は、「誰もメモリを所有しない」という問題を引き起こす。様々なツールやフレームワーク、さらには人工知能（AI）が生成したコメントやログ、課題管理システム（JiraやConfluenceなど）に情報が分散し、それらが多すぎるために、どれが最新で信頼できる情報なのかが分からなくなるのだ。筆者は自分の環境で、AIが生成した不要なメモリファイルを大量に削除したが、システムは何も壊れず、誰もその変化に気づかなかったと述べている。これは、多くの情報が実は誰も必要としておらず、誰も責任を持って管理していない状態であることを示している。

情報が複数の場所に散らばると、たとえ些細な問題であっても、解決のために複数のシステムやファイルを横断的に調べなければならなくなり、無駄な時間と労力がかかる。たとえば、プログラムコード中の記号の配置のような単純な疑問でも、複数の課題トラッカーや記憶ストア、ADRを検索しなければならない状況は、明らかに非効率的だ。この問題に対する解決策として、筆者は「一つのツール、一つの仕事」という古くからの原則が重要だと強調する。つまり、それぞれの情報や機能には、それを管理する唯一の適切な場所やツールがあるべきだという考え方である。

筆者は自身のSDD実践において、「Pi」と呼ぶ独自のシンプルかつ軽量な方法を採用している。この方法では、リポジトリに余計なファイルを追加することを一切しない。筆者のグローバルな設定ファイルであるAGENTS.mdはたった9行で構成されており、最小限の原則と環境設定のみが記述されている。そして、このPiでは、主に三つのシンプルな「スキル」を使って開発を進める。

一つ目は「Research（調査）」だ。これは読み取り専用のスキルで、与えられた問題を複数の側面から分析し、独立したサブエージェント（特定の役割を持つAI）に調査させる。その結果として、参照元を明記した調査結果を返すだけで、システムに新しいファイルを書き込むことはない。

二つ目は「Transfer（転送）」である。これは、セッション中に得られた情報、例えば調査結果や仕様書の内容などを、一時的なディレクトリにMarkdown形式の「ハンドオフ」ファイルとして書き出すスキルだ。このハンドオフファイルは、そのセッションの所有者のみが閲覧可能で、機密情報が自動的に匿名化される。そして、このスキルが実行されると、そのセッションは終了する。

三つ目は「Apply（適用）」だ。これはTransferスキルによって作成されたハンドオフファイルを受け取り、その内容を現在のリポジトリのコードベースと照合する。そして、その情報に基づいて必要最小限の変更をリポジトリに加え、リポジリに設定された自動テストやチェックを実行する。永続的に保持すべきガイダンスやルールは、すでにリポジリ内に存在する既存の指示ファイルに書き込むことで対応する。これにより、中間的な成果物がリポジトリ内に永続的に残されることはない。

もし一つの開発セッションが長くなり、人工知能モデルが処理できる情報の量（トークン数）を超えそうになった場合、筆者はTransferを実行して現状をハンドオフし、そこから新しいセッションを再開する。仕様書が完成した場合も同様に、ハンドオフを行い、使用するAIモデルの能力を一つ下のティア（例えば、高機能なOpusからよりシンプルなSonnetへ）に切り替えてApplyを行う。これにより、仕様書は一度作成され、開発プロセスで利用された後は、その役割を終えて役目を終える。このように、筆者のアプローチは、リポジトリの肥大化を防ぎ、情報の新鮮さを保ちながら開発を進めることを目指している。

結論として、筆者は、無意味な議論に時間を費やすのではなく、目の前の具体的な開発に集中することの重要性を訴える。人工知能モデルの知能は日々進化しているが、最終的な「真実の源」は常にコードベースにあるべきだという。AIエージェントが毎時間新しいバージョンになる可能性がある一方で、開発者が投資し、維持していくべきは、安定したコードリポジトリである。ソフトウェア開発の基本的なサイクルは何十年も前から存在しており、AI技術のマーケティングがそれを覆そうとしているように見えるかもしれないが、それに盲目的に従うと、「腐った仕様書」という代償を支払うことになる、と筆者は警鐘を鳴らしている。大切なのは、AIを賢く活用しつつも、人間が管理しやすいシンプルで持続可能な開発プロセスを維持することなのである。