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

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

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

ETH Zurich 的 AGENTS.md 研究（Gloaguen 等人）直接證實在 coding agent 上的效果：LLM 生成的 context 檔案比完全不提供還讓任務成功率降低 3%。人工撰寫的只提升 4%，推理成本增加超過 20%。

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

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

三層架構

解法是漸進式揭露 -- 在對的時間、用對的量、為對的任務載入資訊。三個檔案、三種 scope、三種載入行為。

層級	檔案	載入時機	Scope	Token 預算
1 -- 基礎層	AGENTS.md	每次 session，永遠載入	跨工具專案 context	< 100 行
2 -- 工具專屬層	CLAUDE.md	每次 session，永遠載入	Claude Code 專屬覆寫	< 20 行
3 -- 按需層	SKILL.md	僅當任務符合 description	任務專屬能力	每個 skill < 500 行

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

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

AGENTS.md 是通用專案 context 檔。Claude Code、Codex CLI、Copilot CLI、Gemini CLI、Cursor 都讀。每次 session 開始就載入，整個對話持續存在。每個 token 都影響每個任務。

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

該放的：

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

不該放的：

Agent 從 package.json、tsconfig.json 或程式碼看得到的資訊。
任務專屬 workflow（屬於 skill）。
Linter 規則（linter 確定性強制執行）。
冗長參考文件（改連結）。

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

團隊只用 Claude Code 的話可以全放 CLAUDE.md。但只要有人用 Codex CLI、Copilot 或 Cursor，那些 context 對他們看不見。務實策略：AGENTS.md 持有正式版，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 只在當前任務符合 description 時才載入。Claude Code 在 session 開始讀所有 skill description -- 短字串，總共幾百 token。完整 body 只在比對成功時才載。

開發者裝 20 或 50 個 skill，觸發前每個只消耗極少 token。載入時可以很詳細 -- 最多 500 行 -- 因為成本只在需要時支付。

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

案例：拆解 2000 行 CLAUDE.md

實際場景。某金融科技團隊有經過六個月成長到 2000 行的 CLAUDE.md。架構概覽、API 慣例、migration 流程、deploy checklist、review 標準、測試模式、錯誤處理、資安要求、效能基準、入職說明。

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

之前：巨型檔案

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

之後：三層

AGENTS.md (65 行)
├── 架構概覽（精簡到 20 行）
├── 程式碼慣例（精簡到 15 行）
├── 硬性限制 (10 行)
└── Build/測試指令 (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 行。Deploy 任務載 73 + 160 = 233 行。跟之前不管做什麼都 2000 行比，差距巨大。

Token 數學

粗估（markdown 含程式碼區塊平均 1 行 ~ 15 token）：

配置	Context 行數	估計 Token	Session 成本（$3/M 輸入 token）
巨型 CLAUDE.md	2,000	~30,000	~$0.09/session
分層（code review）	193	~2,900	~$0.009/session
分層（deploy）	233	~3,500	~$0.011/session

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

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

漸進式揭露實戰

追蹤開發者要求 Claude Code「為 users table 新增 preferences 欄位建一個 migration」時發生什麼。

第一階段：Session 啟動。 載入 AGENTS.md（65 行，~975 token）和 CLAUDE.md（8 行，~120 token）。同時讀所有 skill description -- 短字串。總計：~1,200 token 基礎 context。

第二階段：任務比對。 請求提到「migration」。比對 database-migration skill 的 description：

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

比對成功。載入完整 database-migration/SKILL.md（140 行，~2,100 token）。

第三階段：執行。 65 + 8 + 140 = 213 行 context。每行都跟任務相關。逐步執行 migration workflow：讀 schema、檢查命名慣例、修改 schema、生成 migration、跑測試。

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

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

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

量測 Context 影響

無法改善沒量測的東西。

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。

5% 法則

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

追蹤指令遵循率

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

成本監控

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

ETH Zurich：少即是多

研究值得深入，因為它推翻常見假設。

多數開發者假設更多 context 更好。「告訴 agent 一切就少犯錯。」研究用 AGENTbench -- 138 個來自冷門 repository 的真實 Python 任務 -- 和四個 agent（Claude 3.5 Sonnet、Codex GPT-5.2、GPT-5.1 mini、Qwen Code）直接測試。

結果：

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

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

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

Try Termdock — Workspace Sync works out of the box. Free download →

實戰：多團隊 Monorepo

四個 package 的 monorepo，各由不同團隊負責：

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

根 AGENTS.md（全域）

## 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 有自己的：

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：

.claude/skills/
├── api-endpoint/SKILL.md         # 後端：建 Fastify endpoint
├── db-migration/SKILL.md         # 後端：migration workflow
├── 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 挑戰：跨 package 保持 skill 設定同步。平台團隊更新共享型別協定 -- shared-type skill 需反映。API 團隊新增 middleware -- api-endpoint skill 需更新。

Workspace 層級工具在這裡變重要。管理 monorepo 不同 package 的 skill 設定、context 檔案和終端環境，正是 Termdock workspace sync 處理的多專案協調 -- 切換 package 時完整 context 設定跟著切，每個成員用對的 skill。

Workspace 層級 Skill 配置

Monorepo 之外，個別開發者也跨多個不同 context 需求的專案工作。三個開源加兩個工作專案意味著五份 AGENTS.md、五套 skill、五種工具設定。

切換專案意味著切心智模型 -- 和切 AI agent context。Rust 專案 CLAUDE.md 在 TypeScript 專案是錯的。AWS deploy skill 不適用 Vercel 專案。

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

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

實作步驟：重構 Context

CLAUDE.md 超過 200 行的話：

第一步：審計。 讀每一行。每段問：「這適用於每個任務還是特定類型？」

第二步：提取通用 context。 適用每個任務的移到 AGENTS.md。大膽精簡 -- 程式碼已顯示的就移除。

第三步：識別 skill 候選。 任務專屬段落都是候選。找：多步驟 workflow、領域知識、範本或範例、驗證 checklist。

第四步：建 skill。 每個候選在 .claude/skills/ 建目錄和 SKILL.md。具體的、稍微強勢的 description。指令從 CLAUDE.md 搬過來。

第五步：消除重複。 同時出現在 AGENTS.md 和 skill 的指令 -- skill 寫「遵循 AGENTS.md 慣例」而非重述。

第六步：縮減 CLAUDE.md。 只剩 Claude Code 專屬行為。其他引用 AGENTS.md。

第七步：測試。 每個 skill 跑 5 個代表性任務。驗證觸發準確度、指令遵循、輸出品質。

Skill 設計細節 -- description 最佳化、eval loop、漸進式揭露 -- 看設計原則。什麼時候用哪個檔案，SKILL.md vs CLAUDE.md vs AGENTS.md 比較有完整決策框架。

浮現的模式

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

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

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

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

Danny Huang·Follow on Threads →

Free Download

Ready to streamline your terminal workflow?

Multi-terminal drag-and-drop layout, workspace Git sync, built-in AI integration, AST code analysis — all in one app.

Download Termdock →

#context-engineering#agent-skills#skill-md#claude-md#agents-md#claude-code

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