在分析代码库技术债、编写债务登记册或评估可维护性时…

对 JavaScript/TypeScript 代码库自动+人工识别代码坏味、架构、依赖、文档、安全等债务，并分类、评级、记录、排期与预防。

适用场景

解决思路

1. 运行自动化脚本检测代码坏味：`python3 scripts/detect_code_smells.py src --output markdown`，识别超过 500 行的大文件、圈复杂度 >10 或超过 50 行的复杂函数、TODO/FIXME/HACK/XXX/BUG 注释、遗留的 console 语句、TypeScript 中的 `any` 弱类型、参数超过 5 个的函数、嵌套超过 4 层的代码、硬编码的魔法数字。
2. 运行依赖分析脚本：`python3 scripts/analyze_dependencies.py package.json`，识别已废弃包（如 request、tslint）、功能重复的包（多个 HTTP 客户端或日期库）、过松或过严的版本约束、已知存在安全问题的包。
3. 在自动化分析之外进行人工代码审查，重点关注：架构债（组件紧耦合、缺少抽象、关注点分离差、循环依赖）、测试债（关键路径缺覆盖、测试脆弱耦合实现、缺少集成/E2E 测试、测试执行慢）、文档债（缺少 README 或安装说明、无架构文档、API 文档过时、重大决策缺少 ADR）、性能债（N+1 查询、低效算法、内存泄漏、包体积过大）、安全债（缺少输入校验、无认证/授权、SQL 注入、XSS、密钥泄露）。
4. 按 9 类标准债务分类整理发现：代码质量债、架构债、测试债、文档债、依赖债、性能债、安全债、基础设施债、设计债（详见 `references/debt_categories.md`）。
5. 按影响与紧迫性评定严重级别：Critical（安全漏洞、生产中断、数据丢失风险，需立即修复）、High（严重性能问题、阻塞功能的架构问题、高风险未测试代码，当前或下个 sprint 修复）、Medium（高频变更文件中的代码质量问题、缺失文档、非安全性的过时依赖，本季度内处理）、Low（轻微代码坏味、优化机会、锦上添花项，方便时处理）。
6. 用优先级矩阵（影响/工作量）排序：高影响低工作量先做，高影响中工作量次之，高影响高工作量需规划后做，中影响低工作量次之，中影响中/高工作量规划后做或考虑，低影响低工作量为快速收益，低影响中工作量为考虑，低影响高工作量避免。
7. 使用 `assets/DEBT_REGISTER_TEMPLATE.md` 创建技术债登记册，每条债务记录包含：编号与标题、类别、严重级别、位置（文件名）、描述、影响（业务/技术/风险）、建议方案、工作量估算、优先级理由、目标解决时间。
8. 登记册包含以下部分：活跃债务项、已解决项、不予修复项（接受的权衡）、趋势分析（按类别/严重级别/年龄）、定期审查计划。
9. 对重大技术决策使用 `assets/ADR_TEMPLATE.md` 编写架构决策记录（ADR），适用场景包括选择框架或库、架构变更、重大重构、技术迁移、性能优化策略；ADR 包含状态、日期、背景、决策、后果（正面/负面/技术债）。
10. 制定修复计划：Critical 项立即加入当前 sprint，High 项纳入 sprint 规划，Medium 项加入季度路线图，Low 项在相关工作中间机修复。
11. 分配时间预算：每个 sprint 容量的 20% 用于技术债，或采用特性 sprint 与债务 sprint 交替，或设立专门的季度“技术健康”sprint。
12. 跟踪进度指标：债务总数（应下降）、按严重级别的债务数（Critical 应为 0）、债务年龄（越老越需关注）、解决率（每 sprint 修复数）、新增债务率（每 sprint 新增数）。
13. 实施预防措施：PR 合并前检查是否引入代码坏味、是否补充/更新测试、是否更新文档（README/注释/ADR）、是否引入安全漏洞、是否考虑性能影响、是否无理由新增依赖、是否遵循团队约定与模式。
14. 配置自动化预防：在 lint 规则中设置 `complexity: ["error", 10]`、`max-lines-per-function: ["error", 50]`、`max-params: ["error", 5]`、`max-depth: ["error", 4]`、`no-console: "warn"`；启用 TypeScript strict 模式、最低测试覆盖率阈值（80%）、禁止高危安全漏洞、强制包体积上限。
15. 建立定期维护节奏：每周审查并分类 TODO/FIXME 注释、更新债务登记册；每月更新依赖（安全补丁）、审查登记册、规划高优先级修复；每季度做全代码库债务分析、架构审查、重大依赖升级、趋势分析与策略调整。
16. 遵循最佳实践：定期运行分析（每周或每两周）、自动化与人工审查结合、优先处理高频变更区域、让团队参与债务识别、保持客观（所有代码库都有债务）；文档要具体（文件名、行号、示例）、解释影响、提出方案、估算工作量、跟踪趋势；修复时立即处理 Critical（尤其安全）、持续分配时间（sprint 的 20%）、庆祝成果、接受渐进改进、预防新债优于修复旧债；沟通时让债务可见、向干系人说明业务影响、争取支持、在 sprint 评审中定期更新、避免指责。
17. 跟踪成功指标：数量指标（债务总数下降、Critical 为 0、每千行代码债务数）、质量指标（测试覆盖率上升、圈复杂度下降、平均文件/函数大小稳定或下降）、速度指标（每 sprint 解决数、每 sprint 新增数应低、解决时间下降）、业务指标（缺陷率下降、特性交付速度上升、开发者满意度上升）。

适用边界 · 注意事项

• 不适用于非 JavaScript/TypeScript 代码库（脚本与依赖分析针对 JS/TS 生态）。
• 不适用于需要立即修复的生产事故——应先止血，再走债务分析流程。
• 不适用于一次性原型或即将废弃的代码，投入债务治理收益低。