Answering Your GitHub Spec Kit Questions

前言

今天我不會繼續講解更多 Spec Kit 功能和變更,而是專注在回答你們的問題。關於 Spec Kit 演進的影片獲得了很多關注,收到許多留言。我認為透過影片來回答會更好,讓未來使用這個工具的開發者、產品經理、設計師、資料科學家都能受益。

規格文件更新與版本管理

如何處理規格文件的更新?

Bobby Wang0120 的提問:感謝影片和 Spec Kit。快速問題:你在多次迭代後會在規格文件末尾加入學習心得。計畫、任務和其他空白檔案可能會與實際交付的內容產生差異。你會更新這些檔案還是保留歷史記錄?在你看來,工作完成時應該只更新規格文件還是所有文件?

我的工作流程是這樣的:我會把規格本身作為唯一的真實來源,除非我要對特定實作細節進行變更。舉例來說,如果我要為網站設計新的首頁,我已經做了某些設計決策、版面配置等決定,有些決定會在事後才出現--你已經開始規格化,已經開始實作,然後突然意識到,噢,我忘記加入見證列表、聯絡表單或訂閱電子報的區塊。

規格文件的持久性

你當然會請 LLM 去建立這個功能,但這不在你的初始規格中。我通常會這樣做:知道很多這些東西我未來會重複使用。例如我在先前影片提到的,如果我決定更換靜態網站產生器或後端,我仍然希望有一份規格書作為真實來源,反映我對最終輸出的意圖。

在這種情況下,我會請 LLM 將對話和情境中的學習心得編碼到規格書中。有些學習心得也可以編碼到計畫中。我個人認為規格書是所有文件中最持久的產出,因為計畫會改變。計畫檔案是技術規格,定義 API 的形式、使用的框架、資料庫。這些都可能改變。

更新策略

如果你沒有改變這些,可以保持計畫原樣,只更新規格書。如果你發現選擇的資料庫不太適合--無法使用 SQLite,實際上需要使用雲端託管的文件資料庫--那當然也要更新計畫。但我傾向在整個過程中持續更新它們,因為你說得對,會有很多地方規格不足,我會在事後才發現它與最初設想的差異相當大,因為我沒有問到我以為會問的問題。

保持更新通常是個好主意,但從優先順序來看,我會說規格文件和 constitution 可能是最重要的。實作計畫和任務通常是技術計畫的反映,所以你可以直接刪除任務,根據需要重新建立。

多專案儲存庫架構

團隊使用不同儲存庫的案例

Carlos Pravia 4967 的提問:我們團隊傾向使用不同的 git 儲存庫來開發應用程式的不同部分。例如,一個儲存庫實作應用程式邏輯和端點,另一個處理客戶端和 UI,也許還有一個用於部署 GraphQL 和維護其他類型的資料查詢。在這種情況下,你會建議每個儲存庫使用一個 Spec Kit 來以模組化和安全的方式定義、精煉和測試這些元件嗎?也許讓不同的團隊成員專注在應用程式的該部分,然後有另一個儲存庫維護高階規格。你如何整合並維護這些元件之間的一致性?

單一儲存庫的優勢

這是個有趣的問題,因為在我們目前的範例中,都是關於一個儲存庫。當你在一個儲存庫中操作時,事情相對受限且容易管理。如果你使用內建的 Spec Kit 範本,會注意到使用 specify 命令時,它會在該儲存庫內建立一個新分支。

該分支會包含一個基於 constitution 編碼的範本版本,會有規格版本,以及該特定迭代中可能包含的任何其他內容。

跨儲存庫的挑戰

如果有共享的規格儲存庫,那麼你需要從其他儲存庫交叉參照它。如果你有 7、10、15 個不同的儲存庫,那麼核心規格儲存庫如何被包含進來?是作為子模組嗎?你可以這樣做,但這只是增加了管理程式碼的複雜性。

推薦方案

從我的觀點和個人實驗來看--再次強調,請持保留態度,因為可能不適合每個情境--我發現在一個儲存庫內使用一個 Spec Kit 部署(基本上就是為特定專案在一個儲存庫中進行初始化)是最有幫助的,因為工作被包含在該儲存庫中,管理起來比跨多個儲存庫容易得多。

共享內容的處理

