# 產品術語與資料語義

產品會依賴許多術語和資料欄位，但名稱本身通常不足以說明它在產品中代表甚麼。例如，`country` 欄位可能指法定受僱國家、居住地、國籍，或某項計算採用的司法管轄區。組織術語可以有全企業共用的定義，產品卻可能需要較窄的解讀；上游系統或會公開一百個欄位，但只對其中部分業務事實擁有決策權。熟悉產品歷史的人員通常能憑經驗處理這些差異。AI 系統則可能根據欄位名稱、供應商文件或一般語言含義作出看似合理的判斷，並把它當作已確立的產品知識繼續工作。

規格優先交付把產品術語與資料語義視為[共享知識系統](/zh-tw/hub/shared-knowledge-system)中的持久產品脈絡。團隊要建立的是現行的產品含義，讓合資格人員和 AI 在規格、實作、測試、審查或營運決策中使用術語或外部資料前，都能先找到正確解讀。

組織術語和供應商語義若符合產品的取用情境，產品可以直接採納；若組織或外部系統以不同方式使用同一概念，產品就應記錄自己的解讀。修改語義定義的決策權取決於其適用範圍：組織定義仍由組織負責；產品全域的含義須由交付團隊達成共識；只限於某個功能範圍且不影響其他產品行為的含義，則可由該範圍的負責角色維護。

資料語義把同一項責任延伸到介面。API、資料庫、事件串流、檔案、MCP 工具、知識圖譜及其他外部系統，都應提供足夠的語義資訊，讓產品能負責任地使用資料。即使產品沒有公開 API，OpenAPI 仍是成熟的參照：它把機器可讀的結構、供人閱讀的描述、限制條件、列舉值、範例和其他介面資訊，整合在一份持續維護、可由人員和軟件共同解讀的描述中。[^citation-01] 規格優先交付把這項設計原則用於所有會實質影響產品的外部系統，不要求採用 OpenAPI 或任何特定文件技術。

## 1. 產品術語與語義決策權

產品術語是交付團隊目前用來一致理解產品概念的詞彙。它涵蓋使用者、業務事實、狀態、責任、工作流程、類別，以及其他會影響交付的概念。它必須能支援實際工作：另一名合資格參與者應能在需求、規格、資料解讀、實作和審查中使用同一術語，毋須從個人記憶重新推斷含義。

獨立系統若要在共享領域中交換資訊並據此推理，正式本體論可用來明確界定含義。它列出領域概念、界定概念之間的關係，並說明這些概念應如何解讀，讓不同系統能一致使用同一套詞彙。Gruber 關於可攜式本體規格的研究，將問題表述為：為共享論述領域界定共同詞彙，使已表述的知識可在 AI 系統之間共享。[^citation-02] 產品術語通常不需要如此完整的表述，但只要一般語言或外部術語容許多種會造成實質差異的解讀，產品仍須明確記錄概念、含義、關係和限制條件。

[共享知識系統](/zh-tw/hub/shared-knowledge-system)一文把組織脈絡和產品脈絡界定為不同的知識層，產品術語正是這個模型在術語上的應用。組織可在術語表、知識圖譜、資料目錄、內部入口網站或其他脈絡層維護企業定義；若定義正好表達產品採用的含義，產品可直接引用。若產品的取用情境需要較窄、經映射或以其他方式調整的解讀，產品脈絡就應記錄該解讀，同時保留它與組織來源的關係。

1. **組織術語**

   由組織決策權界定和維護的術語。產品可以引用或採納其定義，而組織含義的變更仍由組織負責人決定。

2. **產品術語**

   本產品目前採用的含義。產品可以採納組織定義，或記錄其取用情境所需的產品解讀。產品全域的語義變更須由交付團隊取得共識。

組織脈絡層讓人員更容易找到企業共用的含義。中央術語表、資料目錄或知識圖譜可公開共同定義、關係、責任歸屬和權威參考資料，無須每個產品各自複製。當多個產品都需要辨識相同的企業概念，或把問題交由負責該概念的組織職能處理時，這類安排尤其有用。

