Tcuzzo Repo Map
Effort: light — 第一次走一遍，之后几乎免费。消除：agent 每个会话都重新推导仓库形状——这是无索引仓库最大的延迟与 token 税。
有索引的代码库可以免费回答“X 在哪里”。大多数仓库没有索引，所以每个 会话都交同一笔税：扫描目录树、重新发现布局、会话结束后全部忘掉。这个 技能只交一次。走一遍目录树，把学到的东西写进一份地图，让后续每个问题 都先读地图，再决定要不要扫描。
什么时候跑
- 第一次进入冷仓库时——没有地图，也没有索引。
- 地图过期时（见下面的过期规则）。
步骤
- 只走一遍目录树。 对真实结构做一次遍历：目录、入口点、各类东西 在哪里。这应该是仓库唯一需要的一次完整扫描。
- 在仓库根目录写一份
CODE_MAP.md。 它包含：- 入口点——执行从哪里开始；
- 各分区与接缝，每项用一行说明用途；
- 测试在哪里；
- 构建、运行和测试命令；
- 热路径——可按历史频率（
git log --name-only）播种，也可留空， 让后续会话补上。
- 保持精瘦。 它是地图，不是文档。每条事实一行。某项长成一段话， 就是在漂成文档——把它砍回一个指针。
- 记录目录树的形状。 在地图中保存一个便宜的指纹：
git ls-files | sha256sum（能抓新增、移动和重命名），让后续会话知道 形状是否改变。
地图优先法则
调研、寻路和 plays 在扫描目录树之前先读地图。只有地图没有答案时，才 回退到原始扫描——而扫描学到的一切，都要在会话继续之前写回地图。地图 吸收每次扫描。重新推导只付一次成本，绝不每个会话都付。
过期规则
只有目录树的形状发生变化时才刷新地图——相对已记录状态，文件被新增、
移动或重命名。把保存的指纹（git ls-files | sha256sum）与实况目录树
比较。绝不按定时器刷新。绝不每个会话刷新。按计划重建的地图，只是换了
名字的每会话税。
硬性规则
- 只写事实与位置，绝不写意见。 “Auth 在
src/auth/”属于地图； “auth 代码很乱”不属于。 - 死指针一发现就死。 已经无法解析的路径，当场修正或删除。会撒谎的 地图比没有地图更糟。
- 地图绝不携带秘密。 不放 key、token、凭据或私有主机名。它是受 版本控制的文件；按这个级别对待它。
搭配使用
- live-research — 调研者先读地图，再读源头。
- wayfinder — 寻路从地图开始，不从冷扫描开始。
- session-handoff — 地图是每个会话共享的交接部分。