Back to Details

managing-tech-debt

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Managing Tech Debt

技术债务管理

Scope

范围

Covers
  • Identifying and making technical debt visible (including user-visible symptoms)
  • Prioritizing debt work using a transparent scoring model
  • Deciding refactor vs migrate vs rebuild vs deprecate with explicit criteria
  • Planning incremental modernization (avoid “rewrite traps”)
  • Building a business case for hard-to-measure investments (metrics + small tests)
  • Creating an execution-ready paydown plan with risks, milestones, and comms
When to use
  • “Create a tech debt register and prioritize what to fix next quarter.”
  • “We’re considering a rewrite/migration—help us make the call and plan it safely.”
  • “Our legacy system slows delivery—build a paydown plan with milestones and metrics.”
  • “Leadership won’t fund refactors—quantify impact and propose a measurable plan.”
When NOT to use
  • You need to respond to an active incident (use incident response/runbooks)
  • You only need to fix a small localized bug or a single refactor (just do the work)
  • You need a full architecture redesign from scratch without existing constraints (separate architecture/design process)
  • You need roadmap prioritization across many product bets (use 
    prioritizing-roadmap
    )
涵盖内容
  • 识别技术债务并使其可视化（包括用户可见的症状）
  • 使用透明评分模型对债务工作进行优先级排序
  • 依据明确标准决定重构vs迁移vs重写vs弃用
  • 规划增量现代化改造（避免“重写陷阱”）
  • 为难以衡量价值的投资构建业务案例（指标+小型测试）
  • 创建可执行的偿还计划，包含风险、里程碑和沟通方案
适用场景
  • “创建技术债务登记册并确定下一季度优先修复的内容。”
  • “我们正在考虑重写/迁移——帮助我们做出决策并安全规划。”
  • “我们的遗留系统拖慢了交付速度——制定包含里程碑和指标的偿还计划。”
  • “领导层不愿为重构提供资金——量化影响并提出可衡量的计划。”
不适用场景
  • 需要响应活跃事件（使用事件响应/运行手册）
  • 仅需修复小型本地化bug或单次重构（直接执行即可）
  • 需要在无现有约束的情况下从零开始进行完整架构重新设计（使用独立的架构/设计流程）
  • 需要在多个产品项目中进行路线图优先级排序（使用
    prioritizing-roadmap
    ）

Inputs

输入项

Minimum required
  • System/service(s) in scope + brief description
  • Primary pain: reliability risk, velocity tax, scalability/perf, security/compliance, operability, UX fragmentation, cost
  • Time horizon (e.g., “6 weeks”, “next quarter”, “12 months”) + any fixed deadlines
  • Stakeholders + decision-maker(s) (Eng/PM/Design/Leadership)
  • Constraints: team capacity, freeze windows, compliance/security requirements
Missing-info strategy
  • Ask up to 5 questions from references/INTAKE.md, then proceed with explicit assumptions.
  • If estimates are unavailable, use ranges and label confidence.
  • Do not request secrets/credentials; use redacted or synthetic identifiers if needed.
最低要求输入
  • 涉及的系统/服务+简要描述
  • 主要痛点：可靠性风险、交付速度损耗、可扩展性/性能、安全/合规性、可操作性、UX碎片化、成本
  • 时间范围（例如：“6周”、“下一季度”、“12个月”）+任何固定截止日期
  • 利益相关方+决策者（工程/产品经理/设计/领导层）
  • 约束条件：团队产能、冻结窗口、合规/安全要求
缺失信息处理策略
  • 从references/INTAKE.md中最多提出5个问题，然后基于明确假设继续推进。
  • 如果无法获取估算值，使用范围值并标注可信度。
  • 不要请求机密/凭证；必要时使用编辑后的或合成标识符。

Outputs (deliverables)

输出项（交付物）

Produce a Tech Debt Management Pack in Markdown (in-chat; or as files if requested):
  1. Context snapshot (scope, pains, constraints, stakeholders, success definition)
  2. Tech Debt Register (inventory table with owners, symptoms, impact, effort range, risks)
  3. Scoring + prioritization (model + ranked list + rationale)
  4. Strategy decision(s) (refactor/migrate/rebuild/deprecate) with explicit criteria
  5. Execution plan (incremental milestones, sequencing, resourcing, decommission plan)
  6. Migration + rollback plan (if applicable; includes “dual-run” cost/plan)
  7. Metrics plan (baseline, targets, leading indicators, instrumentation gaps, small tests)
  8. Risks / Open questions / Next steps (always included)