話雖如此,你可以有共享的內容。例如,如果你有定義組織內如何建立 Web 應用程式的 constitution,那麼該 constitution 可以透過 git 子模組引入。這似乎相當容易設定且可重複使用。

但有些東西可能不太適合,因為你為一個儲存庫建立的某些規格並不真的適用於另一個。如果你有一個用於行動應用程式的儲存庫,另一個用於 Web 應用程式,那麼這些規格範本甚至已經存在的規格集可能沒有價值去匹配它們,除非你在討論特定的 API 設計文件。

所以我會說這真的取決於工作流程,但我個人發現每個儲存庫的 Spec Kit 配置比擁有一個共享的效果更好,除非你絕對需要。然後你可以再次使用 git 子模組之類的工具來建立這種基礎設施,確保內容在儲存庫之間實際共享。

重構與功能遺失處理

重構過程中的問題

Suzie Q codes 的提問:很棒的影片。我加入到現有專案並用它來幫助重構一個單體的 page.tsx TypeScript 元件。看起來進展很順利,但當它做了一些變更時,我注意到它丟失了一些先前的功能。我使用 Cursor。我問了幾個問題,它立即開始進行更多程式碼變更,即使我們還沒有規格化這些變更--這確實有道理。如果你疏忽了某些東西,它開始建立新檔案然後你發現了,捕捉正確的規格、研究、任務的最佳流程是什麼?我不得不回退並撰寫新規格,即使規格一還沒有正確完整實作,還是規格二會處理第一個分支中發生的事情?

使用 Git 的重要性

這是個有趣的情境。我認為如果我解開這個說明,基本上是你已經啟動了一個專案,有了規格書,完成了規格流程,然後發現 Cursor 開始有點偏離軌道,自己建立了你沒要求的東西,所以你需要去移除這些檔案。

我開始做的事情--這就是為什麼使用 git 如此重要,使用原始碼控制非常非常重要--我的方法是:當我開始處理新功能、新元件或錯誤修復並使用 Spec Kit 時,使用 slp specify 當然會建立新分支,這讓事情變得很簡單。

Git 客戶端的使用

我也使用 git 客戶端,像是 GitHub Desktop、Sublime Merge 或 Git Kraken。任何一個都很好,就像冰淇淋一樣,取決於你的偏好和你實際喜歡什麼。

迭代過程中的管理

但我開始做的是:當我進行這個迭代過程,特別是一旦進入實作階段,事情可能會變得有點模糊,因為有些東西你在初始規格和初始提示中沒有指定,然後你必須去覆蓋它。有時它確實會偏離軌道,開始建立新檔案,建立你沒要求的體驗。

回退策略

讓你回退的最簡單方法是:首先編碼你想要的需求。你發現了,比如「我不想在我的網站上有頁尾變更的元件」。那很好,你把它編碼到規格書中,然後你去你使用的 git 客戶端,因為你已經在一個分支上操作。選擇那些尚未提交的檔案--因為我們在使用 git,不會自動提交每個變更,而是批次處理--你可以直接捨棄那些變更。

規格可以保持不變,規格文件在那裡,確保它實際上已經檢入分支並提交推送。然後程式碼變更是靈活的。如果你看到它偏離軌道,只需更新規格,捨棄檔案的變更,然後使用規格重新進行建立過程。

核心建議

對我來說,最簡單的方法就是大量依賴實際的 git 工作流程。超級重要。我認為如果有一件事我鼓勵那些試圖使用 Spec Kit 的人,那就是非常熟悉 git 的運作方式、分支如何運作,以及如何暫存變更並迭代它們,而不必擔心一個失控的代理會偏離軌道,因為它決定以不同方式設計某些東西,現在你必須去展開並找出所有出錯的地方以及程式碼變更是什麼。

使用 git,在你迭代時經常提交有效的東西,確保你在我們預設為你建立的分支上用 git 追蹤它,然後利用這一點。這將是我的方法,這是管理它的最簡單方式。

規格重用與專案重構

跨技術棧的規格重用

griff.an 的提問:你提到未來重構網站的可能性,並能夠簡單地重用規格,因為它不包含技術實作細節。這樣的流程會如何運作?代理會逐一檢視每個功能規格,包括分支,如果你要建立一個只有 constitution 和規格的新空專案?

網站的歷史背景

