一份 50 頁的規格書，三個人讀了三天

規格書（SRS，Software Requirements Specification）品質決定了後續開發的成本。讀過爛的規格書的人都知道那是什麼感受：邏輯打架、約束遺漏、最後上線才發現「咦，這裡其實不支援」。

我對這個問題的想法很簡單：大多數公司沒有辦法解決這個問題，不是因為問題難，而是因為現有工具在這裡沒有立足點。

今日目標

讀完這篇，你會知道：人工 SRS 審查為什麼這麼貴；為什麼現有工具都不靠譜；我們怎麼用 Agent 解決這個問題；怎麼在 30 天內從零到生產級系統。

重點不是馬上寫代碼，而是先搞清楚問題和方向。

SRS 的現實

一份正常的規格書會有這些問題：

• 邏輯矛盾。第 2 章說系統支持多用戶並行，第 8 章說單用戶模式。讀規格書的人（無論是 PM 或工程師）會疲勞。三天之內跨章節的矛盾會被忽過去。
• 隱含依賴。功能 A 依賴功能 B，但這個依賴在規格書裡沒寫明。後來有人改了 B 的邏輯，A 就爆炸了。
• 模糊術語。「系統應該快速」，但快速的定義呢？1 秒？100 毫秒？沒人問。
• 重複定義。同一個需求在三個不同章節用三種不同的措辭出現。實現的時候就有三種實現。
• 邊界情況被遺漏。大多數邏輯衝突只在極端情況下浮現。

為什麼？因為人工審查規格書，實質上是靠經驗和記憶力。一個人讀 50 頁文件的時候，第 3 頁的約束會在第 25 頁被遺忘。

現狀：手動審查的局限

業界的做法是讓 PM 或需求工程師過一遍規格書，用經驗判斷。這樣做的問題很清楚：

1. 成本：一份 50 頁的 SRS 需要 2–3 人花 2–3 天。一個人的標準日薪是多少？算一算。
2. 遺漏：人工審查的時候，人會累。跨章節的隱性衝突容易被忽視。
3. 無法追蹤：找到一個矛盾後，你知道是在哪兩個需求間出現的嗎？有辦法快速回溯嗎？
4. 難以迭代：規格書改了一次，整份都要重新審查。
5. 沒有量化指標：你無法比較「這版的規格書比上版改進了多少」。

現有工具為什麼不行

規範管理工具（Jira、Azure DevOps、Confluence）

✅ 版本管理、團隊協作、權限控制

❌ 只能存儲需求，分析不了邏輯

形式化方法（Alloy、Z3）

✅ 能精確驗證邏輯

❌ 需要用形式語言寫規格書。學習曲線很陡。業務文檔不可能用形式語言寫。

靜態分析工具

✅ 能檢查語法、格式

❌ 無法理解自然語言的邏輯。「系統支持多用戶」和「單用戶模式」的矛盾，靜態工具找不出來。

LLM 聊天機器人（直接用 ChatGPT）

✅ 理解自然語言

❌ 有幾個要命的問題：

• 黑盒。看不到推理過程。
• 無記錄。問一遍就完事。下次想看同樣的分析，沒有。
• 無比較。改了 prompt 之後，不知道有沒有真的改進。
• 超過 token 上限。複雜的規格書分析不了。

所以我才要構建一個不同的東西。

Agent 可以做什麼

SRS 審查 Agent 不是聊天機器人，是一個系統。它的核心特點：

1. 透明的推理過程

記錄每一步推理，不是直接給答案。類似這樣：

讀入規格書
  ↓
[提取所有需求]
  ├─ REQ-2.1.3: 系統支持多用戶並行
  ├─ REQ-8.4.2: 單用戶模式
  └─ ...

[對照約束，檢測矛盾]
  ├─ 衝突: REQ-2.1.3 ↔ REQ-8.4.2
  └─ ...

輸出報告

這個流程對誰有用？對之後想改進算法的人有用。因為你能看到 Agent 在哪個環節出錯了。

2. 可測試、可量化

不是「好不好」的主觀評價，而是數字：

• Precision：Agent 檢出的矛盾中，有多少是真的？（要低誤報率）
• Recall：規格書裡真正的矛盾中，Agent 檢出了多少？（要低漏報率）
• 成本：分析一份 SRS 花多少時間？多少 token？
• 延遲：響應時間是多少？