Templates: references/TEMPLATES.md
生成Markdown格式的技术债务管理包（在对话中；或按需生成文件）：
  1. 上下文快照（范围、痛点、约束条件、利益相关方、成功定义）
  2. 技术债务登记册（包含负责人、症状、影响、工作量范围、风险的清单表格）
  3. 评分与优先级排序（模型+排名列表+理由）
  4. 策略决策（重构/迁移/重写/弃用）及明确标准
  5. 执行计划（增量里程碑、排序、资源分配、停用计划）
  6. 迁移与回滚计划（如适用；包含“双运行”成本/计划）
  7. 指标计划（基线、目标、领先指标、 instrumentation 缺口、小型测试）
  8. 风险/未解决问题/下一步行动（必须包含）
模板：references/TEMPLATES.md

Workflow (8 steps)

工作流程（8个步骤）

1) Intake + decision framing

1) 需求收集与决策框架

  • Inputs: User context; references/INTAKE.md.
  • Actions: Confirm the decision(s) to be made, scope boundaries, time horizon, and constraints. Define what “success” means (e.g., fewer incidents, faster deploys, simpler UX integration).
  • Outputs: Context snapshot (draft).
  • Checks: A stakeholder can answer: “What will we decide/do differently after reading this?”
  • 输入：用户上下文；references/INTAKE.md。
  • 行动：确认需做出的决策、范围边界、时间范围和约束条件。定义“成功”的含义（例如：更少的事件、更快的部署、更简单的UX集成）。
  • 输出：上下文快照（草稿）。
  • 检查项：利益相关方可回答：“阅读此文档后，我们的决策/行动会有何不同？”

2) Surface the “debt symptoms” (user + engineering)

2) 梳理“债务症状”（用户+工程视角）

  • Inputs: Known pain points; incident/perf history if available; qualitative reports.
  • Actions: List user-visible symptoms (inconsistent UX, broken integrations, slow workflows) and engineering symptoms (deploy pain, flaky tests, high MTTR, brittle dependencies). Map symptoms → suspected debt sources.
  • Outputs: Symptoms → suspected causes map (bullet list).
  • Checks: At least 1 symptom is tied to a measurable signal (latency, errors, cycle time, support volume) or explicitly marked “needs instrumentation”.
  • 输入：已知痛点；如可获取的事件/性能历史；定性报告。
  • 行动：列出用户可见的症状（不一致的UX、集成故障、缓慢的工作流）和工程视角的症状（部署困难、不稳定的测试、高平均恢复时间（MTTR）、脆弱的依赖）。将症状映射到疑似债务来源。
  • 输出：症状→疑似原因映射表（项目符号列表）。
  • 检查项：至少有1个症状与可衡量指标（延迟、错误、周期时间、支持量）相关联，或明确标记为“需要 instrumentation”。

3) Build the Tech Debt Register (inventory)

3) 构建技术债务登记册（清单）

  • Inputs: Repos/services/components in scope; symptoms map.
  • Actions: Create a debt register with a consistent schema (type, location, current workaround, impact, risk, rough effort, dependencies, owner). Separate “must fix” from “nice to have.”
  • Outputs: Tech Debt Register (table).
  • Checks: Every item has an owner, an impact statement, and an effort range (even if coarse).
  • 输入：涉及的代码库/服务/组件；症状映射表。
  • 行动：创建具有统一结构的债务登记册（类型、位置、当前临时解决方案、影响、风险、大致工作量、依赖项、负责人）。区分“必须修复”和“可选修复”。
  • 输出：技术债务登记册（表格）。
  • 检查项：每个条目都有负责人、影响说明和工作量范围（即使是粗略的）。

4) Score and prioritize (make trade-offs explicit)

4) 评分与优先级排序（明确权衡）

  • Inputs: Debt register.
  • Actions: Score items on impact and risk (user harm, reliability, security, velocity tax) vs effort and sequencing constraints. Produce a ranked list and explain the top 5–10.
  • Outputs: Scoring model + prioritized list.
  • Checks: Top-ranked items are defensible: rationale references symptoms/signals and constraints, not “taste”.
  • 输入：债务登记册。
  • 行动：根据影响和风险（用户损害、可靠性、安全性、交付速度损耗）与工作量和排序约束对条目进行评分。生成排名列表并解释前5-10项。
  • 输出：评分模型+优先级排序列表。
  • 检查项：排名靠前的条目具有可辩护性：理由参考症状/指标和约束条件，而非“个人偏好”。

5) Decide strategy per top item: refactor vs migrate vs rebuild vs deprecate

