團隊 Agent Skills 導入：CONTEXT.md 與 ADR 實戰
團隊導入 Agent Skills，真正困難的不是安裝，而是讓術語、架構決策與工單流程成為共同資產。本文用 CONTEXT.md、ADR 與 tracer-bullet tickets 建立可維護的 AI 開發規範。
目錄+
把同一套 Skill 發給整個團隊，不會自動產生一致的工程決策。每個人仍可能用不同術語、讀到不同背景，最後讓 Agent 在同一個 repository 寫出互相衝突的邏輯。團隊導入真正要建立的，是共享的工程記憶。
團隊如何導入 Agent Skills？
團隊 Agent Skills 是一套由 repository 共同管理的工作流程：用 CONTEXT.md 固定 domain language、用 ADR 保存長期決策、用 issue tracker 表達可執行任務，再讓實作、測試與 review 都讀取同一批來源。
Matt Pocock 的 setup-matt-pocock-skills 會先確認 issue tracker；已安裝 triage 時才處理 labels，偵測到 monorepo 時才詢問多組 domain context。團隊如果連「規格寫去哪裡」都沒有答案，後面的自動化只會把混亂跑得更快。
這張圖的重點不是工具名稱，而是所有執行階段都回到同一組事實。
用 CONTEXT.md 建立共同語言
CONTEXT.md 不該變成另一份 README，也不是把整個產品規格塞進 Agent context。它要回答的是：這個 domain 裡有哪些重要名詞？哪些詞容易混淆？哪些關係永遠成立？
一份最小版本可以包含以下內容：
Domain glossary
Terms
- Member：完成登入並擁有帳號的人
- Subscriber：具有有效訂閱 entitlement 的 Member
- Course Pack：可獨立購買的內容組合，不等於訂閱
Invariants
- Entitlement 決定能不能進入內容
- Progression 決定下一步是否解鎖
當規格、函式、資料表和測試都使用同一套詞，Agent 不需要每次把自然語言重新翻成自己的概念。grill-with-docs會在訪談過程搭配 domain modeling，發現新術語、挑戰模糊定義，再把共識寫回文件。
共同語言不是一次完成的字典。當產品概念改變，改動同一份 CONTEXT.md，並在 code review 檢查新程式是否仍使用舊詞。否則文件和程式會分裂成兩個世界。
用 ADR 保存難以重複解釋的決策
ADR（Architecture Decision Record）保存的不是「做了什麼」，而是「當時為什麼這樣選」。適合記錄的，是日後只看程式碼看不出理由，而且改動成本高的決策。
例如：
ADR-0007：Entitlement 與 progression 分開判斷
Status
Accepted
Context
一次性購買與訂閱都能授權內容，但學習進度不等於商業權限。
Decision
Access gate 先判斷 entitlement，再由獨立 progression gate 判斷下一步。
Consequences
課程頁面不能用 completion 狀態代替購買權限。
不需要每個按鈕顏色都建立 ADR。判斷標準很簡單：如果半年後換了一位工程師，他會不會只看程式就誤解這項選擇？如果會，而且誤解會跨越模組，就值得記。
ADR 也不該只是墓園。Spec 在觸及相關模組時要引用它，code review 要檢查變更是否違反它，domain glossary 改詞時也要回頭確認相關 ADR 是否仍成立。
用 tracer-bullet tickets 控制大小與依賴
團隊常把 Agent ticket 拆成資料庫、API、前端、測試四張水平工單。問題是前三張都無法單獨驗證，最後才發現資料形狀和使用者行為對不起來。
Matt Pocock 的 to-tickets要求 tracer-bullet vertical slices：每張 ticket 都走過完成該行為所需的層，完成後可以 demo 或驗證，而且大小要能放進一個新的 Agent context window。
一張團隊可接手的 ticket 至少要有：
- What to build：從使用者角度描述可工作的行為。
- Acceptance criteria：完成後能客觀檢查的結果。
- Blocked by：只有真正阻擋它的前置 ticket。
- Status：例如
ready-for-agent，讓人和 Agent 都知道現在誰能接。
這讓團隊可以處理「frontier」：所有 blockers 都完成的 tickets。任務不是照編號盲目往下做，而是依真實依賴解鎖。
若你還沒走過個人版流程，先看Matt Pocock Skills 的安裝與實作教學；系列入口則整理了這套 Skills 解決的四種 AI Coding 失敗。
Skill 的版本、維護者與修改權限
團隊把 Skills 放進 repository 後，必須把它們當成程式碼管理。至少決定四件事：
- 來源：全隊使用 plugin，或使用 repository 內的可編輯副本，不要兩者混用。
- 維護者：誰負責處理 Skill 和實際流程不一致的問題。
- 變更方式：修改
SKILL.md是否需要 PR、review 與實際任務驗證。 - 更新節奏：何時拉取上游版本，如何檢查上游修改沒有覆蓋團隊規則。
Plugin 適合想跟隨作者更新、接受唯讀內容的團隊。skills.sh 複製版適合要固定版本、加入公司術語或明確驗證指令的團隊。後者自由度高，也代表你要負責維護。
混用 Claude Code 與 Codex 時，把工具差異留在最薄的一層。Domain language、ADR、ticket schema、typecheck 和 test 指令都保存在 repository；不同 Agent 只負責載入同一套規則。
多人同時操作 Agent 還會增加協作面積。Claude Code 多人協作與 Agent Teams 的差別可以補上 session 協調層，但它不能取代共享規格。
當任務進一步擴張到多個 Agent，還要處理執行順序與驗證角色；Claude Code Dynamic Workflows 的協調方式補的是 orchestration 層，同樣不能替代 CONTEXT.md、ADR 與可驗收 tickets。
七天漸進式導入計畫
不要週一宣布全隊改流程，週二就把所有舊做法停掉。用一個低風險功能跑一輪：
- 第一天：盤點既有
CLAUDE.md、AGENTS.md、issue tracker 與驗證指令。 - 第二天：建立最小
CONTEXT.md，只收最常混淆的術語與 invariants。 - 第三天：挑一項已存在的架構決策，補一份能被引用的 ADR。
- 第四天：用
grill-with-docs對齊一個小功能。 - 第五天：產生 spec 和 tracer-bullet tickets，由工程師 review。
- 第六天：只實作第一張 ticket，跑完 TDD 與 code review。
- 第七天：回顧哪個 gate 有用、哪段只是儀式，修改 Skill 後再擴大。
成功指標不要看 Agent 說自己省了多少時間。看需求來回次數、ticket 被退回的原因、測試是否抓到回歸，以及 review 是否重複指出相同問題。
長時間進行團隊 pairing 或 Agent review 的桌面環境，可以參考蝦皮開發者桌面四件套整理鍵盤、USB-C Hub、螢幕掛燈與站立書架。這只是工作環境選項，不是導入團隊流程的必要採購。
利益揭露：本文部分連結為聯盟連結；若你透過連結購買，本站可能獲得回饋，不影響你的購買價格。
常見問題
CONTEXT.md 和 CLAUDE.md、AGENTS.md 有什麼差別？
CONTEXT.md 保存產品領域的共同語言與不變條件；CLAUDE.md 或 AGENTS.md 告訴 Agent 如何在 repository 工作。前者回答「這個系統裡名詞代表什麼」，後者回答「在這裡要遵守哪些操作規則」。
每個功能都需要建立 ADR 嗎？
不需要。只有影響多個模組、日後很難從程式碼推回原因，或團隊容易反覆爭論的長期決策才值得建立 ADR；一次性實作細節留在 spec 或 ticket 即可。
團隊應該使用 plugin 還是把 Skills 複製進 repository？
需要統一審查、固定版本或深度客製時，複製進 repository 通常更容易治理；想直接跟隨作者更新、接受唯讀套件時可用 plugin。重點是全隊只選一條來源。
Claude Code 和 Codex 可以共用同一套團隊 Skills 嗎？
可以共用流程與文件，但叫用方式可能不同。把 domain language、驗證指令和完成標準寫進 repository，並分別測試兩種 Agent 的載入行為，不要假設工具整合完全相同。
團隊不缺另一份 Prompt 大全。真正缺的是一組每個人和每個 Agent 都能查到、能質疑、能修改的工程記憶。先選一個低風險功能跑七天，再問團隊：哪一個 gate 真的阻止了返工，哪一個只是增加文件？