# 共享知識系統

產品意圖、組織術語、架構限制、領域含義、營運假設和過往決策，都會左右一項實作是否真正適合該產品。需求、程式碼庫或 AI 指示，都不可能包含軟件交付所需的完整知識。[規格優先交付](/zh-tw/hub/specification-first-delivery)把這些知識視為交付系統的一部分，並將它們保存下來，讓合資格的人與 AI 在軟件持續演進時都能找到、運用、審查和維護。

## 1. 知識系統：交付問題、定義與範圍

即使沒有人刻意設計，成熟的軟件團隊往往也會逐漸形成一套非正式的記憶系統。知識隨產品演進而累積，有些甚至只留在曾經參與產品工作的人腦中。例如：

- 工程師可能知道，一個名為 `status` 的欄位必須連同另一個欄位一起解讀。
- 產品負責人可能知道，某一類使用者雖然在技術上受支援，產品卻刻意把他們排除於某個工作流程之外。
- 架構師可能記得，一個看似更簡單的整合方式，曾經因故障隔離、成本或其他系統層面的限制而被否決。

這些都是工作中累積、尚未明文記錄的默會知識。組織知識始於個人，再經過清楚表達和廣泛傳播，成為整個組織可以重用的知識。[^citation-01] 日後工作一旦要依賴這些理解，組織便要把它們從個人記憶移到持久的來源，讓其他人能夠找到、審查和重用。

人類團隊常靠對話補回沒有明文記錄的脈絡。新工程師看見不尋常的設計會追問原因，審查者會發現不符合領域規則的假設，資深同事也可能察覺，一個局部看來合理的改動，正在重開團隊多年前已經解決的問題。開發人員工作習慣研究記錄了重建這類隱含知識的代價：開發人員花大量心力探索程式碼，又要不斷打斷同事查問，最後找回的知識往往仍只留在記憶中。[^citation-02] AI 程式開發代理令這個問題發生得更快，影響範圍也更廣，因為實作可能趕在這些非正式修正出現之前展開。

AI 程式開發代理即使只掌握不完整的解讀，也能寫出前後一致的實作。假如它遺漏了架構、資料語義、監管要求、產品意圖或其他產品特有的限制，成果可能在技術上自洽，卻不符合這個產品。這些錯誤解讀一旦留存到最初工作之後，就可能形成**連鎖猜測**：後續的規格、實作決策、測試、文件或 AI 工作階段把較早的假設當成既定知識，後來的參與者再根據一項從未驗證的決定繼續推論。規格優先交付保存持久知識，正是要讓未來參與者直接從已確立的產品理解開始工作。

> **保存持久的產品知識，讓另一位合資格參與者可以根據已確立的脈絡作出重大變更。**

在規格優先交付中，**知識系統**是由脈絡、規格、程式碼、決策和證據互相連繫而成的持久共享知識，人與 AI 靠它理解、修改、驗證和延續軟件。這套系統涵蓋多種知識：脈絡說明組織、產品、領域、限制條件和營運環境；規格記錄預期行為和已同意的要求；程式碼呈現目前可執行的實作；決策交代重要選擇；證據記錄已同意的條件是否得到滿足。實作和營運中得到的新知識，也會回過頭來更新這些來源。

這些來源之所以構成**系統**，在於它們彼此補足、標明各類知識的權威來源，並隨軟件一同演進。參與者應能從現有實作追溯塑造它的意圖和限制，也能把新確立的知識放回日後工作會使用的來源。

**共享**的意思，是團隊每位成員及其 AI 程式開發代理都能查閱重要知識。這些知識存放於持久、容易找到並可供審查的來源，讓合資格的人與 AI 在需要時取用。

知識共享不會抹平各專業的視角。不同實務社群會在工作中形成各自認識和理解事物的方式，組織的優勢部分來自跨越這些差異，協調各社群掌握的知識。[^citation-03] 因此，共享知識系統既要保留各專業的責任歸屬，也要把產品、領域、架構、安全、營運和工程知識中會影響產品的內容帶入共同交付流程。這個共同知識層讓專業知識能夠影響規格、實作、審查和日後變更，同時保留各專業職能原有的責任。

本文主要討論參與者理解產品和正確解讀變更所需的脈絡。[需求、結構化討論與交付作業](/zh-tw/hub/requirements-increments-and-structured-discussion)說明交付需要如何運用這些脈絡，形成連貫的交付作業；[交付作業生命週期中的知識收斂](/zh-tw/hub/knowledge-convergence-across-the-increment-lifecycle)探討實作所得知識如何回到共享知識；[可信賴交付作業與驗收證據](/zh-tw/hub/trusted-increments-and-acceptance-evidence)則界定驗收時的檢查，以確認交付後的現況知識連貫一致，並可供日後使用。

