别再让 Agent 在你的代码堆里“瞎撞”了：5 组提示词，让它进场就知道先看哪里

cjm_success

487人浏览 · 2026-03-23 09:01:37

cjm_success · 2026-03-23 09:01:37 发布

别再让 Agent 在你的代码堆里“瞎撞”了：5 组提示词，让它进场就知道先看哪里

Desk with laptop, sticky notes, and sunlight.

这是昨天那篇《AGENTS.md 越写越长，Codex 反而越用越笨》的后续。昨天讲为什么，今天直接给操作手册。

你一定见过这个场面。

上午那个 session 刚把仓库脉络摸清，下午换个新窗口，Agent 又从 ls、rg、扫目录、猜入口开始重来。

它看起来很忙。

但真正被烧掉的，往往不是模型能力，而是每个新 session 的开场十分钟。

你以为是模型不够强？

很多时候，不是。

是你的仓库里，还缺一层给 Agent 用的“项目路由”。

它不负责解释每一行实现。

它只负责回答一个问题：

这次任务，先看哪儿？

一句话：

项目路由层不是替 Agent 理解项目，它只是先替 Agent 找到入口。

致命误区：你给的是“说明书”，它要的是“进场路线”

很多团队一看 Agent 发挥不稳，第一反应都是补背景。

项目介绍补一段。

目录说明补一段。

历史坑点再补一段。

最后，一个本来想帮 Agent 的 AGENTS.md，被写成了谁都不想看的项目说明书。

看起来很完整。

用起来很拖沓。

因为对一个新 session 来说，最难受的从来不是信息不够，而是开工前先读了一堆不该先读的东西。

它真正需要的，只有三件事：

1. 这个项目到底在解决什么问题。
2. 这次任务高概率会落在哪几个模块。
3. 哪些区域风险高，必须回代码确认。

写到这里，其实就能看清一件事：

文档负责带路，代码负责定案。

一旦文档开始替代码发言，误导就开始了。

记住：路由层不是知识库，它是 Agent 进入项目后的第一块路牌。

为什么你的 Agent 总在“重复造轮子”？

很多人把这个问题理解成“上下文断了”。

更准确的说法是：你没有把一次次理解，沉淀成能被后续 session 复用的导航资产。

于是，仓库里每天都在重复发生三件事。

第一，重复找路。

入口文件重新找。

测试路径重新找。

高风险区重新找。

看上去是谨慎，实际上大半时间都花在“重新定位”。

第二，复制负担。

不少人喜欢 fork 旧 session，觉得这样能继承理解。

但 fork 过去的，往往不只是项目知识，还有已经膨胀的上下文、已经过时的推断、已经失效的讨论。

第三，文档冒充事实。

一旦某份总结写得太像“真相”，Agent 就容易跳过代码确认。

文档一过期，它就开始带着你往错的方向走。

所以项目路由层最核心的边界，最好第一行就写清楚：

它是用来缩小搜索半径的，不是用来下判断的。

极简导航：一套路由层最少该有的 6 件套

如果你准备从零搭一层，最小可用组合就是 6 个文件。

1. AGENTS.md作用不是介绍业务，而是规定工作协议：先进哪张图，再读哪份索引，动手前要确认什么。
2. docs/ARCHITECTURE.md给一个高层结构地图。项目目的是什么，核心链路怎么走，哪些边界不能随便打穿。
3. docs/MODULE_INDEX.md把“任务描述”往“模块和目录”上落。看到问题以后，先看哪儿，心里要有数。
4. docs/TASK_ROUTING.md这是最实用的一层。它负责把“修 bug”“补测试”“改 schema”这类任务语言，翻译成高概率代码路径。
5. docs/COMMON_PITFALLS.md很多坑不写在函数名里，而写在隐式契约、历史兼容、初始化顺序和 side effect 里。这份文件就是提前打招呼。
6. docs/repo_map.json前面 5 个更像给人看，这一份更像给工具看。把模块、入口、关键词、测试、风险标记做成结构化索引，后续自动化也更好接。

