用 Skill 做 Context Engineering：CLAUDE.md、AGENTS.md、SKILL.md 分層策略

問題：你的 Context Window 不是免費的

你放進 AI agent context window 的每一個 token，都在跟 agent 的推理能力搶資源。這不是比喻，這是 transformer attention 的運作方式。輸入 token 越多，模型的注意力就越分散，輸出品質就會可量測地下降。

Chroma 的 context rot 研究測試了 18 個前沿模型，發現每一個模型的表現都會隨著輸入長度增加而變差 — 即使是簡單的檢索任務也不例外。一個號稱 200K token window 的模型，在 50K token 就可能出現顯著退化。加入完整對話歷史（~113K token）會讓準確率比只用 300 token 的精簡版降低 30%。

蘇黎世聯邦理工學院（ETH Zurich）針對 AGENTS.md 的研究（Gloaguen 等人的 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"）直接證實了這點在寫程式 agent 上的效果：LLM 生成的 context 檔案比完全不提供 context 還讓任務成功率降低 3%。人工撰寫的檔案只提升了 4%，同時推理成本增加超過 20%。

結論很清楚：context 不是免費的，更多 context 不等於更好。智力不是瓶頸 — context 才是。問題不是「我能告訴 agent 什麼？」而是「這個特定任務，agent 需要的最少高訊號資訊是什麼？」

這就是 context engineering。而 CLAUDE.md、AGENTS.md、SKILL.md 的三層架構，是 2026 年我們解決這個問題最好的工具。

三層架構

解法是漸進式揭露（progressive disclosure）— 在對的時間、用對的量、為對的任務載入資訊。三個檔案、三種作用範圍、三種載入行為。

摘要：AGENTS.md 承載每個 AI 工具都讀的通用專案上下文。CLAUDE.md 加上 Claude Code 專屬指令。Skill 只在當前任務需要時才載入專業知識。結果是精簡的基礎 context，加上按需可用的深度能力。

第一層：AGENTS.md — 永遠載入、跨工具

AGENTS.md 是通用的專案上下文檔案。Claude Code、Codex CLI、Copilot CLI、Gemini CLI、Cursor 都會讀它。它在每次 session 開始時載入，在整個對話中持續存在。這個檔案裡的每一個 token 都會影響你執行的每一個任務。

因此，AGENTS.md 必須無情地精簡。100 行以下。每一行都要通過一個測試：「拿掉這行，agent 會犯一個它自己讀程式碼也無法恢復的錯誤嗎？」

該放的：

• 程式碼不會顯示的架構決策。 程式碼顯示你用 Fastify，但不會顯示你為什麼選它而不是 Express。程式碼有 PostgreSQL 查詢，但不會顯示你用 Result pattern 處理錯誤。
• 硬性限制。 絕不修改 migration 檔案。絕不用 default export。所有新 endpoint 都要有整合測試。這些是 agent 推斷不出來的護欄。
• 建構和測試指令。 pnpm test、pnpm lint、pnpm build。Agent 不該猜。

不該放的：

• Agent 能從 package.json、tsconfig.json 或程式碼本身看到的資訊。
• 任務專屬的工作流程（那些屬於 skill）。
• Linter 規則（linter 會確定性地強制執行）。
• 冗長的參考文件（改用連結指向它）。

第二層：CLAUDE.md — 永遠載入、Claude Code 專屬

如果團隊只用 Claude Code，你可以把所有東西放在 CLAUDE.md。但只要團隊裡有人用 Codex CLI、Copilot 或 Cursor，那些 context 對他們就是看不見的。務實的策略：AGENTS.md 持有正式版 context，CLAUDE.md 只持有 Claude Code 專屬的覆寫。

# CLAUDE.md

Read AGENTS.md for project architecture and conventions.

## Claude Code-Specific
- When compacting, preserve the full list of modified files
- Prefer subagents for research tasks over inline exploration
- Use TodoWrite for multi-step tasks

8 行。引用 AGENTS.md 處理所有共享內容，只加上 Claude Code 獨有的行為。零重複。

第三層：SKILL.md — 按需載入、任務專屬

架構在這一層真正發揮作用。Skill 只在當前任務符合 skill 的 description 時才載入。Claude Code 在 session 開始時讀取所有已安裝 skill 的 description — 這些是短字串，總共只要幾百個 token。完整的 skill 內容只在比對成功時才載入。

開發者可以安裝 20 或 50 個 skill，但在觸發之前，每個 skill 只消耗極少量的 token 預算。當 skill 被載入時，它可以很詳細 — 最多 500 行任務專屬的指令、範本和參考資料 — 因為這個成本只在需要這些知識時才被支付。

