結論

知識寫入框架前,依「受眾 x 形態」二軸決定載體,而不是順手寫在當下開啟中的檔案。核心判定一句話:代理人定義回答「你是誰、你能做什麼、你偏好怎麼做」;skill 回答「這件事怎麼做」——前者是人格與授權(換一個代理人就不同),後者是可重複流程(任何角色觸發都應得到同一流程)。

載體受眾載入時機責任
CLAUDE.md所有角色每回合自動專案身份、指令、專案級技術選型
rules/core/所有角色每回合自動行為禁令速查 + 路由(有 token 預算)
pm-rules/僅主線程 PM(只調度不執行的主對話)情境按需調度流程 SOP(派發、驗收、決策樹)
AGENT_PRELOAD全體代理人派發時注入代理人通用行為禁令
agents/*.md單一代理人派發時載入身份、責任邊界、設計偏好(命名、技術手法、語氣)
skills/觸發者(角色無關)觸發時漸進揭露(先載觸發入口、細節按需展開)可重複工作流與方法(TDD、寫作、ticket CLI)
methodologies/主動查閱者按需30 秒理念複習清單
references/執行特定動作者按需技術參考、規則的完整論證
error-patterns/任務前查詢者按需失敗案例(症狀 / 根因 / 解法 / 預防)
memory(專案層)僅本專案每回合自動專案特定活教訓的單行索引(教訓升級為正式規則後即移出)

情境

框架以「主線程只調度、任務交代理人」為分工原則運作。規範自然長出多個放置點:rules 收所有角色通用規則、pm-rules 收主線程專用流程、AGENT_PRELOAD 收代理人通用禁令、各代理人定義檔收身份與偏好、skills 承載工作流、methodologies 承載理念。

問題在每次學到新東西的時候浮現:這段知識該寫進哪裡? 沒有頂層地圖時,答案是「寫在最不會忘記的地方」,也就是自動載入層。專案演進至今,自動載入集合膨脹到 82.5k tokens(200k context 模型的約 40%),而代理人定義檔裡混進了操作流程步驟、與通用品質規範重複的檢查清單、錯誤案例全文、工具使用指南。這四種都不屬於「這個代理人是誰」的內容。

演進歷程

  1. 單檔期:一切塞 CLAUDE.md。專案設定、品質規則、流程說明混在一起,單檔暴漲。
  2. 規則分層期:拆出 rules/core/(通用品質底線)與 pm-rules/(主線程專用)。動機直接來自分工原則:PM 不寫程式只調度,調度 SOP 沒理由佔用代理人的 context。
  3. 代理人標準期:建立 AGENT_PRELOAD(通用行為禁令,派發時注入)與代理人定義三區塊標準(允許產出 / 禁止行為 / 適用情境),讓派發前可查表確認職責邊界。
  4. Skill 承載期:可重複的工作流(TDD 流程、寫作方法、ticket 操作)移入 skills,藉觸發時漸進揭露控制 context 成本。
  5. Token 收斂期:自動載入集合 82.5k 收斂到 41.9k。關鍵發現是膨脹根因不是「規則太多」而是「表達形態錯置」:論證、案例、教學混進了每回合載入的層。建立 45k 預算的機器量測 + 「自動載入層只放禁令與路由」的形態約束。
  6. 責任地圖期(本篇):收斂解決了「放多少」,本階段補「放哪裡」的頂層判定:受眾 x 形態二軸地圖,並首次權威化「代理人定義該裝什麼」。

理想做法

標題點名的三個載體在此各有答案:rules 的答案在「二軸定位」(自動載入層的形態約束)、agents 與 skills 的答案在「人格與流程的分界」。

二軸定位,先問受眾再問形態

受眾軸縮小候選載體(所有角色 / 僅 PM / 全體代理人 / 單一代理人 / 動作觸發者 / 僅本專案),形態軸確定最終位置(行為禁令 / 調度流程 / 身份偏好 / 工作流方法 / 理念清單 / 技術參考 / 失敗案例 / 專案設定)。兩軸都過了,再檢查目的地是否屬自動載入層並過預算閘門:規範類知識的閘門是必要性否決(「每回合都需要嗎?」)加上把形態壓成「禁令 + 路由」;專案設定這類事實陳述不適用必要性否決,閘門只管體積精簡與不混入框架通用知識。

代理人定義 vs skill:人格與流程的分界

代理人檔案該裝的是人格與授權:身份定位、責任邊界三區塊、設計偏好(命名習慣、技術手法傾向、文法語氣)、分工路由。操作流程屬於 skill。流程與人格解耦後,同一個寫作 skill 可以被任何代理人觸發,行為一致;而「該由誰執行、用什麼語氣與偏好執行」才是代理人檔案的事。

一個容易踩的細節:「技術選型」分兩層。專案級選型(用什麼框架、什麼版本)屬 CLAUDE.md 的專案設定;代理人層放的是「手法傾向」:代理人帶著多種方案的知識,依專案設定選用。把專案選型寫進代理人定義,跨專案 sync 時就會把錯的選型帶去別的專案。

重複內容一律路由化

品質清單、錯誤案例、工具指南在代理人檔案裡只放一行路由(「品質標準見 quality-common『常數管理』節」「詳見 IMP-003」,錨點用語意標題不用位置編號)。複製全文的代價是漂移:來源更新後副本不會跟著動,兩份規範開始打架。

沒這樣做的麻煩

  • Token 污染:知識預設寫進自動載入層,每 session 固定燒掉 context 的 40%,而且 attention 稀釋會降低規則遵循率:載越多,守得越差。
  • 知識失傳:跨專案原則寫進專案 memory,不會隨框架 sync,其他專案重踩同樣的雷。
  • 規範打架,執法強的一方贏:載體錯置會製造規則矛盾(例:寫作規範要求每段完整論證 vs 自動載入層要求壓縮形態)。矛盾規則競爭時勝負不看道理,看執法強度:有 hook 阻擋或常駐審查(每次變更必跑的審查代理人)的一方必勝,只有事後量測的一方形同虛設。這是本階段演進最重要的單一洞察:載體地圖必須與執法機制對齊,否則正確的原則會輸給有 hook 的舊習慣
  • 代理人檔案變成第二份過時手冊:流程寫兩份(agent + skill),更新只改一份,派發時代理人讀到舊流程。

判讀徵兆

下次遇到這些訊號,代表載體錯置正在發生:

訊號診斷與行動
寫新知識時的第一反應是「加進 CLAUDE.md / rules 才不會忘」用載入頻率換安全感;該問的是受眾與形態
代理人定義出現「執行步驟 1-2-3」流程混進人格層,外移 skill
同一份清單出現在兩個檔案漂移倒數計時開始,改路由化
自動載入預算量測逼近上限,而最近沒有新增「每回合行為禁令」有論證或案例混進自動載入層
兩條規則對同一動作給出相反指示立刻盤點概念詞重疊的既有規範,矛盾修補與新規則同批落地

後續

框架內的權威版(30 秒地圖 + 檢查清單)維護在框架 methodologies/knowledge-carrier-allocation-methodology.md,隨理念演進持續更新;本篇是此階段思考歷程的快照。存量錯置的盤點(30 份代理人定義、57 份方法論的體量稽核)已建 ticket 排程,依地圖逐檔分類後再搬移。