这 6 个文件加在一起，刚好够用。

再少，容易断层。

再多，很容易重新写回“项目百科全书”。

流程化协作：5 组提示词，刚好构成一个闭环

很多人想找一条万能提示词。

但实际用下来，真正能拉开差距的，从来不是一句话写得多花。

而是你有没有把“什么时候用哪一条”固定下来。

这 5 组提示词，建议这样用：

说到底，提示词不是主角。

流程才是主角。

真正稳定的协作，不是某一次回答超常发挥，而是每次都从同一个路口进入项目。

下面这部分建议直接收藏

第一次建层，用提示词 1。

AGENTS.md 没写清楚，用提示词 2。

以后每个新任务开工，先跑提示词 3。

任务做完，顺手用提示词 4 回写更新。

如果文档越来越像说明书，再用提示词 5 做一轮纠偏。

顺序一旦固定下来，后面很多重复消耗就会自己消失。

下面这份手册，建议直接放进你的知识库里。

项目路由层提示词手册

以下提示词示例保留原样，方便直接复制使用。

提示词 1：生成项目路由层（主提示词）

你的任务不是修改业务代码，而是为当前代码仓库生成一套“项目路由层（Project Routing Layer）”文件，供后续的 Codex / agent 快速定位任务相关代码。

## 任务目标

请以“生成项目路由层”为目标，先扫描仓库结构，再重点阅读核心链路、关键入口、测试、配置与高风险区域；不要求穷尽所有实现细节。

请一次性创建或覆盖以下 6 个文件：

1. `AGENTS.md`
2. `docs/ARCHITECTURE.md`
3. `docs/MODULE_INDEX.md`
4. `docs/TASK_ROUTING.md`
5. `docs/COMMON_PITFALLS.md`
6. `docs/repo_map.json`

## 这些文件要解决的问题

这些文件的职责是：
- 帮助后续 agent 快速知道项目做什么
- 帮助后续 agent 快速知道项目结构与模块边界
- 帮助后续 agent 快速识别高风险区域与常见坑
- 帮助后续 agent 将“任务描述”映射到“高概率相关代码路径”
- 帮助后续 agent 缩小代码深读范围
- 强制后续 agent 回到代码、测试、配置、schema 中确认事实

## 非目标（非常重要）

不要把这些文件写成：
- 项目百科全书
- 代码事实源
- 逐函数实现说明
- 详细设计替代品
- 大而全的长篇总结

代码、测试、配置、schema 才是最终事实源。

## 全局要求

### 1. 文档定位声明
每个 markdown 文件开头都必须明确声明：
- 本文档用于项目导航、任务定位和风险提示
- 不作为实现事实的最终依据
- 函数行为、接口签名、字段语义、默认值、依赖关系等必须以当前代码和测试为准

### 2. 写作风格
- 短、硬、可扫描
- 导航价值优先
- 不追求面面俱到
- 避免大段空泛总结
- 避免复述代码细节
- 不确定的内容写“待代码确认”或不写

### 3. 允许写什么 / 不允许写什么
可以写：
- 模块用途
- 大致边界
- 常见入口
- 常见任务涉及路径
- 风险点
- 修改建议顺序

不要写死：
- 未确认的实现细节
- 易过期的具体逻辑描述
- 缺少代码依据的推断

## 各文件要求

### 1) `AGENTS.md`

目标：给未来 Codex / agent 的工作协议，而不是业务实现介绍。

必须包含：
- 项目一句话目标
- 仓库目录与职责概览
- 后续 agent 的默认工作流
- 如何判断任务落在哪个模块
- 高风险区域
- 不要轻易大改的区域
- 常用构建/测试/检查命令（如果仓库中能识别到）
- 强约束：路由层只用于导航；实现事实必须回到代码确认
- “任务开工检查清单”

建议结构：
- Project Purpose
- How to Start
- Repository Layout
- How to Route a Task
- High-Risk Areas
- Safe Working Rules
- Validation Checklist

### 2) `docs/ARCHITECTURE.md`

目标：提供高层结构地图，而不是详细设计文档。

