3 か月が経過した時点で、追加された構造が役に立つ場面と邪魔になる場面がより明確になりました。
あるエンジニアがデータ移行の準備を進める中で、作業計画に仕様駆動型開発 (SDD) を採用することにしました。 SDD は、早期にギャップを特定し、アプローチのレビューを容易にし、エージェントに明確な方向性を示すことを目的としていました。 その結果生まれた計画は詳細で、紙面の上ではかなり理にかなっているように見えました。 作業は次のように構成されていました。
問題 → リサーチ → 仕様 → レビュー → 実装 → 検証
実装が進むにつれて、エンジニアは 2 つのジョブが競合し、重複するカスタムフィールドが作成される可能性があることに気づきました。 また、このアプローチではコードがますます複雑になり、追跡が困難になっていました。 幸いにも、エンジニアは問題に気づき、実装を中止し、1 ページのデザイン文書を作成し、数人の同僚をタグ付けして意見を求めました。 彼らは一緒にデザインを検討し、より安全なアプローチを見つけました。
元の仕様書は、私たちが求めたことを実現していました。つまり、プロジェクトを当初の方向へと導いていました。 問題は、その方向性が間違っていたことです。 詳細な仕様のおかげで、最初のアイデアが不確かなものであっても、プロジェクトを継続しやすくなりました。 エージェントは、人々が立ち止まって疑問を投げかけるよりも早く、そのアイデアを実現することができました。
このプロジェクトは、構造を追加することによるリスクの1つを示しました。1人のエージェントが、仕様から同じ誤った前提をコードとテストに持ち込む可能性があるのです。 仕様、コード、テストは互いに一致していましたが、それは根底にある前提が正しいという意味ではありませんでした。 リスクの高い意思決定を行う場合は、誰かが当初の目標に戻り、実装によって目標が損なわれる可能性がないかを確認する必要がありました。
それでも、エージェントは1つのセッションよりも長く続く作業に取り組んでおり、プロジェクトが何をしようとしているのか、なぜなのかを維持するには、プロンプトだけでは不十分なことが多かった。 そこで、仕様書を中心に据えたワークフローハーネス「/spec-driven」を構築することになりました。 仕様書により、プロジェクトの方向性を次のセッションでも確認できるようになりました。 スクリプトがコンテキストを取り込み、チェックを実行しました。 実行時にルール、チェック、またはコンテキストの一部が欠けていることが判明した場合、それをワークフローに追加することで、後続のエージェントが同じ欠落に再度気づく必要がなくなります。
SDDによる構造の追加に価値があるかどうかについては、依然としてかなりの意見の相違があります。 Microsoft と AWS は SDD を推進していますが、Thoughtworks は SDD を「新興で議論の余地がある」と表現しており、実践者からは賛否両論の意見が寄せられています。 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 さんに心から感謝申し上げます。
