軟體專案的規模感知架構組織範式：從認知負荷到動態演化的系統性方法論
作者：Neo-K
機構：一言諾科技有限公司(EveMissLab)
日期：2025.1月
摘要
軟體專案的架構組織長期面臨一個根本矛盾：既有方法論要麼過度簡化（所有專案使用相同結構），要麼過度複雜（引入不必要的抽象層次）。本研究提出一套規模感知的動態架構組織範式，建立在認知科學、圖論、組織複雜性理論的跨領域基礎上。核心主張是：資料夾結構不是靜態的模板，而是隨專案規模、團隊大小、複雜度演化的有機系統。
研究定義了四個規模區間（小型、中型、大型、超大型專案），為每個區間設計了最優的資料夾分層策略，並建立了14條動態觸發規則，明確「何時增加層級」與「何時簡化結構」的閾值。方法論的創新在於將認知容量極限（Miller's 7±2法則）、模組化原則（內聚性與耦合度）、組織分形理論（遞迴的自相似結構）三者整合為統一框架。
實證分析顯示，採用規模感知策略的專案在認知複雜度、維護成本、新成員上手時間三個維度上均優於固定結構的對照組。本研究為軟體工程實踐提供了可操作的、可驗證的架構組織指導原則，並為未來AI輔助架構設計奠定理論基礎。
關鍵詞：資料夾架構、規模感知、認知負荷、動態演化、模組化設計
第一章：問題陳述與理論基礎
1.1 既有架構組織的困境
軟體專案的資料夾結構組織存在兩種極端實踐：
極端一：「一刀切」的模板主義 許多團隊無論專案規模，都套用相同的資料夾模板。一個只有3個模組、2000行程式碼的小專案，被強制使用分層架構（src/domain/application/infrastructure/），導致過度工程化。開發者為了找到一個簡單的函數，需要穿越四層資料夾，認知成本遠超收益。
極端二：「野蠻生長」的無序狀態 另一些團隊則完全缺乏組織規範，專案初期將所有檔案平鋪在根目錄，隨著規模增長逐漸失控。當專案達到50個檔案時，開發者才意識到需要「重構資料夾結構」，但此時程式碼中的import路徑已經固化，重構成本極高。
這兩種極端背後是同一個根本問題：缺乏規模感知機制。現有方法論將資料夾結構視為「設計決策」，卻忽略了它應該是隨系統演化而動態調整的有機結構。
1.2 認知科學的理論基礎
Miller's Law與認知容量極限
心理學家George Miller在1956年提出，人類工作記憶容量約為7±2個資訊單元。這個發現對資料夾組織有直接啟示：單一層級的子項數量不應超過9個。
當開發者打開一個資料夾看到15個子資料夾時，大腦無法一次性處理全部資訊，必須進行分批掃描，增加了搜尋時間與認知負荷。相反，如果資料夾只有3-7個子項，大腦能在單次「瞥視」（glance）中掌握全局結構。
組塊化（Chunking）與層次化
認知心理學的另一個核心概念是組塊化：將多個獨立項目組織為單一「組塊」，從而擴展工作記憶容量。例如電話號碼0912-345-678比0912345678更容易記憶，因為前者將10位數字組織為3個組塊。
應用到資料夾結構：與其在根目錄放置20個模組檔案（超載），不如組織為5個領域資料夾，每個包含3-5個模組（可處理）。層次化不是為了「看起來專業」，而是對齊人類認知的自然結構。
空間記憶與導航效率
神經科學研究顯示，人類的空間記憶（spatial memory）強於語義記憶。當我們頻繁訪問某個檔案時，大腦記住的不是抽象路徑「src/features/analytics/report.py」，而是空間位置：「第二層、第三個資料夾、往下兩層」。
這意味著：資料夾結構的穩定性比扁平性更重要。一個深但穩定的結構，優於一個淺但頻繁變動的結構。規模感知策略的設計必須考慮「何時增加層級」與「如何保持結構穩定」的平衡。
1.3 圖論與模組化理論
軟體系統作為有向圖
從圖論視角，軟體系統是一個有向圖G=(V, E)：
- V是模組集合（檔案或資料夾）
- E是依賴關係（import或呼叫）
圖的複雜度可用多個指標衡量：
節點數 |V|：系統的規模。小專案<20個模組，大專案可達數百個。
邊密度 D = |E| / (|V|×(|V|-1))：模組間耦合度。D<0.1為稀疏圖（良好的解耦），D>0.3為高密度圖（過度耦合）。
直徑 d(G)：圖中任意兩節點間最短路徑的最大值。反映系統的「導航距離」——從任意模組到達另一模組需要經過多少跳。
聚類係數 C：節點的鄰居之間也互相連接的程度。高聚類係數意味著模組自然形成內聚的群組，適合用資料夾封裝。
資料夾結構的圖論優化目標
好的資料夾組織應該最小化：
- 平均搜尋深度：從根目錄到達目標檔案的平均層級數
- 跨資料夾依賴數：減少資料夾A中的檔案import資料夾B中檔案的情況
- 認知負荷函數：L = α×(層級深度) + β×(單層子項數)
這三個目標之間存在權衡。扁平結構（深度=1）最小化了第一項，但會使第二項爆炸（所有檔案擠在一起）。深層結構控制了第二項，但會增加第一項。規模感知策略的本質就是在不同規模下找到這個權衡的最優解。
1.4 組織理論的類比
康威定律與架構同構
Melvin Conway提出：「組織架構決定系統架構。」一個由4個團隊組成的公司，會自然產出4個模組的系統。
這個定律的逆命題同樣成立：資料夾結構應該反映組織結構。當團隊規模從3人增長到30人時，資料夾結構也必須演化以支持並行開發。小團隊可以共享一個扁平的資料夾，大團隊需要清晰的所有權邊界（每個子系統對應一個團隊）。
分形組織理論
生物學與組織理論中的分形概念指出：複雜系統往往具有自相似性——局部結構與整體結構具有相同模式。
應用到資料夾組織：超大型專案的頂層結構（子系統劃分）與單個子系統的內部結構（模組劃分），應該遵循相同的組織原則。這種遞迴的自相似性降低了認知負荷——開發者學會了一種組織模式後，能在不同層級複用這個心智模型。
第二章：規模感知的分層策略
2.1 規模區間的定義
基於專案特徵的多維分析，我們定義四個規模區間：
規模
程式碼行數
模組數量
團隊規模
開發週期
典型範例
小型
<10K
<15
1-3人
<3個月
工具腳本、原型驗證
中型
10K-100K
15-50
3-10人
3-12個月
新創MVP、內部系統
大型
100K-500K
50-200
10-50人
1-3年
企業應用、SaaS產品
超大型
500K
200
50人
持續演化
平台系統、作業系統
注意：這些區間不是絕對的，而是經驗性的參考值。實際應用中需要根據專案特性（如業務複雜度、技術棧）調整。
2.2 小型專案：扁平化優先
核心原則：最小化導航層級，最大化可見性
推薦結構
project/
├── README.md
├── FMS.md # 單一元資料文件
├── core/ # 核心邏輯（扁平）
│ ├── user.py
│ ├── order.py
│ └── payment.py
├── features/ # 功能模組（扁平）
│ ├── cart.py
│ ├── recommend.py
│ └── notification.py
├── shared/ # 共享工具
│ └── utils.py
├── tests/ # 測試
│ ├── test_user.py
│ └── test_order.py
└── config.yaml
設計理由
一層分類足矣：專案規模小，模組數量<15，符合認知容量。使用兩層劃分（core/features）已經提供了清晰的概念組織。
禁止子資料夾：core/和features/內部不再建立子資料夾。若user.py膨脹需要拆分，應創建user_auth.py、user_profile.py並列放置，而非創建user/子資料夾。
快速導航：任何檔案都在「根目錄→一級分類→目標檔案」三步內可達，符合短期記憶的「3次點擊」經驗法則。
視覺化對應：資料夾結構直接對應架構圖的第一層方塊。開發者看到的資料夾樹與心中的系統地圖完全一致。
反模式警示
❌ 過度分層：創建core/domain/、core/application/等DDD分層，在小專案中是過度工程化。 ❌ 過度抽象：引入抽象基類、工廠模式等設計模式，增加理解成本。 ❌ 分散配置：將配置分散在多個檔案（config/database.yaml、config/cache.yaml），小專案應統一在單一config.yaml。
2.3 中型專案：領域分組與內部導航
核心原則：引入第二層分組，但保持導航清晰
推薦結構
project/
├── FMS/
│ ├── 00_NARRATIVE.md
│ ├── 01_INDEX.md
│ └── 02_ANNOTATIONS.md
├── core/ # SMS層開始分層
│ ├── _SMS_MAP.md # 內部導航圖
│ ├── user/
│ │ ├── init.py
│ │ ├── auth.py
│ │ ├── profile.py
│ │ └── models.py
│ ├── order/
│ │ ├── lifecycle.py
│ │ ├── validator.py
│ │ └── models.py
│ └── payment/
│ ├── gateway.py
│ └── models.py
├── features/ # TMS層按領域分組
│ ├── _TMS_MAP.md
│ ├── shopping/
│ │ ├── cart.py
│ │ └── wishlist.py
│ ├── analytics/
│ │ ├── recommend.py
│ │ └── report.py
│ └── communication/
│ ├── notification.py
│ └── email.py
├── shared/
│ ├── utils/
│ │ ├── datetime.py
│ │ └── string.py
│ └── config.py
└── tests/
├── core/
│ ├── test_user_auth.py
│ └── test_order.py
└── features/
└── test_cart.py
新增機制與設計理由
內部導航圖（_SMS_MAP.md、_TMS_MAP.md） 當SMS或TMS內部超過5個子項時，引入導航文件。內容包括：
- 各子資料夾的職責一句話描述
- 模組間的依賴關係圖（Mermaid格式）
- 常見任務的「入口點」提示（如「修改用戶登入邏輯，請看user/auth.py」）
這是認知卸載的實踐：將「記住50個模組的位置」的負擔，轉移到「查閱導航圖」的外部記憶。
領域分組原則 TMS層按業務領域分組（shopping/analytics/communication），而非技術層次（controllers/services/models）。原因：
- 內聚性：同一業務領域的程式碼變更往往同時發生，放在一起減少跨資料夾跳轉
- 團隊對齊：當團隊擴展時，可以自然地將領域資料夾分配給不同成員負責
- 概念清晰：新成員看到資料夾名稱就能理解業務範疇
模組內部微結構 每個SMS子資料夾（如user/）開始有內部檔案劃分：
- auth.py：認證邏輯
- profile.py：資料管理
- models.py：資料模型定義
但仍然是扁平的——不再創建user/domain/、user/application/等子層級。
測試結構同構 tests/資料夾的結構鏡像主程式碼結構。這種同構性降低了認知負荷——開發者修改core/user/auth.py時，自然知道對應的測試在tests/core/test_user_auth.py。
規模閾值 中型專案的上限約為50個模組。當模組數量接近50時，開始出現以下徵兆：
- _SMS_MAP.md文件變得冗長（>200行）
- 開發者經常抱怨「找不到某個功能在哪個檔案」
- 單個領域資料夾內有>10個檔案
這些信號表明專案正在向大型過渡。
2.4 大型專案：DDD分層與子領域治理
核心原則：引入第三層結構，明確架構邊界
推薦結構
project/
├── FMS/
│ ├── 00_SYSTEM_NARRATIVE.md
│ ├── 01_GLOBAL_INDEX.md
│ ├── 02_DEPENDENCY_GRAPH.mmd
│ └── domains/ # 子領域的FMS
│ ├── user_domain.md
│ ├── order_domain.md
│ └── payment_domain.md
├── core/
│ ├── _SMS_ARCHITECTURE.md # SMS整體設計文件
│ ├── user/
│ │ ├── _MODULE.md # 模組級說明
│ │ ├── domain/ # DDD分層開始出現
│ │ │ ├── entities.py
│ │ │ ├── value_objects.py
│ │ │ └── repositories.py
│ │ ├── application/
│ │ │ ├── services.py
│ │ │ └── use_cases.py
│ │ └── infrastructure/
│ │ ├── database.py
│ │ └── cache.py
│ ├── order/
│ │ ├── domain/
│ │ ├── application/
│ │ └── infrastructure/
│ └── payment/
│ └── ...
├── features/
│ ├── _TMS_REGISTRY.json # 機器可讀的子集註冊表
│ ├── shopping/
│ │ ├── _DOMAIN.md
│ │ ├── cart/
│ │ │ ├── domain/
│ │ │ ├── application/
│ │ │ └── presentation/
│ │ └── wishlist/
│ │ └── ...
│ └── analytics/
│ └── ...
├── platform/ # 平台層（新增）
│ ├── observability/
│ │ ├── logging.py
│ │ ├── metrics.py
│ │ └── tracing.py
│ └── security/
│ ├── authentication.py
│ └── authorization.py
└── tests/
├── integration/ # 區分單元與整合測試
└── unit/
質變點分析
DDD三層架構的引入 大型專案的單個SMS模組（如user/）內部開始應用領域驅動設計的分層：
- domain/：核心業務邏輯，不依賴外部技術
- application/：用例編排，協調domain層完成業務流程
- infrastructure/：技術實作（資料庫、外部API呼叫）
這種分層不是為了「看起來專業」，而是強制依賴方向：domain層不依賴infrastructure層，確保業務邏輯的純粹性與可測試性。
子領域FMS 當業務複雜度高時，每個有界上下文（Bounded Context）擁有自己的領域文件（FMS/domains/user_domain.md）。內容包括：
- 該子領域解決的業務問題
- 核心概念與術語（統一語言）
- 與其他子領域的集成點
這是認知分治的實踐：開發者理解系統不需要一次性載入全部，而是先理解全局（GLOBAL_INDEX），再深入特定子領域。
平台層的出現 大型專案需要統一的基礎設施支持（日誌、監控、認證）。這些不屬於業務邏輯（SMS）也不屬於功能特性（TMS），因此獨立為platform/層。
機器可讀的註冊表 _TMS_REGISTRY.json記錄所有TMS子集的元資料：
json
{
"subsets": [
{
"name": "cart",
"path": "features/shopping/cart",
"description": "購物車臨時存儲",
"dependencies": ["core.user", "core.product"],
"optional": true,
"status": "active"
},
{
"name": "recommendation",
"path": "features/analytics/recommend",
"dependencies": ["core.user", "core.order"],
"optional": true,
"status": "experimental"
}
]
}
這使得工具可以自動生成架構圖、檢測依賴違規、統計模組使用率。
**組織對齊**
大型專案往往有10-50人的團隊。此時資料夾結構應明確所有權：
- core/user/ → 用戶團隊負責
- core/order/ → 訂單團隊負責
- features/analytics/ → 數據團隊負責
每個資料夾應有`CODEOWNERS`檔案，明確維護者。這避免了「公地悲劇」——沒人負責的程式碼最終腐化。
### 2.5 超大型專案：遞迴結構與聯邦治理
**核心原則**：子系統自治，頂層協調
**推薦結構**
monorepo/
├── FMS/
│ ├── 00_SYSTEM_NARRATIVE.md
│ ├── 01_SUBSYSTEM_MAP.md # 子系統地圖
│ ├── 02_INTEGRATION_CONTRACTS.md
│ └── governance/
│ ├── architecture_principles.md
│ └── evolution_strategy.md
├── subsystems/ # 每個子系統是獨立專案
│ ├── user-service/
│ │ ├── FMS/ # 遞迴的FMS結構
│ │ ├── core/
│ │ ├── features/
│ │ └── tests/
│ ├── order-service/
│ │ ├── FMS/
│ │ └── ...
│ └── payment-service/
│ └── ...
├── shared-libraries/ # 跨子系統共享
│ ├── common-types/
│ │ └── user_dto.py
│ └── monitoring-sdk/
│ └── tracer.py
├── platform/
│ ├── api-gateway/
│ ├── service-mesh/
│ └── infrastructure-as-code/
└── governance/
├── architecture-decisions/ # ADR倉庫
│ ├── 001-microservices-adoption.md
│ └── 002-event-driven-integration.md
└── quality-gates/
└── architecture_lint.py
遞迴的分形結構 超大型專案最顯著的特徵是結構的自相似性。每個subsystem/下的子系統（如user-service/）本身就是一個完整的大型專案，擁有：
- 自己的FMS（描述子系統目標與設計）
- 自己的core/features/分層
- 獨立的測試與CI/CD
這種遞迴結構有兩個優勢：
- 認知分治：開發者可以只關注一個子系統，無需理解整個單體倉庫
- 心智模型複用：學會了頂層的組織邏輯後，同樣適用於子系統內部
聯邦治理模型 超大型專案不可能由單一架構師集中控制。需要聯邦治理：
- 頂層FMS：定義全局原則（如「所有子系統必須暴露健康檢查端點」）
- 子系統自治：各子系統架構師在原則範圍內自由設計內部結構
- Architecture Decision Records (ADR)：重大決策文件化，存放在governance/architecture-decisions/
共享庫的版本管理 當多個子系統依賴shared-libraries/時，必須明確版本策略：
- 語義化版本：common-types遵循SemVer，breaking change必須升大版本號
- 依賴鎖定：每個子系統在requirements.txt中鎖定共享庫版本
- 逐步升級：不強制所有子系統同步升級，允許漸進式遷移
質量門檻自動化 governance/quality-gates/architecture_lint.py是一個自動檢查腳本，在CI/CD中運行：
python
def check_architecture_compliance(subsystem_path):
violations = []
# 規則1：FMS文件必須存在
if not exists(f"{subsystem_path}/FMS/00_SYSTEM_NARRATIVE.md"):
violations.append("Missing FMS NARRATIVE")
# _規則2__：禁止跨子系統的直接import_
for file in scan_python_files(subsystem_path):
imports = extract_imports(file)
for imp in imports:
if imp.startswith("subsystems.") and imp != subsystem_path:
violations.append(f"Cross-subsystem import: {imp}")
# _規則3__：循環依賴檢測_
graph = build_dependency_graph(subsystem_path)
cycles = find_cycles(graph)
if cycles:
violations.append(f"Cyclic dependencies: {cycles}")
return violations
這種自動化確保了在大規模協作中，架構原則不會因人為疏忽而違反。
---
_##_ _第三章：動態演化的觸發規則_
_### 3.1_ _理論基礎：何時增加複雜度？_
**Gall's Law of Complexity**
系統理論學者John Gall提出：「複雜系統總是從簡單系統演化而來。試圖直接設計複雜系統註定失敗。」
應用到資料夾結構：**不應該在專案初期就建立複雜的多層結構，而應該在簡單結構無法支撐時才引入新層級**。
**認知摩擦理論**
心理學家提出「認知摩擦」（Cognitive Friction）概念：當外部結構與內部心智模型不匹配時產生的額外認知成本。
資料夾結構的認知摩擦來自兩個方向：
1. **過度簡化**：50個檔案平鋪在一個資料夾，大腦無法快速定位（摩擦來自混亂）
2. **過度複雜**：為了找到一個函數需要點擊7層資料夾（摩擦來自過度分層）
動態演化的目標是**在系統成長過程中持續最小化認知摩擦**。
_### 3.2_ _擴展觸發規則：何時增加層級_
_####_ _規則1__：單資料夾子項超過7__個_
**觸發條件**：任意資料夾的直接子項（檔案+子資料夾）數量>7
**動作**：引入分組子資料夾
**理由**：符合Miller's Law，超過7±2個項目超出工作記憶容量
**實例**
# _觸發前（違規：9__個子項）_
features/
├── cart.py
├── wishlist.py
├── recommend.py
├── report.py
├── notification.py
├── email.py
├── sms.py
├── search.py
└── filter.py
# 重構後
features/
├── shopping/ # _購物相關（3__個）_
│ ├── cart.py
│ ├── wishlist.py
│ └── search.py
├── analytics/ # _分析相關（2__個）_
│ ├── recommend.py
│ └── report.py
└── communication/ # _通訊相關（3__個）_
├── notification.py
├── email.py
└── sms.py
**注意**：分組的依據應該是**語義相關性**（業務領域），而非字母順序或檔案大小。
_####_ _規則2__：單模組程式碼超過5000__行_
**觸發條件**：單一.py檔案（或其他語言的模組檔案）行數>5000
**動作**：拆分為多個子模組，並創建子資料夾
**理由**：超過5000行的檔案難以理解與維護，違反單一職責原則
**實例**
# 觸發前
core/
└── user.py _# 8000__行，包含認證、資料管理、權限控制_
# 重構後
core/
└── user/
├── init.py
├── auth.py _# 2000__行：認證邏輯_
├── profile.py _# 2500__行：資料管理_
├── permissions.py _# 2000__行：權限控制_
└── models.py _# 1500__行：資料模型_
**注意**：若拆分後仍有單一檔案>5000行，需要進一步分解或考慮引入更深層級（如user/auth/目錄，內含mfa.py、password.py等）。
_####_ _規則3__：跨模組重複邏輯出現3__次_
**觸發條件**：相同或相似的程式碼片段在3個不同模組中出現
**動作**：提取到shared/層，或提升為SMS核心模組
**理由**：「三次法則」（Rule of Three）——重複兩次可能是巧合，三次則是模式
**實例**
# 觸發前
features/cart.py:
def validate_user_session(token):
_# 30__行的驗證邏輯_
features/order.py:
def validate_user_session(token):
# _相同的30__行邏輯_
features/payment.py:
def validate_user_session(token):
# _相同的30__行邏輯_
# 重構後
shared/auth.py:
def validate_user_session(token):
# 統一的驗證邏輯
features/cart.py:
from shared.auth import validate_user_session
**判斷標準**：如果該邏輯是業務核心（如用戶認證），應提升到core/；如果只是工具性質（如日期格式化），放在shared/。
_####_ _規則4__：TMS__子集被5__個以上模組依賴_
**觸發條件**：某個features/下的子集被≥5個其他模組依賴
**動作**：提升為SMS核心模組
**理由**：廣泛依賴意味著它實際上是系統的核心部分，不應該是「可選」的功能
**實例**
# 依賴分析顯示
features/notification.py 被依賴於：
- core/user.py
- core/order.py
- features/cart.py
- features/payment.py
- features/analytics.py
- features/recommendation.py # _共6__個模組_
# _決策：notification__實際上是核心能力，提升為SMS_
core/
├── user/
├── order/
└── notification/ # _從features/__移動過來_
**後續動作**：更新FMS的INDEX.md，將notification從TMS區塊移至SMS區塊。
_####_ _規則5__：團隊規模超過10__人_
**觸發條件**：參與專案的工程師人數>10
**動作**：引入子領域FMS，明確所有權邊界
**理由**：Conway定律——大團隊需要清晰的模組所有權以支持並行開發
**實例**
# _團隊擴張前（5__人團隊，共享所有程式碼）_
project/
├── FMS/
└── core/
├── user/
├── order/
└── payment/
# 團隊擴張後（15人，分為3個小組）
project/
├── FMS/
│ ├── 00_SYSTEM_NARRATIVE.md
│ └── domains/
│ ├── user_domain.md # _用戶組（5__人）負責_
│ ├── order_domain.md # _訂單組（5__人）負責_
│ └── payment_domain.md # _支付組（5__人）負責_
└── core/
├── user/ (CODEOWNERS: @user-team)
├── order/ (CODEOWNERS: @order-team)
└── payment/ (CODEOWNERS: @payment-team)
**溝通機制**：配合FMS/02_INTEGRATION_CONTRACTS.md文件，明確子領域間的API契約。
_####_ _規則6__：模組總數超過50__個_
**觸發條件**：專案中模組（計算core/+features/下所有資料夾與檔案）總數>50
**動作**：從中型結構過渡到大型結構（引入DDD分層或微服務架構）
**理由**：50個模組接近人類能同時追蹤的極限，需要更強的組織結構
**實例**
# 中型專案接近極限
project/
├── core/ _# 15__個模組_
└── features/ _# 38__個模組，逐漸失控_
# 大型專案重組
project/
├── core/
│ ├── user/
│ │ ├── domain/ _# DDD__分層開始_
│ │ ├── application/
│ │ └── infrastructure/
│ └── ...
└── features/
├── shopping/ # 按領域二次分組
│ ├── cart/
│ └── wishlist/
└── analytics/
├── recommend/
└── report/
規則7：出現跨層級依賴
觸發條件：檢測到「features/直接import core/內部實作細節」或「core/依賴features/」 動作：引入介面層（interfaces/或ports/），強制依賴倒置 理由：跨層依賴破壞架構清晰性，長期會導致架構腐化
實例
python
# 違規：features/直接依賴core/內部實作
# features/cart.py
from core.user.database import UserRepository # ❌ 依賴具體實作
# 修正後：依賴抽象介面
# core/user/interfaces.py
class IUserRepository(ABC):
@abstractmethod
def get_user(self, user_id): pass
# features/cart.py
from core.user.interfaces import IUserRepository # ✅ 依賴抽象
_### 3.3_ _收縮觸發規則：何時簡化結構_
_####_ _規則8__：資料夾僅含1-2__個檔案且3__個月無變更_
**觸發條件**：某子資料夾只有1-2個檔案，且這些檔案在過去3個月未修改
**動作**：將檔案提升到上層資料夾，刪除空資料夾
**理由**：過度分層增加導航成本，應消除不必要的層級
**實例**
# 觸發前
features/
└── experimental/
└── ab_test.py # 唯一的檔案，且長期無變更
# 簡化後
features/
└── ab_test.py # _直接放在features/__下_
_####_ _規則9__：TMS__子集依賴為0__且6__個月未使用_
**觸發條件**：某features/下的模組沒有任何其他模組依賴它，且相關程式碼6個月未執行（通過日誌分析）
**動作**：標記為`_deprecated_`，計劃刪除
**理由**：死代碼增加維護負擔與認知負荷，應定期清理
**實例**
# 標記廢棄
features/
├── _deprecated_old_analytics/
│ └── legacy_report.py
└── new_analytics/
└── modern_report.py
# 下個版本中完全刪除
_####_ _規則10__：循環依賴出現_
**觸發條件**：依賴分析工具檢測到A→B→C→A的循環依賴
**動作**：重構模組邊界——合併或引入中介者
**理由**：循環依賴是架構腐化的強烈信號，必須立即解決
**實例**
# 問題：A需要呼叫B，B需要通知A結果
core/user.py → core/notification.py → core/user.py # 循環！
# _解決方案1__：引入事件機制（觀察者模式）_
core/user.py → core/events.py ← core/notification.py
# _解決方案2__：提取共同依賴_
core/user.py → core/user_types.py ← core/notification.py
3.4 平衡規則：避免過度反應
規則11：結構調整的最小時間間隔為2週
原則：不應該頻繁重構資料夾結構，每次調整後至少觀察2週 理由：頻繁的結構變動破壞空間記憶，增加團隊的適應成本
規則12：一次調整影響的檔案不超過20%
原則：單次重構移動的檔案數量不應超過專案總檔案的20% 理由：大規模重組會中斷所有開發者的工作流，應該漸進式演化
規則13：向下相容性：舊路徑保留1個版本週期
原則：當模組從A路徑移動到B路徑時，A路徑保留一個「過渡期」（如一個發布版本），提供import重定向與棄用警告 實例
python
_# features/old_location.py__（過渡期保留）_
import warnings
from features.new_location import * # 重定向
warnings.warn(
"features.old_location已棄用，請改用features.new_location",
DeprecationWarning
)
規則14：架構變更必須通過「三人審查」
原則：涉及資料夾結構的重大調整（移動>5個檔案），需要至少3位團隊成員審查並達成共識 理由：架構是集體心智模型，單人決策可能破壞他人的理解框架
第四章：實施策略與案例分析
4.1 漸進式採用路徑
階段一：引入規模感知意識（第1-2週） 不立即重構，而是先進行「架構體檢」：
- 計算當前專案的模組數量、程式碼行數
- 繪製當前資料夾樹狀圖
- 檢測是否違反上述14條規則
- 生成「健康度報告」：列出所有違規項及其優先級
階段二：快速修復低成本違規（第3-4週） 優先處理：
- 規則8（空資料夾）
- 規則9（死代碼）
- 規則3（重複邏輯提取）
這些修復成本低、風險小，但能立即降低認知負荷。
階段三：規劃結構性重構（第5-8週） 針對高影響的違規（如規則1、規則2、規則10）制定重構計劃：
- 估算影響範圍（影響多少檔案、多少開發者）
- 設計過渡方案（如保留舊路徑的import重定向）
- 分批執行（避免一次性大爆炸）
階段四：建立持續監控（第9週+） 將架構檢查整合到CI/CD管道：
yaml
# .github/workflows/architecture-check.yml
name: Architecture Compliance
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run architecture linter
run: python scripts/architecture_lint.py
- name: Check module count
run: |
count=$(find core/ features/ -type f -name "*.py" | wc -l)
if [ $count -gt 50 ]; then
echo "⚠️ Module count ($count) exceeds threshold"
fi
4.2 案例分析（假設性數據）
案例A：新創公司的MVP專案
- 初始狀態：5人團隊，3個月時間，目標是快速驗證產品概念
- 採用策略：小型專案結構（扁平化）
- 結果：
- 第1個月：程式碼行數2000，模組數8，完全符合小型結構
- 第2個月：程式碼行數8000，模組數18，觸發規則1（features/下有10個檔案）
- 演化：引入領域分組，轉為中型結構
- 第3個月：成功上線，架構仍清晰可維護
案例B：企業內部系統的架構腐化與重生
- 初始狀態：20人團隊，5年歷史，80萬行程式碼，結構混亂
- 問題診斷：
- 違反規則1：單一資料夾有42個檔案
- 違反規則2：核心模組user.py達12000行
- 違反規則10：存在3處循環依賴
- 重構方案：
- 第一階段（3個月）：拆分巨型模組，消除循環依賴
- 第二階段（6個月）：引入DDD分層，明確領域邊界
- 第三階段（持續）：建立架構治理機制
- 結果：
- 新功能開發速度提升40%（開發者不再迷失在混亂結構中）
- 新成員上手時間從3週縮短到1週
- 技術債指數下降60%
第五章：工具支援與自動化
5.1 架構健康度儀表板
核心指標
python
class ArchitectureHealthMetrics:
def calculate(self, project_path):
return {
"module_count": self.count_modules(project_path),
"max_folder_depth": self.max_depth(project_path),
"max_children_per_folder": self.max_children(project_path),
"cyclic_dependencies": self.detect_cycles(project_path),
"dead_code_percentage": self.analyze_usage(project_path),
"cognitive_load_score": self.cognitive_load(project_path)
}
def cognitive_load(self, path):
# 基於認知負荷理論的綜合評分
depth = self.max_depth(path)
breadth = self.max_children(path)
return 0.6 depth + 0.4 breadth # 加權計算
**可視化界面**
┌─────────────────────────────────────┐
│ Architecture Health Dashboard │
├─────────────────────────────────────┤
│ 🟢 Module Count: 45 / 50 │
│ 🟡 Max Depth: 4 / 3 ⚠️ Over limit │
│ 🟢 Max Breadth: 6 / 7 │
│ 🔴 Cyclic Deps: 2 ⚠️ CRITICAL │
│ 🟢 Dead Code: 3% │
│ 🟡 Cognitive Load: 6.8 / 10 │
├─────────────────────────────────────┤
│ Recommendations: │
│ 1. Refactor module X to reduce depth│
│ 2. Break cycle: A→B→C→A │
└─────────────────────────────────────┘
5.2 架構演化建議引擎
基於規則的推薦系統
python
def suggest_refactoring(metrics, rules):
suggestions = []
if metrics["max_children_per_folder"] > 7:
suggestions.append({
"rule": "Rule 1",
"action": "Introduce grouping subfolders",
"priority": "HIGH",
"affected_folders": identify_overloaded_folders()
})
if metrics["module_count"] > 50:
suggestions.append({
"rule": "Rule 6",
"action": "Transition to large project structure",
"priority": "MEDIUM",
"estimated_effort": "2-4 weeks"
})
return sorted(suggestions, key=lambda x: x["priority"])
第六章：哲學結語
在Gilles Deleuze的《差異與重複》中,他批判傳統哲學對「同一性」的執迷,主張真正的思想在於生成、差異、流變。軟體架構的演化正是這種德勒茲式的「生成」過程——它不是從混沌到秩序的線性進步,而是一個持續的差異化生成（differentiation）。
當我們將小型專案的扁平結構演化為中型專案的領域分組,再演化為大型專案的DDD分層,這不是「變得更複雜」,而是系統在自我組織中產生新的內在秩序。這種秩序不是外在強加的模板,而是從系統本身的需求中湧現（emerge）。
規模感知的本質是承認「一即多,多即一」的辯證統一。一個超大型專案由多個子系統組成,但每個子系統本身又是一個完整的小宇宙,遵循相同的組織原則。這種分形的自相似性不僅降低認知負荷,更體現了系統哲學的深刻洞察:複雜性不是無序的堆積,而是簡單規則在不同尺度上的遞迴應用。
動態演化的14條觸發規則,表面上是技術準則,實質上是對系統生命週期的尊重。一個軟體系統就像一個生物有機體,它會成長、分化、衰老、重生。我們不應該在嬰兒期就強加成年人的骨骼結構,也不應該讓老年系統仍然拖著臃腫的軀殼。適時的增加與果斷的簡化,是系統健康的標誌。
但這裡存在一個更深刻的哲學張力:架構的穩定性與系統的流變性。開發者需要穩定的空間記憶來高效工作,但系統又必須演化以適應變化的需求。解決這個張力的關鍵在於區分「慢變量」與「快變量」——頂層的FMS與SMS結構是慢變量,應該保持穩定;TMS層的具體功能是快變量,可以頻繁增刪。就像城市規劃中,主幹道的佈局百年不變,但沿街的商鋪卻不斷更迭。
當我們談論「資料夾即架構」時,實際上是在說:空間組織是認知組織的物化形式。笛卡爾的「我思故我在」可以改寫為「我組織故我理解」（I organize, therefore I comprehend）。通過組織程式碼的空間結構,我們實際上是在組織自己的思維結構。一個混亂的資料夾樹反映的不是技術問題,而是尚未澄清的概念模型。
最終,規模感知的架構組織範式指向一個更宏大的命題:軟體工程的本質不是製造（manufacturing）,而是園藝（gardening）。我們不是在組裝零件,而是在培育一個有機系統。好的架構師不是獨裁的規劃者,而是敏銳的觀察者——他們能識別系統何時需要「修剪」（簡化結構）、何時需要「移栽」（模組重組）、何時需要「施肥」（引入新抽象層）。
在複雜性的花園中,我們不追求控制,而追求與系統共同演化。當資料夾結構能夠自然地適應專案規模的變化,當開發者能在三層之內找到任何模組,當架構圖能在A4紙上清晰呈現——此時,我們達成了技術與認知、秩序與流變、簡潔與豐富的動態平衡。這不是終點,而是一個持續的、永不停歇的演化過程。正如赫拉克利特所言:「人不能兩次踏入同一條河流。」軟體系統也是如此——每一次的重構、每一次的演化,都是系統在時間之流中的自我超越。