# Repo Map

> 第一次进入没有索引的冷仓库时用它；地图过期时也用。只走一遍目录树，在仓库根目录写一份 CODE_MAP.md，让后续每个会话都先读地图——地图优先，只有地图没有答案才扫原始目录树。Trigger words: repo map, code map, map first, map-first, index the repo, cold repo, stale map, refresh the map. 中文触发词：仓库地图、代码地图、先看地图、给仓库建索引、冷仓库、地图过期、刷新地图。

- Skill: `tcuzzo/repo-map-7` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tcuzzo/repo-map-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tcuzzo/repo-map-7/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Tcuzzo (https://skillmd.com/u/tcuzzo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tcuzzo/repo-map-7

---


# Repo Map
**Effort:** light — 第一次走一遍，之后几乎免费。消除：agent 每个会话都重新推导仓库形状——这是无索引仓库最大的延迟与 token 税。

有索引的代码库可以免费回答“X 在哪里”。大多数仓库没有索引，所以每个
会话都交同一笔税：扫描目录树、重新发现布局、会话结束后全部忘掉。这个
技能只交一次。走一遍目录树，把学到的东西写进一份地图，让后续每个问题
都先读地图，再决定要不要扫描。

## 什么时候跑

- 第一次进入冷仓库时——没有地图，也没有索引。
- 地图过期时（见下面的过期规则）。

## 步骤

1. **只走一遍目录树。** 对真实结构做一次遍历：目录、入口点、各类东西
   在哪里。这应该是仓库唯一需要的一次完整扫描。
2. **在仓库根目录写一份 `CODE_MAP.md`。** 它包含：
   - 入口点——执行从哪里开始；
   - 各分区与接缝，每项用一行说明用途；
   - 测试在哪里；
   - 构建、运行和测试命令；
   - 热路径——可按历史频率（`git log --name-only`）播种，也可留空，
     让后续会话补上。
3. **保持精瘦。** 它是地图，不是文档。每条事实一行。某项长成一段话，
   就是在漂成文档——把它砍回一个指针。
4. **记录目录树的形状。** 在地图中保存一个便宜的指纹：
   `git ls-files | sha256sum`（能抓新增、移动和重命名），让后续会话知道
   形状是否改变。

## 地图优先法则

调研、寻路和 plays 在扫描目录树之前先读地图。只有地图没有答案时，才
回退到原始扫描——而扫描学到的一切，都要在会话继续之前写回地图。地图
吸收每次扫描。重新推导只付一次成本，绝不每个会话都付。

## 过期规则

只有目录树的形状发生变化时才刷新地图——相对已记录状态，文件被新增、
移动或重命名。把保存的指纹（`git ls-files | sha256sum`）与实况目录树
比较。绝不按定时器刷新。绝不每个会话刷新。按计划重建的地图，只是换了
名字的每会话税。

## 硬性规则

- **只写事实与位置，绝不写意见。** “Auth 在 `src/auth/`”属于地图；
  “auth 代码很乱”不属于。
- **死指针一发现就死。** 已经无法解析的路径，当场修正或删除。会撒谎的
  地图比没有地图更糟。
- **地图绝不携带秘密。** 不放 key、token、凭据或私有主机名。它是受
  版本控制的文件；按这个级别对待它。

## 搭配使用

- [live-research](../live-research/SKILL.md) — 调研者先读地图，再读源头。
- [wayfinder](../wayfinder/SKILL.md) — 寻路从地图开始，不从冷扫描开始。
- [session-handoff](../session-handoff/SKILL.md) — 地图是每个会话共享的交接部分。