知識管理 on Tarragonhttps://tarrragon.github.io/blog/tags/%E7%9F%A5%E8%AD%98%E7%AE%A1%E7%90%86/Recent content in 知識管理 on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Mon, 15 Jun 2026 00:00:00 +0000知識載體責任分配：rules、agents、skills 各該裝什麼https://tarrragon.github.io/blog/report/knowledge-carrier-responsibility-allocation/Fri, 12 Jun 2026 00:00:00 +0000https://tarrragon.github.io/blog/report/knowledge-carrier-responsibility-allocation/<h2 id="結論">結論</h2> <p>知識寫入框架前，依「<strong>受眾 x 形態</strong>」二軸決定載體，而不是順手寫在當下開啟中的檔案。核心判定一句話：<strong>代理人定義回答「你是誰、你能做什麼、你偏好怎麼做」；skill 回答「這件事怎麼做」</strong>——前者是人格與授權（換一個代理人就不同），後者是可重複流程（任何角色觸發都應得到同一流程）。</p> <table> <thead> <tr> <th>載體</th> <th>受眾</th> <th>載入時機</th> <th>責任</th> </tr> </thead> <tbody> <tr> <td>CLAUDE.md</td> <td>所有角色</td> <td>每回合自動</td> <td>專案身份、指令、專案級技術選型</td> </tr> <tr> <td>rules/core/</td> <td>所有角色</td> <td>每回合自動</td> <td>行為禁令速查 + 路由（有 token 預算）</td> </tr> <tr> <td>pm-rules/</td> <td>僅主線程 PM（只調度不執行的主對話）</td> <td>情境按需</td> <td>調度流程 SOP（派發、驗收、決策樹）</td> </tr> <tr> <td>AGENT_PRELOAD</td> <td>全體代理人</td> <td>派發時注入</td> <td>代理人通用行為禁令</td> </tr> <tr> <td>agents/*.md</td> <td>單一代理人</td> <td>派發時載入</td> <td>身份、責任邊界、設計偏好（命名、技術手法、語氣）</td> </tr> <tr> <td>skills/</td> <td>觸發者（角色無關）</td> <td>觸發時漸進揭露（先載觸發入口、細節按需展開）</td> <td>可重複工作流與方法（TDD、寫作、ticket CLI）</td> </tr> <tr> <td>methodologies/</td> <td>主動查閱者</td> <td>按需</td> <td>30 秒理念複習清單</td> </tr> <tr> <td>references/</td> <td>執行特定動作者</td> <td>按需</td> <td>技術參考、規則的完整論證</td> </tr> <tr> <td>error-patterns/</td> <td>任務前查詢者</td> <td>按需</td> <td>失敗案例（症狀 / 根因 / 解法 / 預防）</td> </tr> <tr> <td>memory（專案層）</td> <td>僅本專案</td> <td>每回合自動</td> <td>專案特定活教訓的單行索引（教訓升級為正式規則後即移出）</td> </tr> </tbody> </table> <h2 id="情境">情境</h2> <p>框架以「主線程只調度、任務交代理人」為分工原則運作。規範自然長出多個放置點：rules 收所有角色通用規則、pm-rules 收主線程專用流程、AGENT_PRELOAD 收代理人通用禁令、各代理人定義檔收身份與偏好、skills 承載工作流、methodologies 承載理念。</p> <p>問題在每次學到新東西的時候浮現：<strong>這段知識該寫進哪裡？</strong> 沒有頂層地圖時，答案是「寫在最不會忘記的地方」，也就是自動載入層。專案演進至今，自動載入集合膨脹到 82.5k tokens（200k context 模型的約 40%），而代理人定義檔裡混進了操作流程步驟、與通用品質規範重複的檢查清單、錯誤案例全文、工具使用指南。這四種都不屬於「這個代理人是誰」的內容。</p> <h2 id="演進歷程">演進歷程</h2> <ol> <li><strong>單檔期</strong>：一切塞 CLAUDE.md。專案設定、品質規則、流程說明混在一起，單檔暴漲。</li> <li><strong>規則分層期</strong>：拆出 <code>rules/core/</code>（通用品質底線）與 <code>pm-rules/</code>（主線程專用）。動機直接來自分工原則：PM 不寫程式只調度，調度 SOP 沒理由佔用代理人的 context。</li> <li><strong>代理人標準期</strong>：建立 AGENT_PRELOAD（通用行為禁令，派發時注入）與代理人定義三區塊標準（允許產出 / 禁止行為 / 適用情境），讓派發前可查表確認職責邊界。</li> <li><strong>Skill 承載期</strong>：可重複的工作流（TDD 流程、寫作方法、ticket 操作）移入 skills，藉觸發時漸進揭露控制 context 成本。</li> <li><strong>Token 收斂期</strong>：自動載入集合 82.5k 收斂到 41.9k。關鍵發現是膨脹根因不是「規則太多」而是「表達形態錯置」：論證、案例、教學混進了每回合載入的層。建立 45k 預算的機器量測 + 「自動載入層只放禁令與路由」的形態約束。</li> <li><strong>責任地圖期（本篇）</strong>：收斂解決了「放多少」，本階段補「放哪裡」的頂層判定：受眾 x 形態二軸地圖，並首次權威化「代理人定義該裝什麼」。</li> </ol> <h2 id="理想做法">理想做法</h2> <p>標題點名的三個載體在此各有答案：rules 的答案在「二軸定位」（自動載入層的形態約束）、agents 與 skills 的答案在「人格與流程的分界」。</p> <h3 id="二軸定位先問受眾再問形態">二軸定位，先問受眾再問形態</h3> <p>受眾軸縮小候選載體（所有角色 / 僅 PM / 全體代理人 / 單一代理人 / 動作觸發者 / 僅本專案），形態軸確定最終位置（行為禁令 / 調度流程 / 身份偏好 / 工作流方法 / 理念清單 / 技術參考 / 失敗案例 / 專案設定）。兩軸都過了，再檢查目的地是否屬自動載入層並過預算閘門：規範類知識的閘門是必要性否決（「每回合都需要嗎？」）加上把形態壓成「禁令 + 路由」；專案設定這類事實陳述不適用必要性否決，閘門只管體積精簡與不混入框架通用知識。</p> <h3 id="代理人定義-vs-skill人格與流程的分界">代理人定義 vs skill：人格與流程的分界</h3> <p>代理人檔案該裝的是人格與授權：身份定位、責任邊界三區塊、設計偏好（命名習慣、技術手法傾向、文法語氣）、分工路由。操作流程屬於 skill。流程與人格解耦後，同一個寫作 skill 可以被任何代理人觸發，行為一致；而「該由誰執行、用什麼語氣與偏好執行」才是代理人檔案的事。</p> <p>一個容易踩的細節：「技術選型」分兩層。專案級選型（用什麼框架、什麼版本）屬 CLAUDE.md 的專案設定；代理人層放的是「手法傾向」：代理人帶著多種方案的知識，依專案設定選用。把專案選型寫進代理人定義，跨專案 sync 時就會把錯的選型帶去別的專案。</p> <h3 id="重複內容一律路由化">重複內容一律路由化</h3> <p>品質清單、錯誤案例、工具指南在代理人檔案裡只放一行路由（「品質標準見 quality-common『常數管理』節」「詳見 IMP-003」，錨點用語意標題不用位置編號）。複製全文的代價是漂移：來源更新後副本不會跟著動，兩份規範開始打架。</p> <h2 id="沒這樣做的麻煩">沒這樣做的麻煩</h2> <ul> <li><strong>Token 污染</strong>：知識預設寫進自動載入層，每 session 固定燒掉 context 的 40%，而且 attention 稀釋會降低規則遵循率：載越多，守得越差。</li> <li><strong>知識失傳</strong>：跨專案原則寫進專案 memory，不會隨框架 sync，其他專案重踩同樣的雷。</li> <li><strong>規範打架，執法強的一方贏</strong>：載體錯置會製造規則矛盾（例：寫作規範要求每段完整論證 vs 自動載入層要求壓縮形態）。矛盾規則競爭時勝負不看道理，看執法強度：有 hook 阻擋或常駐審查（每次變更必跑的審查代理人）的一方必勝，只有事後量測的一方形同虛設。這是本階段演進最重要的單一洞察：<strong>載體地圖必須與執法機制對齊，否則正確的原則會輸給有 hook 的舊習慣</strong>。</li> <li><strong>代理人檔案變成第二份過時手冊</strong>：流程寫兩份（agent + skill），更新只改一份，派發時代理人讀到舊流程。</li> </ul> <h2 id="判讀徵兆">判讀徵兆</h2> <p>下次遇到這些訊號，代表載體錯置正在發生：</p> <table> <thead> <tr> <th>訊號</th> <th>診斷與行動</th> </tr> </thead> <tbody> <tr> <td>寫新知識時的第一反應是「加進 CLAUDE.md / rules 才不會忘」</td> <td>用載入頻率換安全感；該問的是受眾與形態</td> </tr> <tr> <td>代理人定義出現「執行步驟 1-2-3」</td> <td>流程混進人格層，外移 skill</td> </tr> <tr> <td>同一份清單出現在兩個檔案</td> <td>漂移倒數計時開始，改路由化</td> </tr> <tr> <td>自動載入預算量測逼近上限，而最近沒有新增「每回合行為禁令」</td> <td>有論證或案例混進自動載入層</td> </tr> <tr> <td>兩條規則對同一動作給出相反指示</td> <td>立刻盤點概念詞重疊的既有規範，矛盾修補與新規則同批落地</td> </tr> </tbody> </table> <h2 id="後續">後續</h2> <p>框架內的權威版（30 秒地圖 + 檢查清單）維護在框架 <code>methodologies/knowledge-carrier-allocation-methodology.md</code>，隨理念演進持續更新；本篇是此階段思考歷程的快照。存量錯置的盤點（30 份代理人定義、57 份方法論的體量稽核）已建 ticket 排程，依地圖逐檔分類後再搬移。</p>結論