必须包含：
- 系统/项目主要目的
- 核心模块分层
- 高层数据流 / 调用链
- 核心入口点
- 模块级关键依赖关系
- 核心链路与外围模块区分
- 不能轻易打破的边界（若可识别）

不要展开到函数级细节。

建议结构：
- Scope
- Main Layers / Subsystems
- Main Data / Control Flow
- Key Entry Points
- Dependency Boundaries
- Notes for Future Agents

### 3) `docs/MODULE_INDEX.md`

目标：让后续 agent 看到任务后，能迅速定位应该先深读哪些模块、目录、文件。

请按“模块/目录”组织。每个模块尽量包含：
- 模块名 / 目录
- 模块职责（1~3 句话）
- 常见任务会涉及什么
- 关键入口文件
- 高价值类 / 函数 / 脚本
- 上游依赖
- 下游影响
- 修改前建议先读哪些文件
- 典型风险 / 注意事项
- 明确说明：实现细节必须回代码确认

要求：
- 优先覆盖核心模块
- 不追求列全所有文件
- 要突出“任务如何落到这个模块”

建议结构：
- Module Overview Table
- Detailed Module Entries

### 4) `docs/TASK_ROUTING.md`

目标：把“任务描述”映射到“高概率代码路径”，提高首轮定位命中率。

请归纳常见任务类型，例如：
- 新增功能
- 修 bug
- 调整配置
- 改 schema / 请求字段
- 修改数据处理逻辑
- 修改核心算法 / 求解逻辑
- 调整接口层
- 补测试
- 排查性能问题
- 排查依赖/初始化问题
- 排查线上行为与本地不一致问题

对每类任务，尽量使用以下固定结构：
- `First Read`：先看哪些目录/文件
- `Then Check`：再看哪些调用链位置 / 测试 / 配置 / schema
- `Expand Search If`：什么情况下需要扩大搜索范围
- `Common Mistakes`：常见误区
- `Fact Check Reminder`：最终改动点必须以代码阅读结果为准

要求：
- 这是高概率路由，不是绝对规则
- 不要写成教条式流程

### 5) `docs/COMMON_PITFALLS.md`

目标：记录那些代码不一定一眼能看出来、但很容易踩坑的地方。

优先记录：
- 隐式契约
- 历史兼容逻辑
- 名称与真实语义不一致
- 改动一处会波及多处
- 测试覆盖不足但风险高
- 配置与运行行为耦合
- 初始化顺序 / 注册机制 / 全局状态
- 性能热点 / 内存敏感点
- 导入顺序 / side effect / monkey patch
- 生成逻辑与消费逻辑不在同一处

建议每条使用以下结构：
- `Pitfall`
- `Symptom`
- `Why It Is Risky`
- `Related Paths`
- `Check Before Edit`

要求：
- 尽量具体
- 每条附带相关路径
- 不确定时不要臆测

### 6) `docs/repo_map.json`

目标：输出可供后续 agent / 工具读取的结构化路由索引。

请尽量为核心模块/核心文件生成条目。

顶层建议包含：
- `project_summary`
- `generated_from`
- `routing_principles`
- `modules`

其中 `modules` 是数组，每项尽量包含：
- `name`
- `path`
- `purpose`
- `task_keywords`
- `entry_files`
- `key_symbols`
- `upstream_dependencies`
- `downstream_dependencies`
- `related_tests`
- `related_configs`
- `risk_flags`
- `read_before_edit`
- `routing_confidence`
- `expand_search_when`
- `notes`

要求：
- 只写高价值字段
- 不要求 100% 完整
- 必须实用
- 必须面向“定位任务”

## 工作方式要求

请按以下步骤执行：

1. 快速扫描仓库结构
2. 识别核心目录、入口点、测试、配置、文档
3. 对核心链路与高价值入口进行重点阅读
4. 产出上述 6 个文件
5. 自检：
   - 这些文件是否真的在帮助 agent 快速定位？
   - 是否把文档写成了事实源？
   - 是否明确要求后续 agent 回到代码确认事实？
   - 是否出现了过度总结、百科全书化或无代码依据推断？
   - 是否体现了“任务描述 -> 高概率代码路径”的映射价值？