5) 为每个高优先级条目决定策略：重构vs迁移vs重写vs弃用

  • Inputs: Top-ranked debt items; constraints; required capabilities (incl. operational flexibility).
  • Actions: For each top item, pick a strategy and document options + criteria. If proposing a rebuild, include a plan to avoid the rewrite trap: migration phases, parallel support cost, cutover and decommission.
  • Outputs: Strategy decision(s) + decision memo(s).
  • Checks: For any “rebuild/migrate” decision, the plan includes a decommission path and acknowledges dual-run cost.
  • 输入：高优先级债务条目；约束条件；所需能力（包括操作灵活性）。
  • 行动：为每个高优先级条目选择策略并记录选项+标准。如果提议重写，需包含避免重写陷阱的计划：迁移阶段、并行支持成本、切换和停用方案。
  • 输出：策略决策+决策备忘录。
  • 检查项：对于任何“重写/迁移”决策，计划中包含停用路径并确认双运行成本。

6) Create the incremental execution plan

6) 创建增量执行计划

  • Inputs: Strategy decisions; constraints; dependencies.
  • Actions: Convert work into milestones (thin slices), define sequencing, and set resourcing/capacity (e.g., % per sprint). Add explicit “done means decommissioned” criteria for migrations.
  • Outputs: Execution plan (milestones + owners + timeline).
  • Checks: Each milestone has a measurable acceptance criterion and a rollback/stop condition.
  • 输入：策略决策；约束条件；依赖项。
  • 行动：将工作转化为里程碑（细粒度切片），定义排序，并设置资源/产能（例如：每个 sprint 投入的百分比）。为迁移添加明确的“完成即停用”标准。
  • 输出：执行计划（里程碑+负责人+时间线）。
  • 检查项：每个里程碑都有可衡量的验收标准和回滚/终止条件。

7) Quantify value: metrics + small tests

7) 量化价值：指标+小型测试

  • Inputs: Baselines (or estimates); execution plan.
  • Actions: Define metrics that make the investment fundable (e.g., incident rate, MTTR, p95 latency, deploy frequency, lead time, cost). Where impact is hard to measure, propose a small test (limited rollout, canary, instrumentation spike).
  • Outputs: Metrics plan (baseline → target → measurement method).
  • Checks: Metrics include at least 1 leading indicator and 1 guardrail; instrumentation gaps are listed with owners.
  • 输入：基线（或估算值）；执行计划。
  • 行动：定义使投资可获得资金支持的指标（例如：事件发生率、MTTR、p95延迟、部署频率、前置时间、成本）。对于难以衡量影响的情况，提议小型测试（有限部署、金丝雀发布、 instrumentation 峰值测试）。
  • 输出：指标计划（基线→目标→测量方法）。
  • 检查项：指标至少包含1个领先指标和1个防护指标；列出 instrumentation 缺口及负责人。

8) Align stakeholders + quality gate + finalization

8) 利益相关方对齐+质量 gates+最终定稿

  • Inputs: Draft pack.
  • Actions: Add stakeholder cadence (updates, review gates). Run references/CHECKLISTS.md and score using references/RUBRIC.md. Finalize Risks / Open questions / Next steps.
  • Outputs: Final Tech Debt Management Pack.
  • Checks: Plan is incrementally executable, risks are explicit, and the first milestone can start immediately.
  • 输入：草稿包。
  • 行动：添加利益相关方沟通节奏（更新、评审 gates）。运行references/CHECKLISTS.md并使用references/RUBRIC.md评分。最终确定风险/未解决问题/下一步行动。
  • 输出：最终技术债务管理包。
  • 检查项：计划可增量执行，风险明确，且第一个里程碑可立即启动。

Quality gate (required)

质量 gate（必填）

  • Use references/CHECKLISTS.md and references/RUBRIC.md.
  • Always include: Risks, Open questions, Next steps.
  • 使用references/CHECKLISTS.md和references/RUBRIC.md。
  • 必须包含：风险、未解决问题、下一步行动。

Examples

示例

Example 1 (quarterly planning): “Use 
managing-tech-debt
. System: payments-service. Pain: frequent incidents + slow delivery. Horizon: next quarter. Output: a Tech Debt Management Pack with a prioritized register and paydown plan.”
Example 2 (rewrite decision): “We want to rebuild our pricing engine. Compare refactor vs rebuild, include migration phases, dual-run costs, rollback plan, and a metrics-based justification.”
Boundary example: “Tell me whether tech debt is bad and how to avoid it.”
Response: explain this skill produces an actionable pack; ask for system + pain + horizon; otherwise provide a minimal intake checklist and an example register schema.
示例1（季度规划）：“使用
managing-tech-debt
。系统：payments-service。痛点：频繁事件+交付缓慢。时间范围：下一季度。输出：包含优先级登记册和偿还计划的技术债务管理包。”
示例2（重写决策）：“我们想要重建定价引擎。比较重构vs重写，包含迁移阶段、双运行成本、回滚计划以及基于指标的合理性说明。”
边界示例：“告诉我技术债务是否有害以及如何避免。” 响应：说明此技能可生成可执行的管理包；请求提供系统+痛点+时间范围；否则提供最小需求收集清单和示例登记册结构。