technical-debt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Debt

技术债务

Technical debt audit and prioritization framework for PHP/Laravel (MySQL) and Node/TypeScript/React projects. Contains 42 rules across 10 categories covering code, security, design, dependency, test, performance, data, documentation, infrastructure, and process debt. Produces a ranked ledger (effort × impact) so teams know what to fix first, not just what's broken. Supports both coding reference and audit mode with PASS/FAIL/N/A output.

针对PHP/Laravel（MySQL）和Node/TypeScript/React项目的技术债务审计与优先级排序框架。涵盖代码、安全、设计、依赖、测试、性能、数据、文档、基础设施和流程债务10个类别，包含42条规则。生成基于「工作量×影响」的排序清单，让团队不仅知道哪里有问题，更清楚优先修复什么。支持编码参考和审计模式，输出结果分为PASS/FAIL/N/A三类。

Metadata

元数据

Version: 1.0.0
Scope: PHP / Laravel (MySQL) + Node / TypeScript / React
Rule Count: 42 rules across 10 categories
License: MIT

**版本：**1.0.0
**适用范围：**PHP / Laravel（MySQL） + Node / TypeScript / React
**规则数量：**10个类别共42条规则
**许可证：**MIT

How to Audit

审计流程

When the user asks to "audit technical debt", "find tech debt", or "what should we refactor first" — run the checklist below against their codebase and produce a ranked debt ledger.

当用户要求“audit technical debt”“find tech debt”或“what should we refactor first”时，按照以下清单对其代码库进行审计，并生成排序后的债务清单。

Audit Step 1: Determine Scope

审计步骤1：确定范围

If arguments provided (
```
$ARGUMENTS
```
): audit only those paths or modules
If no arguments: audit the entire repository starting from the root

若提供参数（
```
$ARGUMENTS
```
）：仅审计指定路径或模块
若无参数：从根目录开始审计整个代码库

Audit Step 2: Detect Project Stack

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

Inspect

composer.json

and

package.json

to determine which of the supported stacks (PHP/Laravel, Node/TypeScript/React, or both) is in use. Tooling commands (

composer outdated

npm outdated

phpstan

eslint

knip

, etc.) are chosen based on this detection.

检查

composer.json

和

package.json

，确定使用的是哪种支持的技术栈（PHP/Laravel、Node/TypeScript/React，或两者兼有）。根据检测结果选择对应的工具命令（

composer outdated

、

npm outdated

、

phpstan

、

eslint

、

knip

等）。

Audit Step 3: Run Debt Checklist

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

Work through every item below. For each, output:

PASS — brief confirmation of what was verified
FAIL — exact
```
file:line
```
(or command output), description of the debt, effort estimate (S/M/L), and impact (LOW/MED/HIGH/CRITICAL)
N/A — if the check does not apply to this project

逐一检查以下各项，针对每项输出：

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

Code Debt

代码债务

Security Debt

安全债务

Design Debt

设计债务

No circular dependencies between modules/packages
Layers respect direction (UI → service → repository, never reversed)
No "shotgun surgery" patterns (one change forcing edits in 5+ files)
Abstractions hide implementation details (no leaking framework types across boundaries)

模块/包之间无循环依赖
分层结构遵循方向（UI → 服务 → 仓库，不可反向）
无“霰弹式修改”模式（一处变更需修改5个以上文件）
抽象层隐藏实现细节（框架类型不会跨边界泄露）

Dependency Debt

依赖债务

No dependencies more than 2 major versions behind
No abandoned/unmaintained packages (no release in > 24 months)
No known CVEs reported by
```
npm audit
```
/
```
composer audit
```
at HIGH or CRITICAL
No unused dependencies in
```
package.json
```
/
```
composer.json
```

无落后2个以上主版本的依赖
无已废弃/无人维护的包（超过24个月未发布新版本）
```
npm audit
```
/
```
composer audit
```
未报告HIGH或CRITICAL级别的已知CVE
```
package.json
```
/
```
composer.json
```
中无未使用的依赖

Test Debt

测试债务

Critical paths have integration test coverage
No skipped/disabled tests without linked issue or removal date
No known flaky tests left in main branch
Test suite runs in under 10 minutes (or has explicit budget documented)

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

Performance Debt

性能债务