6. Subagent Peer Review：
   - 在完成初稿后，使用 4 个 subagent 并行审查，角色分别为：
     1. 产品经理
     2. 需求分析师
     3. 开发工程师
     4. 测试工程师
   - 每个 subagent 重点检查：
     - 文档是否真的帮助快速定位任务相关代码
     - 文档是否错误承担了事实源职责
     - 是否缺失模块边界、入口文件、任务路径、风险提示、测试入口
     - 是否存在无代码依据的推断
     - 是否存在过度总结、过长、过虚的问题
     - 是否能帮助新 agent 从“任务描述”收敛到“应优先深读的代码路径”
   - 对 subagent 建议的处理规则：
     - 只采纳合理、可解释、最好有代码依据、且符合“项目路由层”目标的建议
     - 不采纳会把文档推向“事实层”“百科全书化”或明显增加上下文负担的建议
     - 对未采纳建议，简要记录原因
   - review 轮数限制：
     - 默认执行 2 轮 review-modify
     - 若第 2 轮后仍存在重大导航问题，可追加第 3 轮，并说明原因
     - 不允许无限迭代
   - 满足以下任一条件即可停止：
     - 4 个 subagent 均未提出重大问题
     - 剩余问题仅是措辞偏好、组织偏好或轻微补充意见
     - 文档已经足以支持后续 agent 快速建立方向感、定位高概率代码路径并回到代码确认事实

### Subagent 输出建议格式
每个 subagent 尽量使用以下结构：
- Role
- Overall Assessment
- What Works
- Major Problems
- Suggested Fixes
- Risk of Over-Documenting
- Risk of Misleading Future Agents
- Final Verdict

## 最终输出要求

最终请额外给出一段简短总结：
- 你识别到的项目主功能
- 你划分出的核心模块
- 后续 agent 最应该先读哪几个文件
- 本轮共进行了几轮 review
- 每个 subagent 的关键建议是什么
- 哪些建议被采纳，哪些未采纳，原因是什么

## 最终验收标准

如果后续一个全新的 Codex session 只读这 6 个文件，它应该能做到：
- 知道项目大概是做什么的
- 知道项目核心结构与模块边界
- 知道常见任务从哪里开始找
- 知道有哪些高风险点
- 知道下一步应该去深读哪些代码
- 但仍然必须回到代码和测试中确认事实

请现在开始执行。

提示词 2：单独强化 `AGENTS.md`（轻量版，可选）

说明：只有在你发现 AGENTS.md 没有把“如何使用路由层”讲清楚时，才需要单独执行这一条。不要再重复完整四角色 review。

请重写或增强 `AGENTS.md`，目标不是介绍项目，而是指导未来的 Codex / agent 如何使用本仓库的“项目路由层”文件。

请确保 `AGENTS.md` 明确规定后续 agent 的默认工作流：

1. 先读 `AGENTS.md`
2. 再读：
   - `docs/ARCHITECTURE.md`
   - `docs/MODULE_INDEX.md`
   - `docs/TASK_ROUTING.md`
   - `docs/COMMON_PITFALLS.md`
   - `docs/repo_map.json`
3. 根据任务先判断：
   - 任务属于哪一类
   - 高概率相关模块是什么
   - 高概率相关路径是什么
   - 哪些区域高风险
4. 然后回到代码中确认：
   - 入口文件
   - 调用链
   - schema / config
   - 相关测试
   - 相关调用方
5. 禁止只根据路由层文档直接修改代码并下结论

请把以下规则明确写进 `AGENTS.md`：
- 路由层文件的目的是导航，不是替代代码
- 实现事实必须以代码和测试为准
- 如果路由层文档与代码不一致，以代码为准
- 修改核心模块前，必须查看相邻模块、测试、配置、schema、调用方
- 对不确定的实现细节，不得依赖文档臆断
- 重要任务完成后，应在必要时回写更新路由层文件

