持續脈絡清理

所有團隊回饋的核心洞察是：脈絡污染會隨著程式庫演進而累積。一次性清理是不夠的；團隊需要一個持續的流程來維護脈絡品質。

核心原則： 脈絡品質會自然退化。沒有主動維護，每個程式庫最終都會隨著模式累積、框架並存、文件過時而變得「AI 不友善」。

為何持續清理很重要

持續清理循環

階段 1：識別污染

目標： 在影響 AI 效能之前偵測脈絡污染。

信號	如何偵測	範例
AI 使用錯誤模式	審查 AI 生成的 PR	AI 建立 DAO 而非 Repository
AI 遺漏現有元件	追蹤重複程式碼生成	AI 實作新按鈕而非使用共用元件
AI 選擇棄用框架	監控新程式碼的框架使用	AI 使用 XML binding 而非 Jetpack Compose
命名不一致	Code review 檢查命名違規	AI 生成 deviceId 但標準是 DeviceKey

偵測方法：

1. 每週 AI 輸出審查

   • 抽樣 5-10 個 AI 生成的程式碼變更
   • 對照專案標準檢查
   • 記錄違規以進行模式分析

2. 搜尋污染審計

   # 統計常見搜尋的結果數
   grep -r "api handler" --include="*.go" | wc -l  # 應該少於現代結果
   grep -r "clean architecture controller" --include="*.go" | wc -l

3. 開發者回饋迴路

   • 在 PR 評論中加入「AI 做出錯誤選擇」選項
   • 追蹤哪些模式造成最多 AI 困惑

階段 2：文件化標準

目標： 讓現行標準明確且可被 AI 發現。

CLAUDE.md 模板：

# 專案名稱 - AI 指引

## 現行標準（請使用這些）
- **API 層**: `/internal/restful/` - Clean Architecture 控制器
- **資料存取**: `/internal/.../repository/` - Repository 模式
- **狀態管理**: Pinia composition stores
- **UI 框架**: Jetpack Compose (Android), SwiftUI (iOS)

## 已棄用（請勿使用）
- `/internal/openapi/` - 遺留 API 處理器
- `/pkg/dao/` - 遺留 DAO 模式
- 使用 Map 物件的 Vuex stores
- XML binding layouts

## 搜尋建議
| 當尋找... | 請搜尋... | 不要搜尋... |
|-----------|----------|-------------|
| API 處理器 | "controller" + "restful" | "handler" |
| 資料庫存取 | "repository" | "dao" |
| 裝置資訊 | "DeviceIdentity" | "deviceId", "mac" |

階段 3：標記棄用

目標： 讓棄用程式碼對 AI 和人類都可見。

Go 套件層級棄用：

// Package openapi 包含已棄用的遺留 API 處理器。
//
// Deprecated: 不要在此新增端點。
// 新 API 應加到 /internal/restful/ 使用 Clean Architecture。
// 此套件僅為 V1 行動 app 的向後相容而維護。
package openapi

JavaScript/TypeScript 棄用：

/**
 * @deprecated 自 v2.0 起 - 請改用 Pinia 的 useDeviceStore()
 *
 * 此 Vuex 模組使用不可序列化的 Map 物件，會破壞
 * AI 脈絡理解和 DevTools 檢查。
 *
 * 遷移指南：docs/migration/vuex-to-pinia.md
 * 計畫移除：v3.0
 */
export default {
  state: {
    deviceMap: new Map()  // 反模式：不可序列化
  }
}

階段 4：漸進遷移

目標： 將程式碼移至現代模式，避免大規模重寫。

遷移策略：

階段 5：驗證與監控

目標： 確保清理工作有效且持續。

驗證指令：

# 檢查棄用程式碼比例
echo "已棄用套件："
grep -r "Deprecated:" --include="*.go" -l | wc -l
echo "總套件數："
find . -name "*.go" -type f | xargs dirname | sort -u | wc -l

# 檢查 CLAUDE.md 覆蓋率
echo "有 CLAUDE.md 的專案："
find . -name "CLAUDE.md" -type f | wc -l

每月審計檢查清單：

• [ ] 審查 AI 輸出準確度指標
• [ ] 更新棄用程式碼比例
• [ ] 檢查是否有新的未文件化模式
• [ ] 驗證 CLAUDE.md 反映當前狀態
• [ ] 抽樣搜尋污染率
• [ ] 審查開發者對 AI 困惑的回饋

快速入門指南

第 1 週：基礎

1. 在專案根目錄建立 CLAUDE.md
2. 列出現行 vs 棄用模式
3. 為最令人困惑的 3 個套件加上棄用標記

第 2 週：意識

1. 為棄用目錄新增 pre-commit hook
2. 與團隊分享 CLAUDE.md 位置
3. 開始追蹤 AI 困惑事件

第 3 週：流程

1. 在 PR 模板中加入 AI 脈絡檢查清單
2. 安排每月審計
3. 選擇第一個遷移目標

持續

1. 隨著模式演進更新 CLAUDE.md
2. 審查每月指標
3. 根據結果迭代流程

返回： 提案概覽

參考資料

• Claude Code 文件 - CLAUDE.md AI 指引檔案的官方文件
• Strangler Fig 模式 - Martin Fowler 對漸進遷移模式的描述