用途
ponytail-debt 用于把代码库中所有有意为之的“捷径”注释汇总成一份技术债台账。每一处 ponytail 捷径都会用 shortcut: 注释标记，注明其能力上限和升级路径（较旧的代码可能写作 ponytail:）。该工具把这些标记收集到一起，避免某个被推迟的问题悄悄变成永久性问题。
主要能力
- 扫描仓库中的注释标记，跳过 .git 目录以及被 .gitignore 忽略的内容（依赖、构建输出和缓存）。
- 每个命中项生成一行台账记录，按文件分组。
- 从注释中提取能力上限（ceiling）和重新审视的触发条件（upgrade）。
- 对没有写明升级路径或触发条件的标记打上 no-trigger 标签，标识可能悄悄腐化的债务。
- 报告结尾统计标记总数以及其中无触发条件的数量。
- 未发现任何标记时输出：No shortcut debt. Clean ledger.
使用方式
扫描时使用如下命令（如技术栈使用其他注释前缀可自行添加）：
git grep --no-index --exclude-standard -nE '(#|//|/[*]) ?(shortcut|ponytail):'
如果用户指定了自己的标记词（例如 /ponytail-debt TODO），则改为搜索该词。
每个命中项对应一行台账记录。注释前缀可以避免仅仅提及该约定的普通文字被计入台账。需要跳过并非“推迟”性质的命中项，例如关于键盘快捷键的说明。
输出格式为每个标记一行，按文件分组：
<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.
该约定为 shortcut: <ceiling>, <upgrade path>，因此能力上限和触发条件可直接从注释中提取。如果希望每行还带上负责人，可加上 git blame -L<line>,<line>。
适用场景
适用于需要盘点代码库中所有被有意推迟的简化、并希望确保这些推迟不会被遗忘的开发者。适合在代码审查、技术债梳理或项目交接时快速生成一份只读的债务清单。
限制
该工具只读取和报告，不修改任何内容。如需持久化，需要主动要求，它才会把台账写入文件（例如 PONYTAIL-DEBT.md）。它是一次性运行，可通过“stop ponytail-debt”或“normal mode”退出。