安安～我是ChiYu～

昨天，我把前面累積的 24 份 Policy 分別放回適合的位置：跨 Repository 可重用的判斷進入 Skill，專案自己的領域語言、架構與測試規則留在 Repository，風險接受與最後決策仍由工程師負責。

今天不再做新的 AI 實驗，我想直接打開完成的版本，看看它保留哪些 Clean Code 精神、調整了哪些傳統做法，以及實際上該怎麼安裝與使用。

v0.4.0 已採用 MIT License 正式發布，Release、固定 Tag 與公開評測資料都能直接查閱。你可以下載、修改，也可以拿自己的案例到 GitHub 提出 Issue。

Skill 如何保存可重用流程？

Skill 是提供給 AI Agent 的可重用工作指南。Prompt 交代這次任務，Skill 則保存同類任務會反覆使用的判斷流程、停止條件與輸出方式。

這個專案以 SKILL.md 作為入口，詳細判斷分散在七份參考文件中：

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

Agent 先讀入口，再依任務載入必要內容。整理私有方法名稱時，不必把部署、並行與外部 Provider 規則全部讀進來；需求碰到公開 API、資料、通知或權限時，Skill 才提高審查深度。

圖：Skill 先讀取 Repository 事實與任務風險，再載入需要的 Clean Code 判斷，最後以實際 Gate 和證據回報結果。

為什麼 AI Coding 仍然需要 Clean Code？

AI 可以快速產生能編譯、能執行的程式碼，後續修改卻仍然依賴閱讀。Agent 必須從名稱與型別找到責任，沿著依賴確認邊界，再透過測試和錯誤訊息判斷哪些行為不能改。

Clean Code 提供的正是這些理解線索：領域名稱減少猜測、清楚責任幫助修改範圍收斂、穩定邊界避免繞過設計，而能讀出行為的測試則保護重構結果。下一輪 Agent 不必每次都從混亂的實作反推規則。

這些條件經常能降低理解與返工成本，但不代表安裝後一定節省 Token。查證 Context、比較方案與執行更多驗證本來就會增加成本，因此只能在品質相近的候選之間比較消耗。

我保留了哪些 Clean Code 原則？

我保留的是 Clean Code 真正想守住的品質價值，不把所有形式要求一起搬進 Skill。

這些價值對人類有效，對 AI 也有用。因為 Agent 不只負責第一次生成，它還要回來理解、修改、驗證、解釋，甚至把結果交給下一個 Agent。

哪些 Clean Code 做法改成依情境判斷？

Clean Code 的品質目標仍然保留，但部分做法不再被當成跨專案的絕對命令。

函式行數只提供警訊，不直接命令拆分

小函式通常比較容易理解，但拆得過小也會增加跳轉、參數搬運與 Context 切換。Skill 會檢查責任與抽象層次，不會看到超過二十行就要求 Agent 繼續拆。

TDD 與 TCR 改成可選擇的開發節奏

TDD 對規則、邊界值與高風險行為很有價值；TCR 適合能切成小步、測試夠快，而且失敗修改應立即丟棄的工作。

可是單純格式修改、探索性 Prototype，或測試 Oracle 尚未可信時，硬套同一節奏不一定比較好。Skill 會先辨識風險與行為，再選擇測試策略。

Interface 必須對應替換需求或真實邊界

Interface、Adapter、Wrapper、Domain Model 與更多 Project 都有成本。沒有第二個實作、變更來源或獨立發布需求時，為了看起來「有架構」而新增抽象，只會增加 Agent 的導航與同步負擔。

實驗結果保留採用條件，不升級成唯一答案

Stepdown、Behavior DSL、Contract-First、Outbox 與 Intention-revealing Rule，都曾在前面的特定情境中成為合理選擇。Skill 保存的是採用條件與反例，不是「以後全部照做」。

SKILL.md 只做路由，細節按任務載入

入口過長會讓每次任務載入大量無關規則。因此 SKILL.md 只負責路由、風險、CLEAN、授權與輸出；細節放進按需載入的 References。

Token 消耗只比較，不作節省保證

好的名稱、清楚責任與穩定邊界，很多時候能降低 Agent 的理解成本。但更完整的查證與驗證也會消耗 Token。這個 Skill 不用無法可靠取得的數字做行銷。