No N+1 query patterns on list endpoints (query count constant per request)
No list endpoint returns an unbounded result set (pagination present)
Frontend initial bundle within budget (~200 KB gzip); route-level code splitting in place
Expensive read paths (aggregations, external APIs, static configs) are cached at a sensible layer

列表端点无N+1查询模式（每个请求的查询次数恒定）
列表端点无无限制结果集（已实现分页）
前端初始包大小在预算内（约200 KB gzip）；已实现路由级代码分割
高开销读取路径（聚合、外部API、静态配置）已在合理层级缓存

Data Debt

数据债务

Migrations are the only source of schema changes; production matches migration history
All foreign-key and frequently-queried columns are indexed
No orphaned child records; FK constraints enforced

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

Documentation Debt

文档债务

README reflects current setup and dev workflow
No stale comments contradicting the code they describe
Public APIs / exported modules have docblocks or type hints

README反映当前配置和开发流程
无与所描述代码矛盾的过时注释
公开API/导出模块有文档块或类型提示

Infrastructure Debt

基础设施债务

Runtime versions (Node, PHP) are on supported (non-EOL) releases
No deprecated framework APIs in use (e.g., Laravel
```
Route::get()
```
deprecations)
Build runs cleanly with zero warnings
Secrets stored in a manager (Vault / Doppler / cloud SM); no long-lived shared credentials
Structured logs, error tracking, p95 latency dashboards, and SLO-based alerts in place

运行时版本（Node、PHP）为支持版本（非EOL）
未使用已废弃的框架API（如Laravel
```
Route::get()
```
弃用项）
构建过程无警告
密钥存储在管理器中（Vault/Doppler/云密钥管理服务）；无长期共享凭证
已部署结构化日志、错误追踪、p95延迟仪表盘和基于SLO的告警

Process Debt

流程债务

No
```
TODO
```
/
```
FIXME
```
/
```
HACK
```
comments older than 6 months without owner or ticket
No
```
@deprecated
```
markers without a removal date or replacement
Debt is tracked somewhere visible (issue tracker label, debt register, ADR)
Every path has an owner (CODEOWNERS file present and current)
No feature flags at 100% rollout for more than 6 weeks without a removal plan

无超过6个月且无负责人或工单的
```
TODO
```
/
```
FIXME
```
/
```
HACK
```
注释
无未指定移除日期或替代方案的
```
@deprecated
```
标记
债务已在可见位置追踪（问题追踪器标签、债务登记册、ADR）
每个路径都有负责人（CODEOWNERS文件存在且为最新）
无100%发布超过6周且无移除计划的功能标志

Audit Step 4: Build the Debt Ledger

审计步骤4：生成债务清单

End the audit with a prioritized table:

undefined

审计结束后输出优先级排序表：

undefined

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
...

#	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)


**Priority formula:** `P0 = CRITICAL impact`, `P1 = HIGH impact`, `P2 = MED`, `P3 = LOW`. Within a priority, sort by ascending effort (cheap wins first).

**Effort scale:**
- **S** = under a day
- **M** = 1–5 days
- **L** = more than a week (likely needs to be broken down)

---

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周（可能需要拆分）

---

When to Apply

适用场景

Reference these guidelines when:

Running a tech-debt audit on a codebase
Planning a refactoring sprint or debt-paydown initiative
Reviewing a PR that introduces shortcuts (and deciding whether to accept them)
Building a debt register or backlog category in your issue tracker
Justifying engineering investment to non-engineering stakeholders
Onboarding to a new codebase and assessing its health
Writing an ADR (architecture decision record) for a debt-related decision

在以下场景参考本指南：

对代码库进行技术债务审计
规划重构迭代或债务偿还计划
审查引入捷径的PR并决定是否接受
在问题追踪器中建立债务登记册或待办事项分类
向非技术干系人说明工程投入的合理性
加入新代码库并评估其健康状况
撰写与债务相关的架构决策记录（ADR）

Step 1: Detect Project Stack

步骤1：检测项目技术栈

Always detect the stack before running tooling. This skill targets PHP / Laravel (with MySQL) and Node / TypeScript / React projects; detection commands below assume one or both are present.

