AI 代理友善知識庫

本提案解決傳統知識管理系統（Confluence、SharePoint、Google Docs）與 AI 驅動開發工作流程需求之間的根本錯配。為人類設計的可讀 Wiki 成為阻礙 AI 代理的環境，導致脈絡碎片化並妨礙自主代理運作。

核心洞察： 為人類瀏覽設計的知識系統會主動阻礙 AI 代理。轉向代理友善基礎建設，可在保持人類可編輯的同時讓知識可被機器讀取。

問題陳述

當前狀態：人類導向的知識孤島

團隊回饋的證據

痛點	對 AI 工作流程的影響
專有格式	AI 代理無法直接讀寫；需要 API 轉譯
無 Git 整合	規格變更與程式碼變更脫鉤
富文字膨脹	複製貼上引入格式偽影，破壞解析
附件依賴	圖片/檔案無法被 AI 代理索引
權限複雜性	AI 代理難以管理存取權杖
搜尋限制	全文搜尋不足以支援語意查詢

根本錯配

傳統 Wiki 優化於：

視覺呈現
點選導航
即時協作
富媒體嵌入

AI 代理需要：

純文字解析
程式化存取
版本控制整合
結構化中繼資料

提議解決方案：Git-Based Markdown 知識系統

目標架構

核心原則

Markdown 優先：所有內容使用純 Markdown，可選擇性擴充（Mermaid、frontmatter）
Git 原生：版本控制是事實來源，而非同步目標
結構化中繼資料：每份文件包含機器可讀的 frontmatter
扁平層級：最小化巢狀；偏好標籤和交叉引用
代理可定址：每份文件有穩定、可預測的路徑

知識庫架構

目錄結構

knowledge-base/
├── CLAUDE.md                    # AI 代理指引
├── INDEX.md                     # 人類可讀目錄
├── .kb/
│   ├── schema.json             # Frontmatter schema 定義
│   ├── glossary.json           # AI 脈絡的術語定義
│   └── relationships.json      # 文件關係圖
│
├── products/
│   ├── vsaas/
│   │   ├── _product.md         # 產品概覽
│   │   ├── requirements/
│   │   │   ├── device-management.md
│   │   │   ├── video-playback.md
│   │   │   └── analytics.md
│   │   └── specs/
│   │       ├── api-v2.md
│   │       └── data-models.md
│   │
│   └── vortex/
│       ├── _product.md
│       └── ...
│
├── domains/
│   ├── device-identity.md      # 跨產品領域概念
│   ├── authentication.md
│   └── video-streaming.md
│
├── glossary/
│   ├── terms.md                # 通用語言定義
│   └── acronyms.md
│
├── architecture/
│   ├── decisions/              # ADRs（架構決策記錄）
│   │   ├── 001-use-grpc.md
│   │   └── 002-event-sourcing.md
│   └── patterns/
│       ├── repository-pattern.md
│       └── clean-architecture.md
│
└── guides/
    ├── onboarding.md
    └── contribution.md

Frontmatter Schema

每份文件包含結構化中繼資料：

markdown

id: req-device-management-001
title: 裝置管理需求
type: requirement
product: vsaas
domain: device-identity
status: approved
version: 2.1.0
created: 2025-01-15
updated: 2025-11-28
authors:
  - alice@company.com
reviewers:
  - bob@company.com
tags:
  - device
  - management
  - crud
related:
  - spec-api-v2
  - domain-device-identity
ai_summary: |
  裝置生命週期管理的核心需求，包含
  註冊、設定、監控和除役。
# 裝置管理需求

...內容...

關鍵中繼資料欄位

欄位	用途	AI 使用方式
`id`	唯一識別碼	交叉引用、穩定連結
`type`	文件分類	過濾、脈絡載入
`product`	產品歸屬	範圍限定代理脈絡
`domain`	業務領域	語意分組
`status`	生命週期狀態	過濾活躍 vs 封存
`tags`	彈性分類	發現、搜尋
`related`	明確關係	脈絡擴展
`ai_summary`	預先計算摘要	快速脈絡載入

代理整合模式

1. MCP 資源提供者

將知識庫公開為 MCP 資源：

typescript

// 知識庫 MCP server
const knowledgeBaseServer = {
  resources: {
    list: async () => {
      // 回傳所有文件及中繼資料
      return documents.map(doc => ({
        uri: `kb://products/${doc.product}/${doc.id}`,
        name: doc.title,
        mimeType: 'text/markdown',
        metadata: doc.frontmatter
      }))
    },
    read: async (uri: string) => {
      // 回傳文件內容
      return { content: await readDocument(uri) }
    }
  },
  tools: {
    search: async ({ query, filters }) => {
      // 跨知識庫語意搜尋
      return searchDocuments(query, filters)
    },
    getRelated: async ({ documentId }) => {
      // 回傳相關文件
      return findRelatedDocuments(documentId)
    }
  }
}

2. CLAUDE.md 整合

markdown

## 知識庫

### 存取需求
- **位置**：`knowledge-base/products/{product}/requirements/`
- **格式**：含 YAML frontmatter 的 Markdown
- **搜尋**：使用 MCP 工具 `kb_search` 進行語意查詢

### 實作功能前
1. 搜尋知識庫的現有需求：`kb_search("功能名稱")`
2. 檢查相關規格：`kb_getRelated("requirement-id")`
3. 審查領域概念：`knowledge-base/domains/`

### 更新文件
實作功能時，更新相關知識庫文件：
1. 在需求檔案加入實作註記
2. 如需求已滿足則更新狀態
3. 為 API 變更建立新規格

遷移策略

階段 1：平行運行（第 1-3 個月）

活動：

