SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场technical-debt

technical-debt

编程与开发

查看项目

更新于 10-15 12:40

技能介绍

用途

技术债审计与优先级排序框架，适用于 PHP/Laravel（MySQL）以及 Node/TypeScript/React 项目。它包含覆盖 10 个类别的 42 条规则，涉及代码、安全、设计、依赖、测试、性能、数据、文档、基础设施和流程债。该技能会产出一份排序后的台账（工作量 × 影响），让团队知道先修什么，而不只是知道哪里坏了。它同时支持编码参考和审计模式，审计模式下输出 PASS/FAIL/N/A。

主要能力

审计流程分为四步：

  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（检查不适用于该项目）。
  4. 构建债务台账：以优先级表格结束审计。

检查清单涵盖以下类别与部分规则：

  • 代码债：无超过 30 行的重复代码块、函数不超过 50 行或圈复杂度不超过 10、类不超过 300 行或公开方法不超过 15 个、无不可达代码/未使用导出/注释掉的代码块、业务逻辑中无魔法数字、函数参数不超过 4 个。
  • 安全债：源码（或 git 历史）中无密钥/API key/凭据、每个公开端点通过 schema/FormRequest/DTO 校验输入、密码使用 bcrypt 或 argon2id 哈希、会话有生命周期限制且认证敏感端点有限流、存在安全响应头、每条受保护路由强制执行授权（不仅认证）。
  • 设计债：模块/包之间无循环依赖、分层遵循方向（UI → service → repository，不可反向）、无“霰弹式修改”模式、抽象隐藏实现细节。
  • 依赖债：无依赖落后超过 2 个主版本、无废弃/无人维护的包（超过 24 个月无发布）、npm audit/composer audit 无 HIGH 或 CRITICAL 的已知 CVE、package.json/composer.json 中无未使用依赖。
  • 测试债：关键路径有集成测试覆盖、无未关联 issue 或移除日期的跳过/禁用测试、主分支无已知不稳定测试、测试套件运行时间在 10 分钟以内。
  • 性能债：列表端点无 N+1 查询、列表端点不返回无界结果集（有分页）、前端初始包在预算内（约 200 KB gzip）且有路由级代码分割、昂贵的读路径有合理层级的缓存。
  • 数据债：迁移是 schema 变更的唯一来源且生产环境与迁移历史一致、所有外键和频繁查询列都有索引、无孤立子记录且强制外键约束。
  • 文档债：README 反映当前设置和开发工作流、无与所述代码矛盾的过时注释、公开 API/导出模块有 docblock 或类型提示。
  • 基础设施债：运行时版本（Node、PHP）处于受支持（非 EOL）版本、未使用已废弃的框架 API、构建干净无警告、密钥存储在管理器中、具备结构化日志、错误追踪、p95 延迟仪表盘和基于 SLO 的告警。
  • 流程债：无超过 6 个月且无负责人或工单的 TODO/FIXME/HACK 注释、无缺少移除日期或替代方案的 @deprecated 标记、债务在可见处被追踪、每条路径都有负责人（存在且最新的 CODEOWNERS 文件）、无 100% 灰度超过 6 周且无移除计划的功能开关。

使用方式

审计步骤 4 会生成按优先级排序的技术债台账表格，包含 #、Category、Item、File/Location、Effort、Impact、Priority 等列，并给出 PASS/FAIL/N/A 数量汇总以及“优先偿还的前 3 项”。优先级公式：P0 = CRITICAL 影响，P1 = HIGH，P2 = MED，P3 = LOW；同一优先级内按工作量升序排列（先做便宜的）。工作量分级：S = 一天以内，M = 1–5 天，L = 超过一周（可能需要拆分）。

适用时机包括：对代码库运行技术债审计、规划重构冲刺或债务偿还计划、审查引入捷径的 PR、在 issue tracker 中构建债务登记或 backlog 类别、向非工程相关方论证工程投入、入职新代码库时评估其健康状况、为债务相关决策编写 ADR。

工具速查：

# PHP / Laravel
composer outdated --direct
composer audit
vendor/bin/phpstan analyse
vendor/bin/phpmd app text cleancode

# Node / TS
npm outdated
npm audit
npx depcheck
npx tsc --noEmit
npx eslint . --max-warnings 0

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

单个规则可阅读对应文件（如 rules/code-duplication.md、rules/design-circular-deps.md 等），每个规则文件包含 YAML frontmatter 元数据、为何重要的简要说明、检测方式、错误示例与正确示例或整改策略。完整指南见 AGENTS.md。

适用场景

适用于 PHP/Laravel（MySQL）和/或 Node/TypeScript/React 项目，尤其适合需要评估代码健康、规划重构优先级、向非工程相关方论证投入、入职新代码库或构建债务登记的场景。

限制

元数据：版本 1.0.0，范围限定为 PHP/Laravel（MySQL）与 Node/TypeScript/React，共 42 条规则、10 个类别，许可证为 MIT。价格、收费等商业信息暂未提供。