technical-debt

技术债务

面向 PHP/Laravel (MySQL) 和 Node/TypeScript/React 项目的技术债务审计与优先级排序框架。包含 10 个类别中的 42 条规则，涵盖代码、安全、设计、依赖、测试、性能、数据、文档、基础设施和流程债务。生成按工作量 × 影响排序的债务清单，让团队知道应该先修复什么，而不只是了解有哪些问题。同时支持编码参考和审计模式，输出 PASS/FAIL/N/A。

元数据

• **版本：**1.0.0
• **范围：**PHP / Laravel (MySQL) + Node / TypeScript / React
• **规则数量：**10 个类别中的 42 条规则
• **许可证：**MIT

如何审计

当用户要求“审计技术债务”“查找技术债务”或“我们应该先重构什么”时，根据以下清单检查其代码库，并生成按优先级排序的债务清单。

审计步骤 1：确定范围

• 如果提供了参数（$ARGUMENTS）：仅审计指定的路径或模块
• 如果未提供参数：从根目录开始审计整个代码库

审计步骤 2：检测项目技术栈

检查 composer.json 和 package.json，确定项目使用了哪些受支持的技术栈（PHP/Laravel、Node/TypeScript/React，或两者）。根据检测结果选择工具命令（composer outdated、npm outdated、phpstan、eslint、knip 等）。

审计步骤 3：运行债务检查清单

逐项检查以下所有内容。对每一项，输出：

• PASS — 简要说明已验证的内容
• FAIL — 精确的 file:line（或命令输出）、债务描述、工作量估算（S/M/L）和影响（LOW/MED/HIGH/CRITICAL）
• N/A — 如果该检查不适用于此项目

代码债务

• 文件之间没有超过 30 行的重复代码块
• 函数不超过 50 行，圈复杂度不超过 10
• 类不超过 300 行，公共方法不超过 15 个（上帝类）
• 源代码中没有遗留不可达代码、未使用的导出或注释掉的代码块
• 业务逻辑中没有魔法数字或未说明含义的字符串字面量
• 函数参数不超过 4 个（使用参数对象）

安全债务

• 源代码（或 git 历史）中没有提交密钥、API 密钥或凭据
• 每个公共端点都通过 schema / FormRequest / DTO 验证输入
• 密码使用 bcrypt 或 argon2id 哈希；不使用 MD5/SHA-1
• 会话有明确的有效期；对身份验证敏感的端点实施速率限制
• 已设置安全标头（CSP、HSTS、X-Content-Type-Options、Referrer-Policy）
• 每条受保护路由都实施授权检查（而不只是身份验证）

设计债务

• 模块/包之间没有循环依赖
• 各层遵循依赖方向（UI → 服务 → 仓库，绝不反向）
• 没有“霰弹枪式改动”模式（一次变更导致需要编辑 5 个以上文件）
• 抽象层隐藏实现细节（不在边界之间泄漏框架类型）

依赖债务

• 依赖项落后不超过 2 个主版本
• 没有已废弃/不再维护的包（超过 24 个月未发布新版本）
• npm audit / composer audit 未报告等级为 HIGH 或 CRITICAL 的已知 CVE
• package.json / composer.json 中没有未使用的依赖项

测试债务

• 关键路径有集成测试覆盖
• 没有未关联问题或未注明移除日期的跳过/禁用测试
• 主分支中没有已知的不稳定测试
• 测试套件在 10 分钟内运行完毕（或有明确记录的时间预算）

性能债务

• 列表端点没有 N+1 查询模式（每个请求的查询数量保持恒定）
• 列表端点不会返回无上限的结果集（已实现分页）
• 前端初始资源包在预算范围内（约 200 KB gzip）；已实现路由级代码拆分
• 耗时的读取路径（聚合、外部 API、静态配置）在合理的层级进行缓存

数据债务

• 迁移是架构变更的唯一来源；生产环境与迁移历史保持一致
• 所有外键列和经常查询的列都已建立索引
• 没有孤立的子记录；已强制执行外键约束

文档债务

• README 反映当前的设置和开发工作流
• 没有与所描述代码相矛盾的过时注释
• 公共 API / 导出模块包含文档块或类型提示

基础设施债务