## 2. 程式碼庫：可執行的知識

程式碼庫是共享知識系統中最重要的知識來源，因為它就是產品目前可執行的實作。它呈現產品現時的行為、系統責任如何組織、哪些介面和相依關係正在運作，以及如何驗證這些行為。任何合資格的參與者，包括 AI 程式開發代理，都可把程式碼庫視為可靠起點，理解即將修改的軟件。程式碼庫也讓人看見目前的資料依賴、請求流向、程式碼實際執行的限制，以及保障現有行為的測試；其他知識來源則保存實作本身未必能呈現的決策理據和產品解讀。兩者結合，日後參與者才有更完整的基礎延續產品。

以下各節介紹的知識來源，補上解讀目前實作所需的組織環境、產品意圖、領域含義和長期適用要求。AI 程式開發代理除了程式碼庫，也必須能夠存取這些來源。相關資料可以放在程式碼庫的 `docs/` 目錄，也可以透過其他合適機制取得，讓代理在變更需要時查閱。

早在 AI 輔助交付出現之前，軟件設計研究已經把真實而反覆演進的設計過程，與審查設計、指導程式開發和支援維護所需的條理化說明區分開來。[^citation-04] 到了 AI 輔助交付，這份工程說明還要涵蓋產品意圖、組織限制、規格、決策、程式碼和證據，讓人與 AI 都能從已確立的產品知識出發。

本技術白皮書系列把產品文件統一放在程式碼庫的 `docs/` 目錄，不依賴特定工具，AI 程式開發代理和參與軟件工作的人都能存取。這只是本系列採用的實用慣例；團隊可以用其他機制提供共享知識，只要同樣容易存取，並有明確的管治程序。從當前實作向外延伸，下一層便是產品所處的組織脈絡。

## 3. 組織脈絡

每項軟件產品都處於一個已有自身語言、系統、架構、政策、控制措施和工作方式的組織。交付決策所需的這些廣泛知識，就是**組織脈絡**。

正式記錄的組織脈絡較容易查找和引用。它可以包括企業架構標準、安全政策、工程實務、監管指引、資料分類、已批准的技術平台、組織術語、共享基礎設施、身分識別架構、共用服務契約，以及組織內其他系統的責任。

尚未明文記錄的組織脈絡最難保存，因為資深同事可能早已把某些知識視為常識。同一產品的技術團隊與業務團隊，可能用不同詞語表達同一業務概念；工程師可能熟知應採用的身分識別平台；架構師掌握企業平台支援的整合方式；領域專家一眼便認得內部縮寫；安全專業人員也知道某種資料分類會觸發哪些額外控制措施。

跨職能合作的難處，在於知識往往集中在創造它的職能，並深深植根於該職能的實務與專業投入。一項新產品開發的民族誌研究顯示，參與者需要把這些知識表達出來，跨越職能之間的知識分界相互學習，有時還要調整原有的知識或做法。[^citation-05] 在軟件交付中，架構、安全、資料、領域、平台和工程知識可以繼續扎根於各自的專業實務，但其中會影響產品的內容，必須讓整個團隊都能運用。

在大型組織中，這類知識大多應由中央持續維護，例如存放於架構儲存庫、按既定程序管理的文件平台、內部入口網站、資料目錄、知識圖譜，或 AI 可透過 MCP 等機制存取的服務。這些集中維護的來源共同構成**脈絡層**，每個權威來源仍由對該領域負責的組織職能維護。這樣，專門知識由責任歸屬明確的職能掌管，產品團隊與 AI 程式開發代理也能在交付決策需要時找到它。

組織脈絡比產品脈絡更廣，不屬於任何單一產品，卻在很多情況下不可或缺。AI 程式開發代理要正確解讀產品需求，可能先要了解整個企業如何處理身分識別、哪些基礎設施模式已獲批准、某項內部服務負責甚麼，或某類資料適用哪些控制措施。

完整的組織知識很少會全部與同一產品相關，一項實作工作所需的部分更少。產品團隊因此要讓真正影響產品的組織知識容易找到，並明確記錄它們對本產品的具體影響。

例如，企業架構標準可能列出多種已批准的服務對服務身分驗證方式。產品團隊應說明此系統採用哪一種方式、相關責任在哪裏實作，以及變更需要深入審查時應到哪裏查閱權威的企業指引。企業標準仍由原有權威來源維護，而產品則保存正確運用該標準所需的具體知識。

