改善提案
本章呈現源自脈絡工程分析的可執行提案。每個提案都針對跨團隊回饋中識別的具體挑戰，並提供具體的實施指引。
目的： 將脈絡工程洞察轉化為團隊可漸進式採用的可實施改善方案。
提案框架
本章所有提案遵循一致的結構：
每個提案包含：
- 問題陳述 - 從團隊回饋中識別的具體問題
- 提議解決方案 - 解決問題的架構與方法
- 實施路線圖 - 分階段推出與具體交付物
- 成功指標 - 可測量的效果追蹤指標
- CLAUDE.md 整合 - 如何為 AI 消費文件化解決方案
提案分類
流程提案
建立維護脈絡品質的持續實踐。
| 提案 | 說明 | 狀態 |
|---|---|---|
| AI-First 決策框架 | 在每個決策點系統性評估 AI 作為主要執行者的框架 | 已完成 |
| AI-DLC 群體精煉 | AI 增強開發生命週期與協作精煉會議 | 已完成 |
| 持續脈絡清理 | 識別、文件化和遷移棄用模式的框架 | 已完成 |
| 規格萃取 | 從現有實作逆向工程規格作為「既存事實」脈絡 | 已完成 |
基礎建設提案
建立提升 AI 程式碼生成準確度的基礎系統。
| 提案 | 說明 | 狀態 |
|---|---|---|
| 設計系統 | 跨平台一致性的統一設計系統架構 | 已完成 |
| shadcn/ui 基礎 | 採用 shadcn/ui 作為 Web 設計系統實作基礎 | 已完成 |
| AI 代理友善知識庫 | 從 Confluence 遷移至 Git-based Markdown 供 AI 代理存取 | 已完成 |
| 全域需求儲存庫 | 產品導向的集中式需求儲存庫，確保跨平台一致性 | 已完成 |
| 技術雷達與路線圖 | 用於技術治理的互動式技術雷達視覺化與路線圖管理 | 已完成 |
| 內部規格平台 | 具日期版本控制和多產品支援的集中式規格託管平台 | 已完成 |
| Claude Skills 採用 | 鼓勵團隊建立、分享和維護 Claude Code Skills 以實現可重複使用的 AI 工作流程 | 已完成 |
標準提案
定義 AI 理解的術語和文件模式。
| 提案 | 說明 | 狀態 |
|---|---|---|
| 通用語言 | 跨團隊術語標準與領域詞彙表 | 已完成 |
| 多產品、多層級規格管理 | 適用於多產品組織的階層式規格管理框架 | 已完成 |
| Frontmatter 規格協調 | 用於跨規格系統協調 Markdown 文件的標準化 YAML frontmatter 模式 | 已完成 |
| CLAUDE.md 標準 | AI 指引檔案的模板與最佳實務 | 規劃中 |
提案摘要
AI-DLC 群體精煉
問題： 傳統 SDLC 方法未能在關鍵決策點運用 AI。PM、RD、UX 和架構師之間的順序式交接造成知識孤島，遺漏在開發後期才浮現的邊界案例。
解決方案： 引入群體精煉會議，所有利害關係人與 AI 同時協作：
- PM、RD、UX、架構師和 AI 共同參與
- AI 浮現邊界案例、檢查一致性、產生文件
- 單一會議產出完整規格
- 跨視角即時綜合
核心洞察： 當多元視角同時挑戰假設時，需求品質會顯著提升。AI 增加了一個不知疲倦的參與者，能夠即時發現缺口並維護完整的文件。
持續脈絡清理
問題： 脈絡污染會隨著程式庫演進而累積。遺留模式、棄用框架和不一致命名會混淆 AI 程式碼生成。
解決方案： 五階段持續循環：
- 識別 - 透過 AI 輸出審查偵測污染
- 文件化 - 更新 CLAUDE.md 現行標準
- 標記 - 為遺留程式碼加入棄用標記
- 遷移 - 漸進式遷移至現代模式
- 驗證 - 監控 AI 準確度並迭代
核心洞察： 脈絡清理應整合到開發工作流程，成為持續實踐。
設計系統
問題： 元件重複是最常見的 AI 程式碼生成失敗之一。AI 建立新的 UI 元件而非重用現有的，因為元件分散、未文件化、命名不一致。
解決方案： 建立統一設計系統：
- 具可搜尋索引的集中元件目錄
- 跨平台元件對應（Web、iOS、Android）
- 用於一致樣式的設計 tokens
- 具提示和使用指南的 AI 優化文件
核心洞察： AI 無法「發現」未組織的元件。如果它們不在預期位置且沒有清晰文件，對 AI 而言等於不存在。
shadcn/ui 基礎
問題： 傳統元件庫（Ant Design、Material UI）為 AI 帶來挑戰：
- AI 無法理解的黑箱實作
- 需要 CSS 覆蓋技巧的有限客製化
- 破壞已學模式的版本升級
解決方案： 採用 shadcn/ui 的「複製並擁有」模式：
- 完全程式碼擁有權 - 無上游依賴自由修改
- AI 可存取的實作 - 程式碼在你的專案中
- 自訂 registry - 跨專案共享領域元件
- MCP 整合 - AI 驅動的元件發現
核心洞察： shadcn/ui 將 UI 開發從依賴消費轉變為基礎建設擁有權，讓人類和 AI 開發者都能使用完全可存取的程式碼。
AI 代理友善知識庫
問題： 傳統知識系統（Confluence、SharePoint、Google Docs）為人類瀏覽設計，而非機器消費：
- AI 無法解析的專有格式
- 無 Git 整合進行版本關聯
- 破壞 AI 解析的富文字
- 阻擋代理存取的權限複雜性
解決方案： 遷移至 Git-based Markdown 知識系統：
- 具結構化 frontmatter 的純 Markdown
- 版本控制作為事實來源
- 用於 AI 存取的 MCP 資源提供者
- 語意搜尋和關係圖
核心洞察： 為人類瀏覽設計的知識系統會主動阻礙 AI 代理。讓知識可被機器讀取同時保持人類可編輯，可啟用代理協作。
全域需求儲存庫
問題： 分散在平台特定文件中的需求導致實作分歧。每個團隊（Web、iOS、Android、Backend）對同一 PRD 有不同詮釋，AI 代理只看到其平台的詮釋，造成：
- 不一致的功能實作
- 某些平台遺漏邊界情況
- 衝突的 API 合約
- 冗餘的規格工作
解決方案： 建立集中式、產品導向的需求儲存庫：
- 產品中心組織（需求按產品分組，而非平台）
- 單一事實來源，附帶平台特定補充
- API 優先合約與需求一起定義
- AI 原生格式，具結構化 frontmatter 中繼資料
- 版本關聯，連結需求變更到實作 PR
核心洞察： 分散在平台特定文件中的需求會導致實作分歧。一個單一的、AI 可存取的需求儲存庫讓代理能從相同的事實來源在所有端點生成一致的程式碼。
通用語言
問題： 術語碎片化導致 AI 程式碼生成失敗。當不同團隊對同一概念使用不同術語（camera vs device vs channel），AI 產生需要人工修正的不一致程式碼。
解決方案： 建立跨團隊術語標準：
- 具規範術語定義的領域詞彙表
- 遷移指引的遺留術語對應
- 平台特定命名慣例
- 強制執行的驗證工具
核心洞察： AI 代理從程式碼模式學習。如果同一概念在程式庫中有多個名稱，AI 會持續複製這種不一致性。通用語言是可靠 AI 程式碼生成的基礎。
多產品、多層級規格管理
問題： 現有的 AI 開發框架假設單一產品、單一團隊的環境。多產品組織面臨挑戰：AI 代理缺乏組織標準的脈絡、遺漏產品特定約束、無法偵測跨產品邊界的衝突規格。
解決方案： 建立具有五個層級的階層式規格管理框架：
- 層級 0：組織原則（永遠適用）
- 層級 1：產品規格（產品特定約束）
- 層級 2：功能規格（要建構什麼）
- 層級 3：平台規格（各平台如何建構）
- 層級 4：實作規格（詳細設計）
並透過共享領域、API 標準、設計系統和安全政策處理跨所有產品的橫切關注點。
核心洞察： 規格應從組織層級原則向下傳遞到產品特定實作，同時維持可追溯性。低層級從高層級繼承（而非複製），覆寫需要有明確文件化的理由。這使 AI 代理在生成程式碼時能夠導航完整的脈絡階層。
Frontmatter 規格協調
問題： 組織內的 Markdown 文件缺乏標準化元數據。每個團隊發明不同的 frontmatter 欄位，關係僅存在於散文中，AI 代理無法在不解析整個內容的情況下建立文件圖譜。
解決方案： 為所有規格文件建立標準化的 YAML frontmatter 模式：
- 必要識別欄位（id、title、type、status、version、owner）
- 明確關係宣告（inherits、depends_on、related、cross_product_refs）
- 需要理由說明的覆寫追蹤
- 用於脈絡優先排序的 AI 指引欄位
- CI 管線中的 JSON Schema 驗證
核心洞察： Markdown frontmatter 是規格文件的天然協調層。當標準化後，frontmatter 成為可查詢的關係圖譜，讓 AI 代理能夠遍歷規格、偵測衝突並維護一致性，無需專有工具。
技術雷達與路線圖
問題： 分散在 wiki、試算表和部落知識中的技術決策，導致重複的評估工作、不一致的採用，以及對組織技術方向的能見度不足。
解決方案： 在內部開發者入口網站建置技術雷達與路線圖功能：
- 互動式雷達視覺化，包含 Adopt/Trial/Assess/Hold 環
- 四個象限：語言與框架、工具、平台、技術
- 技術提案與投票工作流程
- 具時間軸視圖的策略路線圖管理
- 歷史追蹤以比較雷達隨時間的變化
核心洞察： 統一的技術雷達提供了「我們應該使用什麼技術」的單一事實來源，消除跨團隊的重複技術評估。
內部規格平台
問題： 管理多個產品的組織面臨規格存取碎片化的問題。規格散落在不同儲存庫中、沒有稽核追蹤的版本控制、缺乏跨產品可見性，且 AI 代理每次會話都需重新取得和解析。
解決方案： 建立具日期版本控制的集中式規格平台：
- URL 結構：
https://spec.{company.domain}/{date}/{product-id}/{spec-type}/specs/{spec-id} - 多種規格類型：
func、ux、api、infra（遵循 OpenSpec 結構） - 日期版本優於語意版本（客觀、稽核友善、多產品同步）
- 版本別名：
/latest、/head、/{date} - 尊重 OpenSpec 的扁平能力命名慣例
- Git-based 解析（無儲存重複）
- MCP 整合供 AI 代理存取
核心洞察： 日期版本控制比語意版本控制更適合規格管理。「給我看 2024-09-15」是客觀且可稽核的，而「Q3 上線的是哪個版本？」需要解釋。跨產品相同日期意味著相同快照，消除版本對齊的痛苦。
逆向工程規格萃取
問題： 遺留程式庫缺乏結構化脈絡。AI 代理每次會話都重新探索相同的程式碼，浪費脈絡窗口。機構知識鎖在實作中沒有文件。
解決方案： 從現有程式碼逆向工程規格以建立「既存事實」脈絡：
- 四層萃取方法論（邊界、結構、行為、邊界案例）
- 既存事實規格與前瞻性需求有明確區分
- AI 輔助萃取搭配人類驗證
- 信心等級指示可信度
- 相較原始程式碼有 10-20 倍的脈絡壓縮
核心洞察： 從實作萃取的規格作為壓縮的、權威的脈絡。一份良好撰寫的規格比其描述的程式碼小 5-20 倍，大幅減少脈絡窗口使用量，同時保留關鍵知識。
實施優先順序
建議順序
- 從持續脈絡清理開始 - 建立持續流程
- 加入設計 Tokens - 一致樣式的基礎
- 實施 shadcn/ui - 現代元件架構
- 定義通用語言 - 跨團隊術語對齊
快速參考
哪個提案解決哪個問題？
| 問題 | 提案 |
|---|---|
| 需求不完整、遺漏邊界案例 | AI-DLC 群體精煉 |
| PM/RD/UX/架構師之間的知識孤島 | AI-DLC 群體精煉 |
| AI 建立重複元件 | 設計系統 |
| AI 使用棄用模式 | 持續脈絡清理 |
| 元件庫升級破壞程式碼 | shadcn/ui 基礎 |
| AI 硬編碼顏色值 | 設計系統 |
| AI 無法存取 Confluence 規格 | AI 代理友善知識庫 |
| 需求分散在平台特定文件 | 全域需求儲存庫 |
| 跨平台功能實作不一致 | 全域需求儲存庫 |
| 跨團隊命名不一致 | 通用語言 |
| AI 不知道專案慣例 | CLAUDE.md 標準（規劃中） |
| AI 缺乏組織層級脈絡 | 多產品、多層級規格管理 |
| 規格無法跨產品傳遞 | 多產品、多層級規格管理 |
| 無規格繼承或覆寫追蹤 | 多產品、多層級規格管理 |
| 文件間 frontmatter 不一致 | Frontmatter 規格協調 |
| AI 無法發現文件關係 | Frontmatter 規格協調 |
| 無文件參照驗證 | Frontmatter 規格協調 |
| 遺留程式碼沒有文件 | 規格萃取 |
| AI 每次會話都重新探索相同程式碼 | 規格萃取 |
| 脈絡窗口浪費在原始程式碼上 | 規格萃取 |
| 機構知識鎖在實作中 | 規格萃取 |
| 規格散落在不同儲存庫 | 內部規格平台 |
| 無稽核用規格版本控制 | 內部規格平台 |
| AI 每次會話都重新取得規格 | 內部規格平台 |
| 跨產品規格不可發現 | 內部規格平台 |
團隊特定入口點
| 團隊 | 從這裡開始 |
|---|---|
| 所有團隊 | 新功能用 AI-DLC 群體精煉，現有程式碼用 持續脈絡清理 |
| Web 前端 | shadcn/ui 基礎 |
| Mobile（iOS/Android） | 設計系統 - 跨平台對應 |
| Backend | 持續脈絡清理 - 模式文件化 |
成功指標
追蹤所有提案的這些指標：
| 指標 | 目標 | 如何測量 |
|---|---|---|
| AI 首次準確率 | >80% | 追蹤需要重新生成的 prompt |
| 元件重用率 | >90% | 審計 AI 生成的 PR 中新元件 vs 現有元件 |
| 棄用程式碼比例 | <20% | grep -r "@deprecated" vs 總檔案數 |
| 設計 token 採用率 | 100% | grep 硬編碼顏色/間距值 |
| 跨平台一致性 | 高 | 視覺比較審計 |
參考資料
- Claude Code 文件 - CLAUDE.md 和 AI 指引檔案的官方文件
- Model Context Protocol (MCP) - Anthropic 的 AI 工具整合協定
- OpenSpec - 用於 AI 輔助工作流程的規格驅動開發框架