技术债说明需用可验证事实替代套话：锁定故障日志中的具体错误码、统计紧急回滚次数并标注耗时、附带行号的劣质代码及优化前后链路对比、量化不改代价（频次、人力、风险、失效点）。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
写技术债说明时，常被套话淹没——“历史原因”“资源紧张”“迭代过快”反复出现，导致真实问题被模糊，后续改进无从下手。要让技术债说明真正推动决策，必须把空泛归因转为可验证的事实陈述，用具体现象替代抽象标签。
先锁定技术债的可见症状
打开最近三次线上故障日志，筛选出报错中重复出现的模块名或错误码（如TimeoutException in OrderService#processPayment），直接复制粘贴进文档开头。这比写“支付模块稳定性差”更有锚点——后者是判断，前者是证据。
查Git提交记录，用git log --since="3 months ago" --oneline | grep -i "hotfix\|rollback\|urgent"统计紧急修复次数。若结果大于5次，就在说明里写明：“过去90天内，该服务触发6次紧急回滚，平均每次回滚耗时47分钟”。数字不修饰，不解释“为什么多”，只呈现它客观存在。
用代码片段代替定性描述
方法一：截取一段真实劣质代码，附上注释说明缺陷点。
例如：// 这里硬编码了超时时间（3000ms），但下游PaymentGateway实际SLA是8s，导致重试逻辑失效
方法二：对比重构前后调用链长度。原路径：A→B→C→D→E（5层），优化后：A→X→E（3层）。在说明里画个极简箭头图，旁边标注“链路缩短40%，平均响应P95下降210ms”。不要写“提升了性能”，性能提升是结果，链路缩短是动作，后者才可追溯。
用于在用户想通过浏览器自动化与 Google Gemini 或 ChatGPT 交互时。触发短语包括“ask Gemini”“ask ChatGPT”“ask GPT”“让...”。
【切勿删除原始代码行号】——保留行号能让读者快速定位上下文，删掉就变成脱离环境的抽象批评。
明确写出“不改的代价”而非“改的好处”
第一步：列出当前绕过问题的具体操作。例如，“每次发布需手动执行curl -X POST /api/v1/flush-cache，由运维同学在凌晨2点触发”。
第二步：统计该操作发生频次与人力成本。例如，“近一个月执行14次，单次占用0.5人时，累计7人时”。
第三步：指出风险敞口。例如，“该接口无鉴权，任何能访问内网的机器均可调用，已发现2次非预期调用（见审计日志ID: audit-20240511-88xx）”。
第四步：给出失效临界点。例如，“当前缓存刷新脚本依赖Redis 6.2特性，若基础镜像升级至7.0，脚本将静默失败”。