知識寫入框架前，依「受眾 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 排程，依地圖逐檔分類後再搬移。

]]>知識載體責任分配方法論 - rules/agents/skills 各該裝什麼https://tarrragon.github.io/blog/record/%E7%9F%A5%E8%AD%98%E8%BC%89%E9%AB%94%E8%B2%AC%E4%BB%BB%E5%88%86%E9%85%8D%E6%96%B9%E6%B3%95%E8%AB%96-rules/agents/skills-%E5%90%84%E8%A9%B2%E8%A3%9D%E4%BB%80%E9%BA%BC/Mon, 15 Jun 2026 00:00:00 +0000https://tarrragon.github.io/blog/record/%E7%9F%A5%E8%AD%98%E8%BC%89%E9%AB%94%E8%B2%AC%E4%BB%BB%E5%88%86%E9%85%8D%E6%96%B9%E6%B3%95%E8%AB%96-rules/agents/skills-%E5%90%84%E8%A9%B2%E8%A3%9D%E4%BB%80%E9%BA%BC/<h2 id="核心概念">核心概念</h2> <p>知識寫入框架前，依「<strong>受眾 x 形態</strong>」二軸決定載體。載體錯置有兩種代價：寫進自動載入層 → token 污染（attention 稀釋 + 45k 預算耗盡）；困在專案 memory → 跨專案失傳。本方法論是頂層地圖；各載體的細部規範（如有）路由至 Reference 所列文件。</p> <p><strong>Scope</strong>：本地圖涵蓋 LLM context 載體（人與 AI 閱讀的知識）；專案產物層（<code>docs/</code> / <code>src/</code>）不屬本地圖，劃分見 <code>framework-asset-separation.md</code>；機器讀取層（<code>config/*.yaml</code>、hook 引用的凍結錨點）另計。memory 行由受眾軸「僅本專案」唯一決定，不需形態軸。</p> <p><strong>代理人定義 vs skill 的歸屬判準</strong>：一段知識可能落在代理人定義或 skill、不易區分時，以「該知識是否隨執行者改變」為判準，不憑直覺擇一。</p> <ul> <li>屬<strong>代理人定義</strong>的知識回答「你是誰、你能做什麼、你偏好怎麼做」——身份定位、授權邊界、設計偏好。識別測試：換一個代理人來執行，這段內容就應該不同。本質是人格與授權。</li> <li>屬 <strong>skill</strong> 的知識回答「這件事怎麼做」——可重複執行的流程步驟。識別測試：任何角色觸發都應得到同一份流程，與執行者是誰無關。本質是可重複流程。</li> </ul> <p>兩者衝突時，對該知識套用識別測試「換一個代理人，內容會不會變」：會變則歸代理人定義；不會變、任何角色執行都應一致則歸 skill。</p> <h2 id="載體地圖受眾-x-載入時機-x-形態">載體地圖（受眾 x 載入時機 x 形態）</h2> <table> <thead> <tr> <th>載體</th> <th>受眾</th> <th>載入時機</th> <th>裝什麼（形態）</th> <th>不裝什麼（→ 正確去處）</th> </tr> </thead> <tbody> <tr> <td><code>CLAUDE.md</code></td> <td>所有角色</td> <td>每回合自動</td> <td>專案身份、開發指令、專案級技術選型、路由</td> <td>框架通用知識（→ <code>.claude/</code>，否則無法 sync）</td> </tr> <tr> <td><code>rules/core/</code></td> <td>所有角色</td> <td>每回合自動</td> <td>行為禁令速查 + 路由（與 CLAUDE.md 同屬 file-size-guardian 45k 量測集合；MEMORY.md 每回合注入但不在量測集合內）</td> <td>論證 / 流程 / 案例（→ <code>references/</code>、<code>error-patterns/</code>）</td> </tr> <tr> <td><code>pm-rules/</code></td> <td>僅 PM</td> <td>情境觸發按需</td> <td>調度流程 SOP（派發、驗收、決策樹、skip-gate）</td> <td>代理人執行知識（→ agents / skills）</td> </tr> <tr> <td><code>agents/AGENT_PRELOAD.md</code></td> <td>全體代理人</td> <td>派發時 @ 注入</td> <td>代理人通用行為禁令（ticket 操作、git 限制、工具選擇、嵌套協議）</td> <td>單一代理人偏好（→ 各 agent 定義）、PM 流程（→ pm-rules）</td> </tr> <tr> <td><code>agents/&lt;name&gt;.md</code></td> <td>單一代理人</td> <td>派發時載入</td> <td>身份定位、三區塊（允許產出 / 禁止行為 / 適用情境）、設計偏好（命名習慣、技術手法傾向、文法語氣）、分工路由與升級條件</td> <td>→ 見「代理人定義內容規範」節</td> </tr> <tr> <td><code>skills/</code></td> <td>觸發者（角色無關）</td> <td>觸發時漸進揭露</td> <td>可重複執行的工作流、方法、CLI 工具（TDD、寫作、ticket、worktree）</td> <td>身份偏好（→ agents）、專案設定（→ CLAUDE.md）</td> </tr> <tr> <td><code>methodologies/</code></td> <td>主動查閱者</td> <td>按需</td> <td>30 秒理念複習清單（核心概念 + 步驟 + 檢查清單）</td> <td>完整流程 / 範例 / 錯誤處理（→ skills）</td> </tr> <tr> <td><code>references/</code></td> <td>執行特定動作者</td> <td>按需</td> <td>技術參考、規則 substance（auto-load stub 的完整版）</td> <td>每回合禁令（→ rules/core stub）</td> </tr> <tr> <td><code>error-patterns/</code></td> <td>ticket 前查詢者</td> <td>按需</td> <td>失敗案例（症狀 / 根因 / 解法 / 預防）</td> <td>規則正文（規則只放一行路由指向 PC/IMP）</td> </tr> <tr> <td>memory（專案層）</td> <td>本專案 PM</td> <td>MEMORY.md 每回合</td> <td>專案特定活教訓的單行索引</td> <td>已固化內容（升級即搬家）、跨專案原則（四問升級後外移）</td> </tr> <tr> <td><code>templates/</code>、<code>.claude/</code> root 歷史遺留檔</td> <td>（未分類）</td> <td>不自動載入</td> <td>—</td> <td>依本地圖二軸重分配（templates 內容須與對應規範同步，否則新實例從模板長出舊形態）；盤點另由 ticket 追蹤</td> </tr> <tr> <td><code>.claude/README.md</code></td> <td>框架瀏覽者</td> <td>不自動載入</td> <td>框架頂層導覽：目錄結構、各載體用途、入口索引</td> <td>規範 substance（→ rules / references）、流程方法（→ skills）</td> </tr> <tr> <td><code>.claude/CHANGELOG.md</code></td> <td>框架維護者</td> <td>不自動載入</td> <td>框架變更記錄（sync 歷史、版本演進）</td> <td>當前規範內容（→ 對應載體；CHANGELOG 只記「變了什麼」不記「規範是什麼」）</td> </tr> <tr> <td><code>.claude/README-subtree-sync.md</code></td> <td>執行 sync-pull / sync-push 者</td> <td>不自動載入</td> <td>同步機制操作說明：設計原理、方案比較、衝突處理</td> <td>同步以外的框架知識（→ 對應載體）</td> </tr> <tr> <td><code>.claude/terminology-dictionary.md</code></td> <td>所有角色（撰寫文字時）</td> <td>經 <code>.claude/rules/core/language-constraints.md</code> 的 <code>@</code> 引用實質載入</td> <td>用語規範對照表：禁用詞 / 正確用語 / 台灣用語</td> <td>語言規則正文（→ <code>.claude/rules/core/language-constraints.md</code>，本檔僅承載對照資料）</td> </tr> </tbody> </table> <h2 id="執行步驟">執行步驟</h2> <ol> <li><strong>受眾是誰</strong>？（所有角色 / 僅 PM / 全體代理人 / 單一代理人 / 動作觸發者 / 僅本專案）→ 縮小候選載體。「動作觸發者」統括地圖表受眾欄的按需情境詞（觸發者 / 主動查閱者 / 執行特定動作者 / 任務前查詢者）</li> <li><strong>形態是什麼</strong>？（行為禁令 / 調度流程 / 身份偏好 / 工作流方法 / 理念清單 / 技術參考 / 失敗案例 / 專案設定）→ 確定載體</li> <li>候選屬<strong>自動載入層</strong>（CLAUDE.md / rules/ / MEMORY.md）？→ 過預算閘門；規範類知識的閘門是必要性否決（「這是否每回合都需要？」否則外移按需層）+ 形態降為「禁令 + 路由」，專案設定 / 指令等事實類的閘門是體積與專案特定性約束（精簡陳述、不含框架通用知識），不適用必要性否決</li> <li>skill / methodology / rule 三選一拿不準 → <code>framework-meta-methodology.md</code> 決策樹</li> <li>寫完 grep 概念詞，盤點與既有規範的指令方向矛盾，並對齊執法強度（PC-V1-006）</li> </ol> <h2 id="代理人定義內容規範">代理人定義內容規範</h2> <table> <thead> <tr> <th>該裝</th> <th>不該裝（外移路由）</th> </tr> </thead> <tbody> <tr> <td>身份定位與核心使命</td> <td>—</td> </tr> <tr> <td>三區塊：允許產出 / 禁止行為 / 適用情境</td> <td>—</td> </tr> <tr> <td>設計偏好：命名習慣、技術手法傾向、文法語氣</td> <td>專案級技術選型（→ CLAUDE.md；代理人帶多方案知識，依專案設定選用）</td> </tr> <tr> <td>多方案技術知識庫（framework-asset-separation 的「框架寫法」段，深度以支撐選用傾向為度）</td> <td>步驟化操作流程（→ 對應 skill，流程與人格解耦）；知識庫展開成教學長文（→ references/）</td> </tr> <tr> <td>分工路由與升級條件（與誰分工、何時上報）</td> <td>操作流程步驟（→ 對應 skill）</td> </tr> <tr> <td>品質標準的章節路由（如 quality-common 指定章節，語意錨點）</td> <td>品質清單全文（複製即漂移，單一來源失效）</td> </tr> <tr> <td>錯誤模式的一行路由（「詳見 IMP-XXX」）</td> <td>錯誤案例全文（error-pattern 才是案例的家）</td> </tr> </tbody> </table> <h2 id="檢查清單">檢查清單</h2> <ul> <li><input disabled="" type="checkbox"> 受眾 x 形態二軸定位完成，不是「順手寫在開啟中的檔案」？</li> <li><input disabled="" type="checkbox"> 自動載入層寫入已過預算閘門；規範類形態已降為禁令 + 路由（事實類過閘門即可）？</li> <li><input disabled="" type="checkbox"> 代理人定義新增內容屬「偏好 / 邊界」而非「流程 / 方法」？</li> <li><input disabled="" type="checkbox"> 重複內容用路由取代複製（單一來源）？</li> <li><input disabled="" type="checkbox"> 概念詞 grep 矛盾盤點 + 執法強度對齊完成（PC-V1-006）？</li> </ul> <h2 id="reference">Reference</h2> <ul> <li><code>.claude/methodologies/framework-meta-methodology.md</code> — skill / methodology / rule 三分決策樹 + 30 秒標準（形態軸的細分）</li> <li><code>.claude/references/framework-asset-separation.md</code> — 框架資產 vs 專案產物、專案設定 vs 代理人知識、Skill Hook 雙層</li> <li><code>.claude/references/auto-load-stub-conventions.md</code> — 自動載入層 stub 構成 + 外移 SOP + 預算驗證</li> <li><code>.claude/rules/core/agent-definition-standard.md</code> — 代理人三區塊結構標準</li> <li><code>.claude/rules/README.md</code> — 自動載入預算原則（每回合必要性自問）</li> <li><code>.claude/pm-rules/pm-quality-baseline.md</code> 規則 7 — memory 升級四問 + 升級目的地預算閘門 + 升級即搬家</li> <li><code>.claude/README.md</code>「同步機制」章 — 寫作類 skill（compositional-writing / multi-round-review）內容 SSOT 在 blog repo，框架端為回流副本；依地圖判定「寫作方法 → skills/」後，內容修改應到上游 repo 執行</li> <li><code>.claude/skills/skill-design-guide/SKILL.md</code> — skills 載體的細部規範（官方規格、frontmatter、漸進揭露結構）</li> </ul> <hr> <p><strong>Last Updated</strong>: 2026-06-15 <strong>Version</strong>: 1.8.0 — 「代理人定義 vs skill 歸屬判準」改寫：去除「一句話判定」總結框架，改為含明確識別測試（換一個執行者內容是否改變）的判準段落。方法論作為框架核心規則供 AI 開發時判斷，內容須明確而可套用，不採壓縮式總結（避免單句總結遮蔽判準細節導致 AI 判斷失準） <strong>Version</strong>: 1.7.0 — root 錯置檔重分配（1.0.0-W8-023.2，第 2/4 批）：4 檔（<code>agent-collaboration.md</code> 794 / <code>decision-workflows.md</code> 116 / <code>quick-ref-agent-dispatch-recovery.md</code> 202 / <code>thinking-process.md</code> 271）逐檔讀內容後<strong>全數 flag superseded/obsolete</strong>（campaign 規則 3，零搬移零連結手術）：<code>agent-collaboration</code> 與 <code>analyses/archived/</code> 同名 794 行副本 near-identical 且內容已被 <code>methodologies/tdd-collaboration-flow.md</code> + agent 定義覆蓋；<code>decision-workflows</code> 五情境已被 <code>pm-rules/skip-gate</code>+<code>incident-response</code>+<code>decision-tree</code> 覆蓋；<code>quick-ref-agent-dispatch-recovery</code> 所述 <code>agent_dispatch_recovery.py</code> hook 已不存在；<code>thinking-process</code> 為 2025-12-01 一次性 session 快照非知識載體。本批 0 檔搬移，故不加 map 行，留 PM follow-up 清理（inbound 連結多在 .3/.4 批檔群） <strong>Version</strong>: 1.6.0 — root 錯置檔重分配（1.0.0-W8-023.1，第 1/4 批）：<code>hook-system-reference.md</code>（Hook 事件索引 / 技術參考）、<code>code-smell-checklist.md</code>（Code Smell 檢測清單 / 技術參考）依二軸（受眾＝動作觸發者、形態＝技術參考）歸入既有 <code>references/</code> 載體列（line 22），故不另加 map 行；superseded 副本 <code>code-quality-examples.md</code>（已遷 <code>docs/</code>，DOC-010 W10-102）與 <code>document-responsibilities.md</code>（DEPRECATED，已被 <code>five-document-system-methodology.md</code> + <code>doc-flow/references/document-responsibilities.md</code> 取代）flag 不併入，留 PM follow-up <strong>Version</strong>: 1.5.0 — 載體地圖補列 4 個 legit root 資產各一行歸屬（README 框架導覽 / CHANGELOG 變更記錄 / README-subtree-sync 同步機制 / terminology-dictionary 用語規範表，後者經 language-constraints <code>@</code> 引用實質載入）（1.0.0-W8-022） <strong>Version</strong>: 1.4.0 — multi-round-review Round 4（實例分配演練）修正：步驟 1 補受眾詞彙映射橋（六選項 vs 地圖表受眾欄斷層）、步驟 3 事實類閘門判準明文化（體積與專案特定性約束，非必要性否決）。8 條盲跑 6 條乾淨落點，停止訊號達成收斂 <strong>Version</strong>: 1.3.0 — multi-round-review Round 3 修正：Scope 句（LLM context 載體限定 + 機器讀取層另計 + memory 受眾軸唯一決定）、rules/core 列量測集合精確化（MEMORY.md 不在 guardian 集合）、規範表補「多方案技術知識庫」劃界列（與 framework-asset-separation「框架寫法」段對齊）、地圖補 templates / root 遺留行、Reference 補 skill-design-guide <strong>Version</strong>: 1.2.0 — multi-round-review Round 2 修正：檢查清單與步驟 3/5 的 R1 劃界同步（清單漂移）、步驟 5 拆動作解歧義、地圖欄名補形態軸、定位句「（如有）」、Reference 補寫作 skill SSOT 例外路由 <strong>Version</strong>: 1.1.0 — multi-round-review Round 1 修正：步驟 3 形態約束劃界（規範類 vs 事實類）、步驟 5 補執法強度對齊、章名對齊 methodology 標準結構、rules/core 列預算範圍精確化、agents 列改路由至專節 <strong>Version</strong>: 1.0.0 — 初始建立：框架知識載體的頂層責任地圖（受眾 x 形態二軸），整合 W7 token 收斂三層防護與既有分離原則；代理人定義內容規範首次權威化（人格與授權 vs 可重複流程）</p>核心概念