v0.4.0 讓 User 自己決定開發節奏與驗證深度

TDD、TCR、E2E 與 Mutation Testing 各自解決不同問題，不適合綁成固定套餐。因此，v0.4.0 把「如何開發」與「驗證多深」拆成兩項設定：

development_rhythm: auto
validation_profile: auto

• development_rhythm 決定「程式碼要用什麼節奏產生與修正」。
• validation_profile 決定「結果要驗證到多深」。

如果這次任務希望採用特定的開發節奏或驗證範圍，可以直接在當次 Prompt 寫下這兩個欄位。若要讓設定成為整個 Repository 的預設值，再把它們寫進 AGENTS.md；不同模組也能在較近的 Repository Instruction 中設定，但實際載入方式仍以 Agent Client 為準。目前不需要另外建立 config.yml。

五種開發節奏處理不同問題

User 可以直接指定節奏，也可以交給 Skill 依風險、Oracle、測試速度與授權判斷。指定條件若不可行，Agent 必須說明缺少的前提並提出替代方案，不能自行換成另一套流程。

五種驗證範圍可以和開發節奏自由搭配

例如，新增加值規則可以使用 tdd 搭配 focused；影響 API、資料庫與外部服務的流程，可以使用 tdd 搭配 acceptance-e2e；Legacy 重構則可能使用 characterization-first 搭配 repository。

選擇 focused 也不能略過 Repository 已明訂的必要 Gate。偏好可以改變節奏與額外驗證，不能取消安全、權限與既有交付規範。

為 AI Coding 加入風險分級、授權檢查與分級輸出

Agent Legibility：讓 Agent 找得到真正的修改位置

clean-code-for-agent-legibility.md 會檢查 Agent 能否找到行為的真正擁有者、從名稱與型別理解意圖、把 Diff 控制在必要範圍，並執行 Repository 規定的 Gate。它把「程式碼是否提供足夠理解線索」變成可以檢查的工程問題。

三層風險路徑，避免每個任務都跑完整稽核

v0.4.0 的 SKILL.md 這樣定義三條路徑：

## Path Selection

Evaluate Full Audit, then Standard, then Lightweight. Evidence may upgrade;
it must not downgrade a path.

- **Full Audit Path:** public contract, production data or migration,
  external effect, dependency, concurrency, security, privilege, CI,
  infrastructure, deployment, destruction, unclear authority, audit,
  material trade-off, or critical unknown.
- **Standard Path:** repository feature, test, defect, refactor, or internal
  design change with known ownership, authorization, behavior boundary,
  and executable gates.
- **Lightweight Path:** local, reversible readability change with one obvious
  option and no behavior, contract, data, side-effect, dependency, ownership,
  or deployment impact.

它要求 Agent 先看高風險條件，再判斷 Standard 或 Lightweight，不能為了少寫報告而自行降級。

三條路徑調整的是流程成本，Clean Code 的品質要求不會因此降低。

Prototype 與 Production-Ready：分開風險和交付成熟度

## Delivery Readiness

- **Prototype:** answer one isolated, disposable question with a repeatable
  Oracle; list remaining gates.
- **Production-Ready:** satisfy repository policy and executable gates;
  report deployment, UAT, and validation blind spots.

Readiness never lowers risk or authorization.
A Prototype touching production data, public contracts, providers,
security, or external effects still uses Full Audit.

Prototype 可以只回答一個隔離、可丟棄的問題，但仍要具備可重複的 Oracle，並列出距離正式交付還缺哪些 Gate。Production-Ready 則必須通過 Repository 規定的驗證，清楚區分本機測試、CI、部署與 UAT。

交付成熟度也不等於風險等級。Prototype 只要碰到正式資料、公開契約、Provider 或安全問題，依然要走 Full Audit。

CLEAN 五原則成為 User 的 Review Lens

## CLEAN Lenses

Use CLEAN as the User's review lens, not an automatic-compliance score.

- **C — Context-Aware Code（情境感知）:** establish Context from repository facts.
- **L — Localized Change（局部變更）:** state the Expected Diff and keep it local.
- **E — Explicit Intent and Boundaries（意圖明確）:** expose Intent, contracts, and ownership.
- **A — Auditable by Evidence（實據可審）:** connect Evidence to validation gaps.
- **N — Non-Surprising Behavior（符合預期）:** preserve Behavior, failures, and side effects.

