【2026 最新】AI Coding Agent 最小配置：AGENTS.md、Skill、Hook、MCP 先裝哪個？

第一次配置 coding agent，很容易把網路上的整套裝備一次搬回來：AGENTS.md、CLAUDE.md、Skill、Hook、MCP，再加一堆 agents 與 workflow。結果工具列變長了，交付卻未必更穩。這篇要做的，是替新手建立一套可重跑、可刪除的AI Coding Agent 最小配置。

本文不把任何人的「神配置」當答案，而是從零外掛 baseline 開始；每次只新增一層，再用同一組五題 smoke eval 比較。你會拿到可複製的規則檔、Skill 骨架、Hook 接法、MCP 判斷題，以及明確的保留與移除條件。

一句話重點：AI Coding Agent 最小配置 ＝ 零外掛 baseline ＋ 逐層加入元件 ＋ 同一組 eval 證明值得保留。

AI Coding Agent 最小配置是什麼？先記住這條公式

先把 coding agent 想成一位剛到職、會讀程式也會操作工具的工程師。模型是腦袋；讓它讀哪些檔案、能呼叫哪些工具、何時被擋下來，合起來就是 Agent Harness（包住模型、讓它能做事的控制層）。本文的錨點是：

最小配置 = Baseline + Σ（通過同一組 Eval 的增量）

保留條件 = 可觀察的改善 > 新增的維護、延遲與權限成本

這裡的「最小」不是檔案數固定為一，而是每一層都有存在理由。某個專案只需要規則檔就能穩定交付，MCP 應先留在門外；另一個專案的核心任務必須讀取 Jira，MCP 也可能提早進場。順序是預設起跑線，不是教條。

四個元件先用白話分清楚

• AGENTS.md／CLAUDE.md＝員工手冊：每次進專案都要知道的命令、慣例與完成定義。Codex 官方說明會在工作前讀取 AGENTS.md；Claude Code 則把 CLAUDE.md列為持續載入的專案脈絡。
• Skill＝任務 SOP：只有碰到特定工作才展開的流程、腳本與參考資料。它像抽屜裡的「發版檢查表」，不用每天把整本貼進對話。
• Hook＝自動閘門：在固定事件發生時執行確定性動作，例如改檔後跑格式檢查。它不是提醒 agent「記得做」，而是把檢查接上事件。
• MCP＝外部系統轉接頭：Model Context Protocol 是讓 AI 應用連接工具與資料來源的開放標準；當任務要碰 Jira、Figma、資料庫或遠端服務時才有價值。

步驟一：替 AI Coding Agent 最小配置做五題 baseline

痛點：如果每次都換題目，就無法判斷提升來自配置，還是任務剛好比較簡單。解法：先從最近真實工作挑五題，把題目、起始 commit、允許的工具與通過條件固定。這五題只是快速的 smoke test，不是具有統計力的 benchmark。

五題怎麼選？要涵蓋五種失敗面

1. 小 bug：修正一個有既有測試可重現的錯誤，通過條件是指定測試與回歸測試全過。
2. 小功能：加入一個邊界清楚的功能，通過條件包含驗收案例，而不是「看起來完成」。
3. 重構：改內部結構但維持對外行為，通過條件是測試與公開 API 不漂移。
4. 文件或介面同步：改一個設定／API 後，同步型別、說明與範例，抓出 agent 常漏的相鄰檔案。
5. 專案特有任務：選一題最能暴露你家規矩的工作，例如前端無障礙、資料遷移，或禁止改動的路徑。

每題至少記五項：一次通過與否、重跑次數、工具顯示的 token／usage、人工修正分鐘數、是否碰到不該改的檔案或權限。不要把不同工具的 token 數直接互比；這個數字只用來比較同一工具、同一題、不同配置的相對變化。

task_id: bug-01
start_commit: abc123
prompt_file: evals/bug-01/prompt.md
grader:
  - npm test -- checkout-rounding
  - git diff --exit-code -- docs/locked/
