本文目录导读：
- 第一层：代码级登记（最推荐，最贴近实际）
- 第二层：结构化表格登记（适用于规划类债务）
- 第三层：集成到工作流（DevOps 与 IDE）
- 第四层：核心管理原则（避免变成形式主义）
- 总结：针对 PHP 项目的落地建议方案
在 PHP 项目中做“技术债务登记”，核心不是找一个复杂的工具，而是建立一个“持续记录”的惯例，技术债务的本质是“已知的、未来需要修复的妥协”。
以下是针对 PHP 项目的技术债务登记实战指南，分为工具选择、代码级登记和流程管理三个层面。
第一层：代码级登记（最推荐，最贴近实际）
这是 PHP 开发者最习惯、成本最低的方式，通过代码注释标记,让债务跟着代码走。
标准注释标记 （@todo / @fixme / @deprecated）
在 PHP 类、方法或逻辑处直接标记，为了便于统计，建议强制使用前缀。
<?php
class PaymentService
{
/**
* 处理支付回调
*
* @todo [TD-20231005] 这里的 MD5 签名算法已过期，需迁移到 HMAC-SHA256，当前为了兼容旧商户暂保留。
* @fixme [TD-20231006] 在高并发下，此处数据库连接未复用，导致连接池耗尽。
* @deprecated 1.5.0 请使用 handleV2() 替代，该方法将在 2.0 版本移除。
*/
public function handleCallback(array $data): bool
{
// 临时实现：为了赶上线，先硬编码了状态。
return true;
}
}
升级：使用 @td 或 @technical-debt 自定义标签
如果团队对 @todo 已经麻痹（到处都是 todo），可以自定义标签，配合 IDE 插件（如 PHPStorm 的 TODO 工具）可以过滤查看。
// @technical-debt 查询条件未加索引，大数据量下全表扫描（涉及表：orders）
$this->db->where('user_id', $uid)->get('orders');
代码扫描工具集成：PHPStan / Psalm
利用静态分析工具配置 基线（Baseline）。这是最优雅的登记方式——让静态分析器强制记住这个债务。
- 当你写了一段不够严谨的代码（比如没有类型声明），不要屏蔽它,而是让它进入基线文件。
- 操作：运行
vendor/bin/phpstan analyse --generate-baseline，它会生成phpstan-baseline.neon文件。 - 效果：这个文件就是债务清单，每次 CI 检查时，只能减少，不能增加（新增违规会导致 CI 失败）。
# phpstan-baseline.neon
parameters:
ignoreErrors:
-
message: '#Access to an undefined property#I'
path: src/Controllers/Legacy/UserController.php
第二层：结构化表格登记（适用于规划类债务）
这类债务通常不是“这段代码烂”，而是“这个系统架构需要重构”或“某个模块缺测试”。
建议在项目根目录维护一个 TECH_DEBT.md 文件（Markdown 表格）。
# 技术债务登记表 > 维护者：技术委员会 > 规则：每季度审视一次，新增需评审，修复需销账。 | ID | 创建日期 | 债务描述 | 影响范围 | 预计工作量 | 提出人 | 状态 | 关联里程碑 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | TD-001 | 2023-08-01 | 支付模块 SQL 语句拼接，存在注入风险 | 支付系统 | 8h | 张三 | 🟡 评估中 | v2.1 | | TD-002 | 2023-08-15 | 尚无可观测性框架，排查问题低效 | 全项目 | 2d | 李四 | 🟢 已计划 | v2.2 | | TD-003 | 2023-09-01 | 订单状态机逻辑分散在 Controller 中 | 订单服务 | 4d | 王五 | 🔴 已确认 | v2.3 |
在 PHP 项目中，表格的存放建议：
如果是单体项目，放在项目根目录；如果是 Monorepo（多仓库），放在 docs/architecture/tech-debt/ 下。
第三层：集成到工作流（DevOps 与 IDE）
登记了如果没人看，就是废纸，以下是如何让登记“活”起来：
IDE 快捷方式（PHPStorm）
- 在
Preferences -> Editor -> TODO中添加自定义模式：\b@td\b或\btechnical-debt\b。 - 这样在代码底部点击 TODO 面板,即可过滤所有债务标记。
Git 提交钩子（Husky / Pre-commit）
如果团队过于健忘，可以在 Pre-commit 钩子里写一个脚本，禁止新增包含高风险注释的代码（或者至少提示确认）。
#!/bin/bash
# .git/hooks/pre-commit
# 检查是否包含 HACK 或者非常规的 FIXME（仅针对 PHP 文件）
if git diff --cached --name-only | grep '\.php$' | xargs grep -n 'FIXME' 2>/dev/null; then
echo "⚠️ 请移除 FIXME 注释后再提交，或将其转移至 TECH_DEBT.md 表格登记。"
exit 1
fi
结合 Issue Tracker（Jira / 禅道）
技术债务需要和业务需求抢排期，建议在 Jira 等工具中设置一个单独的 `技术债务（Tech Debt）看板。
- 触发条件：当你写代码时发现一个问题需要 2 小时以上解决，立刻在 Jira 创建子任务。
- 关联：在 TECH_DEBT.md 的表格里加上对应 Issue 链接,形成闭环。
第四层：核心管理原则（避免变成形式主义）
-
区分“债务”与“糟糕代码”：
- 债务：你清楚知道要修，并且计划在某个版本修（有临时规避方案）。
- 糟糕代码：没有人在意，直接删了重写那种，糟糕代码不属于债务，属于代码腐化，建议直接重构,不进这张表。
-
明确责任人：每条债务必须有一个 “债主”（提出人）,没有责任人的债务会被遗忘。
-
设置“利息”衡量标准：登记时记录“如果不修复会带来什么持续损失”？
TD-002 每天发布耗时 30 分钟，影响效率，这样在排期时,管理层有量化依据。 -
“永不空手”回顾：在每个 Sprint 计划会议上，强制要求读取
TECH_DEBT.md的前 3 条，花 5 分钟决定是否要安排 20% 的容量来进行“还债”。
针对 PHP 项目的落地建议方案
假设你负责一个结构尚可的 Laravel / Symfony 项目,我推荐这个组合：
- 代码注释：使用
@td标签标记局部的、逻辑复杂的临时方案（临时绕过某个 Bug）。 - 静态分析基线：配置 PHPStan 级别 8 并生成基线文件。这是最有效的方式，一旦引入，CI 会强制你面对它。
- Markdown 表格：使用
TECH_DEBT.md记录架构级的重构需求（将 Redis 从单机迁移到集群）。 - README 链接：在
CONTRIBUTING.md中声明：“所有贡献者，遇到代码妥协，必须登记，否则视为流程违规”。
这样，技术债务从“潜意识的赎罪感”变成了“可量化的开发资产”。
