代码库结构地图

要解决的问题

刚接手陌生代码库时，最贵的成本不是写代码，而是建立结构认知：有哪些模块、各自干什么、从哪读起。但顶层包结构会骗人——ls 出来的目录不等于模块边界。伞形包把多个业务域揉在一起，扁平分层让多个模块共享 service/dao/po 同包，仅凭名字和目录数推断会一路踩坑。而读者手中没有可信的标准答案，拿到的往往是一份几周就过时的分析报告。

核心思路：慢变纪律

产物是一份活文档（docs/codebase-map.md），不是给分析师看的报告。它只写抗重构的慢变结构：模块边界与职责、依赖的形状与方向、入口与横切约定。行号、精确文件计数、随提交而变的 impact 一律排除——不是不重要，而是写进去会让地图快速过时。度量数字翻译成读者结论，全文不超过约 8 处。

怎么工作

• 信号配方层：不携带 16 份硬编码栈配方，而是通用信号槽模型（模块单元、导入依赖边、依赖装配、入口点、横切件……）加语言无关的入口名模式，换栈时按槽派生该栈的 grep 写法。
• 能力① 模块测绘：严格分步。1.A 机械采集依赖边（Bash grep）；1.B 智能归子模块（扁平分层靠类名前缀加锚实体交叉判定）；1.C 强度分档（Injected / Import-only / Adapter，@Lazy 不降档）；1.D 标注反向异味。
• 能力⑤ 约定与横切机制：识别请求先过谁（AOP / middleware / 拦截器），测绘认证、错误、日志、配置、事务、缓存六类约定，每条给出定义锚点加一句遵守规则。
• 校准闸门：锚点路径落笔前必须整串反查；「无 X」类断言要过完整性闸逐项反证；拿不准的边界标低置信，并提示对该模块单独深入精读。

适用边界

地图测的是「广」。把某个模块逐行读透属于地图之外的事，技能只在地图里标出值得深读的模块，不替读者执行。机械采集可以脚本化，但归并、判强度、识别反向异味是 agent 的智能任务，不会被硬编码进脚本。它自包含闭环，不读写任何其它 Skill。