規格優先交付的知識系統就緒度

共享知識系統涵蓋軟件交付所依賴、彼此相連的組織知識，支援討論、規格、實作、驗證、驗收，以及日後延續產品交付。對既有產品來說，下一個問題十分實際：在合資格人員或 AI 系統能夠依靠這套知識系統工作之前，團隊要先準備好甚麼？

本文界定這套就緒基準，並提出建立基準的實務方法。後續文章會分別深入討論產品意圖、使用者角色與參與者、穩定使用案例、產品術語與資料語義、產品架構、常設要求、專業職能要求，以及管治指示。

目標是確保所有足以影響決策的重要知識都有清楚的權威來源，相關參與者可以取得並與目前實作互相核對。如果知識不完整或出現爭議，參與者也應知道要把問題交由哪個具備相應專業決策權限的角色處理。

返回頁頂

1. 知識系統就緒度：定義與驗收條件

知識系統就緒度，是指合資格參與者能夠取得履行某項責任所需的產品知識、實作證據、適用限制條件和決策路徑。

就緒度是整個產品交付系統的特性，反映系統是否具備足夠條件，讓參與者負責任地工作，而不是只衡量某一份文件的品質。產品知識可以存放在原始碼儲存庫、按既定管治程序管理的文件平台、架構儲存庫、服務目錄、管控系統、知識圖譜，或其他持續維護的來源。關鍵在於參與者是否知道哪個來源對某個主題具權威性，能否透過日常工作的實際途徑取得內容，以及當現有知識不足時，能否找到真正有權作出決定的人。

一項實用的驗收方法，是不熟悉產品的參與者測試：

如果一名合資格但過往未接觸該產品的參與者，能夠就指定責任掌握產品基本情況、找到並運用相關權威知識和限制條件、把這些資料與目前實作互相核對，並把尚未解決的重大問題交由正確決策負責人處理，知識系統就已具備足以支援這項責任的就緒度。

這名參與者可以是剛加入團隊的工程師、暫時接手陌生範疇的產品負責人、審查某項依賴的架構師、套用產品常設要求的專業人員，或剛開始執行獲授權工作的 AI 程式開發代理。這項測試必須按角色進行，因為不同參與者需要掌握的知識不同，擁有的決策權限亦不同。

一項紮根理論研究追蹤 18 名分別加入 18 個軟件項目的新參與者，分析哪些因素有助或妨礙他們熟悉項目環境。研究指出，早期嘗試、逐步掌握項目結構與文化，以及驗證進展，都是融入過程的重要因素。¹ 不熟悉產品的參與者測試把這個較廣泛的融入問題，收窄到一項明確的交付責任：合資格參與者能否了解產品、取得並運用所需知識，再把尚未解決的問題交由正確負責人處理。

作為實務基準，知識系統至少應讓參與者回答以下問題：

• 產品為何存在、誰會使用，以及哪些穩定成果或使用案例即使局部實作改變也應繼續成立？

• 目前系統如何組成、哪些元件或團隊各自負責甚麼，以及哪些依賴和介面與目前工作有關？

• 哪些產品常設要求，以及安全、私隱、可靠性、營運、資料、無障礙、相容性、本地化或其他要求適用？

• 目前實作在哪裡？合資格工程師如何檢查、配置、建置、執行，或以其他實際方式驗證相關基準？

• 哪些管治指示適用於參與交付工作的人員與 AI？

• 每個重大主題應以哪個來源為權威依據？參與者實際可以透過甚麼途徑取得它？

• 當知識缺失、互相矛盾、無法存取或已經過時時，誰有權作出決定？

這個基準應按相稱原則套用。團隊要根據每項責任和擬進行的工作，判斷真正需要哪些知識、實作證據、存取途徑、限制條件和決策。例如，缺少一項無障礙要求，可能完全不影響後端重構，卻足以令使用者介面變更無法負責任地繼續。

找出的缺口本身也是重要知識，應該明確記錄。團隊可以在相關工作開始前直接解決，也可以先記下負責人，以及最遲必須在哪項工作或決策之前處理完成。

返回頁頂

2. 交付基準：既定意圖、實作證據與決策權限

一個可用的交付基準，會把軟件團隊經常分開處理的三方面連起來：既定意圖與限制條件、實作證據，以及決策權限。

程式碼是目前實作的重要證據，卻不能單憑程式碼判斷某項行為是否刻意設計。生產環境緊急修復後可能留下權宜處理；某項特殊計算可能只為特定使用情境而設，不代表所有情況都應採用；測試亦可能多年來一直保留某個當初偶然形成的解讀。另一方面，描述預期行為的文件也可能早已與實際系統脫節，甚至無法證明當中記載的設定方式是否仍然可用。

