如果在重構之前沒有系統性地理解設計意圖，我們很可能會把問題修錯方向，或者在「修好」一處的同時破壞了其他地方。

於是我們建立了一套方法論，把設計文件的閱讀和驗證，放在所有重構動作的最前面。

為什麼設計文件要在程式碼之前讀

看到壞味道就處理、看到重複就提取——傳統重構路線沒有問題，但對 Domain 層的核心實體來說，這樣做有個盲點：我們可能根本不清楚這段程式碼的業務意圖。

不清楚「Library 為什麼要追蹤 SourceType 而不是 ReadingStatus」，技術上漂亮的重構可能在業務上悄悄引入錯誤。設計驅動重構的前提是：所有重構決策必須基於現有的設計文件，而不是單純從程式碼的技術形狀來判斷。

驗證流程

第一階段：設計文件檢查

在動任何一行程式碼之前，我們先回頭讀文件。閱讀順序很重要：從需求規格出發，再到用例說明，再到 UI 設計規格，最後到錯誤處理設計。

這個閱讀順序的邏輯是：先確立業務目標（需求規格），再理解使用場景（用例），再看 UI 層如何呈現（UI 規格），最後檢查系統如何應對異常（錯誤處理）。這樣走一遍，Domain Root 在整個系統中扮演的角色就會變得清晰。

以 Library 實體為例，文件告訴我們它需要支援不同來源類型的書籍統計——實體書、電子書、借閱書各有不同的計算邏輯。但程式碼裡用的是 ReadingStatus 枚舉，而且還在使用 'digital'、'borrowed' 這些根本不在枚舉定義裡的值。這不是設計問題，這是實作根本跑錯了方向。

第二階段：測試覆蓋率分析

讀完文件之後，我們看測試。測試是另一種形式的設計文件，它告訴我們這段程式碼「被期待如何運作」。

這個階段最常發現的問題是測試的方向跑偏了。我們在 book_test.dart 裡發現，它引用了 flutter_test 套件，但 Domain 層的單元測試根本不應該依賴 Flutter 框架——這意味著這些測試在純 Dart 環境中根本無法執行，CI 流程也因此產生了盲點。

此外還有大量被 skip 的測試。每個 skip 都是一個未被驗證的業務假設，累積起來就是風險。

第三階段：程式實作驗證

前兩個階段讓我們建立了對「設計意圖」的理解。第三階段才是真正對照程式碼，逐一確認哪裡偏離了設計。

這個階段的關鍵產出是一份問題清單，而且每個問題都有分類：是類型系統錯誤、是架構違規、是技術債務，還是可維護性問題。分類決定了後續的修復優先級。

問題分類與修復優先級

我們在實際的 Book 和 Library 重構中，識別出了四類問題，按照影響範圍決定修復順序。

類型系統錯誤優先級最高。 使用不存在的枚舉值、把 String 傳給期望強類型的參數，這類問題一旦進入生產環境就是執行時崩潰。我們把所有這類問題排在第一批處理。

異常處理不統一緊隨其後。 Library 實體裡有自定義的 DuplicateBookException，但整個專案其他地方都統一使用 AppError 體系。這種不一致性不只是風格問題，它讓錯誤處理的呼叫端無法用一致的方式應對。

技術債務屬於第二優先級。 最典型的例子是 author 欄位使用 String 類型。這在功能上可以運作，但它限制了後續的多作者支援、譯者解析和富文字搜尋能力。這類問題有明確的演進路徑，但不是緊急的。

可維護性問題排在最後。 包括缺乏需求追蹤編號的註解、業務規則說明不足等。這些問題不影響功能，但它們是技術債務的溫床——當下一個人來維護這段程式碼時，他沒有足夠的上下文。

幾個具體的重構模式

類型系統修正

問題很常見：用字串或錯誤的枚舉值來做判斷，而不是使用正確的類型。

修正前：

1books.where((book) => book.readingStatus == 'digital')

修正後：

1books.where((book) => book.source.type.isDigital)

表面上看這只是換了一個屬性，但背後的意義完全不同：前者依賴字串的巧合匹配，後者依賴類型系統的保證。

異常處理統一