知識系統由此把組織層面的權威知識與產品連接起來，既引用原有來源，也清楚記錄它們對產品的具體影響。

## 4. 產品脈絡

組織脈絡說明整個企業如何運作；**產品脈絡**則記錄這些知識對特定產品有何含義，又應如何應用。

產品脈絡把產品意圖、術語、使用者、穩定使用案例、系統責任、相依關係與外部介面的具體含義長期記錄下來。另一位合資格參與者在理解局部需求或實作選擇之前，至少要掌握這些基本脈絡。

知識跨越職能或組織脈絡時，處理方式視乎雙方的差異。知識分界從語法進入語義，再深入實務層面時，協調工作也會從直接傳遞，逐步轉為解釋含義，甚至要求雙方共同調整原有知識或做法。[^citation-06] 產品脈絡要按產品實際需要處理這些情況：雙方已有共同含義時，只需引用權威來源；含義或實際後果有別時，產品便要記錄自身實作和決策所需的解讀或調整。

1. **組織脈絡**

   企業共用的知識，例如架構標準、政策、共用平台、組織術語、資料分類和控制要求。這些知識通常由中央維護，當前工作需要時才取用。

2. **產品脈絡**

   本產品長期需要的具體解讀，包括產品意圖、術語、使用者、穩定使用案例、系統責任、依賴和介面。這些知識應放在容易與相關軟件互相查照的位置。

文件形式和儲存方式可以因產品而異，但每個產品團隊都應讓以下幾類重要脈絡容易找到。

1. **產品意圖**

   說明產品為何存在、哪些成果重要、產品優先追求甚麼，以及哪些看似可行的機會不在它的目的之內。

   - 產品目的
   - 預期成果
   - 優先事項與非目標

2. **使用者角色**

   說明哪些人或角色會與產品互動、他們想完成甚麼、掌握哪些資訊，以及擁有哪些權限。

   - 使用者角色
   - 目標與責任
   - 相關權限與假設

3. **產品詞彙表**

   定義重要術語對本產品的含義，包括產品用法與組織層面定義有別的情況。

   - 領域術語
   - 產品專用術語
   - 組織概念在本產品中的含義

4. **穩定使用案例**

   記錄各類使用者反覆透過產品完成的事情，使核心用途在個別功能和介面改變後仍能延續。

   - 主要使用者目標
   - 重複出現的工作流程
   - 重要例外情況

5. **外部介面與 API**

   說明產品依賴哪些系統和供應商、每個介面承擔甚麼責任，以及哪些契約或供應商要求會實質影響實作。

   - 上游與下游系統
   - API 與事件責任
   - 身分驗證與相容性要求

### 4.1. 產品意圖、使用者角色與穩定使用案例

待辦清單可以列出許多期望的變更，卻未必說清產品的根本目標。產品意圖提供持久方向，讓參與者判斷眼前只是欠缺一個細節，還是某項要求正在把產品帶離原來目的；它也解釋了為甚麼兩個局部看來都合理的實作，未必同樣適合這個產品。

使用者角色為產品意圖帶來明確視角。同一項功能對管理員、營運使用者、客戶或稽核人員可能各有不同意義，因為他們的目標、掌握的資訊、權限和職責並不相同。有用的使用者角色會記錄真正影響行為與決策的差異。

穩定使用案例把產品意圖與使用者角色連繫起來。功能需求可能經常改變，使用者的根本目的通常變化較慢。即使介面、工作流程引擎和驗證規則已改過多次，薪酬管理員仍可能需要在處理截止時間前更正一筆付款。保存這個使用案例，後續變更便能繼續服務產品的持久目的，不會逐漸變成一批彼此無關的工作項目。

### 4.2. 產品詞彙表

術語是 AI 最容易作出「看似合理、實際錯誤」解讀的地方之一。假設一個組織設有中央人力資源平台，企業資料目錄可以準確地把它描述為「人力資源系統」，但每個依賴這個平台的產品，仍要記錄這項依賴對自身的具體意義。

對薪酬應用程式來說，這個平台最重要的作用可能是提供計算薪酬所需的員工和薪酬資料；對人力結構與人口統計儀表板來說，重點反而可能是組織層級和人口統計資料。兩個產品使用同一個上游系統，這套系統對各自產品的意義卻不一樣。

產品詞彙表應說清某個概念對本產品意味着甚麼、哪些方面與產品相關，以及相關事實應以哪個來源為準。AI 代理在實作前，便能先掌握這項依賴對產品的具體意義。