這是漸進式揭露應用在 AI agent context 上。概念來自 UI 設計（在使用者需要時才顯示他們需要的東西），但完美地映射到 token 經濟學：只為當前任務需要的東西支付 context 成本。

案例研究：拆解一個 2000 行的 CLAUDE.md

一個實際場景。某金融科技團隊有一個經過六個月成長到 2000 行的 CLAUDE.md。裡面包含架構概覽、API 設計慣例、資料庫 migration 流程、部署檢查清單、code review 標準、測試模式、錯誤處理指引、資安要求、效能基準和入職說明。

結果：Claude Code 又慢又貴又不穩定。有些指令被遵循，有些被忽略。ETH Zurich 的研究解釋了原因 — agent 的注意力被分散在 2000 行指令上，其中大部分跟當下的任務無關。

以下是他們的拆解方式。

之前：一個巨型檔案

CLAUDE.md (2000 行)
├── 架構概覽 (80 行)
├── 程式碼慣例 (120 行)
├── API 設計標準 (250 行)
├── 資料庫 migration 流程 (180 行)
├── 部署檢查清單 (200 行)
├── Code review 標準 (150 行)
├── 測試模式 (220 行)
├── 錯誤處理指引 (130 行)
├── 資安要求 (300 行)
├── 效能基準 (170 行)
└── 入職說明 (200 行)

之後：三層架構

AGENTS.md (65 行)
├── 架構概覽（精簡到 20 行）
├── 程式碼慣例（精簡到 15 行）
├── 硬性限制 (10 行)
└── 建構/測試指令 (20 行)

CLAUDE.md (8 行)
├── 引用 AGENTS.md
└── Claude Code 專屬行為

.claude/skills/
├── api-design/SKILL.md (180 行)
├── database-migration/SKILL.md (140 行)
├── deployment/SKILL.md (160 行)
├── code-review/SKILL.md (120 行)
└── security-audit/SKILL.md (220 行)

基礎 context 從 ~2000 行降到 ~73 行。 五個 skill 合計 820 行，但任何單一任務最多載入一到兩個。一個涉及 code review 的典型 session 載入 73 + 120 = 193 行 context。部署任務載入 73 + 160 = 233 行。跟之前不管做什麼都要載入 2000 行相比，差距巨大。

Token 數學

粗略的 token 估算（markdown 含程式碼區塊平均 1 行 ≈ 15 token）：

摘要：分層方式每次 session 大約少用 10 倍的 context token。這不只是省錢 — 這是效能提升。無關的 token 越少，agent 的注意力越集中在重要的東西上。

團隊回報拆解之後，Claude Code 的指令遵循準確度明顯提升。之前需要 2-3 次嘗試的任務開始在第一次就完成。Agent 不再忽略指令 — 不是因為它變聰明了，而是因為相關的指令不再被埋在 2000 行噪音中。

漸進式揭露實戰

讓我們追蹤開發者要求 Claude Code「為 users table 新增 preferences 欄位建立一個 migration」時，究竟發生了什麼。

第一階段：Session 啟動。 Claude Code 載入 AGENTS.md（65 行，~975 token）和 CLAUDE.md（8 行，~120 token）。同時讀取所有 skill 的 description — 來自每個已安裝 skill frontmatter 的短字串。總計：~1,200 token 的基礎 context。

第二階段：任務比對。 使用者的請求提到「migration」。Claude Code 將此與 database-migration skill 的 description 比對：

description: >
  Create, modify, or review database migrations. Triggers on migration files,
  schema changes, Drizzle ORM modifications, column additions or removals.

比對成功。Claude Code 讀取完整的 database-migration/SKILL.md（140 行，~2,100 token）。

第三階段：執行。 Claude Code 現在有 65 + 8 + 140 = 213 行 context。每一行都跟任務相關。它逐步執行 migration 工作流程：讀取當前 schema、檢查現有 migration 的命名慣例、修改 schema、生成 migration、執行測試。

第四階段：Skill 引用。 Migration skill 寫著「遵循 AGENTS.md 中的錯誤處理慣例」而不是重述。Claude Code 已經有 AGENTS.md 在 context 中。零重複、零額外 token。

如果同一個開發者接著說「review 我剛寫的程式碼」，database-migration skill 繼續載入（仍然相關），code-review skill 額外觸發。兩個 skill，都相關，都值得它們的 context 成本。

這就是 Anthropic 說「智力不是瓶頸 — context 才是」的意思。同一個模型，用更好的 context engineering，產出可量測地更好的結果。

量測 Context 的影響

你無法改善你沒量測的東西。以下是量化 context engineering 影響的方法。

Token 計數

Claude Code 沒有內建的 context 檔案 token 計數器，但你可以估算：