自定義異常類別散落在程式碼各處，是一種常見的技術債務模式。

修正前：

1throw DuplicateBookException('message', bookId: id, title: title);

修正後：

1return OperationResult.failure(
2  BusinessLogicError(
3    message: 'message',
4    businessRule: 'BOOK_DUPLICATE_PREVENTION',
5    code: ErrorCodes.duplicateBook,
6    context: {'bookId': id, 'title': title},
7  ),
8  'userMessage'
9);

這個轉換不只是換個類別，它同時把拋出異常改成了回傳結果——這是更適合 Domain 層的錯誤傳遞方式，讓呼叫端可以明確地決定如何處理每種失敗情況。

Value Object 重構

把 String 提升為 Value Object 是一個需要仔細計畫的重構，因為它涉及所有使用處的同步更新。

修正前：

1final String author;

修正後：

1final BookAuthor author;

關鍵在於轉換策略要設計好：BookAuthor.fromString(stringValue) 負責從舊有字串資料遷移，bookAuthor.displayValue 負責在需要字串輸出的場合提供相容性。有了這兩個轉換點，才能在保持向後相容性的前提下完成遷移。

分階段執行，每段必驗

每個修復階段結束後都要驗證：dart analyze 無錯誤、核心功能正常運作、API 介面保持不變。我們曾經跳過這個步驟，結果後續階段的問題疊加在一起，讓除錯變得極其困難。

從這次重構中得到的

這次對 Book 和 Library 兩個 Domain Root 的重構，最終涉及了 35 個以上的檔案，把 24 個編譯錯誤降到了零，並且完整建立了需求追蹤的 REQ-LIB-XXX 編號體系。

收穫更大的是設計文件優先讓我們避開了幾個危險方向。如果直接看到 author 是 String 就去重構，可能會建出不符合業務需求的 Value Object。如果直接看到自定義異常就去統一，可能會在類型系統問題還沒修好的基礎上做錯誤的抽象。

下次面對需要重構的模組時，先花 15 分鐘讀相關設計文件，再決定從哪裡下手。那 15 分鐘很可能讓你避開一個需要幾個小時才能發現的方向錯誤。

除錯不是試錯過程，是品質提升的系統性工程。隨機修復會產生隨機品質。系統化除錯產生一致的架構改善。

當AI協作處理複雜程式問題時，系統化除錯方法論成為唯一的執行準則。模糊的修復策略會產生模糊的結果。明確的除錯方法論產生一致的品質改善。

系統化除錯的本質

系統化除錯不是什麼

系統化除錯不是：

• 症狀修復：不掩蓋警告，只找根本原因
• 批量處理：不自動修復，只精確分析
• 簡單先行：不從容易修的開始，只按風險優先級
• 表面清理：不只消除警告，只完成未完成的設計

系統化除錯是什麼

系統化除錯是：

• 根因分析：明確區分未完成實作vs過度設計
• 風險導向：按業務風險和架構影響排序修復
• 主從分工：主線程管控進度，代理人執行修復
• 品質提升：每次修復都強化程式設計完整性

除錯的第一原則：根因分析優先

問題本質分類

每個unused警告都屬於以下三類之一：

未完成實作

• 識別：功能設計完整但驗證邏輯缺失
• 處理：補完實作而非移除程式碼
• 範例：測試中建立了secondImport變數但未驗證重複匯入行為

過度設計

• 識別：功能已完成但包含不必要的複雜性
• 處理：移除多餘程式碼保持精簡設計
• 範例：建立獨立服務實例但架構採用單例模式

程式碼風格問題

• 識別：邏輯正確但命名或結構不一致
• 處理：重構改善可讀性和一致性
• 範例：使用File物件但混用path字串操作

分析判斷標準

• 變數有明確的業務意圖 → 未完成實作
• 變數創建後立即被丟棄 → 過度設計
• 變數使用方式不一致 → 程式碼風格問題

不存在「可能是」的情況。如果無法明確分類，則需要更深入的程式碼分析。

範例：完整的根因分析

情境：test檔案中unused變數 ‘initialMemory’

錯誤分析

「這個變數沒用到，直接刪掉。」

正確分析過程