• 运行时版本（Node、PHP）均为受支持的版本（尚未终止生命周期）
• 没有使用已弃用的框架 API（例如，Laravel 的 Route::get() 弃用项）
• 构建过程顺利完成，且没有警告
• 机密信息存储在管理器（Vault / Doppler / 云 SM）中；没有长期有效的共享凭据
• 已配置结构化日志、错误跟踪、p95 延迟仪表板和基于 SLO 的警报

流程债务

• 没有超过 6 个月且未指定负责人或工单的 TODO/FIXME/HACK 注释
• 所有 @deprecated 标记都注明了移除日期或替代方案
• 债务记录在显眼的位置（问题跟踪器标签、债务登记表、ADR）
• 每条路径都有负责人（存在且内容最新的 CODEOWNERS 文件）
• 没有已 100% 发布超过 6 周且没有移除计划的功能标志

审计步骤 4：建立债务清单

审计结束时，生成一张按优先级排序的表格：

## Technical Debt Ledger

| # | Category | Item | File / Location | Effort | Impact | Priority |
|---|----------|------|-----------------|--------|--------|----------|
| 1 | deps | jQuery 1.12 (8y old, 3 CVEs) | package.json:14 | L | CRITICAL | P0 |
| 2 | code | OrderService god class (820 lines) | app/Services/OrderService.php | M | HIGH | P1 |
| 3 | test | 12 disabled tests in auth/ | tests/Feature/Auth/* | S | HIGH | P1 |
...

## Summary
- **PASS:** X checks
- **FAIL:** Y checks
- **N/A:** Z checks
- **Top 3 to pay down first:** (list highest-priority items with rationale)

优先级公式： P0 = CRITICAL 影响，P1 = HIGH 影响，P2 = MED，P3 = LOW。同一优先级内按工作量从低到高排序（优先处理易完成的事项）。

工作量等级：

• S = 少于 1 天
• M = 1–5 天
• L = 超过 1 周（可能需要拆分）

---

何时使用

在以下情况下参考这些指南：

• 对代码库进行技术债务审计
• 规划重构冲刺或偿还债务计划
• 审查引入权宜做法的 PR（并决定是否接受）
• 在问题跟踪器中建立债务登记表或待办事项类别
• 向非工程领域的相关方说明工程投入的合理性
• 加入新的代码库并评估其健康状况
• 为与债务相关的决策编写 ADR（架构决策记录）

步骤 1：检测项目技术栈

运行工具前务必检测技术栈。 此技能面向 PHP / Laravel（搭配 MySQL）以及 Node / TypeScript / React 项目；以下检测命令假设其中一种或两种技术栈都存在。

信号	技术栈	工具
存在 composer.json	PHP / Laravel	composer outdated、composer audit、phpstan、phpcs、phpmd、deptrac
存在 package.json	Node / JS / TS / React	npm outdated、npm audit、eslint、tsc --noEmit、knip、madge
可连接 MySQL	数据库	EXPLAIN、sys.schema_tables_with_full_table_scans、sys.schema_unused_indexes、sys.statement_analysis
任何代码仓库	机密信息扫描	gitleaks git、trufflehog

如果两种技术栈都存在（例如 Laravel + Inertia + React），请分别运行审计。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	代码债务	CRITICAL	code-
2	安全债务	CRITICAL	security-
3	设计债务	HIGH	design-
4	依赖项债务	HIGH	deps-
5	测试债务	HIGH	test-
6	性能债务	HIGH	perf-
7	数据债务	HIGH	data-
8	文档债务	MEDIUM	docs-
9	基础设施债务	MEDIUM	infra-
10	流程债务	MEDIUM	process-

快速参考

1. 代码债务（严重）

• code-duplication — 检测并整合重复逻辑
• code-complexity — 圈复杂度和认知复杂度阈值
• code-long-functions — 函数和方法长度限制
• code-god-classes — 类大小和职责限制
• code-dead-code — 未使用的代码、不可达分支、注释掉的代码块
• code-magic-numbers — 业务逻辑中的硬编码字面值
• code-long-parameter-lists — 位置参数过多的函数

2. 安全债务（严重）

• security-secrets-in-code — 源代码或历史记录中的 API 密钥、密码、令牌
• security-input-validation — 接受不可信输入但未使用架构进行校验的端点
• security-auth-hardening — 过时的身份验证、缺少 MFA、缺少安全标头

3. 设计债务（高）

• design-tight-coupling — 模块之间存在过多直接依赖
• design-circular-deps — 循环导入 / require
• design-leaky-abstractions — 框架类型跨越层边界
• design-shotgun-surgery — 一次改动触及许多文件

4. 依赖项债务（高）

• deps-outdated-versions — 依赖项的主版本落后
• deps-abandoned-packages — 无人维护 / 已废弃的库
• deps-security-advisories — 已安装依赖项中存在已知 CVE
• deps-unused-deps — 已声明但未使用的包

5. 测试债务（高）

• test-coverage-gaps — 关键路径缺少测试
• test-flaky-tests — 结果不确定的测试
• test-disabled-tests — 测试套件中遗留的跳过测试
• test-slow-tests — 阻碍快速反馈的测试

6. 性能债务（高）

• perf-n-plus-one — 线性请求 → 二次方数据库负载
• perf-missing-pagination — 无界结果集
• perf-bundle-bloat — 臃肿 / 未拆分的前端包
• perf-no-caching — 读取密集型路径缺少缓存层

7. 数据债务（高）

• data-schema-drift — 生产环境架构与迁移内容不一致
• data-missing-indexes — 热点查询执行顺序扫描
• data-orphaned-records — 引用完整性存在缺口

8. 文档债务（中）

• docs-stale-comments — 与当前行为相矛盾的注释
• docs-outdated-architecture — README / 架构文档已过时
• docs-undocumented-api — 公共 API 缺少文档块或类型

9. 基础设施债务（中）

• infra-runtime-versions — 已停止支持或即将停止支持的语言 / 运行时版本
• infra-deprecated-apis — 仍在使用的框架弃用项
• infra-build-warnings — 被忽略的构建 / 编译警告
• infra-secrets-management — 长期有效的凭据、明文环境文件、泄露的日志
• infra-monitoring-gaps — 缺少日志、指标、追踪、告警或 SLO

10. 流程债务（中）

• process-todo-fixme-aging — 长期未处理的 TODO/FIXME/HACK 注释
• process-deprecated-markers — 没有移除计划的 @deprecated
• process-debt-tracking — 在台账 / 待办列表中跟踪的债务
• process-ownership-gaps — 没有负责团队的代码（CODEOWNERS）
• process-feature-flags-lingering — 陈旧的功能标记污染代码路径

核心模式

债务台账输出格式

| # | Category | Item                          | Location              | Effort | Impact   | Priority |
|---|----------|-------------------------------|-----------------------|--------|----------|----------|
| 1 | deps     | guzzle 6.x (5y behind)        | composer.json:18      | M      | HIGH     | P1       |
| 2 | code     | InvoiceService dup logic      | app/Services/Invoice* | S      | MEDIUM   | P2       |
| 3 | test     | 8 skipped tests in checkout/  | tests/Feature/Checkout| S      | HIGH     | P1       |

工作量 × 影响优先级排序

              LOW       MEDIUM    HIGH      CRITICAL
S (<1d)   →   P3        P2        P1        P0
M (1-5d)  →   P3        P2        P1        P0
L (>1w)   →   P3        P3        P2        P1   (break down)

先处理成本低、影响大的事项。安排高成本事项前，务必将其拆分。

工具速查表

# PHP / Laravel
composer outdated --direct          # list outdated direct deps
composer audit                      # known CVEs
vendor/bin/phpstan analyse          # static analysis
vendor/bin/phpmd app text cleancode # mess detector

# Node / TS
npm outdated                        # list outdated deps
npm audit                           # known CVEs
npx depcheck                        # unused deps
npx tsc --noEmit                    # type errors
npx eslint . --max-warnings 0       # lint warnings

# Cross-language
git log --since="6 months ago" --diff-filter=A -p | grep -E "TODO|FIXME|HACK"
cloc .                              # lines of code per language

使用方法

阅读各规则文件，了解详细说明和代码示例：

rules/code-duplication.md
rules/design-circular-deps.md
rules/deps-outdated-versions.md
rules/test-flaky-tests.md
rules/process-todo-fixme-aging.md

每个规则文件包含：

• 带元数据（标题、影响、标签）的 YAML frontmatter
• 简要说明其重要性
• 检测方法（命令 / 模式）
• 错误示例及说明
• 正确示例或修复策略

参考资料

• Martin Fowler — 技术债务象限
• Ward Cunningham — 债务隐喻
• SonarQube — 技术债务模型
• OWASP Dependency-Check
• Snyk 开源漏洞数据库

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md