在 AI 輔助軟件交付中，產品脈絡應是產品決策的主要語義脈絡。企業定義即使在組織層面正確，對某個產品仍可能過於寬泛、適用範圍不同，或欠缺所需細節。因此，除非產品明確採納組織定義，組織脈絡只應作為上游和次要的語義來源。組織知識自動載入時，產品解讀或覆寫內容必須容易找到，並有足夠權威性，讓人員和 AI 參與者判斷目前產品決策應以哪一項含義為準。

語義的適用範圍決定變更的影響。產品全域術語可能出現在需求、介面、原始碼、測試、分析、營運程序和使用者溝通中，即使識別碼沒有立即改變，含義改變仍會改變所有這些地方的解讀。因此，產品全域的語義變更必須由依賴該含義的交付團隊職能共同審查並達成協議。

> **產品全域語義變更**
>
> 產品全域的術語變更，就是產品全域的含義變更。應與其需求、資料、實作、測試或決策依賴該含義的交付參與者一同審查。

有些語義確實只在較小範圍內適用。例如，某個欄位若只用於一項專門計算，其他產品功能可能完全不會取用它。只要這個範圍明確受限，負責的專業人員即可作出語義決定。日後若概念成為共享概念，其語義範圍和審查責任也必須隨之擴大。

## 2. 取用情境中的語義

外部來源提供的含義描述的是該來源自己的模型。產品還要知道，同一概念在自身用途下究竟代表甚麼。這就是取用情境語義：當供應商概念與產品所需含義不完全相同，產品會記錄所採用的含義，以及兩者之間的映射。

資料庫整合研究早已把情境視為含義的一部分。Kashyap 和 Sheth 以比較情境為基礎，建模資料庫物件之間的語義接近性，讓情境成為理解語義相似性和綱要對應的要素。[^citation-03] Goh、Bressan、Madnick 和 Siegel 的 Context Interchange 研究也以來源和接收端情境處理語義異質性，讓資訊可按取用端情境的假設解讀，而不是假定任何一種表示方式都具有普遍適用的含義。[^citation-04]

設想一間以中央人力資源平台為核心的大型組織。企業目錄可以正確地把它列為權威的人力資源系統。薪酬產品從中取用員工身分、僱傭狀態、薪酬屬性和付款相關的組織事實；人力結構儀表板則取用組織階層和人口統計屬性。上游系統雖然相同，各產品為不同目的取用的事實子集卻不同，因此這項依賴的業務含義也不同。

產品應記錄與自身決策有關的關係。對薪酬產品來說，人力資源平台可以是僱傭狀態的指定取用來源，而另一個系統仍可能是稅務分類的業務權威來源。對人力結構產品而言，同一平台主要提供的則是階層和人口統計事實。若只寫下 `depends on workforce platform`，人員和 AI 仍要自行推斷究竟依賴哪些事實及其含義。

取用情境也決定資料是否適合某項工作。Wang 和 Strong 的資料品質框架根據資料使用者的證據，將脈絡資料品質界定為資料是否適合當前工作。[^citation-05] 產品語義把這種工作脈絡保存下來，供後續交付使用。供應商的值可以在自己的模型中有效，產品在依賴它前，仍可能需要確認產品專屬的解讀、映射、表示規則或決策權。

有些語義映射保留相同的儲存值，卻改變產品採用的適用範圍或業務解讀；有些則同時改變表示方式和含義。知識系統應保留後續參與者正確使用資料所需的關係。

## 3. 資料的結構與語義表示

有用的資料契約不只說明結構，也會傳達解讀結構所需的業務含義。型別、格式、列舉值、描述、範例、單位、生命週期含義和其他限制條件都能提供這些資訊。資訊需要詳盡到甚麼程度，取決於資料有多容易產生歧義，以及誤解後果有多嚴重。

OpenAPI 把結構和描述性資訊放進同一份人員讀者和軟件工具都能取用的共用契約，因此是有用的語義設計參照。[^citation-01] 欄位可同時帶有型別、格式、描述、允許值、範例和其他限制條件；操作也可提供足夠說明，讓取用端理解預定用途。關鍵在於，機器可讀的結構和說明性語義要放在同一個可取得、持續維護的介面中。規格優先交付將此原則應用於所有實質影響產品的外部系統通訊方式。

