安安～我是ChiYu～

昨天，我重新走了一遍這三十天從 Clean Code 延伸到 CLEAN 五原則的過程，才發現前面的文章已經累積了 24 份 Policy。

單篇看都不長，全部塞進 AGENTS.md 卻會產生新的問題：Agent 只是要修改一個名稱，也得先讀完測試、架構、並行、部署與估算規則，真正重要的專案限制反而容易被埋掉。

我決定把能跨專案重用的判斷流程整理成 AI Agent Skill，其餘規則留在真正負責的位置。先從最基本的問題開始：Skill 到底是什麼？

先用簡單的方式理解 Skill

Skill 可以想成一份提供給 AI Agent 的專業工作指南。

平常我們下 Prompt，是告訴 Agent「這一次要做什麼」；Skill 則把某一類任務會反覆使用的流程、判準、參考資料與停止條件整理起來，讓 Agent 不必每次都從零開始。

一個 Skill 最基本會有 SKILL.md。內容較多時，還能搭配 references/、scripts/ 或其他資源：

my-skill/
├─ SKILL.md
├─ references/
├─ scripts/
└─ assets/

SKILL.md 是入口，交代適用時機、執行順序、限制與輸出；需要細節時，再載入 references/，可重複執行的確定性工具則放在 scripts/。

它很像交給新同事的工作手冊，但 Agent 不會因此自動知道專案真相。每次面對新的 Context，它仍要回到 Repository 查證需求、領域語言與架構。Skill 能保存做事的方法，不能替專案補出不存在的答案。

Prompt、AGENTS.md、Skill、Tests 與工程師各自負責什麼？

前面的文章為了方便示範，經常把 Policy 寫成 AGENTS.md 範例。規則逐漸累積後，我得進一步確認每一項內容真正應該由誰保存。

舉例來說，「改名前先確認領域詞彙、作用域與公開契約」可以放進 Skill，因為每個專案都值得先做這件事。

但 C# 使用 PascalCase、某個 JSON 欄位不能改名、Glossary 放在哪一個資料夾，屬於 Repository 自己的規則，應該留在 AGENTS.md、架構文件、Code 或 Tests。

至於「這次只改內部識別字，不得改變 API Contract」，則是單次 Prompt 的範圍。

同一份 Naming Policy 裡，可能同時混有跨專案的命名判斷、Repository 自己的格式規範，以及這次任務的修改範圍。若整段搬進 Skill，通用流程與專案答案就會混在一起。

為什麼不把所有規則寫進一份超長的 AGENTS.md？

Uncle Bob 在近期訪談中分享過類似經驗。他曾把 TDD、Clean Code 與程式規則整理成五到十頁指令，希望 Agent 照著執行，最後卻發現規則仍可能被弱化成參考建議。

他後來縮短初始指令，把能計算的要求交給測試、複雜度分析與變異測試等工具驗收。

這件事和 Lost in the Middle（迷失在中間）研究帶來的提醒很接近：在特定長 Context 任務中，資訊所在位置可能影響模型取用效果，中段內容有時比較容易被忽略。

長文件不一定會被 Agent 忘記，短文件也不會自動變得有效。真正需要處理的是：重要限制若埋在大段文字裡，又缺少清楚路由與可執行的 Gate，我們便很難確認 Agent 是否真的使用了它。

我因此把入口控制在兩個責任：先依任務選取必要規則；能由 Formatter、Build、Tests、靜態分析或架構檢查判定的條件，直接交給工具把關。文字幫助 Agent 判斷，工具則擋下不合格的結果。

四個問題決定每份 Policy 應該留在哪裡

我重新檢查前面累積的 Policy 時，每一條都先問四件事。

這條規則能不能跨 Repository 使用？

「先確認名稱是否符合領域語言」可以跨專案重用。

「WorkItem 的到期欄位叫做 DueAtUtc」只能留在這個 Demo，不能變成通用 Clean Code 規則。

它是判斷流程，還是當時實驗選出的答案？

前面的實驗曾接受 Stepdown、Behavior DSL、Contract-First 與 Intention-revealing Rule。這些選擇都和當時的程式碼、風險與下一項需求有關。

Skill 可以保留它們的採用條件、成本與反例，不能改寫成「所有 Agent 永遠採用 Stepdown」。

它能不能交給確定性工具驗證？

格式、編譯、測試、套件弱點與部分架構依賴，可以讓工具直接判斷。

既然工具能回答，就不需要只靠 Prompt 提醒 Agent「記得遵守」。Skill 應該要求 Agent 找到 Repository 已有的 Gate，再誠實回報哪些已經執行、哪些仍是盲點。

這個決定最後由誰負責？

採用哪一個領域詞彙、能不能改公開 API、要不要新增資料表、是否接受外部副作用風險，最後仍由具備權責的人決定。

Skill 可以整理證據，不能替 Owner 簽名。

這四個問題跑完後，原本的 24 份 Policy 大致分成三類：

為什麼不是做成 24 個小 Skill？

24 份 Policy 若各自做成 Skill，觸發範圍會大量重疊。「幫我整理這個函式」可能同時碰到命名、註解、測試、簡單設計與類別責任，User 反而得先學會挑選入口。