知識寫入框架前，依「受眾 x 形態」二軸決定載體。載體錯置有兩種代價：寫進自動載入層 → token 污染（attention 稀釋 + 45k 預算耗盡）；困在專案 memory → 跨專案失傳。本方法論是頂層地圖；各載體的細部規範（如有）路由至 Reference 所列文件。

Scope：本地圖涵蓋 LLM context 載體（人與 AI 閱讀的知識）；專案產物層（docs/ / src/）不屬本地圖，劃分見 framework-asset-separation.md；機器讀取層（config/*.yaml、hook 引用的凍結錨點）另計。memory 行由受眾軸「僅本專案」唯一決定，不需形態軸。

代理人定義 vs skill 的歸屬判準：一段知識可能落在代理人定義或 skill、不易區分時，以「該知識是否隨執行者改變」為判準，不憑直覺擇一。

  • 屬代理人定義的知識回答「你是誰、你能做什麼、你偏好怎麼做」——身份定位、授權邊界、設計偏好。識別測試：換一個代理人來執行，這段內容就應該不同。本質是人格與授權。
  • 屬 skill 的知識回答「這件事怎麼做」——可重複執行的流程步驟。識別測試：任何角色觸發都應得到同一份流程，與執行者是誰無關。本質是可重複流程。

兩者衝突時，對該知識套用識別測試「換一個代理人，內容會不會變」：會變則歸代理人定義；不會變、任何角色執行都應一致則歸 skill。

載體地圖（受眾 x 載入時機 x 形態）

載體 受眾 載入時機 裝什麼（形態） 不裝什麼（→ 正確去處）
CLAUDE.md 所有角色 每回合自動 專案身份、開發指令、專案級技術選型、路由 框架通用知識（→ .claude/，否則無法 sync）
rules/core/ 所有角色 每回合自動 行為禁令速查 + 路由（與 CLAUDE.md 同屬 file-size-guardian 45k 量測集合；MEMORY.md 每回合注入但不在量測集合內） 論證 / 流程 / 案例（→ references/、error-patterns/）
pm-rules/ 僅 PM 情境觸發按需 調度流程 SOP（派發、驗收、決策樹、skip-gate） 代理人執行知識（→ agents / skills）
agents/AGENT_PRELOAD.md 全體代理人 派發時 @ 注入 代理人通用行為禁令（ticket 操作、git 限制、工具選擇、嵌套協議） 單一代理人偏好（→ 各 agent 定義）、PM 流程（→ pm-rules）
agents/<name>.md 單一代理人 派發時載入 身份定位、三區塊（允許產出 / 禁止行為 / 適用情境）、設計偏好（命名習慣、技術手法傾向、文法語氣）、分工路由與升級條件 → 見「代理人定義內容規範」節
skills/ 觸發者（角色無關） 觸發時漸進揭露 可重複執行的工作流、方法、CLI 工具（TDD、寫作、ticket、worktree） 身份偏好（→ agents）、專案設定（→ CLAUDE.md）
methodologies/ 主動查閱者 按需 30 秒理念複習清單（核心概念 + 步驟 + 檢查清單） 完整流程 / 範例 / 錯誤處理（→ skills）
references/ 執行特定動作者 按需 技術參考、規則 substance（auto-load stub 的完整版） 每回合禁令（→ rules/core stub）
error-patterns/ ticket 前查詢者 按需 失敗案例（症狀 / 根因 / 解法 / 預防） 規則正文（規則只放一行路由指向 PC/IMP）
memory（專案層） 本專案 PM MEMORY.md 每回合 專案特定活教訓的單行索引 已固化內容（升級即搬家）、跨專案原則（四問升級後外移）
templates/、.claude/ root 歷史遺留檔 （未分類） 不自動載入 — 依本地圖二軸重分配（templates 內容須與對應規範同步，否則新實例從模板長出舊形態）；盤點另由 ticket 追蹤
.claude/README.md 框架瀏覽者 不自動載入 框架頂層導覽：目錄結構、各載體用途、入口索引 規範 substance（→ rules / references）、流程方法（→ skills）
.claude/CHANGELOG.md 框架維護者 不自動載入 框架變更記錄（sync 歷史、版本演進） 當前規範內容（→ 對應載體；CHANGELOG 只記「變了什麼」不記「規範是什麼」）
.claude/README-subtree-sync.md 執行 sync-pull / sync-push 者 不自動載入 同步機制操作說明：設計原理、方案比較、衝突處理 同步以外的框架知識（→ 對應載體）
.claude/terminology-dictionary.md 所有角色（撰寫文字時） 經 .claude/rules/core/language-constraints.md 的 @ 引用實質載入 用語規範對照表：禁用詞 / 正確用語 / 台灣用語 語言規則正文（→ .claude/rules/core/language-constraints.md，本檔僅承載對照資料）

執行步驟

  1. 受眾是誰？（所有角色 / 僅 PM / 全體代理人 / 單一代理人 / 動作觸發者 / 僅本專案）→ 縮小候選載體。「動作觸發者」統括地圖表受眾欄的按需情境詞（觸發者 / 主動查閱者 / 執行特定動作者 / 任務前查詢者）
  2. 形態是什麼？（行為禁令 / 調度流程 / 身份偏好 / 工作流方法 / 理念清單 / 技術參考 / 失敗案例 / 專案設定）→ 確定載體
  3. 候選屬自動載入層（CLAUDE.md / rules/ / MEMORY.md）？→ 過預算閘門；規範類知識的閘門是必要性否決（「這是否每回合都需要？」否則外移按需層）+ 形態降為「禁令 + 路由」，專案設定 / 指令等事實類的閘門是體積與專案特定性約束（精簡陳述、不含框架通用知識），不適用必要性否決
  4. skill / methodology / rule 三選一拿不準 → framework-meta-methodology.md 決策樹
  5. 寫完 grep 概念詞，盤點與既有規範的指令方向矛盾，並對齊執法強度（PC-V1-006）

代理人定義內容規範

該裝 不該裝（外移路由）
身份定位與核心使命 —
三區塊：允許產出 / 禁止行為 / 適用情境 —
設計偏好：命名習慣、技術手法傾向、文法語氣 專案級技術選型（→ CLAUDE.md；代理人帶多方案知識，依專案設定選用）
多方案技術知識庫（framework-asset-separation 的「框架寫法」段，深度以支撐選用傾向為度） 步驟化操作流程（→ 對應 skill，流程與人格解耦）；知識庫展開成教學長文（→ references/）
分工路由與升級條件（與誰分工、何時上報） 操作流程步驟（→ 對應 skill）
品質標準的章節路由（如 quality-common 指定章節，語意錨點） 品質清單全文（複製即漂移，單一來源失效）
錯誤模式的一行路由（「詳見 IMP-XXX」） 錯誤案例全文（error-pattern 才是案例的家）

檢查清單

  • 受眾 x 形態二軸定位完成，不是「順手寫在開啟中的檔案」？
  • 自動載入層寫入已過預算閘門；規範類形態已降為禁令 + 路由（事實類過閘門即可）？
  • 代理人定義新增內容屬「偏好 / 邊界」而非「流程 / 方法」？
  • 重複內容用路由取代複製（單一來源）？
  • 概念詞 grep 矛盾盤點 + 執法強度對齊完成（PC-V1-006）？

Reference

  • .claude/methodologies/framework-meta-methodology.md — skill / methodology / rule 三分決策樹 + 30 秒標準（形態軸的細分）
  • .claude/references/framework-asset-separation.md — 框架資產 vs 專案產物、專案設定 vs 代理人知識、Skill Hook 雙層
  • .claude/references/auto-load-stub-conventions.md — 自動載入層 stub 構成 + 外移 SOP + 預算驗證
  • .claude/rules/core/agent-definition-standard.md — 代理人三區塊結構標準
  • .claude/rules/README.md — 自動載入預算原則（每回合必要性自問）
  • .claude/pm-rules/pm-quality-baseline.md 規則 7 — memory 升級四問 + 升級目的地預算閘門 + 升級即搬家
  • .claude/README.md「同步機制」章 — 寫作類 skill（compositional-writing / multi-round-review）內容 SSOT 在 blog repo，框架端為回流副本；依地圖判定「寫作方法 → skills/」後，內容修改應到上游 repo 執行
  • .claude/skills/skill-design-guide/SKILL.md — skills 載體的細部規範（官方規格、frontmatter、漸進揭露結構）

Last Updated: 2026-06-15 Version: 1.8.0 — 「代理人定義 vs skill 歸屬判準」改寫：去除「一句話判定」總結框架，改為含明確識別測試（換一個執行者內容是否改變）的判準段落。方法論作為框架核心規則供 AI 開發時判斷，內容須明確而可套用，不採壓縮式總結（避免單句總結遮蔽判準細節導致 AI 判斷失準） Version: 1.7.0 — root 錯置檔重分配（1.0.0-W8-023.2，第 2/4 批）：4 檔（agent-collaboration.md 794 / decision-workflows.md 116 / quick-ref-agent-dispatch-recovery.md 202 / thinking-process.md 271）逐檔讀內容後全數 flag superseded/obsolete（campaign 規則 3，零搬移零連結手術）：agent-collaboration 與 analyses/archived/ 同名 794 行副本 near-identical 且內容已被 methodologies/tdd-collaboration-flow.md + agent 定義覆蓋；decision-workflows 五情境已被 pm-rules/skip-gate+incident-response+decision-tree 覆蓋；quick-ref-agent-dispatch-recovery 所述 agent_dispatch_recovery.py hook 已不存在；thinking-process 為 2025-12-01 一次性 session 快照非知識載體。本批 0 檔搬移，故不加 map 行，留 PM follow-up 清理（inbound 連結多在 .3/.4 批檔群） Version: 1.6.0 — root 錯置檔重分配（1.0.0-W8-023.1，第 1/4 批）：hook-system-reference.md（Hook 事件索引 / 技術參考）、code-smell-checklist.md（Code Smell 檢測清單 / 技術參考）依二軸（受眾＝動作觸發者、形態＝技術參考）歸入既有 references/ 載體列（line 22），故不另加 map 行；superseded 副本 code-quality-examples.md（已遷 docs/，DOC-010 W10-102）與 document-responsibilities.md（DEPRECATED，已被 five-document-system-methodology.md + doc-flow/references/document-responsibilities.md 取代）flag 不併入，留 PM follow-up Version: 1.5.0 — 載體地圖補列 4 個 legit root 資產各一行歸屬（README 框架導覽 / CHANGELOG 變更記錄 / README-subtree-sync 同步機制 / terminology-dictionary 用語規範表，後者經 language-constraints @ 引用實質載入）（1.0.0-W8-022） Version: 1.4.0 — multi-round-review Round 4（實例分配演練）修正：步驟 1 補受眾詞彙映射橋（六選項 vs 地圖表受眾欄斷層）、步驟 3 事實類閘門判準明文化（體積與專案特定性約束，非必要性否決）。8 條盲跑 6 條乾淨落點，停止訊號達成收斂 Version: 1.3.0 — multi-round-review Round 3 修正：Scope 句（LLM context 載體限定 + 機器讀取層另計 + memory 受眾軸唯一決定）、rules/core 列量測集合精確化（MEMORY.md 不在 guardian 集合）、規範表補「多方案技術知識庫」劃界列（與 framework-asset-separation「框架寫法」段對齊）、地圖補 templates / root 遺留行、Reference 補 skill-design-guide Version: 1.2.0 — multi-round-review Round 2 修正：檢查清單與步驟 3/5 的 R1 劃界同步（清單漂移）、步驟 5 拆動作解歧義、地圖欄名補形態軸、定位句「（如有）」、Reference 補寫作 skill SSOT 例外路由 Version: 1.1.0 — multi-round-review Round 1 修正：步驟 3 形態約束劃界（規範類 vs 事實類）、步驟 5 補執法強度對齊、章名對齊 methodology 標準結構、rules/core 列預算範圍精確化、agents 列改路由至專節 Version: 1.0.0 — 初始建立：框架知識載體的頂層責任地圖（受眾 x 形態二軸），整合 W7 token 收斂三層防護與既有分離原則；代理人定義內容規範首次權威化（人格與授權 vs 可重複流程）

]]>方法論文件撰寫方法論https://tarrragon.github.io/blog/record/%E6%96%B9%E6%B3%95%E8%AB%96%E6%96%87%E4%BB%B6%E6%92%B0%E5%AF%AB%E6%96%B9%E6%B3%95%E8%AB%96/Wed, 04 Mar 2026 00:00:00 +0000https://tarrragon.github.io/blog/record/%E6%96%B9%E6%B3%95%E8%AB%96%E6%96%87%E4%BB%B6%E6%92%B0%E5%AF%AB%E6%96%B9%E6%B3%95%E8%AB%96/<h2 id="一個根本性的誤解">一個根本性的誤解</h2> <p>我們花了很長時間，把方法論文件寫得越來越完整——完整的定義、詳細的範例、細緻的流程說明，直到有一天發現，這樣的文件根本沒有人在用。</p> <p>問題出在誤解了方法論的讀者是誰。</p>一個根本性的誤解

我們花了很長時間，把方法論文件寫得越來越完整——完整的定義、詳細的範例、細緻的流程說明，直到有一天發現，這樣的文件根本沒有人在用。

問題出在誤解了方法論的讀者是誰。

方法論的讀者是專家。他們已經知道這些內容，只是需要時忘記了細節。他們不需要被教導，只需要一個快速的提醒，幫他們找回記憶。

30 秒電梯理論

我們現在用一個簡單標準評估方法論：能在 30 秒內讀完嗎？如果不能，就太長了。

讀者打開方法論通常是在任務中途，需要確認某個原則或步驟。超出 30 秒的內容搬移到獨立的 SKILL 文件，由方法論引用。

方法論與 SKILL 的分工

方法論是複習清單：告訴你「有哪些原則」「判斷方向是什麼」，讓你快速確認沒有遺漏重要考量。

SKILL 是實作指南：包含範例、錯誤處理、邊界情況，回答「具體怎麼做」。

過去把兩者混在一起，結果兩頭不討好——方法論太長難以快速查閱，又因試圖簡潔而省略了真正需要的操作細節。

撰寫方法論的核查

每次撰寫或改寫方法論，問三個問題：

有完整的操作流程嗎？建立對應 SKILL，方法論只保留原則和引用。

有程式碼範例或錯誤處理細節嗎？屬於 SKILL，不屬於方法論。

精簡後會流失關鍵資訊嗎？如果是，那些資訊本來就不屬於方法論。

消除歧義仍然是核心要求

精簡不代表模糊。「應該」改為「必須」，「建議」改為「要求」，「適當時機」改為具體時間點。每個判斷只有兩種結果：接受或拒絕、必須或禁止。

簡短但模糊的方法論比詳細但模糊的更糟糕——它讓讀者覺得已經複習完了，卻什麼都沒想清楚。

]]>