例如，下列實體資料庫定義：

```text
country VARCHAR(3)
```

這個定義只說明 `country` 會以最長三個字元的文字儲存，沒有說明它在產品中代表哪一種國家。語義定義可以明確指出，這個概念是法定受僱國家，產品指定的表示方式是 ISO 3166-1 alpha-2，而居住地和國籍是另外兩個概念。時間戳記也是同樣道理：其定義必須說明它代表事件時間、生效時間、處理時間、紀錄更新時間，還是另一個會影響產品行為的生命週期時點。

Wand 和 Wang 將資訊系統視為現實世界系統的表示，並從表示可能失敗的情況推導資料品質問題，包括歧義和欠缺意義。[^citation-06] 因此，欄位即使在結構上有效，只要參與者無法判斷它代表哪項現實事實、狀態、單位或生命週期時點，對交付來說仍缺少必要語義。

### 3.1. 外部系統的語義介面

所有會實質影響交付的外部資訊，都要有可理解的語義介面。規格優先交付不指定實作機制，團隊可依系統和組織情況採用合適方式：

- API 可以公開 OpenAPI、等效的機器可讀文件，或另一份持續維護的契約。
- 資料庫可以公開綱要中繼資料、欄位描述、資料目錄、按既定程序管理的文件，或產品層面的語義映射。
- 事件串流或檔案介面可以連同綱要和相容性規則，維護事件和欄位語義。
- MCP 伺服器可以提供 AI 用戶端在工作期間可檢索的工具、參數和結果描述。
- 知識圖譜可以公開組織概念，同時由產品記錄適用於其取用情境的解讀。

現代 AI 工具使用研究也說明可取得語義介面的價值。Gorilla 把錯誤或幻覺式 API 使用列為大型語言模型的重要失效模式，並指出結合模型和文件檢索，可提升對已變更 API 文件的適應能力並減少幻覺。[^citation-07] ToolLLM 則以 API 檢索選取相關工具，並針對 16,464 個真實世界 REST API 進行訓練和評估，處理更大規模的工具使用。[^citation-08] 這些研究關注如何正確選取和調用工具。產品交付還多了一項責任：找到正確的外部介面後，參與者仍須依產品既定的含義、決策權和取用情境使用它。

語義介面必須能從參與者實際使用的存取途徑取得。文件即使人員看得懂，若 AI 程式開發代理無法取得，AI 仍會從綱要名稱或範例推斷含義。反過來說，AI 可以檢索的機器可讀中繼資料，若交付團隊不清楚它是否具有決策權，也會造成問題。[規格優先交付的知識系統就緒度](/zh-tw/hub/knowledge-system-readiness-for-specification-first-delivery)一文要求，知識必須同時可取得，並對當前責任具有權威性。

### 3.2. 最低限度的語義紀錄

語義紀錄必須足夠精簡，團隊才維護得下去。通常只需要五個欄位：

```text
Concept:
Meaning:
Source:
Scope:
Date:
```

`Concept` 說明正在解讀哪個術語或資料概念；`Meaning` 用自然語言寫出目前的產品含義；`Source` 指出定義或資料從何處取得，例如組織定義、供應商契約、產品決定、API、資料庫或其他按既定程序管理的來源。`Scope` 說明含義適用於全產品還是某個具名功能範圍。`Date` 記錄這項語義決定何時成為權威，或最後一次實質修訂的日期，讓參與者知道舊副本可能已被取代。

例如：

```text
Concept: Employment country
Meaning: Country under which the employee is legally employed.
Source: Workforce API; canonical consumption source for this product.
Scope: Product-wide.
Date: 2026-08-28.
```

其他欄位只有在能消除實質歧義時才需要。例如，產品必須區分 `US`、`USA` 和 `United States` 時，`Representation` 可註明 ISO 3166-1 alpha-2。映射備註可說明外部概念如何對應到較窄的內部概念；若現行介面、使用者群組或舊有識別碼仍使用某個別名，也可把它記錄下來。多數一般產品術語只需概念、含義、來源、範圍和日期，紀錄自然能保持精簡。