只有把這三方面連起來，知識系統才真正能支援交付。參與者既可以查看目前實作，又能找到對應的意圖或限制條件；兩者出現差異時，也知道應由誰判斷哪一邊需要修正。

當文件記錄的意圖與實際觀察到的行為不一致時，團隊應交由具備相應決策權限的角色確認哪一項內容需要修正，並：

1. 把差異記錄為就緒缺口；

2. 找出哪個角色對爭議主題具備決策權限；

3. 判斷是實作有誤、現有知識已經過時，還是需要作出新的決定；

4. 決定完成後，更新具權威的現況知識；以及

5. 如需改變產品狀態，透過適當的交付作業處理。

組織交付能力延續有賴既定意圖與實作證據在清楚決策權限下保持一致。組織已經作出的相關決定，日後參與者應能直接找到並採用；如果實作已與文件出現重大偏離，這項差異亦應清楚可見，並在文件再次指導後續工作之前交由正確角色處理。

返回頁頂

3. 建立就緒基準

準備知識系統本身就是一項會產生證據的交付活動。在其他交付工作開始依賴它之前，團隊需要建立一個初始基準，清楚交代產品範圍、就緒責任歸屬、權威知識、存取與升級處理途徑、工程基準，以及目前已知的缺口。

以下活動提供框架層面的準備方法。團隊毋須在正式工作開始前，把每一部分都做到最詳盡。更實際的做法，是先找出下一項責任真正需要哪些知識，請具備相應決策權限的人員提供或確認，再記錄尚未解決的缺口、負責人，以及「必須在甚麼工作之前解決」的條件。

這些活動先建立一個可用的起點。之後，每當新的責任或交付作業需要依賴這個基準，團隊都可以找來不熟悉產品的參與者驗證；很多時候，這名參與者會是只在獲授權範圍內工作的 AI 程式開發代理。只要參與者無法了解產品、找到資料、正確解讀、驗證實作或把問題升級處理，就代表知識系統仍有具體缺口。決策負責人可以直接處理這些問題，但更常見的做法，是把知識系統改善與依賴它的交付作業一併完成。這樣既不用一開始便過度準備，也能為下一項工作留下更可靠的基礎。

返回頁頂

3.1. 界定準備範圍與責任歸屬

第一步是說清楚正在準備甚麼。小型產品可能只涉及一個程式碼儲存庫和一項服務；大型平台則可能涵蓋多個儲存庫、服務、外部介面、文件系統和組織管控來源。

準備範圍可以列明：

• 正在準備的產品或系統；

• 包括哪些實作儲存庫、服務或元件；

• 預期哪些參與者角色會使用這套知識系統；

• 這些參與者預期需要作出或升級處理哪些類型的決策；以及

• 哪一位工程主管（Engineering Leader）或同等角色負責確保預定工作所需的就緒度已經建立。

開始時資料不一定齊全。團隊應運用相稱原則，判斷缺少的知識是否足以影響預定工作；如果會，便應把它記錄為就緒缺口。

返回頁頂

3.2. 建立入口與知識導向

參與者首先需要一個明確起點。這個入口可以是根目錄 README.md、產品入口網站、工程服務頁面、程式碼儲存庫首頁文件，或其他由組織持續維護的合適位置。文件本身可以標示負責人或批准狀態；如果相關權威知識放在其他地方，入口就應清楚指出應往哪裡找。

這個入口應讓參與者迅速回答三個問題：

1. 我正在處理哪個產品或系統？ 參與者應能掌握產品目的、主要負責人、實作位置，以及目前工作的相關範圍。

2. 這項決策應參考哪裡的權威知識？ 產品意圖、架構、安全、可靠性、營運、資料語義和實作指引，可能分別由不同來源和負責人維護。

3. 現有知識不足時，由誰決定？ 參與者應能把重大問題交由正確決策負責人，而不是根據不完整脈絡自行猜測。

工作越深入，需要的知識亦會越具體。共享知識系統把這種做法稱為按需分層載入上下文。貢獻者先從少量而穩定的基本資料開始，只有在目前責任真正需要時，才載入更詳細的上下文。

團隊亦應同時測試人與 AI 的存取能力。文件要採用合資格人員能理解的自然語言和格式；AI 參與者則必須能透過實際交付工具，取得並運用同一批相關知識。例如，一項安全標準即使放在工程師人人都能開啟的內部網站，對只能存取程式碼儲存庫的 AI 程式開發代理仍然等於不存在。反過來，AI 檢索連接器即使能搜尋整個文件集合，如果人員無法分辨哪一份才是現行權威來源，同樣未算準備就緒。人與 AI 都必須能透過各自的實際工作途徑，得出同一套有根據的解讀。

返回頁頂

3.3. 建立工程基準

