代码地图

问题：目录树不等于架构

陌生仓库的难点不是读不到代码，而是把目录树当成模型：入口分散，依赖装配藏在配置里，生成物混进结论，README 和注释互相矛盾。代码地图不做穷举文档，而是用最小证据集建立紧凑、可验证的心智模型。

工作方式：只读取证，再建模

默认把仓库分析视为只读操作：定位根目录，读取适用的 AGENTS.md；不改工作树，不装依赖，不跑迁移，不启动服务，不执行未审脚本。可用盘点脚本扫描结构，需要持久化时用 --output 指定路径。证据从根目录清单、构建或工作区定义、锁文件、部署描述和示例配置开始，再识别入口、公开接口、持久化边界、后台 worker 和外部集成，并用测试、符号引用、定向搜索和 Git 历史交叉验证。

模型按 C4 思路展开但不强套术语：上下文说明问题、用户、外部系统和输入输出；运行单元区分应用、服务、worker、CLI 和数据存储；模块收敛领域或技术边界；代码锚点连接到入口文件、符号、配置、测试或 schema。主图控制在约 6 到 12 个节点，拥挤时拆分视图。

黄金路径按启动装配、主要 API、写入持久化、认证授权、后台任务、故障处理的优先级追踪，注明触发方、入口到结果和关键转换证据，并区分直接调用、配置装配、框架约定和推断关系。热点需要至少两个信号支持，例如 Git 频率、模块大小、依赖中心度、安全边界、测试距离、重复实现、配置漂移或疑似生成物进入关键路径。

边界：结论必须可验证

区分静态推断与运行时观察；仓库不能构建或运行，就继续静态分析，不要宣称生产就绪。供应商代码、缓存、构建、覆盖率和依赖目录不纳入结构性结论；秘密只记录存在和文件名。遇到 AI 生成、复制或未完成项目，要验证入口是否真被引用，区分实现、占位符和 mock 数据，暴露重复服务、废弃路由、未使用配置和并行状态模型。报告通常按项目雷达、架构地图、黄金路径、热点、阅读路线和未决问题输出，长度与仓库规模相称。