> **組織詞彙表定義一個詞在整個組織中的含義；產品詞彙表則定義這個詞對本產品意味着甚麼。**

### 4.3. 外部介面與 API

API 定義描述欄位、型別和結構契約；產品脈絡再補上權威來源、相容性、一致性和供應商義務，說明產品可以如何使用該介面。

上游服務可能只對某個屬性具有權威性，另一個屬性則應以其他來源為準。即使已有設計更簡潔的新契約，下游系統仍可能要求向後相容。事件串流可能只保證最終一致性，而非即時一致。第三方供應商也可能透過契約或政策，限制回傳資料或識別碼的儲存和保留方式。

這些條件會影響產品如何解讀、保存、公開和修改資訊，因此屬於產品脈絡。把它們保存成持久產品知識，日後的介面變更便能沿用已確立的責任和限制來實作與審查。

## 5. 產品整體要求與限制條件

有些知識同時適用於多項功能，規定產品應長期維持的品質、義務或結構限制。安全、可靠性、私隱、相容性和營運義務都是首要交付要求，必須與功能行為一同得到滿足，交付才算正確。產品團隊因此應維護能夠長期適用，並可指導多項變更的要求和限制。

1. **安全與私隱要求**

   說明整個產品都要遵守的重要身分驗證、授權、威脅控制、稽核、機密資料處理、資料分類、保留、刪除、資料所在地和最小化要求。

2. **可靠性目標與要求**

   定義服務在故障時應有的行為、復原目標、韌性要求、可觀測性需要，以及其他可靠性責任。

3. **架構要求**

   把持久的系統責任、已核准的技術方向、部署模式、依賴方向和結構限制保存成產品層級的知識，並保持容易存取。架構規格則記錄某一項具體架構變更的設計與決策。

4. **合規與外部責任**

   說明會實質影響產品處理資料或提供功能的法律、監管、契約、供應商、授權和政策要求，將組織脈絡提煉成適用於本產品的具體解讀。

5. **效能與容量預期**

   清楚記錄相關的延遲、吞吐量、並行量、資料量、擴展能力和資源假設，避免實作按錯誤的運作模式進行最佳化。

6. **營運要求**

   說明部署、監察、支援能力、回退、環境管理、診斷和生產環境責任等方面的要求。

7. **相容性要求**

   記錄支援哪些客戶端、介面版本和舊有使用者，以及結構演進規則與必須維持相容的行為。這些要求只可由責任歸屬明確的角色透過正式變更批准修訂。

8. **無障礙與本地化要求**

   在適用時，記錄需要跨功能一致遵守的無障礙、語言、地區、格式和司法管轄要求。

架構是持久產品知識在軟件工程中的一個具體例子。架構知識既包括設計本身，也包括解釋現有方案何以形成的決策、假設、脈絡和其他因素。[^citation-07] 後來者能夠找到這些因素，便可直接沿用已確立的系統責任和限制。在共享知識系統中，架構知識與產品意圖、領域語義、介面、產品常設要求，以及其他跨越多項變更、持續影響交付的知識互相連繫。

實際需要哪些類別，取決於產品本身。小型內部工具可能只需要其中一部分；受嚴格監管、整合範圍廣或後果重大的系統，內容則可能要深入得多。規格優先交付在這裏沿用與規格相同的相稱原則：需要多詳盡，取決於模糊程度、新穎程度、依賴、風險和後果。

產品常設要求適用於所有相關功能，並一直具有權威，直至責任歸屬明確的角色決定修訂。特定功能要求的權威範圍，則限於該功能或交付作業。

例如，「把這項服務以容器方式部署到已批准的平台」可能是一項產品整體架構要求，之後的功能規格可以直接引用。如果所有客戶識別碼都受同一套保留規則約束，這項要求也應持續保存成產品知識，供所有相關變更查閱。

這類穩定要求可以集中維護，只在要求本身改變時重新審查，之後的規格與實作工作則可直接引用，既減少重複，也不會削弱控制。

## 6. 產品專屬的領域知識

產品專屬的領域知識，記錄產品如何表達所處領域，又如何在其中運作。當中的含義和規則會跨越多項局部變更，持續影響實作。

在這個層面，技術上正確的程式碼尤其容易造成假象。公式可以成功編譯，卻採用了錯誤的業務計算方法；資料庫欄位可以有正確型別，卻代表錯誤含義；狀態轉換在程式碼中完全有效，卻不可能在真實業務流程中發生；查詢可以正確回傳最新紀錄，需求所需的卻是某個歷史時間點有效的紀錄。

