tech-debt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phase 1: Parse Subcommand

第一阶段：解析子命令

Determine the mode from the argument:

```
scan
```
— Scan the codebase for tech debt indicators
```
add
```
— Add a new tech debt entry manually
```
prioritize
```
— Re-prioritize the existing debt register
```
report
```
— Generate a summary report of current debt status

If no subcommand is provided, output usage and stop. Verdict: FAIL — missing required subcommand.

从参数中确定模式：

```
scan
```
— 扫描代码库中的技术债务指标
```
add
```
— 手动添加新的技术债务条目
```
prioritize
```
— 重新排序现有债务登记册中的条目优先级
```
report
```
— 生成当前债务状态的汇总报告

如果未提供子命令，输出使用说明并停止。结论：失败 — 缺少必填子命令。

Phase 2A: Scan Mode

第二阶段A：扫描模式

Search the codebase for debt indicators:

```
TODO
```
comments (count and categorize)
```
FIXME
```
comments (these are bugs disguised as debt)
```
HACK
```
comments (workarounds that need proper solutions)
```
@deprecated
```
markers
Duplicated code blocks (similar patterns in multiple files)
Files over 500 lines (potential god objects)
Functions over 50 lines (potential complexity)

Categorize each finding:

Architecture Debt: Wrong abstractions, missing patterns, coupling issues
Code Quality Debt: Duplication, complexity, naming, missing types
Test Debt: Missing tests, flaky tests, untested edge cases
Documentation Debt: Missing docs, outdated docs, undocumented APIs
Dependency Debt: Outdated packages, deprecated APIs, version conflicts
Performance Debt: Known slow paths, unoptimized queries, memory issues

Present the findings to the user.

Ask: "May I write these findings to

docs/tech-debt-register.md

If yes, update the register (append new entries, do not overwrite existing ones). Verdict: COMPLETE — scan findings written to register.

If no, stop here. Verdict: BLOCKED — user declined write.

搜索代码库中的债务指标：

```
TODO
```
注释（统计并分类）
```
FIXME
```
注释（这些是伪装成债务的bug）
```
HACK
```
注释（需要合理解决方案的临时变通方法）
```
@deprecated
```
标记
重复代码块（多个文件中的相似模式）
超过500行的文件（潜在的上帝对象）
超过50行的函数（潜在的复杂度问题）

对每个发现进行分类：

架构债务：错误的抽象、缺失的设计模式、耦合问题
代码质量债务：重复代码、复杂度、命名问题、缺失类型定义
测试债务：缺失测试、不稳定测试、未测试的边缘场景
文档债务：缺失文档、过时文档、未文档化的API
依赖债务：过时的包、废弃的API、版本冲突
性能债务：已知的慢路径、未优化的查询、内存问题

向用户展示发现结果。

询问："是否要将这些发现写入

docs/tech-debt-register.md

？"

如果用户同意，更新登记册（追加新条目，不覆盖现有内容）。结论：完成 — 扫描结果已写入登记册。

如果用户不同意，在此处停止。结论：受阻 — 用户拒绝写入操作。

Phase 2B: Add Mode

第二阶段B：添加模式

Ask the user for the description, affected files, and impact if left unfixed (plain text prompts).

Then use

AskUserQuestion

to collect the category:

Prompt: "What category does this tech debt belong to?"

Options:

[A] Architecture Debt — wrong abstractions, missing patterns, coupling issues

[B] Code Quality Debt — duplication, complexity, naming, missing types

[C] Test Debt — missing tests, flaky tests, untested edge cases

[D] Documentation Debt — missing/outdated docs, undocumented APIs

[E] Dependency Debt — outdated packages, deprecated APIs, version conflicts

[F] Performance Debt — known slow paths, memory issues, unoptimized queries

Then use

AskUserQuestion

to collect the estimated fix effort:

Prompt: "What is the estimated effort to fix this item?"

Options:

```
[A] S — Small (under 1 day)
```
```
[B] M — Medium (1–3 days)
```
```
[C] L — Large (3–7 days)
```
```
[D] XL — Extra Large (over 1 week)
```

Present the complete new entry to the user.

Ask: "May I append this entry to

docs/tech-debt-register.md

If yes, append the entry. Verdict: COMPLETE — entry added to register.

If no, stop here. Verdict: BLOCKED — user declined write.

向用户索要描述、受影响文件以及未修复情况下的影响（纯文本提示）。

然后使用

AskUserQuestion

收集分类信息：

提示："此项技术债务属于哪个分类？"

选项：

[A] 架构债务 — 错误的抽象、缺失的设计模式、耦合问题

[B] 代码质量债务 — 重复代码、复杂度、命名问题、缺失类型定义