一套可用的工程基準，應讓合資格工程師能透過正式支援的方法，檢查並有效驗證目前實作。開發環境設定本身就是這套基準的一部分。一項在芬蘭軟件公司進行的行動設計研究（Action Design Research）指出，設定和配置本地開發環境往往費時費力，也容易出錯，因而損害開發者體驗。²

因此，對相關產品範圍，團隊應提供一套正式支援的方式，讓工程師可以：

• 取得或檢查原始碼和所需實作工作產物；

• 了解主要程式碼儲存庫或服務各自承擔甚麼責任；

• 知道需要哪些執行環境、套件管理工具、開發工具、帳戶、權限和配置；

• 取得已批准的機密資料或憑證，但不把實際機密值記錄在知識來源之中；

• 建置、啟動、檢查或以其他方式操作相關產品狀態；以及

• 執行有實際意義的基準驗證，包括已知而且預期會出現的失敗。

工程基準應按產品實際情況而定。本地應用程式可能只需要在乾淨環境完成建置並通過測試；大型分散式平台則可能需要服務存取、具代表性的整合測試、部署工具，以及正式支援的可觀測性。就緒度要求工程狀態可以重現或檢查，而正式支援的工程路徑應配合產品本身的運作模式。

這個過程中出現的失敗，本身就是有價值的就緒證據。未記錄的依賴、過時的設定指令、不明的配置鍵、理應通過卻失敗的基準測試，或只有一名工程師知道如何啟動的服務，都把原本隱藏的問題變成可以指定負責人並解決的具體缺口。

返回頁頂

3.4. 揭示並記錄就緒缺口

準備過程通常會找出不少缺失或互相矛盾的知識，但並非所有問題都需要立即解決。重要的是先把缺口明確記錄，避免它們在實作過程中悄悄變成未經授權的決定。

只要能保存決策路徑，一份簡單的缺口紀錄已經足夠：

缺口：
受影響主題：
決策負責人：
必須在以下事項前解決：
解決證據：
狀態：

必須在以下事項前解決 是最重要的相稱性欄位。它不要求所有缺口立即解決，而是指出哪些工作或決策不能在問題尚未釐清時繼續。例如，有爭議的無障礙要求可能要在使用者介面交付作業開始前解決；不清楚的服務責任可能要在修改相關整合前釐清；缺少本地設定步驟，則應在分派依賴該環境的實作工作前補上。

如果某個缺口足以重大改變預期行為、架構責任、常設義務、驗收證據或參與者權限，就必須在相關工作繼續之前處理。至於與目前計劃無關、風險較低的缺口，可以暫時保留，但仍要有清楚負責人和「必須在以下事項前解決」條件。

返回頁頂

4. 知識範疇與決策權限

不同組織可以採用不同的文件分類方式。知識系統就緒的要求，是產品需要長期保存的知識都容易找到，而且每個重要主題的決策權限都清楚。以下知識範疇會在其他 Spec-First Hub 文章分別深入討論。

不同組織使用的職銜可以不同，但責任歸屬應以決策權限為準。

按角色劃分決策權限，可以避免 AI 輔助交付中一個常見問題。工程師或 AI 代理可能最先發現兩個來源互相衝突，但發現問題不等於取得決策權。他們不能因此默默選擇某種產品解讀、放寬安全要求，或重新界定架構責任。

返回頁頂

5. 以程式碼儲存庫為中心的參考結構

以下結構是就緒模型的一個以程式碼儲存庫為中心的參考實作。它既不是規格優先交付的知識系統本身，也不是強制文件分類法。使用 wiki、文件儲存庫、知識圖譜、MCP 伺服器或其他持續維護知識平台的團隊，同樣可以從自己的入口落實這些責任。

如果團隊希望以原始碼儲存庫作為持久產品和工程知識的主要入口，這個結構可以作為實用起點。有些檔案可以直接保存權威知識，並標示負責人或批准狀態；另一些檔案則只負責把讀者導向外部、按既定管治程序維護的來源。大型組織甚至可以把大部分權威知識留在程式碼儲存庫之外，只將儲存庫用作可靠的導向層。

這套結構只是一個初始起點。小型產品可以先用幾份精簡文件保存多個知識範疇；隨產品成長，當拆分有助責任歸屬、可發現性、審查或 AI 上下文載入時，團隊可以把內容密集的文件演進成更聚焦的目錄、紀錄或導向程序。結構可以隨產品演進，但清楚的入口、決策權限和通往現況知識的路徑應繼續保持穩定。

根目錄各個檔案有不同責任：

參考結構中的精簡文件可以各自按需要演進。就使用者角色而言，簡單應用程式可以把完整的使用者角色集合保存在 docs/personas.md；較複雜產品則可逐步演進成 docs/personas/，以獨立且按既定管治程序維護的紀錄保存各個使用者角色，並按需要加入 persona-directory Skill，讓設計、結構化討論和規格工作只找出並載入真正適用的使用者角色。使用者角色與參與者會詳細說明這個模式。架構、模型、要求和其他知識範疇，亦可以在獨立責任歸屬或檢索方式變得有用時採用相同拆分方式。

