规则精选
能点的仓库地图
改一个仓库前先看清它:点任一模块,看到调用方、依赖、相关测试和源码证据,地图随代码更新。
2,670 X 收藏,截至 发帖日期
提示词
分析当前代码库。不要改产品代码,只创建或更新 docs/codemap/ 下的文件。
忽略 vendor、build、dist、cache 和其他生成出来的目录。
如果 docs/codemap/ 已经存在,先拿现有的 codemap.lock 和当前仓库对比,列出改过的模块,再把下面三个文件一起重新生成:
1. docs/codemap/codemap.html
做一个完全自包含、浏览器直接打开的交互式代码地图,包括:
- 主要模块、服务、数据库、队列和外部依赖
- 主节点不超过 20 个,底层文件归到所属模块下
- 模块之间的调用和数据流
- 最重要的 3-5 条端到端流程
- 默认用清晰的深色主题
- 第一屏就能看到系统边界和最重要的数据流
- 按模块类型上色,配一个简单的图例
- 自动布局,尽量减少连线交叉
- 点任意模块,高亮它的上游调用方、下游依赖、相关测试和所属流程
- 选中一条流程,高亮它的完整路径
- 支持搜索、筛选、缩放和拖动
顶部显示仓库名、生成时间,以及基于哪个 commit 生成。
2. docs/codemap/codemap.json
用这个结构:
{ "generated_at": "", "generated_from_commit": "", "scope": [], "nodes": [], "edges": [], "flows": [] }
每个 node 包含 id、path、role、entrypoints、tests、constraints、evidence。
每条 edge 包含 from、to、type、evidence。type 只能是 imports、calls、reads、writes、publishes、subscribes。
每条 flow 包含 trigger、steps、outcome,每个 step 都要引用已存在的 node id。
每个 node 和 edge 都附上对应的源码路径和符号。没有源码证据的关系标成 unknown,不要猜。
3. docs/codemap/codemap.lock
用能解析的 JSON 记录:当前 commit、工作区有没有未提交的改动、生成时间、扫描范围、排除的目录、指纹算法,以及每个顶层模块的确定性指纹(按它受 git 跟踪的文件路径和当前内容计算)。
找不到现有的 codemap.lock,就把所有模块当成新的,生成完整地图。
做完后确认:
- codemap.json 能正常解析
- 每个 node 的路径都存在,每个 evidence 符号都能在源码里找到
- 每条 edge 和每个 flow step 都引用已存在的 node
- codemap.html 和 codemap.json 用的是同一套 nodes、edges 和 flows
- codemap.lock 和当前 commit、工作区状态、模块指纹一致
- 每个没有源码证据的关系都标成了 unknown
这三个文件必须一起从当前仓库生成,永远不要只手动改其中一个。
最后给我看:创建或修改了哪些文件、哪些模块过期了、还剩哪些 unknown、校验结果,以及完整的 diff。下一步 在项目里把提示词发给 Codex,规则贴进项目的 AGENTS.md。

让 Codex 给你的仓库做一张能点的地图,再标出地图生成之后,哪些模块改过。点任意一个模块,就能看到谁在调用它、它依赖什么、主要流程、相关测试和源码证据。
它会生成三个文件,每次都一起重新生成:
docs/codemap/codemap.htmldocs/codemap/codemap.jsondocs/codemap/codemap.lock
然后让代码地图跟着仓库一起更新。
AGENTS.md 规则
每个要改代码的任务开始时,先拿当前仓库和 docs/codemap/codemap.lock 对比。
改一个模块之前,先用 docs/codemap/codemap.json 回答三个问题:
1. 谁在调用它?
2. 它会影响什么?
3. 哪些测试覆盖它?
地图过期了,或者回答不了这三个问题,就先重新生成 codemap.html、codemap.json 和 codemap.lock,再改代码。
模块边界、依赖、路由、数据库、队列或主要数据流有变化时,在同一个 commit 里同步更新代码地图。