[C] 测试债务 — 缺失测试、不稳定测试、未测试的边缘场景

[D] 文档债务 — 缺失/过时文档、未文档化的API

[E] 依赖债务 — 过时的包、废弃的API、版本冲突

[F] 性能债务 — 已知的慢路径、内存问题、未优化的查询

然后使用

AskUserQuestion

收集预估修复工作量：

提示："修复此项工作的预估工作量是多少？"

选项：

```
[A] S — 小（1天以内）
```
```
[B] M — 中（1–3天）
```
```
[C] L — 大（3–7天）
```
```
[D] XL — 超大（1周以上）
```

向用户展示完整的新条目。

询问："是否要将此条目追加到

docs/tech-debt-register.md

？"

如果用户同意，追加条目。结论：完成 — 条目已添加到登记册。

如果用户不同意，在此处停止。结论：受阻 — 用户拒绝写入操作。

Phase 2C: Prioritize Mode

第二阶段C：优先级排序模式

Read the debt register at

docs/tech-debt-register.md

Score each item by:

(impact_if_unfixed × frequency_of_encounter) / fix_effort

Re-sort the register by priority score and recommend which items to include in the next sprint.

Present the re-prioritized register to the user.

Ask: "May I write the re-prioritized register back to

docs/tech-debt-register.md

If yes, write the updated file. Verdict: COMPLETE — register re-prioritized and saved.

If no, stop here. Verdict: BLOCKED — user declined write.

读取

docs/tech-debt-register.md

中的债务登记册。

通过公式为每个条目打分：

(未修复的影响 × 遇到频率) / 修复工作量

按优先级分数重新排序登记册，并建议哪些条目应纳入下一个迭代。

向用户展示重新排序后的登记册。

询问："是否要将重新排序后的登记册写回

docs/tech-debt-register.md

？"

如果用户同意，写入更新后的文件。结论：完成 — 登记册已重新排序并保存。

如果用户不同意，在此处停止。结论：受阻 — 用户拒绝写入操作。

Phase 2D: Report Mode

第二阶段D：报告模式

Read the debt register. Generate summary statistics:

Total items by category
Total estimated fix effort
Items added vs resolved since last report
Trending direction (growing / stable / shrinking)

Flag any items that have been in the register for more than 3 sprints.

Output the report to the user. This mode is read-only — no files are written. Verdict: COMPLETE — debt report generated.

读取债务登记册。生成汇总统计数据：

按分类统计的条目总数
预估修复总工作量
自上次报告以来新增与已解决的条目数量
趋势方向（增长/稳定/减少）

标记所有在登记册中存在超过3个迭代的条目。

向用户输出报告。此模式为只读模式 — 不写入任何文件。结论：完成 — 债务报告已生成。

Phase 3: Next Steps

第三阶段：后续步骤

Run
```
/sprint-plan
```
to schedule high-priority debt items into the next sprint.
Run
```
/tech-debt report
```
at the start of each sprint to track debt trends over time.

运行
```
/sprint-plan
```
将高优先级债务条目安排到下一个迭代中。
在每个迭代开始时运行
```
/tech-debt report
```
，以跟踪债务随时间的趋势。

Debt Register Format

债务登记册格式

markdown

undefined

markdown

undefined

Technical Debt Register

Last updated: [Date] Total items: [N] | Estimated total effort: [T-shirt sizes summed]

ID	Category	Description	Files	Effort	Impact	Priority	Added	Sprint
TD-001	[Cat]	[Description]	[files]	[S/M/L/XL]	[Low/Med/High/Critical]	[Score]	[Date]	[Sprint to fix or "Backlog"]

undefined

Last updated: [Date] Total items: [N] | Estimated total effort: [T-shirt sizes summed]

ID	Category	Description	Files	Effort	Impact	Priority	Added	Sprint
TD-001	[Cat]	[Description]	[files]	[S/M/L/XL]	[Low/Med/High/Critical]	[Score]	[Date]	[Sprint to fix or "Backlog"]

undefined

Rules

规则

Tech debt is not inherently bad — it is a tool. The register tracks conscious decisions.
Every debt entry must explain WHY it was accepted (deadline, prototype, missing info)
"Scan" should run at least once per sprint to catch new debt
Items older than 3 sprints without action should either be fixed or consciously accepted with a documented reason

技术债务并非天生有害 — 它是一种工具。登记册用于记录有意识的决策。
每个债务条目必须说明为何接受该债务（截止日期、原型开发、信息缺失等）
"扫描"操作应至少每个迭代运行一次，以发现新的债务
存在超过3个迭代且未采取行动的条目，要么进行修复，要么记录合理理由后有意识地继续保留