這很有趣,因為這是接在上一支影片之後,我展示了為網站加入閱讀清單。挑戰在於,當我最初啟動網站時,我當然沒有使用 Spec Kit。網站是基於我自己的部落格習慣、配置開始的,我實際上在 Congo 模組上撰寫了一些自訂範本。這全都基於 Hugo 靜態網站產生器。

棕地專案的限制

在這個功能的情境下,不是所有東西都會從頭重建,因為這不是所謂的綠地專案。這不是我從零開始用 Spec Kit 建立所有產出的專案。除非我回頭說「這是首頁的結構、關於頁面的結構、部落格文章頁面的結構」,所有這些當然不會被重建。

使用 Spec Kit 建立的功能

但對於使用 Spec Kit 建立的功能、使用 Spec Kit 建立的錯誤修復、任何實際編碼在規格檔案中的內容,我都可以重建。你可以想像,如果我某個時候決定不使用 Hugo 而改用 Jekyll,Jekyll 使用不同的範本引擎,我沒有相同的能力直接擁有內建的閱讀清單頁面,我可以直接請我當時使用的任何程式碼代理根據該規格重建。

規格即可執行產出

在我操作的程式碼庫情境中,它會繼續重建。當然,它不會重建所有東西,當然會有很多變異性,但這就是方法。你基本上可以將實作與規格分離,這就是規格的價值所在,因為規格本身成為--我想稱之為可執行產出。規格變成程式碼,因為我可以把它丟進 LLM 並說「在我正在操作的情境中建立這個」。

綠地專案的完整重建

如果你從頭開始建立專案,那是一個全新的應用程式--比如一個 SaaS 業務、SaaS 應用程式--然後你將所有東西編碼在規格中,每個功能都是規格,你的首頁、結帳頁面、使用者個人資料頁面,那麼當然,因為你有這些產出,未來你可以用不同的框架、不同的工具集、不同的資料庫等重建。但這取決於專案。如果是棕地專案,那當然會取決於在規格中編碼先前的資訊。

測試驅動開發的權衡

TDD 的挑戰

Alpara Manalp 2933 的提問:感謝你的努力。Spec Kit 的主要問題是 TDD 或測試驅動開發。我認為如果你在 constitution 中放入非 TDD 方法會更出色。我對 TDD 沒有意見,但在智慧情境中,昂貴的 token 等方面,我們還沒到那個階段。

當前的 TDD 實作

是的,我知道,我正在積極處理這個問題。對於不知道的人來說,如果你使用內建範本,我們在其中編碼的其中一件事就是測試驅動開發方法。所以任何新專案、任何新功能開始時,它實際上會說「你需要建立測試」。正如你在我上一支影片中看到的,我談到在我自己的網站上使用這個的可能性--我不需要測試。我只是建立基於現有專案的東西,我只想要網站的新頁面,對吧?測試可能非常非常繁重且耗時,也消耗情境,因為建立它只是一個巨大的痛苦。

即將推出的改進

所以是的,完全承認這是個問題。它即將推出,我們將有一個無 TDD 的選項,然後你可以根據需要加入測試驅動,但它不會預設內建,因為是的,我同意這有點繁重,並不真的適合每個情境。我會說甚至實際上對於大多數非常快速的原型迭代情境--我不需要測試,只要給我產品。我想看到它,我想在螢幕上看到它,我想能夠與它互動,而不用擔心建立了哪些測試,因為所有這些東西稍後都可以為更嚴肅的企業專案加入。

觀點接受了,非常感謝回饋。

在現有專案中加入功能

非 Spec Kit 專案的整合

ninjatronics 的提問:那麼為我沒有用 Spec Kit 啟動的現有網站加入功能的正確方法是什麼?

這跟我在先前影片中做的完全一樣。你看到的網站,我維護的部落格,我自己的部落格實際上不是用 Spec Kit 建立的。我從 2017 年左右開始用 Hugo 以目前的形式維護它,更早之前超過十年因為我之前使用 WordPress--它不是用 Spec Kit 建立的。這是一個自訂主題,我使用 Spec Kit 在其上建立。

提供情境的技巧

你可以使用不同的技術來實際建立程式碼庫的情境。人們一直在使用 claude.md 來提供該情境。順便說一下,當你使用 Spec Kit,特別是其中一個命令會初始化該代理檔案時(如果它不存在的話),它會編碼一些決策。但如果你已經有一個,那你可以用它來提供關於專案結構、元件、如何運作、如何建立的情境。

