本文目录导读：
- 代码注释标记（最轻量，立即可用）
- 使用静态分析工具（强制检查，自动化）
- 技术债务管理仪表盘（半自动化，团队协作）
- 架构决策记录（ADR - Architecture Decision Records）与债务清单
- 代码仓库规则（自动化收集）
- 总结建议：根据团队体量选择
在 PHP 项目中记录技术债务，核心目标是让债务可见、可追踪、可量化，而不是隐藏起来，以下是几种从轻量级到重量级的实践方案,你可以根据团队规模和项目阶段选择。
代码注释标记（最轻量，立即可用）
这是最基础的方式，适合个人项目或小型团队，通过在代码中留下统一的标记，配合 IDE 或命令行工具扫描,可以快速定位。
标准标记： 在注释中使用关键词 + 描述 + 日期 + 责任人。
<?php
class PaymentService
{
// TODO: [2025-05-20] [张三] 这里应该使用依赖注入，而不是直接 new。
// 当前需要快速修复线上 bug，后续必须重构。
public function process($order)
{
$api = new ThirdPartyApi();
// ... 业务逻辑
}
/**
* FIXME: [2025-05-18] [李四] 这个正则表达式效率极低，会导致内存溢出。
* 目前没有更好的方案，先临时处理，必须优化！
*/
public function parseContent($html)
{
return preg_match('/<div.*?>(.*?)<\/div>/s', $html, $matches);
}
// HACK: [2025-05-15] [王五] 为了兼容 IE6 的遗留问题，这里强行改变了返回值类型。
public function getStatus()
{
return 'success'; // 表面上是字符串，实际业务逻辑期望是布尔值
}
}
扫描工具：
- IDE： PhpStorm 自带 TODO 工具窗口，能自动扫描
TODO、FIXME- 命令行（Composer 脚本）： 在
composer.json中添加脚本，用grep扫描。 - 命令行（Composer 脚本）： 在
{
"scripts": {
"todo": "grep -rn \"TODO:\\|FIXME:\\|HACK:\" src/"
}
}
使用静态分析工具（强制检查，自动化）
这类工具不仅能发现代码风格问题，还能识别出会产生技术债务的代码坏味道,并将结果输出为报告。
推荐工具：
-
PHPStan（级别检查）：通过提升检查级别（Level 0-9），强制代码类型安全，如果你在某处使用了
@phpstan-ignore或@phpstan-ignore-line，它实际上就是在记录债务（一处具体的违规）。vendor/bin/phpstan analyse src --level=5 --memory-limit=1G
-
Psalm：类似 PHPStan,同样支持忽略标记和增量扫描。
-
PHP_CodeSniffer (phpcs)：记录风格和规范问题导致的债务。
如何当作“记录”使用： 将生成的报告（XML/JSON）存档，或者在 CI 中设置“允许失败”的阈值，将警告数量作为“债务基线”记录下来，当警告数量超过基线时，CI 失败,防止债务恶化。
技术债务管理仪表盘（半自动化，团队协作）
如果团队有 Jira 或 YouTrack，不建议在代码里写长描述，代码注释只放 ID,详细背景放项目管理工具。
最佳实践： 代码注释指向 Jira 单号。
// TODO: [JIRA-1234] 重构支付模块，当前逻辑容易死锁。
public function pay() {
// ...
}
在 Jira 中：
- 创建 “技术债” 或 “重构” 类型的 Ticket。
- 在 Ticket 中记录：影响范围、风险等级（高/中/低）、预估修复时间。
- 建立 “技术债待办板”，与普通功能开发分离,每周分配固定时间处理。
优点： 债务有了负责人、优先级和截止日期。
架构决策记录（ADR - Architecture Decision Records）与债务清单
如果债务是由于曾经的架构权衡造成的（非无意为之），建议记录 ADR。
创建 docs/adr/ 目录，每个决策一个 Markdown 文件，模板中包含“接受的后果”一节,这里就是债务。
# ADR-001: 使用 Redis 替代 MySQL 存储会话 ## 状态：已接受 ## 背景：... ## 决策：... ## 接受的后果（技术债务） - **债务描述**：Redis 未开启持久化，重启会导致用户全部掉线。 - **缓解计划**：在未来 3 个月内迁移到 Redis Cluster 并开启 AOF。 - **负责人**：核心架构组 - **验收标准**：重启后会话不丢失。
代码仓库规则（自动化收集）
利用 .editorconfig 和 .env 不强制，但可以通过 Git Hooks 强制提交格式。
推荐方案： 结合 phpstan 基线文件。
PHPStan 允许生成一个基线文件（phpstan-baseline.neon），这个文件记录了所有当前存在的问题。
# 生成基线（记录当前债务） vendor/bin/phpstan analyse src --generate-baseline --level=5 # 后续提交时，PHPStan 会忽略基线中的问题，但一旦你修改了那一行代码，基线失效，新代码必须严格通过。
这种方式非常智能：它允许旧债务存在，但阻止你将旧债务复制到新代码中。
总结建议：根据团队体量选择
| 团队规模 | 推荐方案 | 核心诉求 |
|---|---|---|
| 个人 / 2-3人 | 注释标记（TODO/FIXME）+ PhpStorm | 快速回看 |
| 中型团队（4-10人） | PHPStan 基线 + Jira 任务板 | 防止新增债务，排期解决 |
| 大型团队/长周期项目 | ADR + 静态分析阈值 + 定期“还债日” | 架构成熟度管理，沉淀经验 |
最重要的一点： 债务不是记给别人看的，而是记给未来两周后的自己看的，及时处理掉标记的 FIXME，不要让代码注释变成永久的历史文物——注释过期比没有注释更可怕。