1. 變數意圖：記憶體效率測試的基線測量
2. 使用模式：建立但未在驗證邏輯中引用
3. 分類判斷：未完成實作（測試設計完整但驗證缺失）
4. 修復策略：補完基線比較邏輯而非移除變數

除錯的第二原則：風險導向排序

檔案風險等級

檔案修復必須按風險等級執行：

高風險檔案（立即修復）

• 核心業務邏輯：Domain層實作檔案
• 基礎設施元件：Database、Service、Repository
• 關鍵測試：端到端測試、整合測試

中風險檔案（計畫修復）

• 輔助功能：Utility、Helper類別
• 測試工具：Mock、TestData產生器
• 配置檔案：Configuration、Environment設定

低風險檔案（可延後修復）

• 單元測試變數：純測試輔助變數
• 範例程式碼：Demo、Sample實作
• 文件產生器：Documentation工具

風險評估標準

• 影響核心功能 → 高風險
• 影響開發效率 → 中風險
• 純粹警告清理 → 低風險

每個檔案只能歸類到一個風險等級。無法分類表示需要進一步的架構分析。

修復優先序執行規則

• 高風險檔案：立即修復，不考慮複雜度
• 中風險檔案：當前Sprint完成
• 低風險檔案：下個版本或維護期處理

除錯的第三原則：主從分工模式

角色定義

系統化除錯採用明確的角色分工：

主線程職責

• 進度管控：追蹤修復狀態和整體進展
• 策略決策：確定修復優先序和資源配置
• 品質檢查：驗證修復結果符合品質要求
• 工作記錄：更新工作日誌避免遺漏

代理人職責

• 詳細分析：深入檢查程式碼設計意圖
• 修復執行：實際編寫和修改程式碼
• 測試驗證：確保修復後功能正常
• 技術回報：提供修復細節和影響評估

協作執行規則

• 主線程永不直接修復程式碼
• 代理人永不決定修復優先序
• 每修復一個檔案都必須更新工作日誌
• 所有修復決策都必須通過主線程確認

範例：完整的協作流程

情境：發現5個檔案有unused警告

主線程執行

1. 風險評估：將5個檔案按業務風險分類
2. 優先排序：確定高風險檔案的修復順序
3. 委託分析：要求代理人分析第一個檔案
4. 進度追蹤：更新TodoList標記當前處理檔案

代理人執行

1. 根因分析：判斷unused變數屬於未完成實作vs過度設計
2. 修復實施：根據分析結果執行對應的修復策略
3. 結果驗證：執行靜態分析工具確認警告消除
4. 影響報告：回報修復內容和對整體架構的影響

主線程確認

1. 驗證結果：檢查靜態分析工具輸出確認修復成功
2. 更新記錄：在工作日誌中記錄修復成果
3. 繼續協作：標記完成並委託下一個檔案分析

品質標準

修復完成的判斷標準

每個檔案修復完成必須滿足：

• 警告消除：靜態分析工具不再顯示該檔案的unused警告
• 功能完整：所有測試通過，不引入新的錯誤
• 架構一致：修復符合Clean Architecture分層原則
• 文件更新：工作日誌記錄修復內容和影響

整體品質提升指標

• 警告減少率：unused警告數量持續下降
• 功能完整性：修復過程中完成更多未完成的實作
• 架構一致性：程式碼風格和設計模式更加統一
• 可維護性：程式碼可讀性和邏輯清晰度提升

品質驗證機制

• 每個檔案修復後立即執行靜態分析工具驗證
• 定期檢查整體警告數量變化趨勢
• 記錄修復過程中發現的架構改善機會
• 確認每次修復都強化而非弱化程式品質

執行流程

標準修復流程

1. 問題評估 執行靜態分析工具識別所有unused警告

2. 風險分析 將含有警告的檔案按風險等級分類

3. 優先排序 確定高風險檔案的修復順序

4. 逐檔修復 按優先序對每個檔案執行：

   • 委託代理人詳細分析
   • 根因判斷(未完成實作vs過度設計vs程式碼風格)
   • 執行對應修復策略
   • 驗證修復結果
   • 更新工作記錄