凡是會實質改變資料和行為解讀方式的領域知識，產品團隊都應保存。

1. **計算方法**

   定義公式、運算次序、捨入、彙總、排除條件、調整邏輯，以及其他正確性取決於領域解讀而非語法的計算方法。

2. **資料語義**

   說明重要資料代表甚麼、哪些值有效、欄位如何互相關聯、資料如何隨時間改變，以及哪些解讀即使資料結構允許，在領域上仍屬錯誤。

3. **業務不變條件**

   記錄跨功能都必須持續成立的條件，例如唯一性、對帳、資格、守恆或一致性規則。

4. **狀態與生命週期語義**

   清楚定義有意義的狀態、允許的轉換、終止狀態、可逆性和生命週期規則，讓實作與審查有明確依據。

5. **最終權威依據**

   說明某項事實應以哪個來源為準、本地副本代表甚麼、來源不一致時如何處理，以及資料更新時間何時會改變解讀。

6. **時間語義**

   當差異會影響行為時，清楚區分事件時間、處理時間、生效日期、入帳日期、歷史狀態和目前狀態等概念。

7. **參考資料與分類**

   記錄受控代碼、層級、分類體系、類別和其他用於解讀領域資料的參考值，包括其含義和維護責任。

8. **已知領域例外**

   把穩定例外和特殊情況保存成明確的領域知識，讓日後實作持續遵守這些規則。

### 6.1. 計算方法與資料語義

程式碼中的計算讓人看見系統現時怎樣運算；共享知識系統還要解釋，為甚麼這套方法對產品而言正確。例如，捨入可能要在中間步驟進行，而非留待最後處理；某些業務情況需要排除特定數值；比率必須採用監管規定的分母，未必是數學上最直觀的選擇；過往期間的紀錄也可能要在更正後重新表述。共享知識系統應明文記錄這些規則，並連繫實施規則的程式碼和測試。

資料也需要同樣明確的定義。共享知識系統中的資料語義規格，應說清每個重要欄位的含義。`timestamp` 要指明數值代表事件實際發生的時間、組織得知事件的時間、正式生效時間，還是寫入儲存系統的時間；`department` 要說明它指員工現時所屬的組織層級、報告日期當時有效的層級，還是本地維護的報告分類；`country` 則要訂明採用哪種表示方式，例如 `United States`、`US` 或 `USA`。這些語義定義應與使用它們的資料結構和實作保持連繫。

### 6.2. 最終權威依據與時間

產品經常同時依賴多個權威來源。一套系統可能是客戶身分的權威來源，另一套負責契約狀態，還有一套負責某個工作流程目前的營運狀態；即使是同一個物件，不同屬性也可能各有不同的權威來源。每項關於「最終權威依據」的說明，都應準確指出該來源對哪項具體事實具有權威。產品團隊也應記錄本地投影或快取代表甚麼，以及不同來源互相矛盾時如何處理。

時間含義也必須明確。「目前」、「最新」、「生效」和「已記錄」可能各指不同時間點。AI 能夠按照技術上慣用的理解完成實作，產品所需的卻可能是領域專屬定義。因此，實作依賴這些概念之前，參與者必須能夠從知識系統找到正確含義。

## 7. 按需分層載入上下文

共享知識系統需要選擇性載入上下文，讓當前工作所用的上下文集中於真正相關的知識。

現代程式開發工具可以查閱大型程式碼儲存庫、搜尋外部知識系統、載入指示檔、啟用 Skills、呼叫 MCP 工具、查看議題追蹤系統，並閱讀架構文件。這些能力讓知識更容易取得；按需分層載入上下文則隨工作逐步具體，決定哪些來源應進入當前上下文，減少無關資訊造成的**上下文膨脹**。

> **按需分層載入上下文，是隨工作逐步具體，載入更具針對性的上下文；較廣泛的組織知識，只在與目前決策相關時才取用。**

注意力是有限資源，因此上下文視窗應盡量由相關而且具權威性的知識組成。

分散團隊尤其容易顯露脈絡取得方面的問題。一項涵蓋十三個異地團隊的研究發現，常見的共同知識失效包括未能保留脈絡資訊、資訊分布不均、參與者難以看出資訊的重要性，以及取得資訊的速度不一。[^citation-08] 工作需要某項脈絡時，相關知識既要容易找到，參與者也要能辨認其用途。對 AI 輔助交付而言，按需分層載入上下文還要作出另一項判斷：決策逐步具體時，應把哪個權威來源放進當前工作上下文？這條相關性路徑從組織層面的知識開始，經過產品、程式碼儲存庫或模組，最後到達目前工作。