全部塞進一份大型 SKILL.md 也會重新製造長指令問題。最後採用的結構，是一個短入口搭配模組化的 references/：

clean-code-ai-collaboration/
├─ SKILL.md
├─ agents/
│  └─ openai.yaml
└─ references/
   ├─ clean-code-for-agent-legibility.md
   ├─ code-readability.md
   ├─ testing-and-change-safety.md
   ├─ design-and-dependency-boundaries.md
   ├─ collaboration-and-estimation.md
   ├─ repository-context-template.md
   └─ review-output-contract.md

入口會先判斷任務深度，再載入真正需要的參考文件。名稱、函式與類別問題進入 Code Readability；缺陷、測試與行為風險進入 Testing and Change Safety；碰到 Provider、並行或架構時，才載入 Design and Dependency Boundaries。

後來新增的 clean-code-for-agent-legibility.md，則專門檢查整潔的程式碼能否幫助 Agent 找到行為、完成修改、執行驗證並說明結果，避免直接把所有人類習慣套到 AI Coding。

圖：能跨 Repository 使用的判斷流程進入 Skill；專案事實、可執行行為與風險承諾留在各自負責的位置。

轉成 Skill 時，我把規則分成三個層次

我把 24 份 Policy 分成三層：必須保留的品質價值、可以跨專案重用的判斷流程，以及需要視情境決定的實作方式。若把三層混在一起，Skill 很容易從工作指南變成僵硬規章。

保留 Clean Code 的品質價值

有意義的命名、清楚責任、可測試、低耦合、可替換邊界與持續改善，仍然直接影響 Agent 能不能讀懂並安全修改程式碼。

這些價值不只服務人類閱讀。名稱是否指出真正責任、測試是否讀得出行為、依賴是否朝正確方向，也會影響下一個 Agent 要搜尋多少檔案、排除多少錯誤線索，以及能不能把修改限制在合理範圍。

把答案改寫成判斷流程

前面採用過 Stepdown、Behavior DSL、Contract-First、Outbox 與 Intention-revealing Rule。它們在當時的情境下有充分理由，換一個 Repository 卻不一定仍是最佳選擇。

Skill 保存的是能協助判斷的問題：目前面對哪一種變更壓力？哪些行為不能改？新增抽象隔離了什麼？現有 Oracle 能觀察哪些結果？下一項需求可能落在哪裡？

Agent 取得這些答案後，才有足夠依據提出適合目前 Context 的方案。

不把人類習慣寫成跨專案鐵律

固定行數、所有依賴都先抽 Interface，或全部需求一律採用 TDD，都只能在條件吻合時使用。某些 Repository 可能很適合這些做法；換到另一個專案，過度拆分會增加跳轉，過早抽象會增加同步成本，過重流程也可能讓局部修改失去效率。

Skill 會先讀取情境，再判斷哪一種結構最能守住行為，並讓下一次改動維持局部。它保留 Clean Code 的品質價值，同時讓執行方式隨專案情境調整。

轉成 Skill 時，C 與 E 分別檢查 Context 與責任邊界

C — Context-Aware Code 情境感知：通用流程不能假裝成專案真相

Skill 可以要求 Agent 取得領域詞彙、公開契約、資料、副作用、Provider、部署與驗證指令。

如果缺少的 Context 會改變行為、資料、依賴方向或風險接受，Agent 就應該停下來，而不是拿 Work Item API 的答案套到所有 Repository。

E — Explicit Intent and Boundaries 意圖明確：先說清楚每條規則由誰負責

Prompt、AGENTS.md、Skill、Tests 與工程師各有責任。

當一條 Policy 同時混入通用流程、專案事實、單次需求與風險承諾，我會先拆開；拆不開，或來源與適用條件仍不清楚，就不急著放進 Skill。

這樣的篩選能避免 Skill 帶著看似完整、實際上缺少來源與適用條件的規則，直接進入其他專案。

v0.4.0 保存可重用判斷，也保留被反例修正的空間

今天完成的是 24 份 Policy 的責任重整。Clean Code 提供品質判斷，CLEAN 規範 User 與 Agent 的協作方式，Repository 保存自己的領域與架構事實，Tests 和 Gates 負責可重複驗證，Skill 則攜帶跨專案可重用的判斷流程。

規則數量不會直接提高品質。Agent 真正需要知道的是該讀什麼、比較什麼、哪些地方不能猜，以及什麼情況必須停下來。

這套做法已整理成 v0.4.0。目前的入口仍維持精簡，細節由七份參考文件按任務載入；另外加入三種風險路徑，以及可由 User 選擇的開發節奏與驗證範圍。

明天我會直接打開固定版本，介紹實際的 SKILL.md、保留下來的 Clean Code 判斷，以及 Direct、TDD、TCR 和 Characterization First 的選擇方式。

如果你想先看成品，可以開啟 v0.4.0 的 Skill 目錄。這個連結固定在發布版本，不會因為後續更新而改變內容。

參考資料

• Robert C. Martin，《無瑕的程式碼 第二版：敏捷軟體開發技巧守則》，〈可重複的證明〉與〈持續改進〉。
• Uncle Bob on Software Fundamentals in the Age of AI。
• Lost in the Middle: How Language Models Use Long Contexts。
• Clean Code AI Collaboration Skill v0.4.0。