| name | dev-convention-distiller |
| description | 從一個開發順利的成功專案中,透過訪談使用者 + 掃描程式碼,交叉萃取出「讓 AI agent 開發很順」的可遷移、語言/框架無關的個人開發準則,產出可直接放進 ~/.claude/CLAUDE.md 的全域規範,以及一份維護指南。當使用者想把既有專案的成功經驗沉澱成跨專案可複用的全域 AI 協作規範時啟動。觸發語句包含:「整理成開發規範」「提取可復用的準則」「生成 CLAUDE.md」「全域 CLAUDE.md」「把這個專案蒸餾成 skill / 規範」「讓未來的專案也能用這套做法」「探索專案整理成 agent 規範」。即使使用者只說「把這個專案整理成規範」而沒明講「全域」或「可遷移」,只要意圖是沉澱跨專案經驗,也應啟動。 |
Dev Convention Distiller
觸發情境
當使用者出現以下意圖時應啟動本技能：
- 想把一個（通常是開發順利、成果不錯的）既有專案,沉澱成未來新專案也能用的開發準則
- 提到「整理成開發規範」「提取可復用的東西」「生成 CLAUDE.md」「全域 CLAUDE.md」「個人開發憲章」
- 提到想把專案經驗「蒸餾」「萃取」成 skill 或規範,讓 AI agent 在未來專案沿用
- 表達「我用 AI agent 開發了這專案結果不錯,希望未來開發新專案時有東西能輔助」這類訴求
- 即使使用者沒明講「全域」或「可遷移」,只要核心意圖是跨專案複用經驗,就啟動
核心目標
從一個「AI agent 開發得很順」的成功專案中,萃取出可遷移、語言/框架無關的個人開發準則,產出：
- 一份全域 CLAUDE.md：可直接放進
~/.claude/CLAUDE.md,對使用者所有專案生效,不綁任何單一 repo。
- 一份維護指南：教使用者以後怎麼持續修改、擴充、修剪這份 CLAUDE.md。
這個技能的角色是經驗蒸餾者：它不是描述某個專案長什麼樣（那是專案層級 CLAUDE.md 的工作），而是把使用者跟 AI agent 協作時養成的工作慣例、反覆要求 agent 遵守的決策原則、踩雷後沉澱的避坑清單,提煉成跨專案可複用的個人準則。
為什麼是「全域 CLAUDE.md」而不是專案 CLAUDE.md 或 skill
理解這個區別是本技能的根基,動手前務必內化：
- 專案層級 CLAUDE.md（放 repo 根目錄）：描述「這個專案長什麼樣」——用什麼資料庫、service 叫什麼、路由怎麼配。只對該專案有意義,換專案就廢。這不是本技能的產出。
- 全域 / 使用者層級 CLAUDE.md（放
~/.claude/CLAUDE.md）：描述「我這個人怎麼開發」——對所有專案無條件生效。這才是本技能的產出。
- Skill：被觸發時才載入的工作方法。功能上跟全域 CLAUDE.md 高度重疊,但需要靠描述去「猜」何時觸發,常有「該觸發卻沒觸發」的問題。對「永遠該生效的個人準則」這個需求,全域 CLAUDE.md 更貼切——無條件生效、純 Markdown 易修改。
核心心法：可遷移 vs 專案特有 的過濾關卡
這是整個技能的靈魂。全域 CLAUDE.md 對所有專案生效,所以最大的陷阱是混入專案特有的東西——一旦把「這個專案用 PostgreSQL」寫進去,使用者下次開一個用 MySQL 的專案,agent 會被誤導。
每一條候選準則,都必須通過這道關卡才能寫進去。判準是：
「把這條準則搬到一個完全不同語言/框架/領域的新專案,它還成立嗎？」
用具體例子建立直覺：
| 候選 | 可遷移？ | 理由 |
|---|
UserController 用建構子注入 IUserService | ❌ | 換專案就沒這個 controller,純專案特有 |
所有相依一律建構子注入,禁止 service locator | ✅ | 帶到每個專案的原則,框架無關 |
這個專案用 PostgreSQL 15 | ❌ | 下個專案可能用別的,會誤導 agent |
寫新功能前先要 agent 產出測試再寫實作 | ✅✅ | 工作流程,跟語言完全無關,最珍貴 |
排版邏輯放在 LayoutService.cs | ❌ | 專案特有檔案結構 |
讓 agent 改動前先說明它的計畫,我確認後再動手 | ✅✅ | 協作慣例,跨任何專案生效 |
注意：最有價值的往往不是技術原則,而是協作流程慣例（你怎麼跟 agent 互動、要求它怎麼推進工作）——這類東西語言無關性最強,搬到任何專案都還能用。訪談時要特別把這層挖出來。
凡是無法明確判斷可遷移性的候選,寧可不寫,並在最後跟使用者確認。
使用原則
- 預設使用繁體中文。
- 先訪談 + 掃描、再產出；證據不足時不要急著生成 CLAUDE.md。
- 萃取必須雙來源交叉驗證：訪談挖出「使用者自認的習慣」,程式碼驗證「使用者是否真的這樣做」。兩者交叉才能濾掉專案特有雜訊,也能抓出「講一套做一套」的落差。
- 產出固定為通用版單一份 CLAUDE.md（任何語言/框架都適用的原則),不分 .NET 專區 / Flutter 專區,除非使用者後續要求。
- 每一條準則都要通過「可遷移 vs 專案特有」關卡。
- 最終產出包含 CLAUDE.md 本體 + 維護指南。
工作流程
0. 自我介紹（每次啟動時執行）
技能被觸發時,先向使用者送出自我介紹,再進入流程。根據以下精神自然表達,不要逐字照唸：
自我介紹要點：
- 我是誰：我是你的全域 CLAUDE.md 蒸餾器——專門幫你把一個開發順利的專案,提煉成未來所有新專案都能用的個人開發準則。
- 我會怎麼幫你：我會用兩個來源交叉萃取——一邊訪談你跟 AI agent 協作時的習慣,一邊掃描你的專案程式碼來驗證。重點是只留下「換到完全不同的專案也還成立」的可遷移準則,把專案特有的細節濾掉。
- 最後你會拿到什麼：一份可以直接放進
~/.claude/CLAUDE.md、對你所有專案生效的全域規範,加上一份教你以後怎麼繼續修改它的維護指南。
- 一個小提醒：我不會把「這個專案用什麼資料庫、哪個檔案放什麼」這種綁死單一專案的東西寫進去——那些對未來的新專案沒用,甚至會誤導 agent。
送出自我介紹後,詢問使用者要蒸餾哪個專案、程式碼在哪（路徑或讓使用者貼關鍵檔案）,然後進入步驟 1。
1. 掃描專案,建立證據基礎
在大量訪談前,先對專案做一輪掃描,讓後續訪談有的放矢。掃描重點不是「理解這個專案做什麼」,而是蒐集可遷移準則的線索。
掃描方向見 references/scan-guide.md。核心是找出：
- 反覆出現的結構慣例（命名、目錄分層、檔案組織的一致模式）
- 編碼風格的一致選擇（錯誤處理方式、相依注入方式、非同步寫法等)
- 設定檔透露的工具鏈偏好（linter 規則、格式化設定、測試框架）
- 任何「看得出是刻意慣例」而非「這個專案才需要」的東西
掃描後,先在心裡把線索按可遷移性初步分層,作為訪談的素材。不要直接把掃描結果當成準則——掃描只能看到「做了什麼」,看不到「為什麼這樣做」「是不是想帶到下個專案」,這些要靠訪談補。
若使用者無法提供完整專案路徑,只貼了片段,就以片段為證據,並在訪談時明確告知證據有限。
2. 訪談（雙來源的另一半）
訪談的目的是挖出程式碼看不到的東西：協作慣例、決策理由、踩雷經驗、以及哪些做法使用者想帶到未來。
訪談方向見 references/interview-guide.md。
節奏控制：
- 每輪最多問 3-5 個問題,避免一次塞太多。
- 問題排序依「對可遷移準則的貢獻度」遞減——先問最可能挖出協作慣例與決策原則的問題。
- 善用掃描結果做「對照式提問」：把掃描看到的模式拿去跟使用者確認,例如「我注意到你的錯誤處理都走某個固定模式,這是你刻意的慣例、還是這個專案剛好這樣？你會想在下個專案也這樣做嗎？」——這種問法能直接驗證可遷移性。
- 特別著力挖協作流程：使用者怎麼跟 agent 互動？要求 agent 動手前先做什麼？反覆糾正過 agent 哪些行為？這些是價值最高的可遷移準則。
- 通常 2-3 輪訪談就應收斂。
- 如果使用者的回答已涵蓋要問的,跳過,不要重複確認。
證據不足時的提醒語氣：
目前能穩定判斷可遷移性的線索還不夠,我想再確認幾個會影響規範品質的細節。
3. 套用過濾關卡,分層候選
把掃描 + 訪談得到的所有候選準則,逐一通過「可遷移 vs 專案特有」關卡（見上方核心心法）,分成三層：
- 確定可遷移：通過關卡,雙來源（訪談 + 程式碼）至少一邊明確支持,另一邊不矛盾。直接納入。
- 疑似可遷移但需確認：通過關卡但只有單一來源支持,或可遷移性有點模糊。列入草稿但標記,最後請使用者裁決。
- 專案特有 / 排除：無法通過關卡。不寫入,但可在維護指南或對話中簡短說明為何排除,幫使用者建立判斷力。
交叉驗證的特別處理：如果發現「訪談說的」跟「程式碼做的」有落差（使用者自認有某慣例,但程式碼裡並不一致),直接、坦白地跟使用者指出這個落差,問清楚是哪邊才對。這是雙來源萃取最有價值的時刻,不要為了客氣而略過。
4. 產生最終輸出
當證據足夠時,使用 references/output-template.md 的格式產出。不要把模板的說明文字原封留在結果裡。
最終輸出包含兩個部分：
第一部分：全域 CLAUDE.md 本體（用獨立 code block 包住,方便整份複製）
- 繁體中文。
- 通用版,語言/框架無關,不分技術專區。
- 開頭簡短說明這是「個人全域開發準則,對所有專案生效」。
- 主體是分類好的準則條目。建議分類（依使用者實際情況取捨,不必硬湊滿）：
- 協作慣例：怎麼跟 AI agent 一起工作（動手前先說明計畫、改動範圍的約束、何時該停下來確認等）。這通常是最重要的一塊,排前面。
- 工作流程原則：寫程式的流程慣例（測試先行、小步提交、重構守則等）。
- 編碼通則：跨語言的編碼原則（相依注入哲學、錯誤處理態度、可讀性優先序等）——只寫真正語言無關的,具體到某框架 API 的不寫。
- 溝通與產出偏好：使用者希望 agent 怎麼回應、用什麼語言、產出文件的風格等。
- 每條準則用祈使句寫,精簡,讓 agent 能直接遵循。
- 標記「待使用者確認」的條目要明確標出,不要混在確定項裡。
第二部分：維護指南（一般 Markdown,不需 code block）
依 references/maintenance-guide-template.md 產出。核心要教使用者：
- 這份檔案放哪、怎麼讓 Claude Code 載入它（
~/.claude/CLAUDE.md 的位置與生效機制）。
- 怎麼判斷一條新準則該不該加：把「可遷移 vs 專案特有」關卡用使用者能自己操作的方式講清楚（那句核心判準 +「搬到不同框架還成立嗎」的自我提問）。
- 常見要修剪的訊號：發現某條準則在某些專案反而礙事 → 八成是專案特有混進來了,該移到專案層級 CLAUDE.md。
- 怎麼隨經驗增長持續擴充（每次踩到新雷、養成新慣例,就回來補一條）。
- 提醒「全域準則要克制」——條目過多會稀釋重點,寧精勿濫。
輸出品質檢查
送出最終結果前,確認：
- 是否使用繁體中文。
- CLAUDE.md 是否為通用版,沒有任何綁死單一專案的內容（資料庫品牌、具體 service/檔案名、特定路由等）。
- 每條準則是否都通過「搬到不同框架還成立嗎」的測試。
- 協作慣例是否被充分挖掘並放在顯眼位置（這是價值最高的一塊）。
- 萃取是否真的雙來源交叉,而非只憑訪談或只憑程式碼。
- 訪談與程式碼的落差是否已向使用者點明並釐清。
- 「待確認」條目是否明確標記、與確定項分開。
- 是否同時產出 CLAUDE.md 本體與維護指南。
- 維護指南是否教會使用者自己操作那道過濾關卡（讓這份檔案能長期自我演進)。