### 3.3. 建立觸發條件與維護導向

當交付工作需要某個含義，卻不能再只靠熟悉產品的人員憑經驗理解時，就應建立語義紀錄。觸發條件是實質歧義或新的語義責任，不是單純多了一個欄位或術語。

1. **含義模糊的產品術語**

   當一個術語有兩種合理解讀，並會導致需求、實作、驗證、分析或營運出現實質差異時，建立或擴充紀錄。

2. **新的外部資訊**

   當新欄位、事件、API 操作、資料庫來源、檔案、工具或知識來源引入產品會依賴的含義時，加入語義。

3. **取用情境映射**

   當供應商或組織語義與本產品或功能範圍所需的含義不同時，記錄映射。

4. **決策權或指定來源決定**

   當產品確立某項事實的指定來源，或發現公開資料的系統與底層業務權威來源不同時，記錄該決定。

5. **就緒度失敗**

   當不熟悉產品的人員或 AI 參與者無法透過正常知識系統路徑正確解讀重要概念時，新增或改善語義。

權威紀錄應放在最容易維護和查找含義的位置。來源足夠而且可取得時，供應商語義可以留在 OpenAPI、綱要中繼資料、資料目錄、MCP 描述或其他外部契約中；產品解讀則應保留在產品脈絡，例如產品術語表、小型資料語義文件或其他按既定程序管理的產品知識來源。只要引用能為人員和 AI 提供可靠存取途徑，產品就應引用既有的權威語義，不必再複製一份。

管治指示可以把語義維護納入日常交付。例如，儲存庫層級的指示可要求人員或 AI 參與者，在修改外部欄位、共用產品術語、指定來源或表示規則前，先檢查適用的產品術語與資料語義；交付作業出現上述觸發條件時，也要提出語義更新。在以程式碼儲存庫為中心的實作中，`AGENTS.md` 可以承載這類恆常適用的指示。與 AI 程式開發代理進行的[結構化討論](/zh-tw/hub/requirements-increments-and-structured-discussion)，同樣可用來辨識、修訂或維護相關語義紀錄。

語義庫變大後，選擇性載入的 Skill 可減少導向和文書工作。`semantic-directory` Skill 可以根據目前工作涉及的術語、欄位、介面或來源，找出相關概念、載入權威紀錄、比較外部定義與產品映射，並在發現缺口時草擬候選更新。實質變更仍須遵循本文稍後說明的語義決策權。自動化可以減少維護工作量，但產品全域和專業語義的決定仍由具責任歸屬的人員作出。

## 4. 資料決策權、指定取用來源與來源脈絡

業務決策權指的是：在既定情境中，哪個來源或角色有權確立一項底層業務事實或作出相關決定。公開某個值的介面可能產生、複製、轉換、補充、彙總、快取或轉發該值。因此，產品語義要保留足夠的決策權和來源脈絡資訊，清楚區分產品獲准從何處取得某個值，以及哪個來源確立底層業務事實。

要釐清這些資訊，可分別回答以下三個相互關連的問題。

1. **業務決策權**

   指出確立業務事實或其認可含義的負責來源或職能。

   - **問題:** 在相關情境中，誰對這項業務事實擁有事實或決策權？
   - **範圍:** 已確立決策權的具體事實或已界定事實類別。

2. **指定取用來源**

   指出本產品預期從哪個來源取用該事實。

   - **問題:** 在此取用情境中，產品應從哪個介面或系統取得這項事實？
   - **範圍:** 此來源被指定為標準取用來源的產品及取用情境。

3. **來源脈絡**

   記錄理解取用值所需的重要來源或轉換路徑。

   - **問題:** 該值是在這裡產生、從另一個權威來源複製，還是在取用前經過實質轉換？
   - **範圍:** 要正確判斷決策權、資料時效性、轉換過程或資料含義所需的來源脈絡。

把業務決策權、指定取用來源和來源脈絡分開記錄，可釐清企業整合中常見的情況。假設某項服務公開一百個員工欄位，其中二十個由服務所屬領域直接維護，另外八十個則經 ETL 從其他系統傳入。這項服務仍可成為組織取用全部一百個欄位的指定介面。產品因而可以從它取得每個欄位，同時知道許多業務事實的決策權仍在別處。

