仕様主導の開発: メリットと 3 か月間で学んだこと
3 か月が経過した時点で、追加された構造が役に立つ場合と邪魔になる場合がより明確になりました。
あるエンジニアがデータ移行の準備を進めるにあたり、作業計画に仕様駆動型開発 (SDD) を採用することにしました。 SDD は、早期にギャップを把握し、アプローチのレビューを容易にし、エージェントに明確な方向性を示すことを目的としていました。 その結果生まれた計画は詳細で、紙面上で見るとかなり理にかなっているように見えました。 作業は次のように構成されていました。
問題 → リサーチ → 仕様 → レビュー → 実装 → 検証
実装が進むにつれて、エンジニアは 2 つのジョブが競合し、重複するカスタムフィールドが作成される可能性があることに気づきました。 また、このアプローチではコードがますます複雑になり、理解しにくくなっていました。 幸いなことに、エンジニアは問題に気づき、実装を中止し、1 ページのデザイン文書を作成し、数人の同僚をタグ付けして意見を求めました。 彼らは一緒にデザインを検討し、より安全なアプローチを見つけました。
元の仕様書は、私たちが求めたことを実現していました。つまり、プロジェクトを当初の方向へと導いていました。 問題は、その方向性が間違っていたことです。 詳細な仕様のおかげで、最初のアイデアが不確かなものであっても、プロジェクトを継続しやすくなりました。 エージェントは、人々が立ち止まって疑問を投げかけるよりも速く、そのアイデアを構築することができました。
このプロジェクトは、構造を追加することによるリスクの1つを示しました。1人のエージェントが、仕様から同じ誤った前提をコードとテストに持ち込む可能性があるのです。 仕様、コード、テストは互いに一致していましたが、それは根底にある前提が正しいという意味ではありませんでした。 リスクの高い意思決定を行う場合は、誰かが元の目標に戻り、実装によって目標が損なわれる可能性がないかを確認する必要がありました。
それでも、エージェントは1回のセッションよりも長い期間にわたる作業に取り組んでおり、プロジェクトが何をしようとしているのか、その理由を維持するにはプロンプトだけでは不十分なことが多かったのです。 そこで、仕様書を中心に据えたワークフローハーネス「/spec-driven」を構築することになりました。 仕様書により、プロジェクトの方向性を次のセッションでも確認できるようになりました。 スクリプトがコンテキストを取り込み、チェックを実行しました。 実行時にルール、チェック、またはコンテキストの一部が欠けていることが判明した場合、それをワークフローに追加することで、後続のエージェントが同じ欠落に再度気づく必要がなくなります。
SDDによる構造の追加に価値があるかどうかについては、依然としてかなりの意見の相違があります。 Microsoft と AWS は SDD を推進していますが、Thoughtworks は SDD を「新興で議論の余地がある」と表現しており、実践者からは賛否両論の意見が寄せられています。 批判的な意見としては、SDD を使うとエンジニアがメンテナンスできる量を超えて Markdown が増えたり、詳細な仕様が散文で書かれたコードに変わったり、コードから乖離したシステムの別の説明が残ったりする可能性があるという指摘があります。[1][2][3]
3 か月間の実運用を経て、重要なのは SDD を使用するかどうかではなく、 そのプロジェクトにおいて、担当者が何を欠いていたかということでした。 答えは仕様書である場合もありました。 時には、より適切な例、自動チェック、またはその分野に精通したエンジニアが必要でした。
なぜ /spec-driven を開発したのか
Asana の一部のエンジニアはすでに GitHub Spec Kit と OpenSpec を試していましたが、どちらも通常のワークフローの一部にはなりませんでした。 私たちが求めていたのは、学習を進めるにつれて適応させることができ、Asana の開発プロセスに連携できるバージョンでした。
組み込みのプランモードでは、変更を加える前にコードベースを調査し、有用な実装計画を作成することがすでに可能でした。 SDD は、その計画にさらなる構造を加えました。実装と検証を通じて、問題、主要な決定事項、および受け入れ基準を常に可視化します。
実装前に、/spec-driven は問題の理解を再現し、計画を変更する可能性のある疑問点を提起しました。 これにより、エンジニアはコードを書き直す前に方向性を修正する機会を得られました。
その状態をリポジトリに保存しておけば、後のセッションで何が起こったのかを推測する必要がなくなります。 ワークフローのルールを確定的なものにしたかったため、記録とチェックはスクリプトで行いました。 モデルは、判断が役立つ部分、つまり質問をしたり、トレードオフを検討したり、意思決定を説明したりする部分を担当しました。
ワークフローにはいくつかのコマンドが含まれていました。 エンジニアは /spec-driven spec を使用して未解決の質問に対処し、仕様と実装計画を作成しました。 計画を確認した後、/spec-driven ship を使用して計画を実施し、結果を検証し、レビューのために作業を準備しました。 これらのコマンドが実行されるにつれて、ステートマシンがプロジェクトを追跡するため、後続のセッションでは、これまでに何が起こり、次に何が起こるのかを把握できます。
当初から、私たちは /spec-driven を単に仕様書を作成し、実行するための手段以上のものにしたいと考えていました。 また、エージェントワークフローをコーディネートする機能も備えてほしいと考えていました。 /spec-driven は、依存関係に基づいてタスクを並べ替え、重複するファイルの変更を別の実行ラウンドに分けて処理します。 独立した作業を複数のエージェントに並行して送信し、その結果に基づいて次に実行できる作業を決定します。
仕事の GPS のようなものです。いつでも次のステップが明確で、本当に重要な意思決定がどこで行われるのかがわかるため、行き詰まることがありません。”
Asana のエンジニアは、/spec-driven を「スペックファースト」と「スペックアンカー」の両方の方法で使用しました。 スペックファーストでは、スペックを使って方向性を決めた後、スペックの更新を停止しました。 仕様ベースのアプローチでは、作業内容が変わるたびに仕様を最新の状態に保ちました。 また、エンジニアは大規模な作業の一部に対して個別の仕様書を作成したため、チーム全体に採用を求めなくても、1 人でワークフローを使用することができました。
/spec-driven が余分な作業に見合う価値がある場合
追加された構造が最も効果を発揮したのは、重要な背景情報が、複数のセッション、引き継ぎ、または多数の関連タスクにわたって維持される必要がある場合でした。 エンジニアは計画の変更点を振り返ることができ、作業が別のエージェントセッションや担当者に移行しても、プロジェクトの方向性を確認できました。 2 つの製品開発プロジェクトでは、約 2～3 か月間、ライブスペックが維持されました。1 つは大規模な新機能の開発、もう 1 つはサブタスクの日付を親タスクに反映させる作業でした。
先ほど、仕様主導の大きなイニシアチブを終えたのですが、本当に助かりました！ 約2日間計画に取り組み、その後3日間でエンジニアリング作業をすべて完了してマージしました。”
仕様書のおかげで、引き継ぎが簡単になりました。 一時停止されたプロジェクトを引き継ぐ人は、チームが何をしようとしていたのか、なぜその形になったのか、そして何が残っているのかを確認できます。 コミットや会話からプロジェクトを再構築する必要はありませんでした。
エンジニアはまた、/spec-driven を使用して、エージェントが実行する大規模なバッチ処理を調整しました。 Asana の管理者コンソールでは、顧客企業の IT チームが組織全体のセキュリティ、アクセス、連携、共有設定を管理しています。エンジニアは、このコンソールを使用して 66 件の設定を共有フレームワークに移行しました。 それらの設定を移行するには、複数の管理者コンソールのフレームワーク間で約 150 件の移行が必要でした。 各移行はクラウドエージェント用の Asana チケットとなり、エンジニアはそれらを並行してバッチ処理し、これまでの結果に基づいて残りのチケットを更新しました。
この作業を担当したチームによると、移行の 91% はレビュー後に修正を必要とせず、全体的な工数は当初の計画よりも 1 か月以上早く完了したとのことです。
別の大規模な移行では、短いプロンプトだけで済みました。 違いは、コードベースがすでにどの程度明確にされていたかという点にありました。 エージェントが従うべき例と、結果を確認できるチェック項目が用意されていました。 管理者コンソールのエージェントは、コードからすべての要件を把握できなかったため、作業にはより明確な構造が必要でした。
/spec-driven は、プロトタイプの迅速な作成にも役立ちました。 エンジニアは、機能するエンドツーエンドのエクスペリエンスを構築するのに十分な量の未解決のプロダクトに関する質問にすばやく回答できました。 PM やデザイナーは、エンジニアが本番環境の強化に注力する前にプロトタイプを試すことができました。 エンジニアがコードを維持することにした場合、通常、マージする前に大幅なクリーンアップが必要でした。 その時点までに、プロトタイプを通じて、そのアイデアに実行する価値があるかどうかがすでにわかっています。
初期の数値が示すもの
私たちは全員に /spec-driven を一度試すよう促しましたが、継続的な使用は求めませんでした。 エンジニアの約半数が試しました。 最後の月には、毎週 30～50 人のエンジニアが使用していました。 エンジニアが直接呼び出した、組み込みのスキルと Asana が開発したエージェントスキルのうち、/spec-driven は 3 番目に多く使用されました。 継続的な使用は喜ばしいことでしたが、/spec-driven がデリバリーにどのような影響を与えたかはわかりませんでした。
エンジニアリングのスピードは、測定が難しいことで知られています。 プルリクエストや実装コードの追加は、生産性を測る指標としては不完全ですが、傾向を把握する上では有用な指標であると考えています。 速度の比較では、7 人のエンジニアと、4 か月間にマージされた 524 件のプルリクエストを対象としました。 各エンジニアが初めて明確に /spec-driven を使用する前後の作業を比較し、仕様、計画、およびその他のワークフローの成果物を除外しました。 差し戻しの比較では、ワークフローのプロジェクトファイルが変更された場合に、プルリクエストを /spec-driven と分類しました。
1 週間あたりのプルリクエスト数は 38% 増加し、実装コードの追加数は 2.66 倍に増加しました。 短期間で異常に多くのコードが追加された期間が、追加数の結果に影響を与えました。 この期間を除いても、追加数は依然として 66% 上回っていました。 明示的な差し戻し率もわずかに低くなりました。/spec-driven の作業では 1.2% でしたが、他のプルリクエストでは 1.66% でした。
コード量が増えることが必ずしもよい結果であるとは限りません。 エージェントは、より小規模な実装で十分な場合でも、大規模な実装を作成することがあります。そのため、コードの追加数の増加は、完了した作業の増加ではなく、不必要に大規模なソリューションを反映している可能性があります。 通常のレビューにより、そのような失敗モードに対するチェックが 1 つ行われました。 私たちは、問題の解決に必要なものよりも大規模または複雑な実装をレビュー担当者が指摘してくれることに頼っていました。そして、これらの変更は依然として承認されました。 これにより、過剰な実装が全体の増加をけん引しているわけではないという一定の確信が得られました。
これらの比較はコントロールされておらず、/spec-driven の影響を、プロジェクトの組み合わせやエージェントツールのより広範な改善から切り離すことはできませんでした。 こうした制約があるにもかかわらず、私たちは結果に勇気づけられました。
引き続き改善が必要な点
文書のレビューがボトルネックになる可能性がある
仕様書の作成にかかる時間は、エンジニアがその分野にどれだけ精通しているか、またプロジェクトの複雑さやリスクに応じて、30 分から数日までさまざまでした。 エンジニアは /spec-driven を使用して、エージェントに仕様書の下書きをすばやく作成させることができましたが、その確認には依然として時間がかかりました。
ある工数では、エンジニアがresearch.mdという作業用ファイルを使ってプルリクエストのレビューに何時間も費やしました。このファイルには、エージェントが仕様の下書きを作成する前に、コードベース、ドキュメント、過去の決定事項から学んだ内容が記録されていました。 その調査結果の中には、曖昧なもの、不正確なもの、あるいはわずかに間違っているものもありました。
このレビューにより、これらのファイルが一時的な作業メモなのか、それとも将来のエンジニアが信頼すべき文書なのかについて、共通認識が確立されていないことが明らかになりました。 一部のエンジニアは、意思決定の経緯が記録されていることを重視していました。 一方、不完全な調査結果をチェックインすると、それが権威あるものに見えてしまうのではないかと懸念する人もいました。
あるインフラストラクチャチームでは、仕様のレビューが実装前の新しい障害となりました。
コマンドやワークフローは、単に計画を立てて実行するよりもはるかに複雑で、時間がかかるように感じました。”
ほとんどのレビュー担当者は、長い仕様書を読んでからコードもレビューしたくありませんでした。 作業がプルリクエストの段階に達するまでに、意思決定の内容、その理由、リスクと思われる点、結果の確認方法をまとめた引き継ぎが必要でした。 方向性自体を見直す必要がある場合は、まだ変更が容易な段階で、早めにその旨を伝える必要がありました。
有用な仕様はプロジェクトの進捗に合わせて変化する
エンジニアたちは、計画を実行する中で学び続けました。 学んだことを基に仕様を更新するには、工数がかかりました。 仕様書の詳細は、エージェントが何を構築していると考えていたかを示すことで、実装作業に役立ちました。 その後、その詳細の多くはコードと重複するようになりました。
現在、私たちは、プロジェクトが不確実なうちは実用的な仕様書を充実させ、コードで実装を説明できるようになれば、仕様書を縮小すべきだと考えています。 残された部分は、次の読者が設計、重要な意思決定、制約、および未解決のリスクを理解するのに役立つものであるべきです。
仕様が完了すると、関連する疑問が生じます。完了した仕様はどうすればよいのでしょうか？ この問いに答えるのに時間がかかりすぎました。 モノレポに残しておけば見つけやすいものの、誰もオーナーでないドキュメントが残ることになります。 そこで、それらを別のアーカイブに移動することにしました。 今後も重要な情報を保持できる、より短い引き継ぎ方法が必要です。 文書によって節約されるはずの作業量よりも、文書作成にかかる作業量の方が多くなるようなら、それは役に立っていません。
ハーネスにフィードバックループを組み込む
時には、答えは別のドキュメントではなく、エージェントを取り巻くシステムの変更でした。 たとえば、/spec-drivenがMarkdownを読み取る方法にバグがありました。例の中にある見出しやチェックボックスが、実際のマイルストーンや未完了のタスクと誤認される可能性があったのです。 このバグを記録した後、/spec-driven の残りの部分を検索したところ、独自の小さな Markdown パーサーを持ち、同じ盲点を持つコマンドがいくつか見つかりました。 そこで、それらを 1 つの共有パーサーに置き換え、回帰テストとアーキテクチャチェックを追加し、修正を環境に適用しました。 OpenAI は、関連するアプローチをハーネスエンジニアリングと呼んでいます。これは、重要な知識をエージェントが見つけられる場所に置き、ルールを確実に適用できるようにし、失敗を活かしてエージェントを取り巻く環境を改善するというものです。
その他の教訓は、テストやアーキテクチャのルールにはなりませんでした。 繰り返し発生するミスをガイダンスにまとめました。 /spec-driven は、予測可能なワークフローに沿ってユーザーを誘導するため、エージェントが関連するステップに到達したときに各レッスンを表示することができました。 元のプロジェクトを超えてどの教訓を適用するかは、引き続きエンジニアが判断しました。
このガイダンスを、過去のプルリクエスト 8 件と、関連性のないアドバイスを検出するように設計された合成ケースでテストしました。 その後のテストでは、これらの過去のタスクのうち 3 つを、短いプロンプト、中程度のプロンプト、詳細なプロンプトでテストし、合計 9 つの比較を行いました。 ガイダンスは、9つの比較のうち8つで、有用な追加の質問や計画の境界を明らかにしました。 別のテストでは、さらに 3 件の過去のタスクを対象としました。 2 つの計画が明らかに改善されました。3 つ目の計画では、ガイダンスなしのエージェントがすでに問題を発見していました。
最も有用なガイダンスは、行動の変化、影響を受ける消費者とバリアント、および API、スキーマ、またはパーサー間の契約について尋ねるものでした。 評価では、質問と計画のみを対象としました。 ガイダンスによって実装が迅速化されたかどうかは測定していません。 また、範囲が狭いガイダンスはより早く古くなり、場合によっては無関係な作業で表示されることもありました。
ガイダンスと評価のメンテナンスには、初版の作成よりも多くの作業が必要でした。 ガイダンスを使って地雷を特定し、基盤となるシステムを修正して除去するか、エージェントやレビュー担当者が再び地雷を見つけなければならないリスクを受け入れるかのいずれかでした。 通常は、コストが安いため、まずマッピングを行いました。 基盤となる API、テスト、ドキュメンテーション、または例を修正するにはより多くの作業が必要でしたが、全員にメリットがあり、ガイダンスの必要性がなくなりました。
現在、/spec-driven にどのようにアプローチするか
当社は、有益な摩擦をなくすことなく、エンジニアが同じプロンプトを繰り返し、プロジェクトの説明を何度も行うことを避けたいと考えていました。 エージェントは、重要な質問がある場合、証拠が不足している場合、または次のステップで人間の判断が必要な場合にも、作業を停止する必要がありました。 そこで、いくつかの実践的なガイドラインをまとめました。
ほとんどの小規模な局所的な変更では、会話や短い計画で十分です。
方向性について合意するには、スペックファーストのアプローチを採用する。 その後のセッションや引き継ぎでも決定事項が維持される必要がある場合は、仕様を固定しておきます。
不足している情報をすべて仕様書に記載しない。 ハーネスは背景情報を提供し、チェックを実行する必要があります。アーキテクチャに関する判断は、引き続き人間によるレビューが必要です。
仕様書を維持する価値がある場合は、次の読者のために書きましょう。 意思決定事項とリスクを簡単に検索できるようにし、証拠をコピーするのではなくリンクを貼るようにし、プロジェクト終了時に仕様をどう扱うかを決定します。
今後の展望
3 か月が経過した今でも、エンジニアは、作業が複数のセッションにわたる場合、メンバー間で引き継がれる場合、または多くの関連タスクに分割される場合に /spec-driven を使用しています。 エンジニアたちは、数か月にわたるプロジェクトを滞りなく進行させたり、エージェントが実行する大量の作業を整理したりするためにこのワークフローを使用しています。 これは社内実験としてはよい結果です。
/spec-driven を拡張してより多くの種類の仕事に対応する中で、一部の新しい機能が特定のチームの抱える実際の問題を解決したものの、全員にとってワークフローがより複雑になりました。 次のバージョンでは、より小規模で、よりターゲットを絞ったコアを目指したいと考えています。
SDD とハーネスエンジニアリングについては、人によって意見が大きく分かれます。 どちらについても議論するよりも、実際の仕事で試してみることで、より多くのことを学べました。 さらにプロセスを追加する前に、そのプロジェクトでエージェントに何が不足しているのかを尋ねるようになりました。 まずは小さく始めて、ワークフローが役立つ部分と邪魔になる部分を確認し、学んだことに基づいて調整します。
[1] Birgitta Böckeler、「Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl」、2025年10月。
[2] François Zaninotto、「Spec-Driven Development: The Waterfall Strikes Back」、2025年11月。
[3] Gabriella Gonzalez、「A sufficiently detailed spec is code」、2026年3月。
著者について
Walter Li は Asana のコアストレージインフラストラクチャチームのソフトウェアエンジニアで、Rohan Batra はバックエンドフレームワークチームのソフトウェアエンジニアです。 2 人はともに数か月間、エージェントサクセス部門のタイガーチームに所属し、この記事で紹介する /spec-driven ワークフローの開発と評価を主導しました。
チームへの感謝の言葉
/spec-driven の設計と開発にご協力いただき、また早期導入者としてご活用いただいた Leo Zhang さん、Karol Krupa さん、Gordie Levitsky さん、Mitch Conquer さんに心から感謝申し上げます。