# 計算 context 檔案的 token 數（粗估：1 word ≈ 1.3 token）
wc -w AGENTS.md CLAUDE.md
# 字數乘以 1.3 得到近似 token 數

# 計算 skill 的 token 數
find .claude/skills -name "SKILL.md" -exec wc -w {} +

要精確計數，用 Anthropic tokenizer API 或 tiktoken 的 cl100k_base encoding（估算夠接近了）。

5% 法則

你的永遠載入 context（AGENTS.md + CLAUDE.md）應該消耗模型有效 context window 的 5% 以下。對 Claude Opus 4.6 的 200K token window 來說，就是 10,000 token 以下 — 73 行的精簡設定綽綽有餘，超過 500 行就是明確的警訊。

追蹤指令遵循率

重構之後，測試 10 個代表性任務，評分 agent 正確遵循了多少指令。跟舊的巨型檔案做同樣的任務比較。方法粗糙但有效。如果遵循率從 60% 升到 90%，重構就成功了。

成本監控

用 Claude Code 內建的成本追蹤（/cost 指令）比較重構前後的 session 成本。10 倍的 context 縮減在每天跑幾百個 session 的團隊上會轉化為顯著的節省。

ETH Zurich 的發現：少即是多

ETH Zurich 的研究值得深入探討，因為它推翻了一個常見假設。

多數開發者假設更多 context 就是更好。「如果我告訴 agent 關於我專案的一切，它就會犯更少錯。」研究用 AGENTbench — 138 個來自冷門 repository 的真實 Python 任務 — 和四個不同的 agent（Claude 3.5 Sonnet、Codex GPT-5.2、GPT-5.1 mini、Qwen Code）直接測試了這個假設。

結果：

1. LLM 生成的 context 檔案讓效能降低約 3%，比完全不提供 context 檔案還差。
2. 人工撰寫的 context 檔案只提升了約 4%，但推理成本增加 19-20%。
3. 兩種 context 檔案都鼓勵更廣泛的探索 — 更多測試、更多檔案遍歷 — 有時有幫助但經常浪費運算。

核心發現：詳盡的程式碼庫概述跟 agent 自己讀程式碼能發現的內容高度重複。過度限制的指令壓縮了 agent 的解題能力。甜蜜點是最小化的、高訊號 context，防止無法恢復的錯誤，但不微管理 agent 的方法。

這正是三層架構達成的效果。AGENTS.md 提供最小護欄。Skill 只在相關時提供深度知識。Agent 的推理能力被保留給實際任務。

實戰案例：多團隊 Monorepo

考慮一個有四個 package 的 monorepo，各由不同團隊負責：

monorepo/
├── packages/
│   ├── api/          # 後端團隊（Fastify, PostgreSQL, Drizzle）
│   ├── web/          # 前端團隊（Next.js, React, Tailwind）
│   ├── mobile/       # 行動端團隊（React Native, Expo）
│   └── shared/       # 平台團隊（共享型別、工具函式）
├── AGENTS.md         # 根目錄：monorepo 全域 context
├── CLAUDE.md         # 根目錄：Claude Code 專屬
└── .claude/skills/   # 根目錄：共享 skill

根目錄 AGENTS.md（Monorepo 全域）

## Monorepo Structure
pnpm workspace. 4 packages: api, web, mobile, shared.

## Conventions
- All packages use TypeScript strict mode
- Shared types live in packages/shared/src/types/
- Inter-package imports use workspace protocol: "shared": "workspace:*"
- CI runs affected-only: pnpm --filter ...[origin/main] test

## Hard Constraints
- Never import from api/ in web/ or mobile/ (use shared/ for shared logic)
- Never modify packages/shared/src/types/api-contract.ts without API team review

20 行。適用於每個 package 的每個任務。

Package 層級 AGENTS.md（巢狀）

每個 package 有自己的 AGENTS.md，包含 package 專屬慣例：

packages/api/AGENTS.md        # Fastify 慣例、DB 模式、驗證規則
packages/web/AGENTS.md        # Next.js 模式、元件慣例
packages/mobile/AGENTS.md     # React Native 慣例、Expo 設定
packages/shared/AGENTS.md     # 型別導出模式、版本規則

Claude Code 和其他工具會載入根目錄 AGENTS.md 加上相關 package 的 AGENTS.md，根據正在編輯的檔案決定。後端團隊的慣例只在處理後端檔案時才載入。

各 Package 的 Skill

這是 skill 在 monorepo 中真正發光的地方。不同團隊需要不同 skill：