**上下文載入: 工作逐步收窄，上下文逐步聚焦**



1. **組織**

   集中維護企業架構、政策、共用平台、組織術語和其他不針對單一產品的知識，供產品團隊在需要時取用。

2. **產品**

   把持久的產品意圖、使用者角色、術語、穩定使用案例、介面、產品整體要求和領域知識，放在容易與相關軟件互相查照的地方。

3. **程式碼儲存庫或模組**

   載入目前查看或修改的範圍所適用的架構、責任、依賴、慣例和本地文件。

4. **目前工作**

   加入完成眼前工作所需的具體需求、執行範圍、限制條件、驗收條件和待決問題。

採用這個模型，焦點不再只是「代理可以存取甚麼？」，而是「代理現在應該知道甚麼？如果工作延伸至其他範圍，下一步應到哪裏找？」

### 7.1. 以管治指示提供知識導覽

**管治指示**是程式碼儲存庫的強制指示，AI 程式開發代理每次處理工作都應閱讀。視乎所用的程式開發工具，它們可能寫在 `AGENTS.md`、`CLAUDE.md` 或 `copilot-instructions.md`。這些指示應簡明訂立長期適用的規則、知識導覽和必要行為，並在需要時把代理帶到更深入的產品知識。

例如，程式碼儲存庫可以要求代理在每項工作中遵守以下規則：產品行為改變時同步更新相關產品文件、採用指定的驗證方式、避開不可改動範圍，或在修改共用介面前先查閱指定的架構資料。這些規則會影響代理處理多類工作的方式，適合放在管治指示中。

詳細的產品歷史、API 契約、領域公式和營運手冊應保持容易查找，並在目前工作需要時才載入。

### 7.2. 按知識的適用範圍安排位置

知識放置的位置若能反映其適用範圍，參與者就更容易選取目前工作所需的上下文。

適用於整個程式碼儲存庫的知識，應放在儲存庫層級；只適用於某個模組的架構資料，則應在該模組附近容易找到。若一個資料夾承擔清楚而完整的責任，可以用本地 `README.md` 說明它負責甚麼、哪些內容屬於這裏、有哪些依賴，以及修改前還要查閱哪些更深入的文件。

同一原則也適用於程式碼儲存庫之外。企業架構、安全政策或平台文件若同時適用於許多產品，可以繼續保存在中央管理的來源。產品團隊只需在本地保留足夠線索，讓參與者知道何時要進一步查閱。

### 7.3. 文件既保存知識，也提供導覽

一份有用的文件應直接提供答案，或清楚指向可以查得答案的權威來源，而讀者也可能是 AI 程式開發代理。

以模組 README 為例，它可以說明該模組從共享平台取得身分資料，連結到產品層面的介面說明，並指出修改身分驗證行為前必須查閱哪一份組織安全標準。

這樣便形成一條按相關性逐步展開的查找路徑：參與者先從本地知識開始，只有在目前工作確實需要更廣泛脈絡時，才向外查找。

### 7.4. 工作需要時才取用更廣泛的知識

對同時適用於多個產品的組織層級內容，從外部知識來源存取尤其合適。組織可以把架構標準、政策、平台文件或受控術語保存在中央管理的來源，並透過內部搜尋或可由 MCP 存取的服務按需提供。

產品團隊應說明哪些情況需要進一步取用這些來源。更改產品的身分驗證模式，可能需要查閱最新的企業身分識別標準；新增本地 UI 標籤，通常只需產品層級脈絡。

程式開發工具支援時，Skills 和具名代理可以為特定類型的工作提供專門上下文。

1. **Skills**

   Skills 是 AI 模型可按工作需要選用的獨立能力，通常針對某一類操作或程序，就像工具箱中的不同工具。

2. **具名代理**

   具名代理是為軟件開發生命週期中特定工作而設的專門 AI 模型實例，具有指定角色、角色設定、系統提示和一組 Skills。使用者要明確指示 AI 程式開發工具使用該代理。

如果程式開發工具會選擇性載入 Skills，AI 程式開發代理辨認出相符的工作類型後，可自行決定載入相關 Skill，因此 Skills 適合承載特定工作類型的程序。至於每項相關工作都必須遵守的程式碼儲存庫規則，則應放在每逢相關工作都會生效的管治指示中。具名代理可以編入實用的專門能力，而明確選用哪個代理本身是工作流程的一部分。無論選用哪個專門代理，管治指示都會規範必要行為。