在這套 Skill 裡，CLEAN 是 User 的 Review Lens，用來檢查 Context、變更範圍、意圖、證據與可觀察行為，也把 Clean Code 的品質要求延伸到整個 AI 協作流程。

Authorization Gate：證據充分，不等於已取得權限

## Authorization Gate

- **evidence does not grant authority.**
  Authority requires platform permission, repository instructions,
  explicit User authorization, and responsible Owner approval.
- Without explicit authority, stop before changing a public contract,
  dependency, production data or migration, external side effect,
  secret or privilege, CI or infrastructure, deployment,
  or any destructive operation.
- For out-of-scope changes, analyze, propose a Diff, name the Owner,
  and leave external state unchanged.
- Stop for conflicting instructions, a critical unknown,
  or high-risk behavior that available evidence cannot validate.

合理的技術理由不會自動產生修改權限。AI 能在短時間內擴大變更，因此碰到公開契約、正式資料、外部副作用、CI、部署或破壞性操作時，Agent 必須先通過 Authorization Gate。

不同風險使用不同輸出

## Required Output

- **Lightweight Path:** report the facts used, behavior boundary,
  change, validation, and only applicable human decisions.
- **Standard Path:** follow the Standard Output Contract
  and omit non-material sections.
- **Full Audit Path:** follow every Full Audit heading and traceability rule
  in [review-output-contract.md](references/review-output-contract.md).

Lightweight 只回報與本次修改直接相關的資訊，Standard 保留必要決策，Full Audit 才使用完整追溯格式。輸出深度應隨任務風險與決策複雜度增加，不必讓每項工作都產生同樣長的報告。

四句 Core Principle 接起 Clean Code、CLEAN 與 Repository

## Core Principle

Repository facts control Context;
Clean Code supplies quality judgment;
CLEAN defines User-Agent responsibilities.
Evidence supports decisions, not authorization.

Repository 提供真實情境，Clean Code 負責品質判斷，CLEAN 分配 User 與 Agent 的協作責任，Evidence 則支持決策。四者缺少任何一項，都可能產生誤判：通用原則可能套錯情境、既有壞結構可能被當成不能碰的事實，測試全綠也可能被誤解成已取得合併或部署授權。

哪些情況不該使用這個 Skill？

## Do Not Use

Skip syntax-only questions, repository-free conceptual explanations,
standalone examples, formatter-owned layout, and work fully covered by a more
specialized Skill. When that Skill leaves a behavior, boundary, side-effect,
or Clean Code trade-off unresolved, use this Skill only for the remaining judgment.

如果只是問 C# 的 Null 合併運算子（??）怎麼寫，或產生一段不屬於任何 Repository 的示範 Code，就不需要啟動完整 Clean Code 判斷。

清楚排除語法問題、Repository 無關的概念說明與已有專門 Skill 完整處理的工作，可以避免在簡單任務上付出不必要的流程成本。

實際呼叫後，Agent 會怎麼工作？

假設需求是：

在 Work Item API 新增人工重新投遞通知的功能。

只說「幫我實作，記得遵守 Clean Code」，Agent 可能直接在 Controller 呼叫 Provider。功能看起來完成了，卻另外建立一條繞過 Outbox 的通知路徑。

改用 Skill 後，可以這樣下 Prompt：

請使用 $clean-code-ai-collaboration 實作人工重新投遞通知功能。

先確認目前通知路徑、Outbox、重送規則與公開 API Contract，
比較可行方案並說明取捨。將修改限制在必要範圍，
完成後回報實際 Diff、測試、未涵蓋風險與仍需人工決定的事項。

未經授權不要 Commit、Push、部署或修改正式資料。

Skill 會先讀取 Repository，依風險選擇 Full Audit，接著載入需要的參考文件、區分事實與未知，並定義不能改變的行為與預期 Diff。只有通過 Authorization Gate 後才會修改，完成時還要回報實際驗證與盲點。

它不會保證每次都選中團隊最喜歡的方案，但 User 可以清楚看見判斷使用了哪些事實、放棄哪些選項，以及結果為什麼值得接受。

安裝固定版本 v0.4.0 到專案或個人 Skills 目錄