5. 整體驗證 確認警告總數下降且無新錯誤引入

修復策略對應表

例外處理原則

• 分析器誤報：確認變數確實被使用後保持現狀
• 架構衝突：優先解決架構問題後再處理警告
• 測試失敗：立即修復測試問題，暫停警告修復
• 複雜邊界：分解為更小的問題單位處理

成果評估

量化指標

• 警告消除數量：已修復的unused警告總數
• 警告減少率：相對於初始狀態的改善百分比
• 檔案修復數量：完成修復的檔案總數
• 架構改善項目：修復過程中完成的設計改善

質化評估

• 根因解決率：真正解決問題vs僅消除警告的比例
• 架構一致性：程式碼風格和設計模式統一程度
• 功能完整性：修復過程中完成的未完成實作數量
• 可維護性提升：程式碼清晰度和邏輯簡潔性改善

實戰案例：v0.8.19成果

量化成果：

• 初始警告：49個
• 最終警告：25個
• 改善率：49.0%
• 修復檔案：7個高風險檔案

質化成果：

• 補完3個未完成的功能實作
• 移除4處過度設計的複雜程式碼
• 統一5個檔案的程式碼風格
• 解決2個架構不一致問題

持續改進

方法論優化

系統化除錯方法論必須持續優化：

• 記錄邊界案例：遇到的特殊情況和處理方式
• 更新風險分類：基於實戰經驗調整風險評估標準
• 改進協作模式：優化主線程和代理人的分工效率
• 補充修復策略：新增針對特定問題類型的處理方法

知識累積

每次系統化除錯的經驗都必須沉澱為方法論改進：

• 成功的修復策略納入標準流程
• 失效的方法從規範中移除
• 新發現的問題模式補充到分類標準
• 協作過程中的效率改善點持續優化

結論

系統化除錯方法論是品質提升的執行標準。它的價值在精確，它的目的是完成設計。

每個修復都是一次架構改善。每個分析都是一次設計檢視。每個協作都是一次品質提升。

執行系統化除錯就是執行品質標準。遵循這個方法論，我們能持續強化程式架構完整性和設計一致性。

這是工程規範，確保每次除錯都提升而非妥協專案品質。

延伸：套用到 Linux 系統除錯

這套方法論是語言與領域無關的通則。把它落到 Linux 系統除錯這個具體領域——「讀權威狀態而非肉眼猜表象」的紀律、症狀到情境的分流、逐層定位——見 Linux 除錯與診斷：診斷心法。那裡用實機案例（把鎖屏誤判兩次的教訓）展示同一套系統化紀律在 Linux 現場長什麼樣。

在程式開發中，導入聲明往往被視為技術細節，但它們實際上是架構文件的第一行。每個 import/require 都在告訴讀者：這個模組的依賴關係、系統的組織方式、以及設計者的架構思考。

相對路徑如 import '../../../utils/helper.js' 只是路徑的機械表達，而語意化路徑如 import 'package:app/core/utils/helper.dart' 則清楚傳達了模組的架構位置和責任。

導入聲明的本質

導入不是什麼

導入聲明不是：

• 文件路徑的機械化表達：不是為了節省字元數而設計
• 相對位置的簡化表示：不是為了避免長路徑而妥協
• 開發便利性的工具：不是為了快速輸入而犧牲可讀性
• IDE 自動生成的結果：不是讓工具決定程式碼結構

導入是什麼

導入聲明是：

• 依賴關係的明確宣告：清楚表達模組間的連接
• 程式碼架構的文件化：展示系統的組織結構
• 依賴來源的即時說明：讓讀者立即理解依賴的性質
• 架構意圖的表達方式：體現設計者對模組劃分的思考

核心原則

第一原則：導入路徑的架構語意性

每個導入都必須清楚表達來源的架構位置：

1// 正例：清楚表達架構層級
2import 'package:book_overview_app/domains/library/entities/book.dart';
3import 'package:book_overview_app/core/errors/standard_error.dart';
4
5// 反例：隱藏架構關係
6import '../entities/book.dart';
7import '../../../core/errors/standard_error.dart';

第二原則：依賴來源的即時識別

從導入聲明立即理解依賴性質：