.claude/skills/
├── api-endpoint/SKILL.md         # 後端：建立 Fastify endpoint
├── db-migration/SKILL.md         # 後端：資料庫 migration 工作流程
├── react-component/SKILL.md      # 前端：元件建立模式
├── storybook-story/SKILL.md      # 前端：Storybook 慣例
├── expo-screen/SKILL.md          # 行動端：新畫面工作流程
├── deep-link/SKILL.md            # 行動端：deep link 設定
├── shared-type/SKILL.md          # 平台：共享型別修改協定
└── release/SKILL.md              # 平台：發布與版本工作流程

前端開發者說「建立一個新的 Button 元件」會觸發 react-component，可能還有 storybook-story。後端 skill 保持休眠。後端開發者說「為使用者偏好新增一個 endpoint」會觸發 api-endpoint，可能還有 db-migration。前端 skill 保持休眠。

整個 skill 庫是 4 個團隊共 8 個 skill。但任何單次開發者互動最多載入 2-3 個，保持 context 專注和相關。

Workspace 層級設定

Monorepo 的挑戰在於保持 skill 設定跨 package 同步。當平台團隊更新共享型別協定，shared-type skill 需要反映變更。當 API 團隊新增 middleware 模式，api-endpoint skill 需要更新。

這是 workspace 層級工具變得重要的地方。管理 monorepo 中不同 package 的 skill 設定、context 檔案和終端環境，正是 Termdock 的 workspace sync 處理的多專案協調 — 切換 package 時完整的 context 設定一起切換，讓每個團隊成員用對的 skill 處理他們的 package。

Workspace 層級的 Skill 配置

Monorepo 之外，個別開發者也會跨多個有不同 context 需求的專案工作。一個同時貢獻三個開源專案和兩個工作專案的開發者，有五份不同的 AGENTS.md、五套不同的 skill、五種不同的工具設定。

切換專案意味著切換心智模型 — 以及切換 AI agent context。你的 Rust 專案 CLAUDE.md 在 TypeScript 專案是錯的。你的 AWS 部署 skill 不適用於 Vercel 專案。

個人 skill 放在 ~/.claude/skills/ 有幫助：你的 code review 風格、commit message 格式、debugging 方法跟著你跨專案使用。但專案專屬的 skill 需要在你切進該專案時啟動，離開時停用。

這種 workspace 層級的協調 — 對的 context、對的 skill、對的終端環境，在你切換專案時一起切換 — 是高效的多專案工作流程和持續 context-switching 摩擦之間的分水嶺。Termdock 的 workspace sync 管理這件事：終端佈局、環境變數、git 狀態和 skill 設定作為一個整體在你切換 workspace 時一起移動。

實作步驟：重構你的 Context

如果你有一個超過 200 行的 CLAUDE.md，以下是重構流程。

第一步：審計。 讀 CLAUDE.md 的每一行。對每個段落問：「這適用於每個任務，還是只適用於特定類型的任務？」

第二步：提取通用 context。 把適用於每個任務的東西移到 AGENTS.md。大膽精簡 — 如果程式碼已經顯示了，就移除。

第三步：識別 skill 候選。 每個任務專屬的段落都是 skill 候選。找有這些特徵的段落：多步驟工作流程、領域專屬知識、範本或範例、驗證檢查清單。

第四步：建立 skill。 對每個候選在 .claude/skills/ 建立目錄和 SKILL.md。寫一個具體的、稍微強勢的 description。把 CLAUDE.md 的指令搬到 skill 內容中。

第五步：消除重複。 搜尋任何同時出現在 AGENTS.md 和 skill 中的指令。Skill 應該寫「遵循 AGENTS.md 中的慣例」而不是重述。

第六步：縮減 CLAUDE.md。 剩下的應該只有 Claude Code 專屬行為。其他全部引用 AGENTS.md。

第七步：測試。 對每個 skill 跑 5 個代表性任務。驗證觸發準確度（對的 skill 有載入嗎？）、指令遵循（agent 有照 skill 做嗎？）、輸出品質（結果比之前好嗎？）。

要深入了解 skill 設計 — description 最佳化、eval loop、漸進式揭露模式 — 請看好的 skill 設計原則指南。要了解什麼時候用哪個檔案，SKILL.md vs CLAUDE.md vs AGENTS.md 比較提供完整的決策框架。

浮現的模式

用 skill 做 context engineering 遵循的原則跟好的軟體架構一樣：關注點分離加上清楚的介面。

AGENTS.md 是介面合約 — 你專案的普遍真理，每個工具和每個任務都需要。CLAUDE.md 是轉接器 — 工具專屬行為疊在上面。Skill 是實作 — 深度、專業的知識，透過乾淨的觸發介面（description 欄位）按需載入。

做對這件事的團隊花更少的推理費用、得到更一致的結果、而且能把 AI agent 設定擴展到跨專案和跨團隊成員，context 檔案不會變成維護負擔。

Context 是瓶頸。請用工程的態度對待它。