一份實用的根目錄 README.md，應讓不熟悉產品的工程師毋須依賴團隊私下口耳相傳，也能回答：

• 這是甚麼產品？它為何存在？

• 誰負責產品和主要技術責任？

• 權威的產品、架構、專業職能和營運來源在哪裡？

• 哪些程式碼儲存庫、應用程式、服務或套件與工作有關？

• 需要哪些先決條件、配置、帳戶和權限？

• 哪些指令或正式支援程序可以重現目前的建置、執行和基準驗證狀態？

• 當現有記錄不足時，應向誰尋求決定？

完成基本說明後，根目錄 AGENTS.md 便負責規範後續工作。它應把貢獻者導向適用規格和詳細指示，說明哪些實作與驗證規則適用、需要保存哪些證據、知識系統要同步更新哪些內容，也要界定甚麼情況必須停止工作並升級處理，因為所要求的決定已超出貢獻者的權限。

README 與管治指示各有責任。README 幫助參與者了解產品並建立工作基準；管治指示則規定貢獻者應如何改變這個基準。後續的管治指示文章會詳細說明這套機制。

這個參考結構亦示範按需分層載入上下文。根目錄入口保持精簡；工作涉及產品目的時才載入產品意圖，涉及系統責任時才載入架構，涉及安全或可靠性時才載入相關要求，需要特定程序時才載入相應的 Skill。這套做法讓真正相關的權威上下文一直容易取得，同時避免每次工作都載入整套知識系統。

供應商 API 文件或整合夥伴文件等外部知識，可以繼續留在程式碼儲存庫之外。與其自動複製一份到本地，不如在相關文件或本地入口清楚標示外部來源、主題、負責人，以及人與 AI 正式支援的存取途徑。這樣既能維持單一權威來源，也能讓程式碼儲存庫繼續充當可靠起點。

返回頁頂

6. 就緒驗證與缺口管理

初始就緒基準只有在合資格參與者真正用得上時才算足夠。因此，驗證應以具代表性的實際工作來測試，而不是只檢查某些文件是否存在。

返回頁頂

6.1. 不熟悉產品的參與者驗證

可以選擇一名過往未接觸產品的合資格參與者；如果沒有合適人選，也可以請現有參與者刻意只從已記錄的入口開始，不使用自己掌握的團隊內部知識，以模擬相同情況。無論採用哪種方法，參與者使用的存取途徑都應與該角色在實際交付中會獲得的途徑相同。

具代表性的測試包括：

人與 AI 的共同驗證，必須沿用實際交付時真正會使用的存取途徑。人員可以在瀏覽器開啟文件，不代表 AI 程式開發代理也能檢索；企業搜尋工具可以找到文件，也不代表代理能夠分辨現行權威來源和過時副本。因此，驗證既要確認合資格人員能理解文件，也要確認 AI 能透過自己的實際工作路徑取得並正確運用同一套權威知識。

返回頁頂

6.2. 把失敗分類為就緒缺口

每次驗證失敗，都應轉化為一個具體的就緒缺口，而不是只留下一句「文件做得不好」之類的籠統評語。

例如：

就緒度負責人可以接受部分缺口暫時保留，但前提是它們不會阻礙預定工作，而且每個尚未解決的重大缺口都有具明確責任歸屬的負責人，以及「必須在以下事項前解決」條件。這樣可以讓準備深度與實際需要相稱，同時避免未知事項再次落入個人記憶，最後由實作者憑猜測補上。

返回頁頂

6.3. 隨產品變更維持就緒度

產品持續改變，就緒度亦需要持續維護。每項交付作業都可能改變實作、釐清產品意圖、修訂架構、加入新的專業職能要求、揭示未記錄的假設，並產生新證據。這些重要新知識應收斂回知識系統，讓下一名參與者從組織目前真正掌握的知識開始，而不是重新推敲上一項交付作業究竟發生過甚麼。

交付作業生命週期中的知識收斂說明重要實作所得知識，如何在後續工作依賴之前先界定適用範圍，並由具備相應權限的角色確認其權威性。可信賴交付作業與驗收證據則說明規格、實作責任、驗證和證據如何共同支援對變更後產品狀態的驗收。

每次重大變更後，就緒準則仍然相同：一名合資格但不熟悉產品的參與者，應能掌握產品基本情況、取得與其責任有關的權威知識和目前實作、理解適用限制條件，並把尚未解決的決策交由具備正確權限的角色處理。這項能力正是組織交付能力延續的一種實務體現。