Tech Debt Capture

Automated technical debt capture from Phase 4 evaluation reports and conversion to Atomic Tickets.

核心功能

目的: 將 Phase 4 重構評估識別的技術債務自動轉換為可執行的 Ticket

工作流程:

1. 解析工作日誌中的技術債務表格
2. 根據風險等級決定目標版本
3. 建立 Atomic Ticket 檔案
4. 更新 todolist.yaml 技術債務追蹤區塊

完整技術債務處理流程：.claude/pm-rules/tech-debt.md

前置條件

工作日誌技術債務記錄格式

## 技術債務評估

| ID     | 描述                                              | 風險等級 | 建議處理時機 | 影響範圍     |
| ------ | ------------------------------------------------- | -------- | ------------ | ------------ |
| TD-001 | book_tags 表缺少 book_id 索引，大量資料查詢效能低 | 低       | 下一版本     | database     |
| TD-002 | BookRepository 和 TagRepository 錯誤處理邏輯重複  | 低       | 可選         | repositories |

什麼應該被記錄為技術債務

風險等級與版本對應

風險等級分類:

版本推進規則 (UC-Oriented)

決策邏輯:

1. 判斷技術債務來自哪個 UC 版本系列（Example: v0.19.8 = UC-08）
2. 根據風險等級選擇目標版本
   ├─ 高/中 -> 下一個 UC (v0.20.x)
   └─ 低/極低 -> 當前 UC 版本系列或後續版本
3. 如果未指定 --target-version，自動推導

Ticket 建立規則

技術債務 Ticket 使用特殊格式，包含 ticket_type: "tech-debt" 和來源版本資訊。

完整 Ticket frontmatter 範本：references/ticket-template.md 通用 Ticket 格式規範：.claude/skills/ticket/references/create-command.md

Ticket ID 格式

{TargetVersion}-TD-{Seq:03d}

範例: 0.20.0-TD-001, 0.20.0-TD-004

儲存位置

docs/work-logs/v{TargetVersion}/tickets/

TodoList 更新規則

在 docs/todolist.yaml 末尾新增或更新技術債務追蹤區塊：

## 技術債務追蹤

| Ticket ID     | 描述                        | 來源版本 | 目標版本 | 風險 | 狀態    |
| ------------- | --------------------------- | -------- | -------- | ---- | ------- |
| 0.20.0-TD-001 | 新增 book_tags.book_id 索引 | v0.19.8  | v0.20.0  | 低   | pending |

使用方式

互動模式（推薦）

/tech-debt-capture

引導式交互：選擇工作日誌 -> 確認 TD 清單 -> 確認版本對應 -> 建立 Ticket 並更新 todolist

批量模式

uv run .claude/skills/tech-debt-capture/scripts/tech_debt_capturer.py capture \
    docs/work-logs/v0.19.8-phase4-final-evaluation.md

更多 CLI 範例（預覽模式、初始化、列出）：references/cli-examples.md

功能特性

1. 表格解析: 自動解析 Phase 4 工作日誌中的技術債務 Markdown 表格
2. 版本決策引擎: UC-Oriented 版本推導，支援 --target-version 手動覆蓋
3. Atomic Ticket 產生: 單一職責設計，自動填充 5W1H 和 frontmatter
4. 文件更新: 自動更新 todolist.yaml 和建立版本目錄

前置條件

• python3.10+
• pyyaml 套件（UV 自動安裝）
• 完成 Phase 4 重構評估報告

相關資源

• /ticket create - 手動建立 Atomic Ticket
• /ticket track - 追蹤和更新 Ticket 狀態
• .claude/pm-rules/tech-debt.md - 技術債務處理流程
• .claude/methodologies/atomic-ticket-methodology.md - 單一職責原則

Version: v1.1 Last Updated: 2026-03-02 維護責任: basil-hook-architect