以下以 Windows PowerShell 示範。完整的 Windows、macOS 與 Linux 步驟都放在 v0.4.0 README。

先下載固定版本：

git clone --branch v0.4.0 --depth 1 https://github.com/eric861129/Clean-Code-AI-Collaboration-Skill.git
Set-Location .\Clean-Code-AI-Collaboration-Skill

如果只想讓目前專案使用，可以複製到該 Repository 的 .agents/skills：

$skillSource = (Resolve-Path ".\clean-code-ai-collaboration").Path
$projectRoot = "C:\path\to\your-project"
$skillsRoot = Join-Path $projectRoot ".agents\skills"
$target = Join-Path $skillsRoot "clean-code-ai-collaboration"

if (Test-Path -LiteralPath $target) {
    throw "安裝目標已存在，請先確認內容，不要直接覆寫：$target"
}

New-Item -ItemType Directory -Path $skillsRoot -Force | Out-Null
Copy-Item -LiteralPath $skillSource -Destination $target -Recurse

如果想讓同一位 User 的多個專案共用，可以把目標改成個人的 .agents/skills：

$skillsRoot = Join-Path $env:USERPROFILE ".agents\skills"
$target = Join-Path $skillsRoot "clean-code-ai-collaboration"

if (Test-Path -LiteralPath $target) {
    throw "安裝目標已存在，請先確認內容，不要直接覆寫：$target"
}

New-Item -ItemType Directory -Path $skillsRoot -Force | Out-Null
Copy-Item -LiteralPath ".\clean-code-ai-collaboration" -Destination $target -Recurse

v0.4.0 正式採用明確呼叫，Codex Adapter 的 allow_implicit_invocation 設為 false。安裝後，請直接在 Prompt 指定：

請使用 $clean-code-ai-collaboration Review 這次修改。

三個可以直接使用的 Prompt

規劃，但先不修改

請使用 $clean-code-ai-collaboration 規劃這次需求。

先整理 Repository 事實、假設與未知資訊，
比較可行方案、行為風險、Diff 邊界與停止條件。

目前只需要規劃，不要修改檔案、Commit、Push 或部署。

實作並驗證

請使用 $clean-code-ai-collaboration 實作這個需求。

先確認既有行為與測試，將修改限制在必要範圍。
完成後回報實際 Diff、執行過的驗證、
未涵蓋風險與仍需人工決定的事項。

未經授權不要 Commit、Push、部署或修改正式資料。

Review 別人的修改

請使用 $clean-code-ai-collaboration Review 這次變更。

依 Repository 證據檢查意圖、責任、依賴、測試、
行為漂移與副作用。先列出可重現的問題，
再說明驗證盲點與建議。

不要只依作者摘要或「測試全綠」判定可以接受。

使用時還要把實際需求、Repository、允許範圍與驗收方式補進 Prompt。若要指定開發與驗證策略，可以直接加入兩個欄位。以下範例先用 TDD 說清楚行為，再以 E2E 驗證跨邊界結果：

請使用 $clean-code-ai-collaboration 實作這個需求。
development_rhythm: tdd
validation_profile: acceptance-e2e

先確認 RED 的失敗原因確實來自需求缺口，再完成最小 GREEN。
保留 Repository 既有 Gate，並回報尚未涵蓋的外部環境與副作用。

TCR 牽涉 Commit 與 Revert，不能只寫一個設定值就視為已授權。這次若真的要用 TCR，Prompt 還得明列操作範圍：

請使用 $clean-code-ai-collaboration 處理這次高風險重構。
development_rhythm: tcr
validation_profile: repository

我授權 Agent 在這次任務中：
1. 每個通過測試的小步驟可以 Commit。
2. 測試失敗時，可以 Revert 該步驟由 Agent 建立的變更。
3. 不得復原或覆蓋任務開始前已存在的使用者修改。

TCR 只有在測試快速可靠、工作樹已隔離，而且 User 明確授權本次 Commit／Revert 時才能執行。缺少任一前提，Skill 應停止並說明原因；即使 Agent 建議改採 TDD，也不能自行視為 User 已經接受替代策略。

v0.4.0 的評測證明了什麼，又沒有證明什麼？

為了確認 Agent 是否能一致解讀新的兩項設定，我另外做了一組 Strategy Decision-Conformance Full Run。它只測「策略決策契約」，沒有要求 Agent 實作完整功能。