另一種情況是，方便查詢的報表資料庫也可能公開來自權威來源的欄位，但產品核准使用的指定取用來源卻是另一個介面，因為其更新週期、轉換處理和營運契約更符合預定用途。指定取用來源是針對特定事實和取用情境的判定，它說明產品在這個情境下應從哪裡取得該事實。

資料整合實務向來把異質來源資料、綱要轉換和資料清理視為相關責任。Rahm 和 Do 指出，整合異質來源時資料清理格外重要，並主張應與綱要相關的轉換一併處理。[^citation-09] 若產品需要指定的國家表示方式，或必須區分業務含義不同的供應商值，就應在實作前把語義要求提供給工程師和 AI 代理，讓他們以共同依據進行轉換。

> **指定取用來源取決於事實和情境**
>
> 把指定取用來源視為對已界定事實及已界定取用端情境的說明。當兩項責任不同時，記錄已批准的取用來源和底層業務決策權。

## 5. 建立產品術語與資料語義

建立語義時，產品應從目前交付真正依賴的術語和外部資訊開始。初始的語義基準只需涵蓋當前產品決策所需的內容，並隨後續工作發現新的歧義而擴充。

**語義準備: 為人員與 AI 交付確立現行含義**



1. **找出正在使用的概念和外部資料**

   找出其解讀會實質影響目前產品行為或交付決策的術語、欄位、狀態、識別碼、值和外部介面。

2. **取得既有語義**

   尋找已描述該概念的組織定義、供應商文件、API 描述、綱要中繼資料、資料目錄項目、知識圖譜概念或其他權威來源。

3. **確立產品解讀**

   確認既有含義是否可直接套用於此取用情境。產品採用較窄、較寬或以其他方式不同的含義時，記錄產品解讀或語義映射。

4. **記錄重要的表示及來源規則**

   只有在產品需要該精確度以避免實質誤解時，才加入表示方式、指定取用來源、來源脈絡、允許值、單位、生命週期含義或映射資訊。

5. **確認語義範圍和決策權**

   說明含義屬於組織、全產品還是限於某功能範圍，並取得該範圍所需的審查或共識。

6. **公開現行語義**

   讓人員和 AI 可透過規格、實作、驗證、審查和營運時正常使用的存取途徑找到這些現行定義。

第一輪應處理那些只要出現合理的另一種解讀，就會改變產品行為的概念。常見項目包括含義重疊的業務術語、具生命週期意義的狀態、唯一性有特定範圍的識別碼、隱含單位的量度、國家或司法管轄區代碼、時間戳記、外部提供的類別、計算所得的值，以及雖被廣泛公開、卻未必來自權威來源的欄位。

既有語義足夠時，應直接重用。若組織術語表已把某個術語精確定義為產品採用的含義，產品可以引用該定義並記錄其適用範圍。若 OpenAPI 描述已準確傳達供應商概念，而產品採用相同含義，也可直接連結到該契約。只有在取用情境新增或改變含義、來源決策權、表示方式或範圍時，才需要新增產品紀錄。

團隊可以先處理目前決策所涉及的語義。工程師、產品負責人、分析師、專家或 AI 參與者若遇到會改變預期行為的歧義，這就是就緒度缺口。問題必須交由具相關決策權的角色處理，所有依賴該答案的工作才可繼續。後續交付作業引入或揭示更多概念時，語義基準也隨之擴充。

## 6. 語義生命週期、範圍與變更決策權

產品語義是相對穩定的現況知識。只要底層產品概念、取用情境、表示方式和決策權沒有改變，多個交付作業的實作變更都可沿用同一份語義紀錄。未來交付應採用的含義一旦實質改變，就必須修訂紀錄。

常見觸發條件包括：產品出現實質變化，令概念的含義或適用範圍改變；新功能擴大原本局部概念的範圍；供應商或組織定義、代碼集或外部契約改變產品可從中取得的事實；指定來源或來源脈絡的決定改變產品取得事實的方式；以及新的營運或領域證據顯示目前紀錄已不再反映現實。若業務含義不變，純粹的表示方式變更可只更新相關規則，保留原有概念。

