68 lines
2.1 KiB
Markdown
68 lines
2.1 KiB
Markdown
|
# 更新程式碼地圖 (Update Codemaps)
|
|||
|
|
|
|||
|
|
對專案架構進行掃描，並生成針對 AI 優化的文字地圖，以協助處理複雜的跨檔案任務。
|
|||
|
|
|
|||
|
|
## 步驟 1：掃描專案結構
|
|||
|
|
|
|||
|
|
執行全面掃描以識別：
|
|||
|
|
- 核心模組與服務
|
|||
|
|
- API 端點與路由
|
|||
|
|
- 資料模型與資料庫 Schema
|
|||
|
|
- 關鍵依賴項與整合點
|
|||
|
|
- 專案特定的慣用法與模式
|
|||
|
|
|
|||
|
|
## 步驟 2：生成或更新地圖
|
|||
|
|
|
|||
|
|
為每個主要子系統生成或更新地圖 (位於 `.ccg/maps/`)。
|
|||
|
|
|
|||
|
|
### 程式碼地圖格式 (Codemap Format)
|
|||
|
|
|
|||
|
|
每份程式碼地圖都應具備「Token 效率」— 針對 AI 上下文消耗進行優化：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# 後端架構 (Backend Architecture)
|
|||
|
|
|
|||
|
|
## 路由 (Routes)
|
|||
|
|
POST /api/users → UserController.create → UserService.create → UserRepo.insert
|
|||
|
|
GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
|
|||
|
|
|
|||
|
|
## 關鍵檔案 (Key Files)
|
|||
|
|
src/services/user.ts (業務邏輯, 120 行)
|
|||
|
|
src/repos/user.ts (資料庫存取, 80 行)
|
|||
|
|
|
|||
|
|
## 依賴項 (Dependencies)
|
|||
|
|
- PostgreSQL (主要資料儲存)
|
|||
|
|
- Redis (會話快取, 速率限制)
|
|||
|
|
- Stripe (支付處理)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 步驟 3：變更偵測 (Diff Detection)
|
|||
|
|
|
|||
|
|
1. 如果已存在先前的程式碼地圖，計算其變更百分比。
|
|||
|
|
2. 若變更 > 30%，顯示差異並在覆寫前請求使用者核准。
|
|||
|
|
3. 若變更 <= 30%，則直接更新。
|
|||
|
|
|
|||
|
|
## 步驟 4：加入元數據 (Metadata)
|
|||
|
|
|
|||
|
|
為每份程式碼地圖加入「鮮度」標頭：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
<!-- 生成日期：2026-02-11 | 掃描檔案數：142 | 預計 Token：~800 -->
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 步驟 5：儲存分析報告
|
|||
|
|
|
|||
|
|
將摘要寫入 `.reports/codemap-diff.txt`：
|
|||
|
|
- 自上次掃描以來新增/移除/修改的檔案
|
|||
|
|
- 偵測到的新依賴項
|
|||
|
|
- 架構變更 (新路由、新服務等)
|
|||
|
|
- 針對超過 90 天未更新文件的陳舊警告
|
|||
|
|
|
|||
|
|
## 提示小撇步
|
|||
|
|
|
|||
|
|
- 專注於 **高層級結構**，而非實作細節。
|
|||
|
|
- 優先使用 **檔案路徑與函式簽名**，而非完整的程式碼區塊。
|
|||
|
|
- 保持每份地圖低於 **1000 tokens**，以實現高效的上下文載入。
|
|||
|
|
- 使用 ASCII 圖表展示資料流，而非冗長的文字描述。
|
|||
|
|
- 在進行重大功能開發或重構後執行此指令。
|