逆向工程規格萃取
現有程式庫包含隱含在實作中的隱性規格。當 AI 代理在遺留系統上工作時，缺乏關於系統是什麼的結構化脈絡，導致重複的程式碼探索、脈絡窗口浪費，以及跨會話的不一致理解。規格萃取引入從程式碼逆向工程規格的方法論，以建立「既存事實」脈絡。
核心洞察： 從實作萃取的規格作為壓縮的、權威的脈絡。一份良好撰寫的規格比其描述的程式碼小 5-20 倍，大幅減少脈絡窗口使用量，同時保留 AI 代理所需的關鍵知識。
問題陳述
現狀：臨時程式碼探索
缺少規格的痛點
| 問題 | 對 AI 開發的影響 |
|---|---|
| 無正式規格 | AI 每次會話都重新探索程式碼 |
| 部落知識 | 實作決策鎖在開發者腦中 |
| 脈絡窗口浪費 | 必須載入整個檔案才能理解行為 |
| 理解不一致 | 不同 AI 會話對程式碼有不同詮釋 |
| 入職摩擦 | 新的 AI 代理（和人類）從零開始 |
真實案例
重複發現：
AI 代理需要修改認證流程。每次會話都讀取 15 個檔案來理解流程。因為沒有規格文件化認證架構，相同的約 2000 行被重複載入。
失落的機構知識：
原始開發者離開。程式庫沒有文件。新團隊成員和 AI 代理必須從實作逆向工程意圖，經常猜錯。
脈絡溢出：
功能涉及 8 個模組。載入所有程式碼超過脈絡窗口。沒有規格，AI 無法獲得高層次視圖，做出破壞未文件化不變量的變更。
提案：既存事實規格
目標狀態
什麼是既存事實規格？
既存事實規格文件化從現有程式碼萃取的已驗證、已實作行為。不同於描述應該建構什麼的前瞻性需求，既存事實規格描述已經建構的內容。
關鍵區別：既存事實 vs 需求
| 面向 | 需求規格 | 既存事實規格 |
|---|---|---|
| 來源 | 業務需求、使用者故事 | 已實作程式碼 |
| 目的 | 定義要建構什麼 | 文件化已存在的內容 |
| 權威性 | 規範性（應該符合） | 描述性（確實符合） |
| 建立時機 | 實作之前 | 實作之後 |
| 驗證 | 測試驗證實作 | 實作即為真實 |
| 使用案例 | 綠地開發 | 遺留系統理解 |
既存事實規格格式
Frontmatter 模式
yaml
id: ef-auth-oauth-flow
title: OAuth 2.0 認證流程
type: existing-fact
status: verified
version: 1.0.0
created: 2025-12-02
updated: 2025-12-02
extracted_from:
- src/auth/oauth.ts
- src/auth/token-manager.ts
- src/middleware/auth.ts
extraction_method: ai-assisted
confidence: high
verified_by:
- test-suite
- human-review
compression_ratio: 12:1
authors:
- extraction-agent
reviewers:
- senior-developer@company.com
tags:
- authentication
- oauth
- security
ai_summary: |
Web 客戶端的 OAuth 2.0 PKCE 流程實作。
處理授權、token 交換、刷新和登出。
透過標準端點與身分提供者整合。內容結構
markdown
# [功能名稱] - 既存事實規格
## 概述
[1-2 段落摘要說明此程式碼做什麼]
## 系統邊界
### 進入點
- [API 端點、函式簽名]
### 外部依賴
- [此程式碼互動的服務、API、資料庫]
### 資料流
[顯示高層次流程的 Mermaid 圖表]
## 行為規格
### 核心行為
#### 行為：[名稱]
- **觸發條件**：[什麼啟動此行為]
- **前置條件**：[必要狀態]
- **流程**：[發生什麼]
- **後置條件**：[結果狀態]
- **萃取自**：`file.ts:line`
### 錯誤處理
#### 錯誤：[名稱]
- **條件**：[何時發生此錯誤]
- **回應**：[系統如何回應]
- **恢復**：[如何恢復，如果適用]
## 約束與不變量
- [必須永遠成立的規則]
- [限制與閾值]
## 已知技術債
- [不應複製的已知問題]
## 驗證狀態
| 面向 | 狀態 | 證據 |
|------|------|------|
| 核心流程 | 已驗證 | 單元測試、整合測試 |
| 錯誤處理 | 部分 | 某些邊界案例未測試 |
| 效能 | 未驗證 | 無可用基準 |分層萃取方法論
四層方法
以遞減粒度的層次萃取規格，每層提供更多細節：
層次詳情
| 層次 | 萃取內容 | 壓縮目標 | 需要時機 |
|---|---|---|---|
| L1：邊界 | API 契約、介面定義、外部整合點 | 10:1 | 永遠 |
| L2：結構 | 元件職責、模組間依賴、資料流 | 20:1 | 大多數功能 |
| L3：行為 | 演算法模式、狀態機、錯誤處理策略 | 5:1 | 複雜邏輯 |
| L4：邊界案例 | 驗證規則、約束、限制、已知怪異行為 | 3:1 | 關鍵路徑 |
漸進價值
單獨第 1 層就能提供顯著價值。每個額外層次在需要時增加精確度：
萃取工作流程
三階段流程
階段 1：發現
目標： 理解程式庫結構並識別萃取目標。
AI 任務：
- 分析目錄結構和檔案組織
- 識別進入點（API、CLI 命令、事件處理器）
- 映射模組依賴
- 偵測架構模式（MVC、Clean Architecture 等）
- 產生發現報告供人類審查
輸出：
markdown
## 發現報告：[程式庫名稱]
### 架構概述
[高層次描述]
### 關鍵模組
| 模組 | 目的 | 依賴 | 優先順序 |
|------|------|------|---------|
| auth | 認證 | db, identity-provider | 高 |
| api | REST 端點 | auth, services | 高 |
| ... | ... | ... | ... |
### 建議萃取順序
1. [模組] - [原因]
2. [模組] - [原因]
### 複雜度評估
- 預估萃取工作量：[小時/天]
- 高複雜度區域：[清單]階段 2：萃取
目標： 從程式碼產生草稿規格。
AI 任務：
- 徹底閱讀模組程式碼
- 依循層次方法論產生規格
- 與測試交叉參照以驗證行為
- 文件化不確定性和假設
人類任務：
- 審查產生的規格準確性
- 修正誤解
- 加入 AI 無法推斷的脈絡（業務理由、歷史決策）
- 核准或要求精煉
迭代模式：
階段 3：驗證
目標： 建立規格可信度以供 AI 脈絡消費。
驗證來源：
| 來源 | 信心提升 | 證據 |
|---|---|---|
| 自動化測試通過 | +20% | 測試覆蓋報告 |
| 人類審查完成 | +30% | 審查者簽核 |
| 生產行為匹配 | +30% | 監控/日誌比對 |
| 原始開發者確認 | +20% | 開發者核准 |
信心等級：
| 等級 | 標準 | AI 使用指引 |
|---|---|---|
| 高 | 測試驗證 + 人類審查 | 作為權威脈絡使用 |
| 中 | 人類審查，部分測試覆蓋 | 謹慎使用，驗證關鍵路徑 |
| 低 | AI 產生的草稿，等待驗證 | 視為假設，使用前驗證 |
實施路線圖
階段 1：試點萃取（第 1-2 週）
目標： 為 1-2 個高價值模組萃取規格。
交付物：
- [ ] 選擇試點模組（高變更頻率、良好測試）
- [ ] 執行發現階段
- [ ] 產生第 1 層 + 第 2 層規格
- [ ] 與模組負責人驗證
- [ ] 測量壓縮比
成功標準：
- 壓縮比 >10:1
- 模組負責人確認準確性
- AI 代理可使用規格而非閱讀程式碼
階段 2：工具與模板（第 3-4 週）
目標： 建立可重複的萃取流程。
交付物：
- [ ] 既存事實規格模板
- [ ] 萃取 prompt 庫
- [ ] 驗證檢查清單
- [ ] 規格新鮮度檢查的 CI 整合
階段 3：系統性萃取（第 5-8 週）
目標： 為所有高優先順序模組萃取規格。
交付物：
- [ ] 優先模組清單
- [ ] 萃取排程
- [ ] 進度追蹤儀表板
- [ ] 規格對程式碼新鮮度監控
階段 4：持續維護（持續進行）
目標： 保持規格與程式碼同步。
交付物：
- [ ] 變更偵測觸發重新萃取
- [ ] 程式碼變更時的規格差異
- [ ] 過期警示
- [ ] 定期完整刷新排程
CLAUDE.md 整合
加入專案 CLAUDE.md：
markdown
## 既存事實規格
### 目的
既存事實規格文件化已驗證、已實作的行為。
當可用時，使用這些規格而非閱讀原始碼。
### 位置
- `docs/specs/existing-facts/` - 萃取的規格
- 每個規格包含 `extracted_from` 參照原始檔案
### 使用優先順序
1. 先檢查既存事實規格
2. 如果規格存在且信心為高，使用規格作為脈絡
3. 如果規格為中信心，驗證關鍵假設
4. 如果沒有規格或信心為低，閱讀原始碼
### 何時觸發重新萃取
如果你修改既存事實規格涵蓋的程式碼：
1. 註記規格可能已過期
2. 如果變更重大則更新規格
3. 如果不確定則標記規格需要審查
### 規格品質指標
- `confidence: high` - 信任為權威
- `confidence: medium` - 驗證關鍵路徑
- `confidence: low` - 視為假設
- `compression_ratio` - 越高代表越好的脈絡效率脈絡壓縮分析
各層壓縮目標
| 層次 | 程式碼範例 | 規格等效 | 比率 |
|---|---|---|---|
| L1：邊界 | 500 行 API 處理器 | 50 行端點規格 | 10:1 |
| L2：結構 | 10 個模組共 2000 行 | 100 行架構 | 20:1 |
| L3：行為 | 300 行演算法 | 60 行行為規格 | 5:1 |
| L4：邊界案例 | 200 行驗證 | 70 行約束規格 | 3:1 |
真實範例
之前：載入原始碼
認證模組的脈絡 tokens：
- oauth.ts: 450 行（~2000 tokens）
- token-manager.ts: 280 行（~1200 tokens）
- auth-middleware.ts: 180 行（~800 tokens）
- auth.test.ts: 520 行（~2300 tokens）
總計：1430 行（~6300 tokens）之後：載入既存事實規格
認證規格的脈絡 tokens：
- ef-auth-oauth-flow.md: 120 行（~500 tokens）
總計：120 行（~500 tokens）
壓縮：12:1
每次會話節省 tokens：5800 tokens成功指標
| 指標 | 目標 | 如何測量 |
|---|---|---|
| 平均壓縮比 | >10:1 | 程式碼行數 / 規格行數 |
| 規格準確性 | >95% | 人類審查通過率 |
| 脈絡減少 | >50% | Token 使用前/後 |
| AI 任務成功率 | +20% | 有/無規格比較 |
| 萃取效率 | <2 小時/模組 | 時間追蹤 |
| 規格新鮮度 | <30 天 | updated 日期監控 |
應避免的反模式
1. 萃取所有內容
問題： 嘗試為每行程式碼建立規格。
解決方案： 先專注於高價值、高變更頻率的模組。不是所有程式碼都需要規格。
2. 無驗證的規格
問題： 產生規格並假設它們正確。
解決方案： 每個規格都需要人類審查。信心等級傳達可信度。
3. 過期規格
問題： 規格隨時間與實作偏離。
解決方案： CI 檢查、新鮮度監控、變更觸發的重新萃取。
4. 過度詳細的規格
問題： 規格與其描述的程式碼一樣長。
解決方案： 專注於抽象。如果壓縮比 ❤️:1，規格太詳細。
5. 忽略技術債
問題： 為「不應該這樣」的程式碼萃取規格。
解決方案： 在規格中文件化已知技術債。不要透過規格化來合法化壞模式。
常見問題
何時應該萃取規格 vs 撰寫新規格？
萃取當：
- 程式碼存在但文件不存在
- 原始開發者不可用
- 需要快速理解遺留系統
- 想要減少脈絡窗口使用量
撰寫新規格當：
- 建構新功能
- 重新設計現有功能
- 程式碼尚不存在
如何處理違反自身模式的程式碼？
在規格中文件化不一致性：
markdown
## 已知不一致
- 模組 A 使用模式 X
- 模組 B 對相同目的使用模式 Y
- **注意**：這是遺留技術債，非刻意設計既存事實規格應與程式碼放在一起還是分開？
建議： 分開的 docs/specs/existing-facts/ 目錄。
理由：
- 規格聚合多個檔案
- 更容易找到並載入為脈絡
- 可以有不同的審查頻率
- 與程式碼註釋有明確區分
多久應該重新萃取一次？
| 程式碼變更類型 | 需要重新萃取 |
|---|---|
| Bug 修復 | 否（除非改變行為） |
| 重構（相同行為） | 可能（更新檔案參照） |
| 功能新增 | 是（加入規格） |
| 行為變更 | 是（更新規格） |
| 重大改寫 | 是（完整重新萃取） |
相關提案
- AI-DLC 群體精煉 - 前瞻性規格建立
- AI 代理友善知識庫 - 規格應存放位置
- 持續脈絡清理 - 維護規格新鮮度
- Frontmatter 規格協調 - 規格的中繼資料模式
相關： AI 代理友善知識庫 | 返回： 提案概覽
參考資料
- Claude Code 文件 - CLAUDE.md AI 指引檔案的官方文件
- AI 代理的有效脈絡工程 - Anthropic 的脈絡優化指南
- OpenSpec - 規格驅動開發框架
- 遺留程式碼文件模式 - Write the Docs 社群資源