有了這些數字，你就能比較「我改了 prompt，Recall 從 0.65 升到 0.78 了」。這是工程，不是玩 prompt。

3. 全局約束追蹤，不會遺忘

傳統 LLM 按順序讀文本，讀到後面就忘了前面說了什麼。我們用 LangGraph 的狀態機 + 全局約束池解決這個。

想像人工審查時，你先寫便簽記重點需求，然後逐頁檢查。每一頁都對著便簽看有沒有衝突。傳統 LLM 沒有這個「便簽」，讀著讀著就忘了。

我們的 Agent 用全局約束池充當這個便簽：

📖 讀取規格書

[全局約束池]
  ├─ REQ-2.1.3: 「系統支持多用戶並行」
  ├─ REQ-8.4.2: 「單用戶模式」
  └─ ... （全文所有約束）

逐個檢查每一章
  ├─ 第 2 章 vs 約束池 → 無衝突 ✓
  ├─ 第 8 章 vs 約束池 → 發現矛盾 ❌
  │  (REQ-8.4.2「單用戶」 vs REQ-2.1.3「多用戶」)
  └─ ...

輸出：所有發現的矛盾 + 位置 + 建議

這樣 Agent 永遠記得整份規格書的約束。你也能精確定位矛盾在哪些需求之間。

這 30 天要做什麼

第 1 週（Day 1-8）：基礎架構與衝突檢測引擎

Day 1-2：為什麼需要 SRS 審查 Agent + 本地 LLM Agent Runner

• 需求工程問題理論 → 可運行的系統

Day 3-5：文檔分塊 + GlobalConstraintsState + LangGraph 工作流

• Markdown 感知分塊、全局約束池、狀態機編排

Day 6-8：工具集成、性能優化、評測系統

• MCP 工具系統、LRU 快取、基準測試（F1=0.789）

交付物：可讀 SRS、能檢測基本衝突的 Agent 系統

第 2 週（Day 9-17）：檢測優化與生產系統

Day 9-12：檢測優化（智能、混合、LLM、性能）

• 語義分析（F1=0.524）→ 混合策略 → LLM 驗證 → 10 倍性能優化

Day 13-17：完整生產系統（API + 前端 + 認證 + 會話）

• FastAPI（23 測試）→ React 前端 → JWT 認證 → 刷新令牌 + 會話管理（7 測試）

交付物：240+ 個測試通過、2600+ 行生產代碼、完整 Web 應用

第 3 週（Day 18-21）失敗案例分析與 Prompt 改進

Day 18-19：失敗案例分析、Prompt 優化、目標 F1 > 0.85 Day 20-21：重試機制、Guardrail、A/B 測試框架

交付物：改進的版本 + A/B 測試報告

第 4 週（Day 22-30）報告、工具化、容器化、發佈

Day 22-26：報告生成、CLI 工具、Docker 容器化 Day 27-29：大規模測試、完整文檔、開源準備 Day 30：GitHub 開源發佈

最終交付物：完整的生產級系統 + 開源倉庫

你會得到什麼

30 天後有代碼、有文章、有開源倉庫。但更重要的是思路：

• 用 LLM 做長文本邏輯推理的方法
• 怎麼設計一個可觀察、可測試、能迭代的 AI 系統
• 用工程的方法優化 Agent，而不是盲目調 prompt
• 怎麼把 AI 能力實際應用到業務問題上

前置知識

必須懂 Python 基礎（函數、類）、終端機操作、git 的 commit 和 push。

API 用過更好，但沒用過也行。LLM 和 Prompt 工程聽說過最好，沒聽過也沒關係。

LangGraph、MCP 這些我會邊教邊寫。AI 理論完全不需要提前學。

系列的做法

每天寫能跑的代碼，不是紙上談兵。每天一個功能，Day 2 就能看到結果。

從 Day 8 開始用數據說話，Precision、Recall、F1 分數，不是「感覺變好了」。

文章裡明確說「把這個檔案放在這個位置」「執行這個命令」，可以直接跟著做。

明天

明天做最小可用的 Agent Runner。讀 Markdown 檔案、呼叫本地 LLM、返回初步分析。不複雜，但是後面所有功能的基礎。

系列進度

第 1 週：讓 SRS 從黑盒變透明 ← 今天

第 2 週：評測系統與品質量化 → 下週

第 3 週：優化與改進策略 → 兩週後

第 4 週：系統整合與發佈 → 三週後