record:
  pass: true|false
  reruns: 0
  usage: <client 顯示值>
  human_fix_minutes: 0
  scope_violation: true|false

Agent 有非決定性，同一配置最好重跑多次；若要做團隊級決策，再把題庫擴到真實失敗案例。Anthropic 的 agent eval 指南建議從約 20–50 個簡單任務起步，並優先使用可重現環境與確定性 grader。本文用五題，是為了讓個人先在一個下午跑完、找出明顯退步。

步驟二：先加一份最小 AGENTS.md／CLAUDE.md

痛點：agent 一再猜錯測試命令、命名慣例或完成條件。解法：只寫三類常駐資訊：commands、conventions、definition of done。OpenAI 與 Anthropic 的官方文件都把專案規則檔放在擴充起點；Anthropic 的 Claude Code 功能總覽還給出很實用的觸發條件：同一慣例或命令被更正兩次，就值得寫入。

# Project guide

## Commands
- Install: `npm ci`
- Narrow test: `npm test -- <changed-area>`
- Full check: `npm run verify`

## Conventions
- Preserve unrelated worktree changes.
- Reuse existing components before adding a new abstraction.
- External links open in a new tab; internal links use the canonical host.

## Definition of done
- Run the narrow test while iterating, then `npm run verify`.
- Summarize changed files and any check that could not run.
- Do not modify generated files by hand.

使用 Codex 時放在適用範圍的 AGENTS.md；使用 Claude Code 時放在 CLAUDE.md。兩者的搜尋與覆寫規則不同，因此請以各自官方文件為準，不要假設同一檔名能被所有 client 讀取。若規則開始膨脹，可先用 AGENTS.md 五道閘門檢查「該寫規則、該寫測試，還是該做權限限制」。

保留門檻：重跑五題後，至少要看到原本的慣例錯誤下降，且人工修正時間沒有上升。若規則反而造成更多歧義，先刪到每一條都能回答「哪一題失敗促成它」。

步驟三：重複流程才抽成一個 Skill

痛點：每次都要貼相同的發布、審查或資料整理流程。解法：把那段可重複程序抽成一個 Skill，而不是繼續把細節塞進常駐規則。Agent Skills 規格要求技能目錄至少有一份含 name 與 description 的 SKILL.md；腳本、參考資料與 assets 則按需要加入。

---
name: release-check
description: Prepare a release candidate and verify changelog, tests, and build.
---

# Release check
1. Read the current version and unreleased changelog.
2. Run the repository's narrow tests, then the full verify command.
3. Build the release artifact.
4. Stop if version, changelog, and artifact disagree.
5. Report commands run and unresolved failures.

把它放到 client 的官方技能目錄：Claude Code 的專案技能路徑是 .claude/skills/<skill>/SKILL.md；Codex 會掃描 repository 範圍內的 .agents/skills。接著用一句會觸發它的提示重跑題庫，再補一題「不該觸發」的反例。完整拆法可參考 SKILL.md 新手教學；技能多起來時，再用 Skill 路由 A/B Test檢查誤觸發。

保留門檻：正例能穩定載入正確流程、反例不亂啟動，而且常駐脈絡沒有被整份 SOP 塞滿。若一個 Skill 同時做審稿、部署與社群發布，先拆小；描述若必須寫成一段小說才分得出來，通常代表邊界仍不清楚。

步驟四：確定性規則才交給 Hook

痛點：你已在提示裡寫「改完要跑格式檢查」，agent 偶爾仍會漏。解法：把「每逢某事件就執行」的檢查接到 Hook。Hook 適合格式、lint、敏感檔案保護或通知；需要判斷文章品質、架構取捨的工作仍應留給 Skill 或人。

#!/usr/bin/env bash
set -euo pipefail

# 先檢查，不自動改寫；避免 Hook 默默擴大 diff
npm run --if-present format:check

