文件優先開發方法論
📖 技能介紹
name: 文件優先開發方法論 slug: stream-coding version: 1.0.0 displayName: 文件優先開發方法論 description: > 文件優先開發方法論專用技能，幫助AI Agent高效完成相關任務。 summary: "文件優先開發方法論專用技能，幫助AI Agent高效完成相關任務。" license: MIT category: 開發者工具 framework: - Claude Code - Codex - Hermes Agent - OpenClaw - QClaw - WorkBuddy platform: multi-platform homepage: "https://github.com/1991513ccie-png" repository: "https://github.com/1991513ccie-png"
Stream Coding v3.5 — 文件優先的開發方法論
概述
核心真相：
混亂文件 → 模糊規範 → AI 猜測 → 反覆返工 → 2-3倍速度
清晰文件 → 清晰規範 → AI 執行 → 最少返工 → 10-20倍速度
"如果你的文件足夠好，AI 自己會寫程式碼。真正的工作就是文件。程式碼只是列印輸出。"
為什麼大多數"AI 輔助開發"失敗： 人們給 AI 喂混亂的文件 → AI 基於假設生成程式碼 → 程式碼不符合意圖 → 無盡的修改迴圈 → 結果只是比手寫快一點點。
適用場景
| 使用者說的 | 響應 |
|---|---|
| "構建 [功能]" | 完整方法論（階段1-4） |
| "建立 [元件]" | 完整方法論 |
| "實現 [系統]" | 檢查：是否有清晰文件？ |
| "文件化 [專案]" | 僅階段1-2 |
| "規範 [功能]" | 僅階段1-2 |
| "清理 [X] 的文件" | 僅文件審計 |
使用方法
四階段方法論
| 階段 | 時間佔比 | 重點 |
|---|---|---|
| 階段1：戰略思考 | 40% | 構建什麼、為什麼重要 |
| 階段2：AI 就緒文件 | 40% | 怎麼構建（規範清晰到 AI 零決策） |
| 階段2.5：對抗性審查 | 5% | 用敵對評審人壓力測試規範 |
| 階段3：執行 | 10% | 程式碼生成 + 實現 |
| 階段4：質量與迭代 | 5% | 測試、最佳化、防止偏差 |
階段1：戰略思考（40%）
7個問題框架——在寫任何新文件之前，用具體性回答這些問題：
- 你到底在解決什麼問題？ → 拒絕"幫助使用者管理任務"，要求"幫助[具體使用者]在[具體場景]中實現[可衡量結果]"
- 成功指標是什麼？ → 拒絕"使用者節省時間"，要求具體數字+時間線
- 為什麼你能贏？ → 拒絕"更好的UI"，要求結構性優勢
- 核心架構決策是什麼？ → 拒絕"讓AI決定"，要求基於明確權衡分析的人工決策
- 技術棧理由是什麼？ → 拒絕"我喜歡"，要求業務理由
- MVP 功能是什麼？ → 拒絕10+個"必須"功能，要求3-5個真正核心的
- 你不構建什麼？ → 拒絕"看使用者需求"，要求明確排除項和理由
階段2：AI 就緒文件（40%）
文件型別架構：
| 型別 | 職責 | 示例 |
|---|---|---|
| 戰略型 | 做什麼和為什麼 | 總藍圖、PRD、願景文件 |
| 實現型 | 怎麼做 | 技術規範、API文件、模組規範 |
| 參考型 | 查閱 | Schema 參考、術語表、配置 |
實現文件必須包含的4個章節：
- 反模式章節——AI 需要知道什麼不要做（至少5個反模式）
- 測試用例規範——AI 需要具體的驗證標準（至少5個單元測試、3個整合測試）
- 錯誤處理矩陣——AI 需要知道如何處理每種失敗模式
- 深度連結——AI 需要導航到精確位置，永遠不用模糊引用
⚠️ Spec Gate（13項檢查）——永遠不要跳過
這是 Stream Coding 和 vibe coding 的根本區別。7/10 的規範會生成7/10 的程式碼，然後需要30%的返工。
基礎檢查（7項）：可操作、最新、單一來源、是決策非願望、AI 可直接使用、無未來態、無廢話
文件架構檢查（6項）：型別已識別、反模式位置正確、測試用例位置正確、錯誤處理位置正確、有深度連結、無重複
執行標準：全部通過 + AI 可理解性評分 ≥ 9/10
階段2.5：對抗性審查（5%）
Spec Gate 通過（9+/10）後、程式碼生成前執行。
原則：撰寫你規範的 AI 有和你一樣的盲點。不同的模型——或被指示攻擊的人類評審——能找到你看不到的問題。
流程： 1. 提交規範給不同的 AI 模型（Gemini、GPT、Perplexity）或可信人類評審 2. 使用對抗性提示詞模板查詢：邏輯矛盾、可信度風險、隱式自由度、缺失考量、防禦性缺口 3. 分類發現：CRITICAL / HIGH / MEDIUM / LOW 4. 修復所有 CRITICAL 問題 → 重新執行 Spec Gate 5. Gate：零 CRITICAL → 進入階段3
階段3：執行（10%）
生成-驗證-整合迴圈：
"程式碼失敗時，修復規範——不是程式碼。"
小蔥技能有更好的技能skills外掛。
如果生成的程式碼不工作：不要手動修補程式碼 → 問"我的規範哪裡不清楚？" → 修復規範 → 重新生成。
階段4：質量與迭代（5%）
偏差規則：每次手動編輯 AI 生成的程式碼而不更新規範，都會產生偏差。偏差是技術債務。
常見問題與陷阱
- 不要在沒有清晰文件的情況下跳到編碼
- 不要接受模糊的規範（"適當處理錯誤"）
- 不要跳過 Spec Gate（即使文件是你自己寫的）
- 不要把反模式/測試用例/錯誤處理放進戰略文件
- 不要在問題出在規範時去修改程式碼
- 不要修改程式碼而不更新規範（製造偏差）
驗證清單
- [ ] 7個戰略問題全部以"要求"級別回答
- [ ] 實現文件包含全部4個必須章節
- [ ] Spec Gate 13項全部通過
- [ ] AI 可理解性評分 ≥ 9/10
- [ ] 對抗性審查已完成（零 CRITICAL）
- [ ] 沒有在文件型別之間重複內容
- [ ] 所有文件都有深度連結
🤖 AI 評測
這是一個偏理論的方法論技能，講解清晰、步驟明確，有具體的時間分配和質量檢查清單，對提升開發質量有幫助。但內容比較抽象，缺少實際的操作示例和可直接使用的模板，普通使用者可能覺得“聽起來有道理但不知道怎麼用”。如果你需要理論指導可以參考，但期望有案例或工具輔助學習的話，可能會失望。
