用 @Docs 与项目 README 约束幻觉：Cursor 文档索引配置与提问模板
Agent 「一本正经地胡说」时，观众爱骂模型；工程上更常缺的是材料与约束：没有版本对齐的文档索引，没有当真相源的 README，提问又允许它「凭印象补全」。幻觉不是道德失败，是检索失败 + 约束失败。
本文实战解决：如何用Cursor 的文档索引（@Docs一类能力）与项目 README约束幻觉——配置原则、README 应写什么、提问模板、验收清单。菜单名称随版本可能叫 Docs / Documentation / 索引，以你的客户端为准；抓住原则即可：外置权威材料、提问强制引用、不知就说不知。
摘要
- 文档要索引且版本对齐；过期文档制造「结构化幻觉」。
- README 当最小真相源：安装、验证、目录、禁区、链接。
- 提问模板四句：材料、问题、约束、输出。
- 回答必须可点开验证；否则当未完成。
- 冲突时声明以哪份为准，禁止静默调和。
结论：约束幻觉的终点是习惯——每次关键回答都要有出处与命令证据。
结论卡
| 手段 | 作用 | 反模式 |
|---|---|---|
@Docs | 外置权威 API/框架文档 | 只靠模型训练记忆 |
| README | 项目级真相与验证入口 | 空洞徽章墙 |
| 提问约束 | 强制引用、禁止臆测 | 「你随便看看」 |
| 验收 | 出处 + 可跑通 | 看起来很对就合并 |
背景与边界
Cursor 支持将文档站点或资源纳入可@的文档上下文（具体添加入口在设置/文档面板）。索引质量取决于 URL 选择、更新频率与问题是否指向正确版本。本文不保证某文档源的爬取覆盖率；不讨论建设完整 RAG 平台（那是另一条开源工具线）。
边界：内部 Wiki 若含密钥，不要一股脑塞进可被模型随意调用的索引；先脱敏。
原理：幻觉从哪来
常见三条路径：
- 训练先验覆盖了你的项目特例；
- 过期文档被当成现行；
- 无材料提问鼓励模型补剧情。
@Docs打的是 1 和部分 2；README 与版本钉扎打的是 2；提问模板打的是 3。三者缺一，黑洞就从缝里钻。
流水线总览
准备 → 索引 → 提问 → 核对。下面按步骤落地。
步骤 1：把 README 写成真相源
建议 README 固定小节（短而真）：
## 快速验证 `pnpm test` 或 `make test`（写真实命令） ## 目录地图 apps/web — ... packages/core — ... ## 常见错误 - Error: ... → 原因与处理 ## 禁止事项 - 不要对生产库使用可写凭据 - 不要提交 .env ## 文档 - 框架官方文档（含版本）：https://... - 内部设计：docs/adr/...不要：只堆徽章；写「极其简单」却无命令；把过期启动方式留在首页。
Agent 第一站读 README，能少搜一半噪音。
步骤 2：配置文档索引
原则：
- 少而准：官方文档入口 + 你们锁定的大版本；不要索引整个互联网。
- 版本对齐：项目用框架 X 的 major，就索引 X 的文档，而非「latest」口头禅。
- 可更新：依赖升级 PR 里同时改文档索引说明。
- 可禁用：大而无关的文档源会变相增加噪音税。
在团队公约写一句：「回答框架行为时，优先@Docs与 README，不得仅凭记忆断言 API。」
若客户端支持本地docs/目录作为索引源，把 ADR 与 runbook 放进版本库，比散落在聊天记录更好。
步骤 3：提问模板四句
## 材料 请基于 @Docs（{文档名}）与 @README 回答；不足时列出缺失材料，不要猜测。 ## 问题 {一个具体行为问题，例如：如何配置某选项？某 API 是否线程安全？} ## 约束 - 关键步骤必须给出文档出处（标题/小节名即可） - 文档未写的部分明确写「文档未说明」 - 若 README 与 Docs 冲突，并列两者并建议以哪份为准（默认：项目 README 的验证命令 > 泛化教程） ## 输出 1. 简短结论 2. 分步操作 3. 风险与版本注意 4. 验证命令把模板存入片段库；关键配置变更强制使用。
步骤 4：幻觉防护验收
对「看起来很对」的回答：
- 关键步骤能否在文档中找到对应段落？
- API/配置名是否与当前 major 版本一致？
- 示例命令是否在本机跑通？
- 是否承认文档未写的部分？
- 冲突是否被显式指出？
任一失败：退回 Ask 追问，或人直接打开文档核对。不要用 Agent 的自信指数当验收。
步骤 5：与 Rules / Ask 评审的配合
- Rules 里只放短铁律：「配置类问题必须引用 Docs/README」。
- 厚文档不要塞进 Always。
- 设计评审（Ask）时，要求选项旁标注「依据文档/依据代码/依据推测」三级标签——推测不得直接进 Agent 执行。
场景示例
问题：某选项在 v4 是否默认开启？
错误姿势：直接问「默认是什么」，无@Docs。
正确姿势：@Docsv4 文档 + README 中的版本声明；若文档含糊，输出「未说明」并建议写实验命令验证。
问题：项目启动报错。
正确姿势：先@README常见错误；再决定是否搜代码。许多「幻觉修复」其实是没读 README 里已有的排障句。
团队化与 AtomGit
开源模板仓可包含：
- 示例 README 骨架；
docs/sources.md列出索引的文档 URL 与版本；- 提示词片段
prompts/ask-with-docs.md。
方便他人 fork 后替换为自己的文档源——这也是 AtomGit 秋季友好的「可复用」姿势。
踩坑
| 坑 | 后果 | 修正 |
|---|---|---|
| 索引 latest 泛文档 | 版本错乱 | 钉 major |
| README 说谎 | 系统性误导 | 把验证命令当测试养 |
| 要求引用但不验收 | 假引用 | 抽查打开出处 |
| 把 Wiki 整库塞进 Always | Token 税+噪音 | 按需@ |
| 冲突时静默调和 | 隐蔽错误 | 强制并列 |
验收标准（本工作流）
- 至少一个真实问题用模板得到「带出处」的答案
- 至少一次抓住「文档未说明」而不是臆造
- README 快速验证命令本周内有人跑通
- 依赖升级 PR 检查了文档索引是否仍对齐
文档索引的治理角色
指定一名轮值「文档管理员」（可以是兼职）：
- 依赖 major 升级时检查索引；
- 每月点开
@Docs抽样一个 API，确认仍存在； - 收集「假引用」案例进复盘。
没有轮值，索引会像无人区规则一样腐烂，然后反过来污染 Agent。
README 驱动的 onboarding 测试
新人第一天任务：只靠 README +@Docs模板，在无老人口述下跑通验证命令。若失败，修 README，而不是口头补课。这是把「约束幻觉」从模型问题扩展到文档是否配得上模型的问题——很多时候，幻觉的根因是人写的入口在说谎。
与 RAG 小工具的边界
本篇聚焦 Cursor 文档索引与 README，不强行上向量库。若内部文档极长，可另文做「开源 RAG 接入 Ask」；原则仍同：出处可点开、版本可钉扎、提问可约束。工具升级，不取消纪律。
配置检查清单（实施）
- 文档源 URL 列表写入
docs/sources.md - 每个源标注框架 major 版本
- README 快速验证命令本周有人执行
- 提示词模板进片段库
- 抽查 3 个回答的出处链接
- 发现假引用记入复盘
把清单贴进 PR 模板的「文档」小节，升级依赖时强制看到。
反幻觉提问的反例与正例
反例：「我们项目分页怎么做的？你应该知道。」
正例：「@README @src/paging.ts 我们项目分页默认页大小是多少？请引用代码或文档；未知请说未知。」
反例：「按最佳实践配置缓存。」
正例：「@Docs 缓存章节与 @README，本项目是否已有缓存约定？列出冲突点。」
正例的共同点是：材料在前，问题具体，允许未知。
当文档错误时怎么办
若验证命令证明官方文档或 README 错了：
- 先以可跑通的现实为准；
- 开 Issue/PR 修 README；
- 向上游文档反馈（若可）；
- 在 Rules 短记「某页文档过时，以 README 验证为准」。
约束幻觉包含约束「错误权威」——权威也要可纠正。
端到端演练脚本（团队工作坊 60 分钟）
- 准备（10 分钟）：选定一个框架 API 问题与一个项目内问题。
- 对照组（10 分钟）：禁止
@Docs/@README，让 Agent 回答。 - 实验组（15 分钟）：使用本文模板强制引用。
- 核对（15 分钟）：打开出处，跑验证命令，记录假引用。
- 复盘（10 分钟）：把结论写进公约：「配置类问题必须带材料」。
工作坊的目标不是羞辱模型，而是让团队看见：同一模型，约束不同，胡说率不同。
docs/sources.md示例
# 文档源 | 名称 | URL | 对齐版本 | 负责人 | 复查日期 | | --- | --- | --- | --- | --- | | Framework X | https://.../v4/ | 4.x | Alice | 2026-10-01 | | 内部 ADR | ./adr/ | 仓库现行 | Bob | 2026-10-01 |升级框架的 PR 必须同步改「对齐版本」与「复查日期」。这比在群里喊「文档更新了哦」可审计。
与 Token 隐形税的关系
索引过多、无关文档常驻，会变成新的前缀税。所以「约束幻觉」不是「索引万物」，而是索引刚好够回答问题的权威。少而准的 Docs + 真话 README，才是长期解。
发布检查（作者写实战文时）
- 文中模板是否可复制；
- 是否声明以客户端版本为准；
- 是否避免虚构 Docs 面板截图里的精确菜单路径；
- 是否提醒内网文档脱敏。
常见问题
Q：没有官方文档的内部系统怎么办？
A：先补 README/ADR，再谈 Agent；不要用模型填补制度空白。
Q：@Docs与网页搜索冲突？
A：配置类以索引版本为准；搜索仅作发现线索，必须回源验证。
Q：模型给出的出处标题找不到？
A：当假引用处理，要求重答或人肉打开文档；记入复盘。
Q：是否要把所有 Markdown 都索引？
A：否。只索引权威与现行；草稿箱不要进。
把 FAQ 附在文末，方便团队检索；也避免重复踩坑。
实践记录表（可放进团队 Wiki）
| 日期 | 问题 | 是否 @Docs/@README | 假引用？ | 命令是否跑通 | 处理 |
|---|---|---|---|---|---|
坚持两周，你会看到：未锚定材料的行更常出现假引用。把表的统计结果发在冲刺周复盘里，比空喊「大家注意幻觉」有效。
与 Ask 设计评审的衔接
设计评审模板里加一行：「依据标签：文档 / 代码 / 推测」。凡关键选项仅有「推测」标签，不得直接进入 Agent 执行，必须先补文档或实验。这样，文档锚定从「答 API 问题」扩展到「做设计决策」，幻觉更难混进方案层。
收尾：今晚三动作
- 给 README 补上真实可跑的验证命令；
- 把本文提问模板存进片段库；
- 用一个真实问题走一遍「材料→引用→跑通」。
三动作完成，你才算接住了「约束幻觉」；只读文章不练习，幻觉仍会在明天的 PR 里报到。
小结
@Docs与 README 不能消灭幻觉，但能把幻觉从「无法审计的自信」变成「可核对的引用」。配置索引、写真话 README、用模板逼出处、用清单做验收——这是编码助手时代的基本识字能力。先锚定材料，再释放 Agent。
草稿未发布 · 作者 梧桐秋海 · 活动：九月创作之星、工具实践
