Tech Debt Map 是一个技术债诊断技能，用于为一个模块生成债务地图：一份按优先级排序、有证据支撑的“当前最糟问题”清单，以及按小步切片修复的计划。
用途与定位
该技能刻意一次只处理一个模块。作者认为覆盖整个项目的地图没人会真正执行，横跨所有代码的重构也没人愿意启动；项目通过“逐个模块、长期覆盖”的方式逐步清完，并由一份已提交的评审索引记住每个模块上次被查看的时间。
本技能只做诊断，不做重构：运行过程中不修改任何代码。交付物是一份文件，用户可在数周内逐项处理，并在之后重跑以观察变化。它与相邻技能分工明确：/improve-codebase-architecture 聚焦一类问题（浅模块）并以单个候选的追问讨论收尾；/review-axes 评判一次 diff；本技能则对一个模块做全维度扫描，最终产出一份书面地图。
流程
-
划分模块。先检测项目是否已有模块划分，按顺序尝试：声明式（构建清单与项目文件，如各语言 workspace、apps/packages/services 目录树、解决方案下的项目文件、Maven/Gradle 模块、Django apps）；源码布局（源码根下具有业务含义的顶层目录，而非仅按技术分层）；领域（依据 GLOSSARY.md 词汇与代码命名提出的划分，忽略文件夹位置）。同时阅读 GLOSSARY.md、ADR 以及 CLAUDE.md/AGENTS.md；ADR 已记录的决策视为已定，不算发现。团队不拥有的内容排除在外：vendored 代码、生成文件、lockfile、构建产物、已应用的迁移。每个模块获得名称、路径 glob 集合以及来源（声明式或提议式）；提议式划分需明确告知用户这是假设，请其纠正。若存在 docs/tech-debt/README.md，则以其为划分的事实来源：磁盘上新增的模块标记为从未评审；路径全部消失的模块标记 removed 并保留记录；疑似重命名或合并的模块需向用户确认。
-
选择一个模块。列出模块并按“距上次评审时长 × 期间变更量”排序，从未评审的排最前；用 git log 统计变更提交数并展示原始列，便于用户用同样数据质疑排序。若模块过大（实际等同整个源码树，或代码量超出四个子代理可精读的范围），应说明并提出子划分，返回本步骤。一次只选一个模块。
-
扫描。并行派发四个子代理，各读 AXES.md 中对应章节，只返回发现、不给修复：Structure（Architecture、Maintainability）、Code（Code、Testability）、Business rules、Runtime（Performance、Security and robustness）。每个子代理最多返回 5 条排序发现，每条给出证据（实际阅读并引用的文件行号范围，不得靠文件名或目录结构推断）、代价（因该问题而更难或更有风险的具体事项，无代价的属风格偏好，排除在外）、影响范围（该处变动还牵动什么）。需读模块边界而不只是内部，调用方与被调用方作为证据纳入范围；但只有证据位于本模块所拥有的文件时才可成条，模块外文件可在描述中点名。
-
询问只有团队知道的事。汇总需验证的发现，以编号、简短问题加最可能猜测的形式一次性批量询问，然后等待。答案成为地图中记录在案的决策；回答“不知道”的发现不进入排名表，保持 needs-validation 并携带原问题与可回答者。确保不存在既未回答又被排名的发现。
-
撰写地图。先读该模块最新既有报告：已修复的发现标注 resolved 并附修复提交，而非删除。若无历史报告，则读取索引中的 Findings 台账，逐行复核 open 项，已消失的标 resolved 并用 git log 找提交。合并四份报告、去重、剔除无法说明代价的项，最多保留 10 条，未入选者以一行计数带过。写入 .scratch/tech-debt-map/<module-slug>/<YYYY-MM-DD>.md，每次评审一个新文件，内容包括：范围（模块、globs、来源、刻意排除项）；按“收益 vs 影响范围”排序的表（列：编号、发现、位置、维度、严重度、影响范围、收益）；每行一个详情块（问题、为何有害并附示例、证据行号与必要引用、最小改动策略）；未决问题；已记录决策。
-
规划清理。以分阶段计划收尾，每阶段只列行号并加一句顺序说明：Phase 1 影响范围 Contained 的高收益项（本周可安全上线）；Phase 2 提升最差代码可读性的重构，一次一个接缝；Phase 3 需先做设计决策的项，Systemic 项需标注（其影响超出本模块，不由本模块单独排期）。再以一行指出下个功能落地前必须清掉的行及其原因，防止因排序靠后而被忽略。护栏（lint 规则、检查、实践）不放入阶段，而记入索引。
-
记录与交接。更新 docs/tech-debt/README.md 评审索引（模块、路径、来源、上次评审、报告、Open 数），首次创建前需以一行告知用户。索引下方维护 Findings 台账（每模块一张子表：编号、发现、首次发现、状态 open 或 resolved(提交)），以及跨运行只追加不改写的 Guardrails 章节。报告保留在 .scratch/（通常 gitignore），仅摘要提交。随后告知报告路径与前三条，并建议（不代为执行）对值得行动的条目使用 /to-spec 再 /to-tickets 拆分，对 Systemic 影响范围的条目使用 /improve-codebase-architecture。
规则要求
只报告代码当前行为，声称前先读代码；每条发现必须说明代价；看似异常但可能是有意为之的（尤其业务规则）标为 needs-validation 并在第 4 步询问；策略须保持行为不变且可增量完成；划分即契约，一旦写入索引，后续评审均以其为准，改划分须走第 1 步重命名而非私自重画；尊重仓库既有约定与约束。