把腳本存成 scripts/agent-format-check.sh 並先在終端直接執行，再依 client 接到 PostToolUse。截至 2026 年 9 月 7 日，Claude Code 官方 Hooks 指南提供 /hooks 設定與驗證流程；Codex 官方也文件化 .codex/hooks.json 與 config.toml。兩者事件 payload 與設定格式不同，請重用檢查腳本，不要跨 client 複製外層 JSON。

保留門檻：Hook 應抓到題庫裡原本會漏的錯誤，且誤擋、延遲與雜訊在可接受範圍。若它每次改檔都跑完整測試、拖慢回饋，先縮成受影響範圍；若只是提醒文字，則放回規則檔即可。

步驟五：任務真的跨到外部服務，再考慮 MCP

痛點：agent 必須一直等你從 Jira、Figma、Sentry 或資料庫複製資料。解法：先定義它需要讀／寫的最小能力，再評估 MCP。若 repository 裡已有穩定 CLI 或 API 腳本，先把兩條路用同一題比較；MCP 的價值是接通必要資料，不是讓工具清單看起來完整。

# Claude Code：遠端 HTTP server 的官方命令形狀
claude mcp add --transport http <name> <https-url>

# Codex：本機 stdio server 的官方命令形狀
codex mcp add <name> -- <local-command>

先從唯讀、低權限 server 開始，確認來源、登入方式、工具清單與可見範圍，再跑一題「該呼叫」與一題「不該呼叫」。Claude Code 的 MCP 文件與 Codex 的 MCP 文件都提供當前設定方式。若你在 API／CLI／MCP 之間猶豫，可先做 MCP vs CLI 同任務比較；要上正式環境，再補 MCP Production 七關。

保留門檻：外部資料取得步驟確實變少、答案仍可追溯，且權限面沒有超出任務需求。若 server 工具名稱、參數 schema 與回傳內容佔掉大量脈絡，或 agent 常選錯工具，就先停用並回到既有 CLI。

同一張記分卡：何時保留、縮小或移除？

• 保留：至少一個目標指標改善，其他重要指標沒有明顯退步，而且能指出改善發生在哪些題。
• 縮小：有幫助，但規則範圍、Skill 觸發、Hook matcher 或 MCP 權限過大。
• 移除：提升不可觀察、結果只在一題偶發，或維護／延遲／權限成本高於收益。
• 再收集：結果互相打架時，不急著下結論；增加 trial 或加入能分辨兩種配置的新題。

不要只看「五題過了幾題」。例如成功率相同，但重跑從兩次降為零、人工修正少了，這也可能值得保留；反過來，token 下降卻多改了不相干檔案，就不是好交易。若想把這套迴圈接進更完整的 agent 控制層，可延伸到 最小 Agent Harness 實作。

Worked trace：修一個結帳四捨五入錯誤

假設題目是「修正結帳金額在特定小數下多一分，補回歸測試，不改公開 API」。這不是本文聲稱跑出的實驗數據，而是一條示範你如何做決策的完整軌跡：

1. Baseline：agent 找到計算函式並修正，但用了錯的測試命令。記錄失敗類型，不立刻補四個工具。
2. 加規則檔：寫入 narrow test 與 full verify 命令。重跑同一題；如果命令選擇變正確，保留這條。
3. 考慮 Skill：這題只是一次性修 bug，沒有重複 SOP，先不新增。
4. 考慮 Hook：若多題都漏跑 format check，再接唯讀檢查 Hook；只發生一次則先觀察。
5. 考慮 MCP：任務資料全在 repository，沒有外部資料依賴，因此本輪不接 server。

這段軌跡的重點不是最後裝了幾個元件，而是每個「裝」與「不裝」都有題庫證據。這也正是 AI Coding Agent 最小配置能長期維護的原因：你刪得掉，才算真正擁有它。

五個常見坑：配置越多，故障面也越多