評測包含九種固定情境，例如：當次 Prompt 覆寫 Repository 預設值、auto 面對 Legacy Code、TCR 缺少快速測試、TCR 沒有版本控制授權，以及 focused 仍必須保留既有 Gate。

沒有載入 Skill 的九次對照中，有五次符合預先固定的決策契約；載入 v0.4.0 後，九種情境各重複兩次，十八次全部符合契約。原始 Prompt、輸出、判定與雜湊都保留在公開結果中，共二十七份可重播紀錄。

這個結果支持的說法很有限：在這批固定情境裡，Skill 組對開發節奏、驗證範圍、必要 Gate 與阻擋條件的解讀比較一致。

它沒有測量最終程式碼品質，也沒有比較實作結果、Token、時間或費用。公開紀錄能讓人重播輸入、輸出與 Oracle，仍無法單獨證明每一次都是全新 Context，或驗證供應商端實際執行的模型身分。

另外，較早啟動的跨語言 Full Run 是一項獨立評測，目前仍未完成。它不能拿 v0.4.0 的策略契約結果代替，也不該混成「所有語言與 Repository 都有效」的結論。

• v0.4.0 Strategy Full Run 原始結果
• v0.4.0 Benchmark、Oracle 與執行工具

我寧可把「證明到哪裡」寫清楚，也不想讓一個漂亮的通過率替尚未驗證的部分背書。

使用前要知道的限制

目前的評測不能推論所有 Repository、語言、模型與 Client 都會得到相同結果，也沒有證明一定能降低 Token、時間、工具呼叫或費用。Tests 全綠仍不能代表需求、部署與正式環境全部正確。

Skill 也無法自動補出不存在的領域事實、可靠 Oracle 或 Owner 授權，更不能取代資深工程師的 Review 與風險承諾。Repository 缺少關鍵條件時，合理的反應就是停下來指出缺口，避免錯誤答案快速擴散。

Clean Code 成為下一輪 Agent 理解與修改程式碼的基礎

只對 Agent 說「請遵守 Clean Code」，它仍得自行猜測這次在意的是名稱、函式、測試、SOLID，還是架構邊界。這個 Skill 將模糊期待拆成明確流程：先讀 Repository、依風險選擇路徑、載入必要判斷、用 CLEAN 檢查協作過程，再由 Tests 與工具驗證能自動判定的品質。

它保留 Clean Code 對可讀、可測試、可改變與可維護的追求，同時放下固定行數、永遠拆分、永遠 TDD 與所有專案採用同一架構的硬性套用方式。

在 AI Coding 時代，這次產生的程式碼也是下一輪 Agent 的輸入。名稱、責任、行為與依賴方向越清楚，Agent 越容易找到修改位置、控制 Diff，並辨識不能改變的契約。這不等於每次都會節省 Token，卻能減少反覆猜測混亂程式碼所產生的無效成本。

Skill 仍不會替工程師決定需求，也不能從測試綠燈取得合併或部署權限。風險接受與交付承諾，最後仍要由具備權責的人負責。

如果你平常已經大量使用 AI Agent 開發，又常遇到「Code 寫完了，但不知道能不能放心留下」的問題，可以下載 v0.4.0，先從一項真實、範圍明確，而且已有測試的修改開始。

下載 Clean Code AI Collaboration Skill v0.4.0

試用後，如果它在你的語言、框架或 Repository 做出不合理判斷，也歡迎把情境、Prompt、Diff 與驗證結果整理成 Issue。

我更想知道它在哪裡失效，而不是只收集成功案例。因為一套真正能被長期使用的 Skill，也必須持續接受新的 Context 與反例。

明天是這個系列的最後一篇。我會回到最開始的問題：當 Implementation 越來越多交給 AI，工程師究竟可以少做什麼，又有哪些品質判斷與責任始終不能交出去？

參考資料

• Robert C. Martin，《無瑕的程式碼 第二版：敏捷軟體開發技巧守則》，〈可重複的證明〉、〈持續改進〉、〈團隊合作〉與〈永遠不會停止學習〉。
• Clean Code AI Collaboration Skill v0.4.0。
• v0.4.0 Strategy Decision-Conformance Full Run。