按需分層載入上下文讓這些機制各司其職，又互相補足：管治指示訂立強制行為並提供導覽；產品層和模組層文件保存持久知識；工具支援時，Skills 提供專門程序；外部服務按需提供更廣泛的組織知識；目前工作則加入只適用於當次變更的資訊。

## 8. 知識維護與同步

知識系統既是參與者據以工作的權威來源，內容就必須與現況一致，否則過時資料會使他們誤以為系統仍處於早已改變的狀態。

文件維護的實際情況也說明，持久知識需要人持續更新。軟件文件的實證研究發現，工程師更新文件的速度和完整程度，往往達不到軟件流程和管理人員規定的水平，雖然部分過時文件在某些情況下仍有用。[^citation-09] 文件一旦成為現況產品知識，這項維護落差便會變成交付問題。AI 輔助實作更會放大過時資料的後果，因為錯誤的現況知識可能在資深同事發現偏差之前，已經影響新產生的程式碼。

知識維護因此屬於軟件交付的一部分。實作改變某個模組的責任、架構、介面、行為或長期假設時，團隊應在同一交付作業中更新相關知識，使實作與下一位參與者所用的知識保持同步。

### 8.1. README 作為本地現況知識

`README.md` 是最實用的本地產品脈絡之一，因為它通常放在所描述的程式碼附近，人與 AI 都容易找到。一份有用的資料夾 README 應回答以下問題：

- 這個範圍負責甚麼？
- 哪些內容應放在這裏，哪些不應？
- 系統哪些其他部分依賴它？
- 修改前需要知道哪些重要假設或限制條件？
- 還應查閱哪些更深入的架構、領域或介面文件？

README 應描述目前狀態。若實作改變了以上任何答案，更新 README 本身就是實作工作的一部分。這項規則屬於程式碼儲存庫的強制行為，適合寫進管治指示，以便在所有相關工作中一致適用。

### 8.2. 持久的內部產品文件

有些知識過於廣泛或詳細，不適合放入本地 README，程式碼儲存庫仍要有地方承載。架構說明、領域語義、介面契約、產品整體要求與其他持久內容，可以放在 `docs/` 或其他按既定程序管理的文件位置。

例如，程式碼儲存庫可以採用以下結構：

```text
README.md

docs/
  architecture/
  domain/
  interfaces/
  product/

src/
  feature-a/
    README.md
  feature-b/
    README.md
```

產品團隊可以採用其他程式碼儲存庫結構，也可把部分權威知識保存於儲存庫以外。無論選擇哪種結構，仍然有效的知識都要在適當情況下納入版本管理，並保持可供審查、容易找到，且與所描述的實作互相連繫。

> **規格優先交付要求每個產品團隊採用能清楚描述產品的目錄結構；實際結構可以因產品而異。**

### 8.3. 公開產品文件也是交付成果

有些產品知識是為使用者、客戶、營運人員、整合方或其他外部讀者而寫。產品團隊可以維護一套適合直接公開發佈的文件，並與產品同步演進。使用方式、整合指引、支援的工作流程、營運說明或公開 API 資訊，都可以在改變產品的同一項工作中更新，使公開文件、軟件實作和交付期間使用的知識保持一致。

> **公開產品文件應隨產品一起演進，並納入同一交付流程。**

**同步實作與產品知識**



每個交付作業都應同步更新所有記錄相關行為或責任變更的知識來源。



1. **修改實作**

   按照已同意的內容，修改行為、架構、介面或系統責任。

2. **更新本地知識**

   如果目前的責任或假設已改變，更新相關資料夾 README 或附近的模組文件。

3. **更新持久產品知識**

   更新受這次變更影響的架構、領域、介面或其他內部產品文件。

4. **發佈相關文件**

   如果交付後的行為改變了外部讀者需要知道的內容，把面向使用者或整合方的文件納入發佈流程。

文件更新的幅度應與變更相稱。沒有改變責任或行為的局部重構，可能無須更新文件；公開介面、領域含義、系統責任或運作模式一旦改變，通常就要同步更新。

> **保存既有知識，讓專業判斷聚焦新問題**
>
> 保存已確立的知識後，專業判斷仍然不可或缺。合資格專業人員可以直接沿用組織早已作出的決定，把判斷集中在下一個真正尚未解決的問題上。

## 9. 現況知識與交付紀錄

