規格導向的開發：優點以及我們在三個月後學到的內容
三個月後，我們更清楚地瞭解了新增的架構在何時有幫助，以及在何時成為阻礙。
我們的一位工程師正在準備資料遷移，並決定使用規格導向開發 (SDD) 來規劃工作。 SDD 的用意是幫助他們及早發現疏漏，使方法更易於審查，並為客服人員提供明確的方向。 最終的計劃非常詳細，從紙面上看來相當合理。 它將工作組織如下：
問題 → 研究 → 規格 → 審查 → 實施 → 驗證
隨著實施工作的推進，工程師意識到兩個工作可能會發生競爭，從而建立重複的自訂欄位。 這種方法也使程式碼變得越來越複雜，難以理解。 幸運的是，他們發現了這個問題，停止了實施，撰寫了一份一頁的設計文件，並標記了幾位同事以徵求意見。 他們一起梳理了設計，並找到了更安全的方法。
原始規格達成了我們所要求的效果：它讓專案繼續朝著原來的方向前進。 問題在於方向不對。 即使最初的想法不夠穩固，詳細的規格也能讓專案輕鬆地繼續進行。 代理程式可以比人們停下來質疑的速度更快地發展這個想法。
該專案顯示了增加結構的一個風險：一個代理人可能會將規格中的同一個錯誤假設帶入程式碼和測試中。 規格、程式碼和測試彼此一致，但這並不代表潛在的假設是正確的。 對於風險較高的決策，仍需要其他人回溯原始目標，並尋找實施方式可能違反該目標的地方。
儘管如此，代理程式仍會承接持續時間超過一個工作階段的工作，而提示通常不足以保留專案的目標或原因。 這促使我們構建了 /spec-driven，這是一個以規格為核心的工作流程框架。 規格讓專案的方向在下一個工作階段中仍可供參考。 指令碼引入情境資訊並執行檢查。 當執行時發現缺少規則、檢查或情境資訊時，我們可以將其新增至工作流程中，這樣後續的代理程式就不必再次發現相同的缺漏。
關於 SDD 新增的架構是否值得，仍存在相當多的分歧。 Microsoft 和 AWS 推廣 SDD，而 Thoughtworks 則將其描述為新興且有爭議的，從業人員則表示有正反兩面的經驗。 批評者警告，SDD 可能會產生超出工程師維護能力的 Markdown 數量，將詳細的規格轉換為以散文形式撰寫的程式碼，或者留下與程式碼不符的系統描述。[1][2][3]
經過三個月的實際使用後，我們了解到，重要問題並非是否要使用 SDD。 而是服務專員在該專案中缺少什麼。 有時候，答案就是規格。 有時候是更好的範例、自動化檢查，或者是熟悉該領域的工程師。
我們為什麼建立 /spec-driven
Asana 的一些工程師已經嘗試過 GitHub Spec Kit 和 OpenSpec ，但兩者都沒有成為他們日常工作流程的一部分。 我們希望有一個版本，能夠隨著我們的學習而進行調整，並與 Asana 的開發流程相連結。
內建的計劃模式已經可以在進行變更之前研究程式碼庫，並產生有用的實作計劃。 SDD 為該計劃增加了更多結構：它在實作和驗證過程中使問題、關鍵決策和接受標準保持可見。
在實施之前，/spec-driven 會回顧其對問題的理解，並提出可能改變計劃的問題。 這讓工程師有機會在需要重寫程式碼之前修正方向。
我們將該狀態儲存在儲存庫中，這樣後續的會議就不必猜測發生了什麼事。 我們希望工作流程的規則是確定性的，因此由指令碼負責帳目管理和檢查。 該模型處理了需要判斷的部分：提問、權衡取捨以及解釋決策。
工作流程包含多個指令。 工程師使用 /spec-driven spec 來解決未決問題，並制定規格和實施計劃。 在審查計劃後，他們使用 /spec-driven ship 來實施計劃、驗證結果，並準備工作以供審查。 狀態機器會追蹤專案在執行這些指令時的進展，因此後續的階段就能知道發生了什麼事，以及接下來的步驟。
從一開始，我們就希望 /spec-driven 不僅僅是撰寫和執行規格的一種方法。 我們也希望它能夠協調代理式工作流程。 它會依據相依性對任務進行排序，並將重疊的檔案變更保留在不同的執行回合中。 它會將獨立的工作同時傳送給多個代理程式，然後根據結果決定接下來可以執行哪些工作。
感覺就像工作的 GPS：在任何時候都能清楚瞭解下一步是什麼，以及真正需要做出決策的地方在哪裡，因此很難遇到瓶頸。”
Asana 的工程師以「規格優先」和「規格錨定」兩種方式使用 /spec-driven。 在「以規格為先」的情況下，他們使用規格來選擇方向，然後停止更新規格。 在以規格為錨點的情況下，他們會隨著工作的變更而保持規格的最新狀態。 工程師還為較大投入量的部分撰寫了獨立的規範，因此一個人可以使用工作流程，而無需要求整個團隊採用。
/spec-driven 值得額外付出的情況
當重要情境資訊需要跨工作階段、交接或許多相關任務時，新增的結構最能發揮作用。 工程師可以檢閱計劃的變更方式，當工作移至另一個代理程式工作階段或人員時，專案的方向仍可供參考。 兩個產品投入量大約有兩到三個月的時間持續維護動態規格：一個是建置一個重大的新功能，另一個是將子任務日期向上推移至上層任務。
我剛完成一項以規格為導向的較大型計劃，我覺得這對我幫助很大！ 我花了大概兩天的時間來制定計劃，然後在三天內完成了所有工程工作並進行合併。”
規格讓交接變得更輕鬆。 接手暫停專案的人員可以瞭解團隊試圖做什麼、為什麼會變成那樣，以及還有哪些工作待完成。 他們不必從提交內容和對話中重建專案。
工程師還使用 /spec-driven 來協調大量由代理程式執行的工作。 在 Asana 的系統管理主控台中，客戶公司的 IT 團隊負責管理整個組織的安全、存取、整合和分享設定，工程師使用該主控台將 66 項設定移至共用架構。 移動這些設定需要跨多個系統管理主控台架構進行大約 150 次遷移。 每個遷移都成為雲端代理程式的 Asana 支援單，工程師以平行批次的方式執行這些遷移，並根據先前的結果更新剩餘的支援單。
負責此項工作的團隊報告稱，91% 的遷移在經過審查後無需修改，且整體投入量比原計劃提前了一個多月完成。
另一個大型遷移只需要一個簡短的提示。 兩者之間的差異在於程式碼庫已經清楚呈現的程度。 其中包含代理程式可以遵循的範例，以及可以驗證結果的檢查。 系統管理主控台的代理程式無法從程式碼中弄清楚每項需求，因此該工作需要更嚴密的結構。
/spec-driven 也對快速原型製作有所幫助。 工程師可以快速回答足夠的開放式產品問題，以建立可運作的端到端體驗。 在工程師投入生產強化之前，產品經理和設計師可以先試用原型。 如果工程師決定保留該程式碼，通常需要進行大量清理才能合併。 到那時，原型已經顯示出該想法是否值得推進。
早期數據顯示的結果
我們鼓勵大家嘗試一次 /spec-driven，但並不要求持續使用。 大約有一半的工程師試用過。 在最後一個月，每週使用人數介於 30 至 50 名工程師之間。 在工程師直接呼叫的內建和 Asana 開發的代理程式技能中，/spec-driven 排名第三。 持續使用令人鼓舞，但這並未告訴我們 /spec-driven 如何影響交付。
工程速度眾所周知難以測量。 提取請求和實作程式碼的新增並非衡量生產力的完美指標，但我們認為它們通常是具有方向性的有用指標。 為了比較速度，我們觀察了七名工程師和四個月內 524 個已合併的提取請求。 我們比較了每位工程師首次明確使用 /spec-driven 之前和之後的工作，並排除了規格、計劃和其他工作流程產物。 針對還原比較，當提取請求變更工作流程的專案檔案時，我們會將其歸類為 /spec-driven。
每週的提取請求增加了 38%，而實作程式碼的增加量則成長了 2.66 倍。 一個短暫且異常高量的時間段影響了新增的結果。 即使沒有它，新增量仍高出 66%。 明確還原率也略低：/spec-driven 工作的比例為 1.2%，而其他提取請求的比例為 1.66%。
程式碼越多不一定就是好結果。 當較小的實作就能滿足需求時，專員可能會產生較大的實作，因此程式碼新增量的增加可能反映的是不必要的大型解決方案，而非更多已完成的工作。 一般審查為我們提供了一次針對該失敗模式的檢查。 我們仰賴審查人員來標記比問題所需更大或更複雜的實作，而這些變更仍通過審查。 這讓我們有了一些信心，認為過大的實作並非導致整體增加的原因。
這些比較並未受到控制，我們無法將 /spec-driven 的影響與專案組合或代理程式工具的更廣泛改進區分開來。 即使有這些限制，我們仍對結果感到鼓舞。
仍需改進之處
審閱文件可能會成為瓶頸
建立規格所需的時間從 30 分鐘到數天不等，具體取決於工程師對該領域的熟悉程度，以及專案的複雜性和風險。 工程師可以使用 /spec-driven 來讓代理程式快速撰寫規格草稿，但審核草稿仍需要時間。
在一次投入中，一名工程師花了幾個小時審查一個包含 research.md 的提取請求，這是代理程式在草擬規格之前記錄從程式碼庫、文件和先前決策中學到內容的工作檔案。 其中一些發現模糊不清、不夠精確或略有錯誤。
該審查顯示，我們尚未就這些檔案是臨時工作備註，還是未來工程師應予信賴的文件達成共識。 有些工程師重視決策過程的記錄。 其他人則擔心，提交不完善的研究內容會讓人誤以為具有權威性。
在一個基礎架構團隊中，規格審查成為實施前的一個新阻礙。
我認為指令和工作流程感覺比單純制訂計劃然後執行複雜得多，也耗時得多。”
大多數審查人員都不想閱讀冗長的規格，然後還要再審查程式碼。 當工作進展到提取請求時，交接內容需要總結決策、我們做出決策的原因、哪些方面看起來有風險，以及我們如何檢查結果。 如果方向本身需要審查，我們需要更早提出要求，因為那時還可以輕鬆變更。
有用的規格會隨著專案的進展而變化
工程師在實施計劃的過程中不斷學習。 根據他們所學到的內容更新規格需要投入量。 其詳細資料透過顯示代理程式認為正在建置的內容，在實施過程中提供了幫助。 之後，許多詳細資料都與代碼重複。
我們現在認為，在專案尚不確定時，實用規格應該要擴展，而一旦程式碼能夠解釋實作內容，則應縮減。 留下來的內容應該有助於下一位讀者了解設計、重要決策、限制和未解決的風險。
已完成的規格引發了一個相關問題：應該如何處理這些規格？ 我們花太久時間才回答這個問題。 將它們留在單一儲存庫中，可以讓它們易於查找，但也留下了沒有人負責的文件。 我們正將它們移至單獨的封存中。 我們仍然需要更簡短的交接方式，以便保留之後重要的內容。 如果某份文件所產生的工作量多於它所節省的工作量，那麼它就沒有幫助。
將回饋循環納入架構中
有時候，答案並不是另一份文件，而是對代理程式周圍系統的變更。 其中一個例子是 /spec-driven 讀取 Markdown 的方式存在錯誤：範例中的標題和核取方塊可能會被誤認為是實際的里程碑或未完成的任務。 記錄錯誤後，我們搜尋了 /spec-driven 的其餘部分，並發現幾個具有各自小型 Markdown 解析器的命令，且存在相同的盲點。 我們用一個共用的剖析器取代了它們，新增了迴歸測試和架構檢查，並將修復程式放入環境中。 OpenAI 將相關方法描述為「Harness 工程」：將重要知識置於代理程式可以找到的地方，使規則具有可執行性，並利用失敗來改善代理程式周圍的環境。
其他經驗教訓無法成為測試或架構規則。 我們將經常發生的錯誤歸納為指引。 由於 /spec-driven 會引導使用者完成可預測的工作流程，因此當代理程式到達相關步驟時，我們就可以顯示每個經驗教訓。 工程師仍決定哪些經驗教訓適用於原始專案之外。
我們針對八個歷史提取請求測試了該指引，並搭配旨在捕捉不相關建議的合成案例。 在後續工作中，我們使用簡短、中等和詳細的提示測試了其中三項歷史任務，總共進行了九次比較。 在九次比較中有八次，指引提出了有用的額外問題或規劃界限。 一項單獨的測試涵蓋了另外三項歷史任務。 它明顯改善了兩個計劃；在第三個計劃中，沒有使用指引的代理程式已經發現了問題。
最有用的指引詢問了行為變更、受影響的消費者和變體，以及 API、架構或剖析器之間的合約。 評估僅涵蓋問題和計劃。 我們並未衡量指引是否加快了實施速度。 狹義的指引也會更快過時，有時還會在不相關的工作中出現。
維護指引和評估所需的工作量比建構第一版還要多。 我們可以透過指引來標記地雷，透過修復基礎系統來清除地雷，或者接受代理程式或審查人員必須再次找到地雷的風險。 我們通常會先標記，因為這樣比較便宜。 修復基礎的應用程式開發介面 (API)、測試、文件或範例需要更多工作量，但對所有人都有益，且不再需要指引。
我們現在如何採用 /spec-driven 方法
我們希望阻止工程師重複相同的提示，並在不消除有益的阻力情況下重新解釋專案。 當代理程式遇到重要問題、缺少證據或下一步需要人為判斷時，仍需要停下來。 我們總結出幾項實用準則：
對於大多數小型、局部的變更，對話或簡短的計劃就已足夠。
使用「先有規格」來就方向達成共識。 當決策必須在後續會議或交接中延續時，請讓規格始終保持穩定。
不要將所有缺少的資訊都寫入規格中。 Harness 應提供情境資訊並執行檢查；架構判斷仍需要人為審查。
當規格值得維護時，請為下一個閱讀者撰寫。 讓決策和風險易於找到，連結至證據而非複製證據，並決定專案結束時應如何處理規格。
這次課程之後可以
三個月後，當工作跨越多個工作階段、在人員之間傳遞或分解為多個相關任務時，工程師仍會使用 /spec-driven。 他們已將其用於持續推進為期數月的專案，並組織大量由代理程式執行的工作。 對於內部實驗來說，這是一個不錯的結果。
隨著我們擴展 /spec-driven 以支援更多類型的工作，一些新功能為特定團隊解決了實際問題，但卻使所有人的工作流程變得更加複雜。 在下一個版本中，我們希望朝向更精簡、更專注的核心邁進。
人們對 SDD 和 Harness 工程都有強烈的看法。 與其對其中任何一種進行辯論，我們透過在實際工作中嘗試它們來瞭解更多資訊。 在新增更多流程之前，我們現在會詢問代理程式在該專案中缺少哪些內容。 從小處著手，觀察工作流程在哪些方面有幫助或造成阻礙，然後根據您所學到的內容進行調整。
[1] Birgitta Böckeler，《瞭解規格導向開發：Kiro、spec-kit 和 Tessl》，2025 年 10 月。
[2] François Zaninotto，《規格導向開發：瀑布式開發的反擊》，2025 年 11 月。
[3] Gabriella Gonzalez，《足夠詳細的規格就是程式碼》，2026 年 3 月。
關於作者
Walter Li 是 Asana 核心儲存基礎架構團隊的軟體工程師，Rohan Batra 是後端架構團隊的軟體工程師。 兩人均在 Agent Success Tiger 團隊中參與了數月的工作，負責領導本文所述的 /spec-driven 工作流程的開發和評估。
團隊感謝名單
特別感謝 Leo Zhang、Karol Krupa、Gordie Levitsky 和 Mitch Conquer 協助我們塑造和開發 /spec-driven，並成為早期使用者。
