把 AI 工程手冊轉化為 AI 能直接執行的紀律 (Executable Agentic Engineering Guidelines)

原始來源與檔名：2026-05-19T092657+0800-字节写了20篇AI工程手册，我把它做成了AI能直接执行的纪律.md

NAPKIN | 餐巾纸

餐巾紙公式

Agent 生產力 = 方法論 (Know-how) × 系統約束力 (Executable Constraints)

一句話

方法論寫在 PDF 裡只能給人看，AI 看完還是憑感覺做事；唯有將「建議」翻譯成帶有強制性攔截 (Hard Gates) 的 Skill 檔，才能真正建立 AI 工程紀律。

餐巾紙草圖

[人類的文件] "建議修改前確認來源" -> AI 說好 -> 亂改一通 (失敗)
[AI的紀律] "MUST identify canonical files" -> 找不到 -> 拒絕執行並要求澄清 (成功)

ROUND 1: SKELETON | 骨架掃描

• 核心問題: 為什麼讀了很多 Agent 方法論，實作時 AI 的表現依然不受控、充滿幻覺或遺忘目標？
• 核心答案: 因為「知道」與「做到」之間缺少了可執行的結構 (Executable Structure)。必須把人類讀的指引 (Guidelines)，轉譯成 AI 嚴格執行的約束機制 (Skills)。
• 論證結構: 問題剖析 -> 機制轉譯 -> 工具實踐 (Kit) -> 實戰驗證

章節骨架

1. 三個斷層: 建議被忽視、驗證無硬性攔截、規則未分層導致上下文混亂。
2. 轉譯動作: 從「建議 (SHOULD)」升級為「機制 (MUST / MUST NOT)」，實施漸進式上下文載入。
3. Agentic Engineering Kit: 包含行為約束的 agentic-engineering-guidelines 與審計指令 /agentic-scan。
4. 實戰掃描: 透過 8 個維度 (0-3 分) 對專案進行體檢，找出容易讓 AI 翻車的盲點。

ROUND 2: DISSECTION | 血肉解剖

• 隱形假設: 開發團隊願意在專案初期投入時間整理「真相源 (Source of Truth)」並定義驗證閘門 (Gates)，且 LLM 具備足夠的指令遵從能力 (Instruction Following) 來理解 MUST 語意。
• 邊界條件: 框架只能提供「紀律」，無法提供「業務邏輯」。具體的 L1-L3 業務規則仍需要開發者手動填入，否則 AI 依舊無法處理特定領域需求。

ROUND 3: SOUL | 靈魂提取

• 知識連結: 與合規性檢查 (Compliance as Code) 及軟體工程中的 Linter / CI Pipeline 概念高度共鳴。
• 深層洞見: 約束並不是限制，而是安全網。當有了明確的真相源映射與驗證機制兜底時，AI 才敢於進行大規模的複雜重構。
• 行動呼籲: 放棄寫給人看的方法論文件。立即使用 /agentic-scan 審計你的專案庫，並建立強制驗證的 Agent 紀律。

把 AI 工程手冊轉化為 AI 能直接執行的紀律 (Architectural Deep Dive)

前言/背景

網路上充斥著各種 AI 工程方法論，但開發者常面臨「懂了概念卻不知如何落地」的窘境。本文作者精闢地指出，寫在 Markdown 裡的「建議」AI 只會點頭但不執行。真正的解法是將最佳實踐轉譯為具有強制約束力的「工程紀律 (Engineering Disciplines)」，並透過開源工具包 agentic-engineering-kit 提供 AI 原生的驗證攔截與上下文分層管理機制。

章節詳細總結

認知斷層：為什麼寫了規則 AI 卻不聽？(三个“知道但做不到”的断层)

方法論的陷阱在於缺乏「強制力」。

1. 建議 vs 絕對命令：寫 請在修改前確認，AI 會當成建議。必須使用 RFC 2119 標準的 MUST NOT，強制約束其行為。
2. 缺乏驗證閘門 (Gate)：沒有「必須回報驗證指令否則不准宣告完成」的硬性攔截，AI 就會靠「感覺」回報測試通過，最終導致 CI 崩潰。
3. 未分層的全局變數：把所有 React 規範、後端流程塞進同一個文件，會導致嚴重的上下文干擾 (Context pollution)。

架構轉譯：從「建議」到「機制」的 3 大實作(三个翻译动作：从“建议”到“机制”)

1. 強制前置聲明：將「建議確認來源」轉為 MUST identify canonical files before editing。Agent 必須明確說出真相源與鏡像文件的邊界才能開工。
2. 強制驗證聲明：MUST state verification run or why not。用明確的 CLI 執行結果取代 AI 的「幻覺自信」。
3. L0-L3 漸進式架構分層 (Progressive Disclosure)：
   • L0 (全局)：輸出格式、溝通風格。
   • L1 (路徑匹配)：React 寫法、Go 錯誤處理。
   • L2 (動態載入)：特定業務規則。
   • L3 (手動觸發)：發布流程、Code Review。 架構師視角：這是降低 Context Window 負擔的最優解。只預載 Metadata，需要時才拉取完整 Instructions 與 Resources。

核心工具包解構 (Kit 里有什么)

作者開源的 agentic-engineering-kit 包含兩個組件：

1. agentic-engineering-guidelines (Skill 檔)： 核心是 execution-constitution.md，寫死了 10 條不可逾越的紀律（如：模糊需求必須先轉化為 Spec、禁止順手重構無關程式碼、強制沉澱踩坑經驗等）。背後連結了 12 個按需載入 (On-demand loading) 的參考文件。
2. /agentic-scan (審計指令)： 針對倉庫進行 8 個維度的 AI 友善度掃描（0-3分）。包含 Context Engineering, Spec Discipline, Agent Loop Hygiene 等，精準揪出導致 AI 翻車的結構性缺陷。

總結與結論

• 約束帶來安全感 (Constraints create psychological safety)：當底層有堅固的驗證閘門與真相源映射時，AI 會更敢於執行大範圍的複雜重構，因為它知道自己不會弄壞系統。
• 可攜帶的工程紀律：這套架構不綁定單一平台（相容 Claude Code, Codex, OpenCode）。轉換模型時，工程紀律跟著走。
• 競爭維度的轉移：多數人還在比較第一層的「AI 開發工具哪家強 (Cursor vs Claude Code)」。但真正拉開產能差距的，是第二層的「專案庫工程紀律建置 (Repository Readiness)」。