語義決策權取決於變更後含義的適用範圍。這樣既能維持共用定義的穩定，也讓在地專業人員維護真正屬於其範圍的語義。

**組織語義**仍由組織負責人決定。產品可以採納或引用組織定義，也可以記錄自己的解讀。組織定義仍按原有權限維護，產品則負責管理自身解讀。

**產品全域語義**是整個產品共用的現況知識。實質變更可能影響產品意圖的解讀、穩定使用案例、規格、原始碼、整合邏輯、測試預期、分析、支援程序及其他交付範圍。因此，新含義成為權威前，交付團隊必須對產品全域的語義變更達成共識。領域、產品、資料、架構、工程和其他專業職能的參與者，應依含義實際使用的位置參與。

**功能範圍語義**若明確只限於一個功能範圍，可由負責該功能的角色維護。例如，資料專家可維護只用於某項分析計算的欄位含義。另一個產品功能開始取用這個概念時，就要重新評估適用範圍，並在更廣層面審查語義決定。

外部系統可以發布自己的語義定義，這些定義仍是重要的來源脈絡；產品則決定應如何把外部概念映射到自己的術語。供應商欄位可能直接對應一個產品概念，也可能對應較窄的內部概念、需要轉換表示方式，或根本不適合特定用途。工程師和 AI 參與者可以找出不一致之處並提出映射建議；對產品、領域、資料或相關專業範圍具有決策權的角色，負責確認哪些含義成為現行產品知識。

擬議的語義變更會觸發按適用範圍進行的影響審查。交付團隊要找出哪些規格、介面、實作、測試、現況文件、分析、營運程序或下游取用者依賴目前含義。審查同時決定變更是否獲批准，以及哪些依賴範圍必須一併修改。

獲批准後，團隊依變更適用範圍所要求的交付路徑完成語義變更：

1. 更新權威的現行語義紀錄，包括已變更的日期、範圍、來源、表示方式和映射資訊；
2. 透過適用的交付作業，更新受影響的現況知識、介面描述、規格、實作、測試及其他依賴範圍；
3. 若日後參與者需要理解含義為何改變，將重要理據保留在決策歷程中；以及
4. 驗證人員和 AI 在正常上下文中都能取得新的現行含義，不會把已取代的定義同樣呈現為權威選項。

現行紀錄和所有依賴它的產品範圍表達同一項已批准含義時，語義修訂才算完成。

## 7. 語義維護與上下文控制

產品語義屬於現況知識。產品演進時，維護中的術語必須反映參與者現在應採用的含義。這對 AI 上下文尤其重要，因為舊定義和現行定義同時出現，會把已解決的歧義重新變成需要選擇的解讀。

有效別名若有助於參與者理解現行介面、舊有識別碼、使用者表述或外部來源，可以繼續保留。可把它記錄在術語表項目旁，或放進小型 `aliases.md` 索引。除此以外，現況知識應一致採用替代後的術語，讓平常提供給人員和 AI 的上下文保持精簡而有權威。

重要語義決定可保留在決策歷程中。例如，若兩個術語曾經含義模糊，而交付團隊已把它們釐清為不同概念，現行術語表只需呈現已解決的含義；`decision-history.md`、按既定程序管理的決策系統或等效來源，則保留當初決定的理由。需要理據時才載入歷史紀錄，不必佔用每項未來工作的預設上下文。

組織和供應商的變更也應遵循同一套維護紀律。企業術語表、知識圖譜、API 契約或外部綱要一旦變更，產品就要重新評估依賴該語義的映射。在適當的產品層級審查作出修訂前，現行產品解讀仍然具有權威。這讓外部語義變更有明確途徑進入產品，也避免上游文字自行改變產品含義。

這個維護模型把[按需分層載入上下文](/zh-tw/hub/shared-knowledge-system)用於語義。現行產品術語和直接適用的資料含義要容易取得；詳細的供應商定義、組織脈絡、轉換歷程和過往語義決定，則在工作責任需要時才載入。這讓 AI 有足夠上下文避免猜測，也讓日常上下文聚焦於現行含義。