1// 從導入立即理解：這是 Library Domain 的核心實體
2import { Book } from '@app/domains/library/entities/book';
3
4// 從導入立即理解：這是 Core 基礎設施
5import { StandardError } from '@app/core/errors/standard-error';

第三原則：禁用別名與妥協

別名是程式設計不佳的象徵。當我們遇到重名衝突時，核心解決方案是重構和改善命名，而不是用別名掩蓋設計問題。

為什麼禁用別名

別名反映的根本問題：

1. 命名不夠清晰明確：導致不同模組產生重名衝突
2. 架構設計缺陷：同一概念在不同領域使用相同名稱
3. 職責劃分不清：模組邊界和責任沒有明確定義
4. 技術債務累積：用別名掩蓋設計問題而非解決問題

錯誤的別名解決方案

1// 反例：使用別名掩蓋設計問題
2import 'package:app/domains/library/entities/book.dart' as LibBook;
3import 'package:app/domains/search/entities/book.dart' as SearchBook;
4
5// 使用時仍然模糊不清
6LibBook.Book bookEntity = LibBook.Book();
7SearchBook.Book searchResult = SearchBook.Book();

正確的重構解決方案

1// 正例：重構命名，消除重名衝突
2import 'package:app/domains/library/entities/book.dart';
3import 'package:app/domains/search/entities/search_result.dart';
4
5// 使用時語意清楚，職責明確
6Book libraryBook = Book();
7SearchResult searchData = SearchResult();

重構策略

1. 重新審視命名責任：

• 保留核心領域的概念名稱（如 Library Domain 的 Book）
• 重構其他領域的名稱為更精確的描述（如 Search Domain 的 SearchResult）

2. 領域邊界清晰化：

• 根據職責重新命名類別和模組
• 確保每個名稱都有明確的領域歸屬

3. 架構重構優於別名妥協：

• 禁用別名迫使開發者正視設計缺陷
• 推動更清晰的領域劃分
• 維護程式碼品質標準

跨語言實踐標準

Dart/Flutter: Package 系統

1// Package 導入 + 完整路徑語意
2import 'package:book_overview_app/domains/library/entities/book.dart';
3import 'package:book_overview_app/domains/search/services/api_service.dart';

實現機制：pubspec.yaml 定義 package 名稱，Dart 編譯器將 package: 映射到 lib/ 目錄。

Node.js: 混合策略 (V1 專案實踐)

生產環境：

1// 嚴格的目錄規範 + 明確的相對路徑
2const BaseModule = require('./lifecycle/base-module');
3const PageDomainCoordinator = require('./domains/page/page-domain-coordinator');

測試環境：

1// Jest moduleNameMapper 實現語意化
2const { ErrorCodes } = require('src/core/errors/ErrorCodes');
3const QualityAssessmentService = require('src/background/domains/data-management/services/quality-assessment-service.js');

Jest 配置關鍵：

1// tests/jest.config.js
2module.exports = {
3  moduleNameMapper: {
4    '^src/(.*)$': '<rootDir>/src/$1',           // src/ 路徑語意化
5    '^@/(.*)$': '<rootDir>/src/$1',             // @ 別名映射
6    '^@tests/(.*)$': '<rootDir>/tests/$1',      // 測試檔案語意化
7    '^@mocks/(.*)$': '<rootDir>/tests/mocks/$1' // Mock 檔案語意化
8  }
9}

PHP Laravel: 框架 + Composer

 1<?php
 2// Laravel 的命名空間 + Composer Autoloader
 3namespace App\Domains\Library\Entities;
 4
 5use App\Domains\Search\Services\ApiService;
 6use App\Core\Errors\StandardError;
 7use Illuminate\Database\Eloquent\Model;
 8
 9class Book extends Model
10{
11    // 完整命名空間讓讀者立即理解依賴來源
12}

Go: Module System

 1package main
 2
 3import (
 4    // 外部依賴使用 module path
 5    "github.com/gin-gonic/gin"
 6    "gorm.io/gorm"
 7
 8    // 內部模組使用完整 module path
 9    "book-overview-app/domains/library/entities"
10    "book-overview-app/domains/search/services"
11    "book-overview-app/core/errors"
12)