请增加一个“任务开工检查清单”，至少包含：
- 我是否已经识别任务类型？
- 我是否已经看过对应模块索引？
- 我是否已经定位高概率代码路径？
- 我是否已经打开相关测试 / 配置 / schema？
- 我是否已经确认文档不是事实源？

最后做一次轻量自检：
- 是否把 `AGENTS.md` 写成了导航协议，而不是项目介绍？
- 是否明确要求后续 agent 回到代码确认事实？
- 是否避免了冗长复述与重复内容？

请直接修改 `AGENTS.md`。

提示词 3：后续新任务开始时的固定起手词

在开始处理本次任务前，请不要先全仓扫描，也不要先做大范围搜索。

请按以下顺序工作：

1. 阅读项目路由层文件：
   - `AGENTS.md`
   - `docs/ARCHITECTURE.md`
   - `docs/MODULE_INDEX.md`
   - `docs/TASK_ROUTING.md`
   - `docs/COMMON_PITFALLS.md`
   - `docs/repo_map.json`

2. 在读代码前，先输出任务路由判断：
   - 这个项目大致做什么？
   - 本次任务更像哪一类任务？
   - 高概率相关模块是什么？
   - 高概率相关文件路径是什么？
   - 哪些区域可能有隐含风险？
   - 为了确认事实，下一步应该深读哪些代码文件？

3. 然后回到代码中确认：
   - 实现事实
   - 函数签名
   - 调用链
   - 真实依赖
   - 相关测试
   - 配置与 schema

4. 只有在代码事实确认后，才允许提出修改方案。

重要规则：
- 项目路由层文件只用于导航与定位，不作为事实源
- 若文档与代码不一致，以代码和测试为准
- 在没有查看代码前，不要根据文档猜测实现细节
- 在完成代码事实确认前，不要输出修复方案、实现结论或最终改动建议

请先输出你的任务路由判断，再开始读代码。

提示词 4：任务完成后增量更新路由层

本次任务已经完成。现在请不要继续修改业务逻辑，而是检查本次改动是否需要增量更新“项目路由层”文件。

请执行以下步骤：

1. 判断本次改动是否影响以下内容：
   - 模块职责或边界
   - 任务路由路径
   - 常见风险点
   - 关键入口文件
   - `repo_map.json` 中的模块索引
   - 对未来 agent 的导航价值

2. 如果影响，请最小化更新以下文件中的相关部分：
   - `AGENTS.md`
   - `docs/ARCHITECTURE.md`
   - `docs/MODULE_INDEX.md`
   - `docs/TASK_ROUTING.md`
   - `docs/COMMON_PITFALLS.md`
   - `docs/repo_map.json`

3. 更新原则：
   - 只更新被本次任务影响的部分
   - 不进行无关重写
   - 继续保持“导航层”定位
   - 不把文档写成事实源
   - 只补充对未来 agent 有帮助的变化

4. 如果本次改动只影响实现细节、未影响导航价值，请明确说明：
   - 不需要更新路由层文件
   - 原因是什么

5. 最后输出：
   - 哪些路由层文件被更新了
   - 为什么需要更新
   - 这些更新将如何帮助未来 agent 更快定位任务

提示词 5：自检与纠偏

请检查你刚刚生成或更新的项目路由层文件是否存在以下问题：

1. 把文档写成了项目百科全书
2. 把文档写成了代码事实源
3. 大量重复代码细节，导致文档过长
4. 没有明确告诉未来 agent 必须回到代码确认事实
5. 没有把任务语言有效映射到代码路径
6. 没有突出高风险区域与常见坑
7. `repo_map.json` 不够实用，缺乏任务定位价值
8. `TASK_ROUTING.md` 没有区分首读路径与扩搜条件
9. `COMMON_PITFALLS.md` 没有把“症状”和“检查动作”写清楚

如果存在上述问题，请直接修正文件，而不是只口头说明。

修正目标是：
- 更短
- 更硬
- 更实用
- 更强调“导航，而不是裁定事实”
- 更有助于新 session 快速建立方向感并定位到应优先深读的代码