1. 把結果寫成口號：「寫高品質程式」無法評分；改成指定測試、lint、API 不變與允許修改的路徑。
2. 規則、Skill、Hook 重複三份：同一要求可能互相漂移。常駐背景放規則檔、按需流程放 Skill、固定事件放 Hook。
3. 每層都換提示：比較失去控制變因。把 prompt 存檔，配置以外都固定。
4. MCP 一開始給滿權限：先用唯讀、最小 scope 與非正式資料；只有題目需要時才增加寫入能力。
5. 只追 token：少用 token 不代表交付更好。一起看重跑、人工修正與 scope violation；需要進一步節流時，再讀 Claude token 實戰技巧。

截至 2026 年 9 月：跨 client 搬配置時要注意什麼？

截至 2026 年 9 月 7 日，Codex 與 Claude Code 都文件化了專案指令、Skills、Hooks 與 MCP，但檔案位置、事件格式、載入範圍與除錯命令並不相同。可攜的是「意圖」與底層腳本，不是整份設定檔。搬家時逐項回答：這條資訊要常駐嗎？這個流程要按需載入嗎？這個檢查需要確定性執行嗎？這個外部連線需要哪些最小權限？

設定完成後，用 client 自己的診斷入口確認「真的被載入」。Claude Code 官方列出 /memory、/skills、/hooks、/mcp 與 /context 等檢查方式；Codex 則應依其當前文件檢查指令、技能與 Hook 來源。功能可用不等於配置生效，診斷輸出才是證據。

FAQ：AI Coding Agent 最小配置常見問題

1. 新手第一個該裝哪個？

先做 baseline，再加最小規則檔。大多數 repository 都先需要正確 commands、conventions 與 definition of done；等題庫暴露重複流程、固定事件或外部資料缺口，再分別加入 Skill、Hook 或 MCP。

2. AGENTS.md 和 CLAUDE.md 要同時維護嗎？

只有團隊確實同時使用兩種 client 才值得。先保留一份人類可讀的核心規範，再用清楚的同步流程產生或校對 client 專用入口；不要手動複製後任其漂移。

3. 五題 eval 夠嗎？

夠做 smoke test，不夠證明普遍提升。五題適合快速攔下明顯退步；團隊要做穩定決策時，應擴充真實失敗案例、重跑多個 trial，並讓 grader 儘量確定。

4. Skill 和規則檔的分界在哪？

每回合都要知道的放規則檔；特定任務才需要的放 Skill。若移除那段內容後，一般 bug fix 仍不受影響，它多半適合按需載入。

5. Hook 可以取代 Skill 嗎？

不能直接互換。Hook 解決「事件一發生就執行」；Skill 解決「某類任務需要一套流程與判斷」。格式檢查適合 Hook，發布審核流程適合 Skill。

6. 有 CLI 還需要 MCP 嗎？

先比較同一任務再決定。CLI 若已穩定、權限清楚、輸出精簡，MCP 未必增加價值；若 MCP 能減少人工搬運並提供更合適的結構化工具，才值得保留。

7. 怎麼知道配置太肥？

看三個訊號：誤觸發、回饋變慢、錯誤工具變多。再用 client 的 context／skills／MCP 診斷頁面看常駐內容與工具清單，逐層停用後重跑題庫。

8. 什麼時候應該直接移除一層？

當改善不可重現，或成本持續高於收益時就移除。先保存配置與記分卡到版本控制，刪除後重跑；如果表現沒有下降，這一層便不屬於目前的最小集合。

給新手的 5 個帶走重點

1. 先固定五個真實任務，零外掛跑一次，留下 baseline。
2. 規則檔只放 commands、conventions、definition of done。
3. 重複 SOP 才做 Skill；固定事件才做 Hook；外部服務缺口才接 MCP。
4. 每次只改一層，用相同 prompt、commit、grader 與記分方式重跑。
5. 能指出刪除條件，才叫最小配置；配置本身不是成就，交付才是。