[ ] 建立 Git 知識庫 repository
[ ] 定義 frontmatter schema
[ ] 建立包含 AI 指引的 CLAUDE.md
[ ] 在知識庫撰寫所有新規格
[ ] 在 Confluence 加入棄用通知

階段 2：主動遷移（第 3-6 個月）

活動：

[ ] 識別活躍 Confluence 頁面（過去 6 個月存取）
[ ] 轉換為 Markdown 格式
[ ] 加入結構化 frontmatter
[ ] 建立重導向對應
[ ] 更新交叉引用

階段 3：封存與完成（第 6-9 個月）

活動：

[ ] 將剩餘內容匯出為靜態封存
[ ] 停用 Confluence 編輯
[ ] 實作 MCP 資源提供者
[ ] 完成 Context7 註冊
[ ] 訓練團隊新工作流程

比較：Confluence vs Git 知識庫

面向	Confluence	Git 知識庫
AI 讀取存取	需要 API，有速率限制	直接檔案讀取
AI 寫入存取	複雜 API、權限	Git commit
版本歷史	內建但分離	Git log、blame
分支	不支援	原生
程式碼鄰近性	完全分離	同 repo 或連結
離線存取	有限	完整
搜尋	僅全文	語意 + 結構化
協作	即時	PR-based 審查
成本	按用戶授權	免費（Git hosting）
鎖定	高（專有）	無（純文字）

成功指標

指標	目標	如何測量
AI 脈絡載入時間	<2s	測量 MCP 資源取得
規格對程式碼關聯	>80%	追蹤含規格引用的 commits
文件新鮮度	平均 <90 天	監控 `updated` 日期
交叉引用準確度	100%	驗證 `related` 連結
遷移完成度	100% 活躍	審計 Confluence 使用
代理查詢成功率	>90%	追蹤 MCP 工具結果

要避免的反模式

1. 重新建立 Wiki 功能

問題： 加入富編輯、即時協作、複雜權限。

為何失敗： 偏離 Git 簡潔性，產生同步問題，降低 AI 相容性。

替代做法： 接受 PR-based 協作作為模式。

2. 深層巢狀

問題： 建立 5 層以上的資料夾層級。

為何失敗： 難以導航，路徑變得冗長，最終還是需要搜尋。

替代做法： 扁平結構搭配標籤和交叉引用。

3. 忽略 Frontmatter

問題： 撰寫沒有結構化中繼資料的 Markdown。

為何失敗： 失去機器可讀性，無法過濾，破壞關係。

替代做法： 透過 pre-commit hooks 強制 frontmatter。

4. 部分遷移

問題： 無限期同時運行 Confluence 和 Git KB。

為何失敗： 知識分裂，對事實來源困惑，雙重維護。

替代做法： 設定明確遷移截止日期，封存 Confluence。

相關： 持續脈絡清理 | 返回： 提案概覽

參考資料

Model Context Protocol (MCP) - Anthropic 的 AI 工具整合協定
Context7 - AI 文件查詢服務
Claude Code 文件 - CLAUDE.md AI 指引檔案的官方文件
Docs as Code - Write the Docs 的版本控制文件指南

工作流程框架

指導原則

治理

文化

執行

AI 代理友善知識庫

問題陳述

當前狀態：人類導向的知識孤島

團隊回饋的證據

根本錯配

提議解決方案：Git-Based Markdown 知識系統

目標架構

核心原則

知識庫架構

目錄結構

Frontmatter Schema

關鍵中繼資料欄位

代理整合模式

1. MCP 資源提供者

2. CLAUDE.md 整合

遷移策略

階段 1：平行運行（第 1-3 個月）

階段 2：主動遷移（第 3-6 個月）

階段 3：封存與完成（第 6-9 個月）

比較：Confluence vs Git 知識庫

成功指標

要避免的反模式

1. 重新建立 Wiki 功能

2. 深層巢狀

3. 忽略 Frontmatter

4. 部分遷移

參考資料

AI 代理友善知識庫 ​

問題陳述 ​

當前狀態：人類導向的知識孤島 ​

團隊回饋的證據 ​

根本錯配 ​

提議解決方案：Git-Based Markdown 知識系統 ​

目標架構 ​

核心原則 ​

知識庫架構 ​

目錄結構 ​

Frontmatter Schema ​

關鍵中繼資料欄位 ​

代理整合模式 ​

1. MCP 資源提供者 ​

2. CLAUDE.md 整合 ​

遷移策略 ​

階段 1：平行運行（第 1-3 個月） ​

階段 2：主動遷移（第 3-6 個月） ​

階段 3：封存與完成（第 6-9 個月） ​

比較：Confluence vs Git 知識庫 ​

成功指標 ​

要避免的反模式 ​

1. 重新建立 Wiki 功能 ​

2. 深層巢狀 ​

3. 忽略 Frontmatter ​

4. 部分遷移 ​

參考資料 ​

AI 代理友善知識庫

問題陳述

當前狀態：人類導向的知識孤島

團隊回饋的證據

根本錯配

提議解決方案：Git-Based Markdown 知識系統

目標架構

核心原則

知識庫架構

目錄結構

Frontmatter Schema

關鍵中繼資料欄位

代理整合模式

1. MCP 資源提供者

2. CLAUDE.md 整合

遷移策略

階段 1：平行運行（第 1-3 個月）

階段 2：主動遷移（第 3-6 個月）

階段 3：封存與完成（第 6-9 個月）

比較：Confluence vs Git 知識庫

成功指標

要避免的反模式

1. 重新建立 Wiki 功能

2. 深層巢狀

3. 忽略 Frontmatter

4. 部分遷移

參考資料