TypeScript: Module Resolution

1// Module 導入 + 完整路徑語意
2import { Book } from '@app/domains/library/entities/book';
3import { ApiService } from '@app/domains/search/services/api-service';

V1 專案：無框架的成功實踐

為什麼 V1 可以不需要絕對路徑

1. 一致的目錄結構：所有模組都在 /src/background/ 下，層級關係固定
2. 明確的相對路徑語意：./ = 同級，../ = 上一級，路徑語意清楚
3. 避免深層嵌套：最多 3-4 層目錄，相對路徑仍然可讀
4. Jest 測試環境的語意化支援：透過配置實現測試檔案的語意化路徑

npm test vs Jest 直接執行的選擇

V1 專案選擇 npm test 的原因：

1. 一致性管理：統一的測試入口
2. 環境隔離：確保所有開發者使用相同配置
3. 工具鏈整合：可以執行測試前後的額外工作

1// package.json - 統一的測試入口
2"scripts": {
3  "test": "npm run test:core",
4  "test:core": "jest tests/unit tests/integration",
5  "test:unit": "jest tests/unit",
6  "test:integration": "jest tests/integration"
7}

測試路徑語意化的實現機制

1// Jest 如何解析語意化路徑：
2// 1. 測試檔案寫入: require('src/core/errors/ErrorCodes')
3// 2. Jest moduleNameMapper 攔截: '^src/(.*)$': '<rootDir>/src/$1'
4// 3. 實際解析路徑: /project-root/src/core/errors/ErrorCodes.js
5// 4. Node.js 載入模組: 成功匯入 ErrorCodes

語言特性對比

實踐選擇指南

有框架的專案

• 使用框架提供的模組系統
• 例如：Laravel、Angular、Next.js
• 測試環境通常自動繼承框架的模組解析

無框架的專案 (如 V1 範例)

• 生產環境：採用嚴格的目錄規範 + 相對路徑
• 測試環境：使用 Jest moduleNameMapper 實現語意化
• 關鍵優勢：生產簡單，測試語意化

混合策略專案

• 生產環境使用簡單的相對路徑
• 測試環境透過工具配置實現語意化
• 適合輕量級 Node.js 專案

架構透明性的價值

從導入理解系統設計

 1// 從這個檔案的導入可以立即理解：
 2// 1. 這是一個跨 Domain 的協調器
 3// 2. 主要整合 Library、Import、Search 三個領域
 4// 3. 使用 Core 的標準錯誤處理
 5// 4. 依賴外部的 HTTP 套件
 6
 7import 'package:http/http.dart';
 8import 'package:book_overview_app/core/errors/standard_error.dart';
 9import 'package:book_overview_app/domains/library/services/library_service.dart';
10import 'package:book_overview_app/domains/import/services/import_service.dart';
11import 'package:book_overview_app/domains/search/services/search_service.dart';

依賴方向的視覺化

1// 讀者可以立即看出依賴方向：
2// UI → Domain → Core
3// 沒有反向依賴，符合乾淨架構原則
4
5import 'package:book_overview_app/core/interfaces/repository.dart';           // 向下依賴
6import 'package:book_overview_app/domains/library/entities/book.dart';       // 平行依賴
7import 'package:book_overview_app/domains/library/value_objects/book_id.dart'; // 向下依賴

總結

Package 導入路徑語意化方法論的核心價值：

1. 架構透明性：從導入立即理解系統結構
2. 維護便利性：減少理解和修改的認知負擔
3. 團隊協作：統一的導入風格提升溝通效率
4. 跨語言一致性：建立統一的程式碼組織哲學

遵循這個方法論，程式碼將成為自說明的架構文件，每個導入聲明都清楚表達系統的設計意圖和模組關係。無論是有框架還是無框架的專案，都能找到適合的語意化導入策略。

V1 專案證明了即使在無框架環境下，透過嚴格的目錄規範和 Jest 測試配置，仍然可以實現生產環境簡潔、測試環境語意化的理想狀態。這為其他類似專案提供了寶貴的實踐參考。

結論

這是架構透明化機制，讓每個導入聲明都成為架構的即時文件。