最近在vibe coding时发现即使我写明了具体关联功能，但Antigravity仍然从零开始”探索地图”，浪费大量上下文和时间。于是想给AI一份结构化的”项目导航文档”，让它能快速定位而不是盲目探索，同时必须渐进式披露。通过与Claude、Gemini的探讨，得到了下面的方案。
核心思路：两层结构 + 渐进式披露
问题根因：AI每次任务都从零开始”探索地图”，因为它不知道该去哪里找什么。解决方案是给它一个强制入口，让它”查目录”而不是”逛超市”。
两层结构：
Layer 1：PROJECT_MAP.md（顶层索引）— 极简，只有目录和路由表，AI每次必读
Layer 2：MODULE_*.md（模块详情）— 按需读取，包含具体文件路径、数据库表、接口约定
PROJECT_MAP.md（顶层索引）— AI每次必读，极简，只有目录和关键路径
MODULE_*.md（模块详情）— 按需读取，详细描述各模块的文件、数据库表、接口
第一步：让AI生成 Layer 1（PROJECT_MAP）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
| 请分析当前项目的完整目录结构，在项目根目录下创建 `.ai/` 文件夹，并生成 `.ai/PROJECT_MAP.md` 文件。
## 文件顶部必须原样写入以下内容
### 🛑 AI Agent 强制行为规范
1. 接到任何开发任务，必须第一步读取本文件，禁止直接遍历 /backend 或 /frontend 目录
2. 根据本文件的模块索引，按需读取 `.ai/modules/MODULE_*.md` 获取模块详情
3. 严格遵循：总地图 → 模块文档 → 具体代码文件，三步渐进式定位
### 🚫 禁止操作（未经用户明确授权，以下操作绝对禁止）
- 修改已有数据库表的字段名、字段类型、或删除已有字段
- 修改已有 API 的路径或返回值结构
- 向 git 提交或 push 任何代码
- 直接执行 ALTER TABLE，数据库变更必须通过 Alembic migration 脚本
## PROJECT_MAP.md 正文需包含以下内容
1. 目录结构总览（只展示到第二层，不展开所有文件）
2. 模块快速索引表，格式如下：
| 我要修改…… | 先读这个MODULE文件 | 核心代码目录 |
要覆盖项目中所有业务模块
3. 数据库表速查字典：
| 表名 | 存什么（一句话） | 所属版本 |
所属版本标注该表是哪个版本引入的（如 V2.0 / V4.0 / V4.1）
4. 技术栈速查（前端 / 后端 / 数据库 / 容器各一行）
5. 全局业务规则（以下规则必须包含，可补充）：
- 分母为0或NULL时，显示"-"不报错
- 单枪利用率合计用AVERAGE，不用SUM
- 权限控制仅做前端隐藏，无需后端鉴权细分
- 采集任务全成功或全回滚，不实现重试机制
- 站点删除只删记录，历史数据保留
6. 版本功能对照表：
| 版本 | 新增的主要功能 | 涉及的MODULE文件 |
保持整体精简，不超过150行，现在开始分析并生成。
|
第二步：让AI生成 Layer 2（MODULE文件）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| 请分析项目中与"[在此填写模块名，如：数据采集/爬虫]"相关的所有代码，
在 `.ai/modules/` 目录下生成 `MODULE_[模块缩写].md` 文件。
## 文件需包含以下 Section
### 版本归属
标注该模块是哪个版本引入的，以及在后续版本中有哪些变更。
### 涉及文件清单
列出前端页面、后端路由、service、scraper 等文件路径，每个文件附一句话说明其职责。
### 数据库表
列出该模块强关联的表名、关键字段及其含义，标注字段所属版本。
### 对外API接口
列出该模块暴露的接口，格式：方法 + 路径 + 入参摘要 + 出参摘要。
### 模块间依赖
列出该模块调用了哪些其他模块，以及哪些其他模块会调用本模块。
### 已知的坑 / 高频修改点
总结该模块中容易出错、或经常被新需求牵连修改的地方。
不要贴大量源码，保持文档化风格，整体不超过120行，现在开始分析并生成。
|
第三步：在每次开发任务前，使用这个Prompt模板
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| <instruction>
🛑 停止默认探索机制，进入渐进式开发工作流，严格按以下四步执行：
第一步：读取 `.ai/PROJECT_MAP.md`，不做其他任何事
第二步：根据总地图判断本次任务涉及哪些模块，按需读取 `.ai/modules/` 下对应的 MODULE 文件
第三步：精确读取涉及的具体源码文件，不得读取无关文件
第四步：停止！按以下格式输出修改计划，等待我确认后再动手，未经确认禁止修改任何文件
【修改计划格式】
- 计划新增或修改的文件清单（每项说明改什么）
- 计划新增或修改的数据库表（每项说明改什么）
- 本次修改可能影响到的其他功能（即使需求里没有提到）
</instruction>
## 本次开发任务
### 需求说明
[在此填写你的需求]
### 特别约束
[在此填写本次任务特有的限制，没有则删除此项]
请严格按照上方 instruction 执行，从第一步开始。
|
第四步：地图维护（以下任一情况发生后执行）
此步骤应可升级为Rules、Workflow 或在特定的Skill中执行
触发时机：新增了数据库表、新增了后端路由文件、新增了前端页面、或完成了一个PRD版本的全部功能
1
2
3
4
5
6
7
8
9
10
| <instruction>
项目近期有功能变更，请执行 AI 地图同步维护，严格按以下步骤执行：
第一步：读取现有的 `.ai/PROJECT_MAP.md` 及所有 `.ai/modules/MODULE_*.md`
第二步：扫描近期变动的代码（重点关注 /backend/routes、/backend/db/migrations、/frontend/src/views）
第三步：找出代码与地图文件不一致的地方
第四步：直接覆写更新相关的地图文件
第五步：输出《AI 地图更新日志》，列出本次更新了哪些内容
</instruction>
请从第一步开始执行。
|
第四步升级：封装成 sync-ai-map Skill
把 第四步 封装成 sync-ai-map Skill，然后在 publish Skill 中作为一个步骤调用。
sync-ai-map Skill
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| ## Skill: sync-ai-map
## 描述：同步更新 .ai/ 目录下的项目导航地图，使其与当前代码保持一致
## 触发方式：由其他 Skill 调用，或手动触发
### 执行步骤
1. 读取现有的 `.ai/PROJECT_MAP.md` 及所有 `.ai/modules/MODULE_*.md`
2. 扫描近期变动的代码，重点关注：
- /backend/routes（新增路由）
- /alembic/versions（新增migration脚本）
- /frontend/src/views（新增页面）
3. 找出代码与地图文件不一致的地方
4. 直接覆写更新相关地图文件
5. 输出《AI 地图更新日志》，列出本次更新了哪些内容
### 输出
- 更新后的 .ai/ 文件
- 一份简短的更新日志（供调用方 Skill 汇总展示）
|
使用建议
如果你的 publish Skill 执行时间较长，可以把 sync-ai-map 拆成两个时机：
- publish 开始前：只读、校验地图与代码是否一致，不一致则提示（相当于 pre-check）
- publish 结束后：执行完整同步写入
这样能在发布前就发现”地图已过期”的问题，而不是发布完才更新。