## 8. 語義就緒度的驗證

語義就緒度可按[規格優先交付的知識系統就緒度](/zh-tw/hub/knowledge-system-readiness-for-specification-first-delivery)一文所定義的不熟悉產品參與者方法測試。請一名沒有產品歷史的合資格參與者，選取具代表性的產品術語或外部資料依賴，並透過正常知識系統的存取途徑解讀其含義。參與者可以是人員，也可以是使用交付期間相同授權產品上下文的 AI 系統。

1. **產品術語**

   確認參與者可說明重要術語目前的產品含義，並辨識它來自組織術語還是產品解讀。

2. **外部資料含義**

   確認參與者可說明具代表性的欄位或值對本產品代表甚麼，而非只依賴名稱、型別或供應商描述。

3. **指定來源和決策權**

   確認參與者可辨識已批准的取用來源，以及在相關時辨識底層業務決策權或重要來源脈絡。

4. **表示方式和生命週期**

   確認參與者可套用會影響正確使用的重要表示方式、允許值、單位、識別碼範圍或生命週期語義。

5. **語義變更導向**

   確認尚未解決的歧義會交由對其組織、產品全域或功能範圍含義擁有決策權的角色處理。

不熟悉產品的合資格參與者若能取得現行含義、把它套用於相關取用情境、辨識工作所需的來源和表示細節，並把未解決的重要問題交由正確決策權角色處理，而毋須依賴私有產品歷史，該語義範圍便算準備就緒。AI 版本的測試必須走交付工具實際可用的上下文路徑。所需含義即使確實存在，若 AI 無法取得，或幾個可檢索的定義並列而沒有清楚的產品解讀，知識系統仍有語義就緒度缺口。

驗證失敗必須產生具體後續行動。團隊要找出問題是缺少語義、來源不可取得、定義互相競爭、產品映射不清、時間資訊過時，還是沒有人擁有決策權；然後更新現行語義來源或導向機制，在正確權限下記錄重要決定，並透過同一條人員或 AI 存取途徑重複測試。當不熟悉產品的參與者能得出預期的現行含義，不必依賴私有產品歷史或無根據的推論，該語義範圍便通過測試。

## 9. 參考知識系統結構

規格優先交付不規定特定檔案布局。團隊可以用 OpenAPI、綱要中繼資料、外部資料目錄、知識圖譜、按既定程序管理的文件、儲存庫檔案或其組合履行語義責任。不過，以程式碼儲存庫為中心的產品可以採用簡單的參考結構，讓人員和 AI 容易找到現行產品術語與資料語義。

小型產品可以保持精簡。產品全域詞彙和別名可放在一起；權威介面未完整承載的資料語義可保留在一個檔案；重要理據則放在日常現況上下文以外：

- `product/`: 小型語義知識集的聚焦儲存庫示例。
  - `AGENTS.md`: 管治指示的可選儲存庫實作，告訴人員和 AI 貢獻者何時必須載入、檢查或提出更新產品語義。
  - `docs/`: 按既定程序管理的現況產品知識。
    - `glossary.md`: 現行產品術語，以及仍有用的有效別名。
    - `data-semantics.md`: 權威介面未充分承載的產品解讀、語義映射、指定來源規則和表示方式細節。
    - `decision-history.md`: 需要歷史脈絡時才載入的重要語義決定和理據。

語義覆蓋範圍擴大後，若概念的功能範圍、負責人、來源或載入需要不同，分開紀錄會更容易維護。精簡目錄可直接導向人員；可選的 Skill 則可為 AI 程式開發代理提供小型的第一步索引，只載入目前工作相關的語義：