Signal	Stack	Tooling
`composer.json` present	PHP / Laravel	`composer outdated` , `composer audit` , `phpstan` , `phpcs` , `phpmd` , `deptrac`
`package.json` present	Node / JS / TS / React	`npm outdated` , `npm audit` , `eslint` , `tsc --noEmit` , `knip` , `madge`
MySQL connection available	Database	`EXPLAIN` , `sys.schema_tables_with_full_table_scans` , `sys.schema_unused_indexes` , `sys.statement_analysis`
any repo	Secrets scan	`gitleaks git` , `trufflehog`

If both stacks are present (e.g., Laravel + Inertia + React), run audits for each.

运行工具前务必先检测技术栈。本工具针对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），则分别对每种技术栈进行审计。

Rule Categories by Priority

规则分类优先级


code-
security-
design-
deps-
test-
perf-
data-
docs-
infra-
process-

Priority	Category	Impact	Prefix
1	Code Debt	CRITICAL	`code-`
2	Security Debt	CRITICAL	`security-`
3	Design Debt	HIGH	`design-`
4	Dependency Debt	HIGH	`deps-`
5	Test Debt	HIGH	`test-`
6	Performance Debt	HIGH	`perf-`
7	Data Debt	HIGH	`data-`
8	Documentation Debt	MEDIUM	`docs-`
9	Infrastructure Debt	MEDIUM	`infra-`
10	Process Debt	MEDIUM	`process-`


code-
security-
design-
deps-
test-
perf-
data-
docs-
infra-
process-