知識系統包含兩類互相補足的資料：**現況知識**回答「系統現在的狀態是甚麼？」，**交付紀錄**則回答「當初要求了甚麼工作、實際發生了甚麼，以及系統如何演變成這個狀態？」

新的程式開發工作應根據相關規格與現況脈絡來理解現有架構。組織也應保留工作規格、狀態報告、重大偏離、決策和證據，解釋重要變更當時如何交付。不同來源互相衝突時，這些歷史紀錄往往是釐清差異的重要證據。

1. **現況知識**

   描述系統目前實際狀態，包括產品意圖、術語、架構、介面、領域語義、要求和本地 README 指引，並可直接作為未來工作的脈絡。

2. **交付紀錄**

   描述系統如何改變，包括功能工作、錯誤修正工作、狀態報告、重大偏離、實作發現、決策和證據，用來保存交付歷史和可追溯性。

功能開發和錯誤修正尤其需要區分現況知識與交付紀錄。功能工作規格描述將要作出的變更；錯誤修正工作記錄缺陷、預期修正、相關限制和驗證方式；狀態報告則記錄執行期間實際發生的事情。這些工作產物保存交付歷史並支援可追溯性，因此屬於較廣泛的知識系統；交付後的系統狀態則要同步反映在現況知識中。

某項功能若改變了 API 的責任，現有介面文件就應更新；錯誤修正若揭示某項領域不變條件從未記錄，領域知識就應補上；實作若改變了模組的運作方式，相關 README 便應描述變更後的狀態。

> **交付紀錄解釋這次變更；現況知識解釋變更後的結果。**

規格、工作執行、決策歷程和驗收證據的詳細結構與生命週期，屬於框架後續部分的主題。它們與本文的關係很直接：這些內容隨交付推進而產生，加入同一套共享知識系統，並與賦予它們含義的現況產品知識保持連繫。

實務上，共享知識系統要讓合資格的人或 AI 能查明產品要達成甚麼、重要術語有何含義、哪些要求和限制適用、關鍵領域概念如何解讀、權威知識位於何處，以及軟件改變時必須同步更新哪些知識。組織藉此保留對產品的理解，即使人員、團隊、供應商、模型或工具改變，也無須一次又一次重新建立這份理解。

[^citation-01]: Nonaka, I. (1994). *A Dynamic Theory of Organizational Knowledge Creation*. Organization Science, 5(1), 14–37. [DOI](https://doi.org/10.1287/orsc.5.1.14).

[^citation-02]: LaToza, T. D., Venolia, G., & DeLine, R. (2006). *Maintaining Mental Models: A Study of Developer Work Habits*. Proceedings of the 28th International Conference on Software Engineering, 492–501. [DOI](https://doi.org/10.1145/1134285.1134355).

[^citation-03]: Brown, J. S., & Duguid, P. (2001). *Knowledge and Organization: A Social-Practice Perspective*. Organization Science, 12(2), 198–213. [DOI](https://doi.org/10.1287/orsc.12.2.198.10116).

[^citation-04]: Parnas, D. L., & Clements, P. C. (1986). *A Rational Design Process: How and Why to Fake It*. IEEE Transactions on Software Engineering, SE-12(2), 251–257. [DOI](https://doi.org/10.1109/TSE.1986.6312940).

[^citation-05]: Carlile, P. R. (2002). *A Pragmatic View of Knowledge and Boundaries: Boundary Objects in New Product Development*. Organization Science, 13(4), 442–455. [DOI](https://doi.org/10.1287/orsc.13.4.442.2953).

[^citation-06]: Carlile, P. R. (2004). *Transferring, Translating, and Transforming: An Integrative Framework for Managing Knowledge Across Boundaries*. Organization Science, 15(5), 555–568. [DOI](https://doi.org/10.1287/orsc.1040.0094).

[^citation-07]: Kruchten, P., Lago, P., & van Vliet, H. (2006). *Building Up and Reasoning About Architectural Knowledge*. In *Quality of Software Architectures*, Lecture Notes in Computer Science 4214, 43–58. [DOI](https://doi.org/10.1007/11921998_8).

[^citation-08]: Cramton, C. D. (2001). *The Mutual Knowledge Problem and Its Consequences for Dispersed Collaboration*. Organization Science, 12(3), 346–371. [DOI](https://doi.org/10.1287/orsc.12.3.346.10098).

[^citation-09]: Lethbridge, T. C., Singer, J., & Forward, A. (2003). *How Software Engineers Use Documentation: The State of the Practice*. IEEE Software, 20(6), 35–39. [DOI](https://doi.org/10.1109/MS.2003.1241364).