這將允許 LLM 在你建立新功能時使用該情境來實際理解關係,並知道「噢,如果我要建立新的頁尾,我需要在這裡的元件資料夾中尋找這個 tsx 檔案,那將是我的頁尾」。

綠地與棕地專案的差異

這個流程與任何綠地專案沒有太大不同,你最大的瓶頸真的是盡可能提供關於你的專案、你正在建立什麼以及你之前如何建立它的情境,這樣當你開始規格化新東西時,它有那個情境,然後你可以用它操作並說「我知道在哪裡尋找元件」。

現代模型的能力

話雖如此,根據我的經驗,取決於專案的複雜性,LLM,特別是現代模型非常擅長動態推斷這個情境。作為實驗,你知道,我在先前影片中向你展示了閱讀頁面,但我之前也做過的一件事是要求它建立一個我可以嵌入特定頁面類型的新元件,一個 Podcast 播放器,一個新元件。

它實際上會掃描資料夾內的元件定義並說「好的,讓我看看所有這些元件是如何定義的。讓我看看 Podcast 元件可能在哪裡」。它建立得相對不錯。我會說當然有差距,作為工程師的你會掌控並說「你實際上看錯資料夾了,因為這是編譯的元件,不是實際定義的元件」。所以你仍然需要注意這些事情。但我注意到這變得更好了。

主動提供情境的好處

但我會說如果你提前主動提供情境,通常效果會好得多,在任何新功能迭代上都是如此。

Monorepo 架構的考量

簡單案例的適用性質疑

AOSF 的最後提問:對於簡單的使用案例,大多數 Web 開發者在沒有 AI 或簡單 AI 輔助的情況下花費的時間會少得多。對於複雜的使用案例,不確定 constitution 如何適應包含後端、前端、資料庫檔案和其他文件的單一儲存庫。

承認範例的簡單性

你完全正確。我展示給你看的範例--再次強調,如果錯過了先前的影片,去看看--是我為部落格加入閱讀清單頁面。這是一個相對簡單的使用案例,我會說如果你是對 CSS、JavaScript 和 Hugo 範本感到自在的人,當然,是的,我本可以不用 AI 建立這個,這只是一個示範。

同時,我會說它展示了該流程如何運作。對於你提出的複雜使用案例,你知道有一個包含一堆其他不一定綁在一起的東西的 monorepo,這確實變得有點棘手,因為你有一個 .specit 資料夾,其中包含範本和通常其他所有東西--如果你定義 constitution,constitution 會綁定到 .specit 資料夾,該 .specit 資料夾現在直接嵌入到你操作的情境中。

未來的改進方向

我們現在正在研究的是如何適當地分割它,這樣你可以為後端有一個 .specit 資料夾,為前端有一個 .specit 資料夾,為 API 監控解決方案有一個 .specit 資料夾等等。基本上給你細粒度控制,這樣你仍然在你應該有的任何代理資料夾內編碼命令、自訂斜線命令,因為它們是通用的--斜線 specify 是相同的。如果你使用斜線 clarify,它是相同的。無論你在哪個專案上使用,命令本身都完全相同。

多 .specit 資料夾的願景

但改變的是 constitution 的格式、規格的格式、需求。正如我們剛才談到的測試驅動開發,有些需要測試,有些不需要。所以你可以在這些不同的專案中有多個 .specit 資料夾,然後在這些資料夾內照常使用專案的提示。我們現在正在測試這個,會有一個記錄的方法讓它更簡單一點,因為 monorepo 是一回事。我們知道這是一回事,我們知道必須實際涵蓋它。

並非所有情境都相同

所以不是的,不是每個情境都會是這種非常原味、非常受限的 GitHub 環境,像是一個儲存庫一個專案。是的,我們知道它即將推出,會被記錄下來。你會在接下來的其中一支影片中看到這個。我很興奮向你展示我們的進展。

結語

這就是今天的問題。請持續關注下一支影片。我有更多內容即將推出,Spec Kit 會有更多更新。我很興奮看到你們所有人測試它、將它推向極限、提供這麼多回饋。

請前往 github.com/github/spec-kit 提供你的回饋,參與討論。我毫不誇張地說,我很興奮--我不會輕易使用這個詞--我很興奮很快為你帶來更多 Spec Kit 的好東西。到時見。