- `product/`: 具備按需分層載入上下文的大型語義知識集聚焦儲存庫示例。
  - `AGENTS.md`: 為相關交付工作定義強制語義檢查和維護觸發條件的管治指示。
  - `docs/`: 按既定程序管理的產品知識和語義紀錄。
    - `semantics/`: 權威產品語義紀錄和導向入口。
      - `README.md`: 供人員閱讀的語義範圍、適用範圍、負責人、來源和載入路徑目錄。
      - `product-language.md`: 產品全域術語和現行含義。
      - `aliases.md`: 為解讀現行介面、使用者或外部來源而仍有需要的有效別名。
      - `data/`: 當不同來源、功能範圍或載入需要使單一檔案難以維護時，分開保存的資料語義紀錄。
        - `workforce.md`: 與人力資源相關的外部概念、來源決策權和指定表示方式的產品解讀示例。
        - `reference-data.md`: 共用參考資料含義、代碼系統和指定來源規則的示例。
      - `decision-history.md`: 放在正常現況上下文以外的重要語義決定和已取代的理據。
  - `skills/`: 在儲存庫根目錄維護的可重用導向程序。
    - `semantic-directory/`: 用於較大語義知識集的可選按需分層載入上下文導向工具。
      - `SKILL.md`: 精簡的概念和來源索引、適用性規則、載入路徑和語義維護觸發條件。

可選的 `semantic-directory` Skill 是導向和維護輔助工具，權威含義仍保存在擁有該含義的產品語義紀錄或外部契約中。管治指示界定何時必須進行語義檢查；Skill 則協助 AI 參與者找到正確的現行含義，並以較少檢索和文書負擔提出維護工作。只有在語義知識集確實帶來查找或維護需要時，產品才需要採用較豐富的結構。

最理想的狀態是，產品術語或外部欄位都帶有足夠的現行含義，讓新加入的合資格參與者能正確使用，毋須自行補出缺失的語義。實作可以保持精簡，同時清楚呈現決策權、取用情境、時間上的適用性，以及 AI 可讀的存取方式。

[^citation-01]: OpenAPI Initiative. (2025). *OpenAPI Specification, Version 3.2.0*. [Specification](https://spec.openapis.org/oas/v3.2.0.html).

[^citation-02]: Gruber, T. R. (1993). *A Translation Approach to Portable Ontology Specifications*. Knowledge Acquisition, 5(2), 199–220. [DOI](https://doi.org/10.1006/knac.1993.1008).

[^citation-03]: Kashyap, V., & Sheth, A. P. (1996). *Semantic and Schematic Similarities Between Database Objects: A Context-Based Approach*. The VLDB Journal, 5(4), 276–304. [DOI](https://doi.org/10.1007/s007780050029).

[^citation-04]: Goh, C. H., Bressan, S., Madnick, S. E., & Siegel, M. D. (1999). *Context Interchange: New Features and Formalisms for the Intelligent Integration of Information*. ACM Transactions on Information Systems, 17(3), 270–293. [DOI](https://doi.org/10.1145/314516.314520).

[^citation-05]: Wang, R. Y., & Strong, D. M. (1996). *Beyond Accuracy: What Data Quality Means to Data Consumers*. Journal of Management Information Systems, 12(4), 5–33. [DOI](https://doi.org/10.1080/07421222.1996.11518099).

[^citation-06]: Wand, Y., & Wang, R. Y. (1996). *Anchoring Data Quality Dimensions in Ontological Foundations*. Communications of the ACM, 39(11), 86–95. [DOI](https://doi.org/10.1145/240455.240479).

[^citation-07]: Patil, S. G., Zhang, T., Wang, X., & Gonzalez, J. E. (2024). *Gorilla: Large Language Model Connected with Massive APIs*. Advances in Neural Information Processing Systems, 37. [DOI](https://doi.org/10.52202/079017-4020).

[^citation-08]: Qin, Y., Liang, S., Ye, Y., et al. (2024). *ToolLLM: Facilitating Large Language Models to Master 16000+ Real-World APIs*. International Conference on Learning Representations. [Proceedings](https://proceedings.iclr.cc/paper_files/paper/2024/hash/28e50ee5b72e90b50e7196fde8ea260e-Abstract-Conference.html).

[^citation-09]: Rahm, E., & Do, H. H. (2000). *Data Cleaning: Problems and Current Approaches*. IEEE Data Engineering Bulletin, 23(4), 3–13. [Publication](https://dbs.uni-leipzig.de/research/publications/data-cleaning-problems-and-current-approaches).