ADR-005: 方法論與實務的分層（methodology / common-practices / module-practices）
ADR 編號: 005 狀態: 已接受 (Accepted) 決策日期: 2026-06-24 決策者: AppFuse Team + AI Assistant 範圍: docs-methodology（開發方法論自身的組織與同步）
摘要
AppFuse 的「方法論」一直被當成單一層：workspace 的 .claude/rules + .claude/skills，由 /methodology 零分歧下行到 fleet（見方法論規則 m-methodology-sync.md）。但全語料盤點（skill DRY 重構的 Inc 0）顯示，這個單一層其實混了三種性質不同的知識，且模組層的 .claude/（每個參考實作模組自帶的 rules/skills）完全在 /methodology 的治理之外——它隨 scaffold 一次性複製、之後無 re-sync 管道，正是 FU-19 對 workspace 層描述的 fork 漂移問題，只是發生在模組層、且內容夾帶 retarget 識別（業務詞、模組名、app 層類名），無法像 workspace 那樣零分歧覆蓋。
本 ADR 把這個結構顯性化為三個概念層（methodology / common-practices / module-practices）疊在兩個同步機制（workspace=/methodology、模組=/practices）之上，並定下四條原則。本 ADR 只定模型與原則；/practices skill 的實作細節 defer 到後續階段（比照 /methodology：phase-1 ADR 定模型 → phase-2 實作）。
背景 (Context)
問題陳述
/methodology 的 canonical 命名空間是 workspace 層 .claude/rules/*.md + .claude/skills/**。盤點此語料時發現兩件事：
-
workspace 層內混了兩種知識：多數 rule 是「換任何模組型別都成立」的流程/meta（如
m-doc-version、m-change-management、m-skill-format）；但m-web-common/m-server-common/m-mockup-boundary其實是綁某模組型別的實作慣例（daisyUI/i18n、server 設計指南檢索、mock 邊界），只是因為被跨模組 skill 消費、且為該型別所有實例共用，才住在 workspace。 -
模組層
.claude/不在任何同步治理內：每個參考實作模組（app-server、app-office-mockup等）自帶.claude/rules（如 server 的11-java、12-controller-service、17-us-development）與模組操作型 skill（remove-multi-tenancy、env-config）。這些隨/scaffold-module的cp -r複製到下游、之後框架的改進無 re-sync 管道。且其內容夾帶 retarget 識別，無法零分歧覆蓋。
核心張力
/methodology（FU-19 的成果）解決了 workspace 層的 fleet 漂移：canonical 零分歧下行、輕量 reflow 上行。但它的命名空間刻意只到 workspace——模組層 .claude/ 落在治理外，重演同一個「scaffold 一次性快照、之後各自演化」的漂移，只是：
- 無法套同一招：workspace canonical 已中性化（見
m-methodology-hygiene.md），可暴力覆蓋；模組 practices 夾帶花店業務詞、app-office模組名、AuditableTenantEntity等 app 層類名，覆蓋會把參考實作重新注入已 retarget 乾淨的下游。 - mapping 不同：workspace 是「一 repo 一個
.claude/」一對一；模組層是「框架單一app-{type}→ 下游 N 個同型別模組」按 type 一對多。
既有機制的對位
| 機制 | 管什麼 | 與本 ADR 的關係 |
|---|---|---|
m-methodology-sync.md / /methodology | workspace 方法論的 fleet 同步 | 本 ADR 的 Tier 1/2 同步機制；Tier 3 需新對應物 |
m-reference-code.md（@reference-surface） | 下游業務碼（domain surface）的 retarget 標記 | Tier 3 的 retarget 敏感性與其同源——模組 practices 像碼一樣需 per-project retarget |
m-methodology-hygiene.md | 方法論 rules/skills 的 primitive vs convention 引用紀律 | 本 ADR 將其適用面擴張到 practices |
m-skill-execution.md | skill 的「定義位置 vs 執行位置」二維 | 本 ADR 的三層定位與其「方法論 skill vs 模組操作型 skill」二分一致、予以概念命名 |
決策 (Decision)
三個概念層、兩個同步機制
同步是二元的（workspace 走
/methodology、模組走/practices），對齊「方法論 vs 實務」的直覺二分；三層是概念標籤——Tier 1 與 Tier 2 都住 workspace、都走/methodology，差別只在 hygiene 界線（模組無關 vs 型別共用）。
| 概念層 | 住哪 | 同步機制 | 判準 |
|---|---|---|---|
| Tier 1 — methodology | workspace .claude/ | /methodology（零分歧） | 「換任何模組型別都成立」（流程／meta） |
| Tier 2 — common practices | workspace .claude/ | /methodology（同上） | 「綁某模組_型別_、但該型別所有實例共用」（m-web-common / m-server-common / m-mockup-boundary） |
| Tier 3 — module practices | 模組 {module}/.claude/ | /practices（新，待實作） | 「綁單一模組（及其 scaffold 後代）」 |
D-A：common practices 留在 workspace（不搬模組）
Tier 2 的 -common 規則不下移到模組層。理由：
- 它們綁「型別」而非「單一模組」，型別有多個實例（mockup + web + ...），沒有單一模組家可放。
- 它們本就該被所有下游一致取得，現以
/methodology同步是正確的——下移反而打破一致同步。
因此 Tier 1 與 Tier 2 共用 workspace 位置與 /methodology 機制；分層是概念與 hygiene 上的區別，不是位置或機制的區別。無檔案需要搬移。
D-B：hygiene 擴張到 practices
m-methodology-hygiene.md 的「primitive vs convention」紀律從「只管 workspace rules/skills」擴張涵蓋 practices：
- Tier 2（common practices）：可直接引用該型別的框架 primitive（如 web 的
@appfuse/appfuse-web元件、server 的TenantContext／TenantAwareEntity）；須抽象化參考實作 convention（app 層類名、業務實體、模組名）。 - Tier 3（module practices）：與
@reference-surface同源——夾帶來源領域識別的部分屬 retarget 敏感，須 per-project 重做，不可零分歧覆蓋。
D-C：/practices 採 retarget-aware 同步（方向定、細節 defer）
模組層 practices 的同步機制方向：
- 中性的框架使用慣例（如
11-java、12-controller-service——無業務識別）→ 可按 type 同步（框架app-{type}/.claude→ 下游 N 個同型別模組）。 - 夾帶參考實作識別的部分（業務舉例、模組名、app 層類名）→ per-project 保留，比照
@reference-surface由團隊 retarget，不被覆蓋。
細節機制 defer：精確的 type 配對、中性／參考味的切分判準、reflow、安全網等，留待後續 phase 設計與實作 /practices skill（比照 /methodology 的 phase-1 ADR → phase-2 實作節奏）。
後續進展（phase-2 已落地，2026-06-24）：
/practicesskill 與規則m-practices-sync.md已實作。切分機制採顯式 manifest——框架各app-{type}/.claude/practices.json以local清單宣告 per-project 例外（如 web-mockup 的rules/m-design-language.md），其餘按 type 零分歧下行；worked-example 識別（sales/customer/order等）隨 canonical 同步（依 hygiene 的 worked-example 例外），不切為 per-project。type 配對以下游project.json的modules[].type為 SoT。
D-D：框架模組的 .claude/ 不進 /practices
框架模組（appfuse-web、appfuse-server、appfuse-docs 等）的 .claude/ 是框架貢獻者指南（paths: 綁 lib/**），經 npm/Maven 消費、下游無此目錄，故為單一副本、無 fleet 漂移問題，排除於 /practices 之外。
後果 (Consequences)
正面
- 概念清晰：每份 rule/skill 可明確歸位（Tier 1/2/3），消除「這到底是方法論還是某模組的事」的模糊。
- hygiene 全覆蓋：practices 也受 primitive-vs-convention 約束，堵住「型別慣例洩漏參考實作」的縫。
- 模組漂移有路可走：Tier 3 從「無治理」變成「有方向的待實作機制」，FU-19 的根因在模組層也有了對應解法。
- 對齊既有直覺：二元同步機制完全對齊「方法論 vs 實務」的二分，不增加心智負擔。
成本／風險
/practices尚未實作：本 ADR 只定模型；模組層漂移在/practices落地前仍需靠 re-scaffold 或手動處理。- Tier 1 vs Tier 2 界線需判斷：少數 rule 介於「模組無關」與「型別共用」之間（如
m-ide-config涉 Java 模組的 IDE 設定），歸層需個案判讀；判準句為「換到另一個模組_型別_還成立嗎？成立 → Tier 1；只對某型別成立 → Tier 2」。 - retarget-aware 同步較複雜：Tier 3 非零分歧，
/practices設計比/methodology難（須切中性／參考味），這是 defer 的主因。
範圍邊界（本 ADR 不做的事）
- 不實作
/practicesskill（D-C defer）。 - 不搬移任何
-common檔（D-A：留 workspace）。 - 不立即重構模組層 practices 內容（Tier 3 的 DRY/hygiene pass 為後續工作）。
替代方案 (Alternatives)
| 方案 | 為何不採 |
|---|---|
| common practices 下移到模組層（純二分，無 Tier 2） | 型別多實例、無單一模組家；且打破「所有下游一致取得」的同步 |
/practices 採零分歧覆蓋（複用 /methodology 機制） | 會把參考實作（花店業務詞/模組名/app 層類名）重新注入已 retarget 的下游，違反 m-reference-code / m-methodology-hygiene |
| 不分層、維持單一 workspace 方法論 | 模組層 .claude/ 永遠在治理外、持續漂移；且「方法論 vs 型別實務」混淆無解 |
本 ADR 直接完整 spec /practices | 模組 practices 的 retarget-aware 切分需在真檔上驗證才定得準（同 /methodology 的兩階段教訓）；硬定易錯 |
與其他文件的關係
| 文件 | 關係 |
|---|---|
m-methodology-sync.md | Tier 1/2 的同步機制（/methodology）；Tier 3 待建的 /practices 為其模組層對應物 |
m-methodology-hygiene.md | 本 ADR D-B 擴張其適用面到 practices（須同步修訂該規則） |
m-skill-execution.md | 其「定義位置 vs 執行位置」二維、「方法論 skill vs 模組操作型 skill」二分，與本 ADR 三層一致（須補三層概念定位） |
m-reference-code.md | Tier 3 的 retarget 敏感性與 @reference-surface 同源 |
| ADR-003 / ADR-004 | 同為方法論自身演進的 ADR（headless 軌、租戶中性化）；本 ADR 處理方法論的分層與同步 |
FU-19 / methodology-review-notes.md | /methodology（workspace 層同步）的後續——本 ADR 把同一問題延伸到模組層 |