优先级	分类	影响程度	前缀
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-`

Quick Reference

快速参考

1. Code Debt (CRITICAL)

1. 代码债务（CRITICAL）

```
code-duplication
```
— Detect and consolidate duplicated logic
```
code-complexity
```
— Cyclomatic and cognitive complexity thresholds
```
code-long-functions
```
— Function and method length limits
```
code-god-classes
```
— Class size and responsibility limits
```
code-dead-code
```
— Unused code, unreachable branches, commented blocks
```
code-magic-numbers
```
— Hardcoded literals in business logic
```
code-long-parameter-lists
```
— Functions with too many positional params

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

2. Security Debt (CRITICAL)

2. 安全债务（CRITICAL）

```
security-secrets-in-code
```
— API keys, passwords, tokens in source / history
```
security-input-validation
```
— Endpoints accepting untrusted input without schemas
```
security-auth-hardening
```
— Outdated auth, missing MFA, missing security headers

```
security-secrets-in-code
```
— 源代码/历史中的API密钥、密码、令牌
```
security-input-validation
```
— 接受不可信输入但未使用Schema的端点
```
security-auth-hardening
```
— 过时认证方式、缺少MFA、缺少安全头

3. Design Debt (HIGH)

3. 设计债务（HIGH）

```
design-tight-coupling
```
— Excessive direct dependencies between modules
```
design-circular-deps
```
— Cyclic imports / requires
```
design-leaky-abstractions
```
— Framework types crossing layer boundaries
```
design-shotgun-surgery
```
— Changes that touch many files at once

```
design-tight-coupling
```
— 模块间过度直接依赖
```
design-circular-deps
```
— 循环导入/依赖
```
design-leaky-abstractions
```
— 框架类型跨层边界泄露
```
design-shotgun-surgery
```
— 需要修改多个文件的变更

4. Dependency Debt (HIGH)

4. 依赖债务（HIGH）

```
deps-outdated-versions
```
— Major versions behind on dependencies
```
deps-abandoned-packages
```
— Unmaintained / abandoned libraries
```
deps-security-advisories
```
— Known CVEs in installed dependencies
```
deps-unused-deps
```
— Declared but unused packages

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

5. Test Debt (HIGH)

5. 测试债务（HIGH）

```
test-coverage-gaps
```
— Critical paths without tests
```
test-flaky-tests
```
— Tests with non-deterministic outcomes
```
test-disabled-tests
```
— Skipped tests left in the suite
```
test-slow-tests
```
— Tests blocking fast feedback

```
test-coverage-gaps
```
— 无测试覆盖的关键路径
```
test-flaky-tests
```
— 结果不确定的测试
```
test-disabled-tests
```
— 套件中被跳过的测试
```
test-slow-tests
```
— 阻碍快速反馈的测试

6. Performance Debt (HIGH)

6. 性能债务（HIGH）

```
perf-n-plus-one
```
— Linear request → quadratic database load
```
perf-missing-pagination
```
— Unbounded result sets
```
perf-bundle-bloat
```
— Heavy / unsplit frontend bundles
```
perf-no-caching
```
— Missing cache layers on read-heavy paths

```
perf-n-plus-one
```
— 请求→数据库负载呈线性增长的查询
```
perf-missing-pagination
```
— 无限制结果集
```
perf-bundle-bloat
```
— 过大/未拆分的前端包
```
perf-no-caching
```
— 高读取路径缺少缓存层

7. Data Debt (HIGH)

7. 数据债务（HIGH）

```
data-schema-drift
```
— Production schema diverges from migrations
```
data-missing-indexes
```
— Hot queries doing sequential scans
```
data-orphaned-records
```
— Referential integrity gaps

```
data-schema-drift
```
— 生产环境架构与迁移历史不一致
```
data-missing-indexes
```
— 热点查询执行全表扫描
```
data-orphaned-records
```
— 引用完整性缺失

8. Documentation Debt (MEDIUM)

8. 文档债务（MEDIUM）

```
docs-stale-comments
```
— Comments contradicting current behavior
```
docs-outdated-architecture
```
— README/architecture docs out of date
```
docs-undocumented-api
```
— Public APIs without docblocks or types

```
docs-stale-comments
```
— 与当前行为矛盾的注释
```
docs-outdated-architecture
```
— README/架构文档过时
```
docs-undocumented-api
```
— 无文档块或类型提示的公开API

9. Infrastructure Debt (MEDIUM)

9. 基础设施债务（MEDIUM）

```
infra-runtime-versions
```
— EOL or near-EOL language/runtime versions
```
infra-deprecated-apis
```
— Framework deprecations still in use
```
infra-build-warnings
```
— Build/compile warnings ignored
```
infra-secrets-management
```
— Long-lived credentials, plain env files, leaked logs
```
infra-monitoring-gaps
```
— Missing logs, metrics, traces, alerts, or SLOs

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

10. Process Debt (MEDIUM)

10. 流程债务（MEDIUM）

```
process-todo-fixme-aging
```
— Aging TODO/FIXME/HACK comments
```
process-deprecated-markers
```
—
```
@deprecated
```
without removal plan
```
process-debt-tracking
```
— Debt visible in a register / backlog
```
process-ownership-gaps
```
— Code without an owning team (CODEOWNERS)
```
process-feature-flags-lingering
```
— Stale feature flags polluting code paths

```
process-todo-fixme-aging
```
— 过期的TODO/FIXME/HACK注释
```
process-deprecated-markers
```
— 无移除计划的
```
@deprecated
```
标记
```
process-debt-tracking
```
— 在登记册/待办事项中可见的债务
```
process-ownership-gaps
```
— 无负责团队的代码（CODEOWNERS）
```
process-feature-flags-lingering
```
— 污染代码路径的过时功能标志

Essential Patterns

核心模式

Debt Ledger Output Format

债务清单输出格式

| # | 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       |

| # | 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       |

Effort × Impact Prioritization

工作量×影响优先级排序

              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)

Cheap + high-impact items go first. Expensive items always get broken down before scheduling.

              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)

低成本+高影响事项优先处理。高成本事项在排期前必须拆分。

Tooling Cheatsheet

工具速查表

bash

undefined

bash

undefined

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

composer outdated --direct # 列出过时的直接依赖 composer audit # 已知CVE检查 vendor/bin/phpstan analyse # 静态分析 vendor/bin/phpmd app text cleancode # 代码异味检测

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

npm outdated # 列出过时依赖 npm audit # 已知CVE检查 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 . # lines of code per language

undefined

git log --since="6 months ago" --diff-filter=A -p | grep -E "TODO|FIXME|HACK" cloc . # 按语言统计代码行数

undefined

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

YAML frontmatter with metadata (title, impact, tags)
Brief explanation of why it matters
How to detect (commands / patterns)
Incorrect example with explanation
Correct example or remediation strategy

阅读单个规则文件获取详细说明和代码示例：

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前置内容（标题、影响程度、标签）
简要说明该规则的重要性
检测方法（命令/模式）
错误示例及解释
正确示例或整改策略

References

参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需包含所有扩展规则的完整指南：

AGENTS.md