用 Docs 与项目 README 约束幻觉Cursor 文档索引配置与提问模板Agent 「一本正经地胡说」时观众爱骂模型工程上更常缺的是材料与约束没有版本对齐的文档索引没有当真相源的 README提问又允许它「凭印象补全」。幻觉不是道德失败是检索失败 约束失败。本文实战解决如何用Cursor 的文档索引Docs一类能力与项目 README约束幻觉——配置原则、README 应写什么、提问模板、验收清单。菜单名称随版本可能叫 Docs / Documentation / 索引以你的客户端为准抓住原则即可外置权威材料、提问强制引用、不知就说不知。摘要文档要索引且版本对齐过期文档制造「结构化幻觉」。README 当最小真相源安装、验证、目录、禁区、链接。提问模板四句材料、问题、约束、输出。回答必须可点开验证否则当未完成。冲突时声明以哪份为准禁止静默调和。结论约束幻觉的终点是习惯——每次关键回答都要有出处与命令证据。结论卡手段作用反模式Docs外置权威 API/框架文档只靠模型训练记忆README项目级真相与验证入口空洞徽章墙提问约束强制引用、禁止臆测「你随便看看」验收出处 可跑通看起来很对就合并背景与边界Cursor 支持将文档站点或资源纳入可的文档上下文具体添加入口在设置/文档面板。索引质量取决于 URL 选择、更新频率与问题是否指向正确版本。本文不保证某文档源的爬取覆盖率不讨论建设完整 RAG 平台那是另一条开源工具线。边界内部 Wiki 若含密钥不要一股脑塞进可被模型随意调用的索引先脱敏。原理幻觉从哪来常见三条路径训练先验覆盖了你的项目特例过期文档被当成现行无材料提问鼓励模型补剧情。Docs打的是 1 和部分 2README 与版本钉扎打的是 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 泛文档版本错乱钉 majorREADME 说谎系统性误导把验证命令当测试养要求引用但不验收假引用抽查打开出处把 Wiki 整库塞进 AlwaysToken 税噪音按需冲突时静默调和隐蔽错误强制并列验收标准本工作流至少一个真实问题用模板得到「带出处」的答案至少一次抓住「文档未说明」而不是臆造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不要用模型填补制度空白。QDocs与网页搜索冲突A配置类以索引版本为准搜索仅作发现线索必须回源验证。Q模型给出的出处标题找不到A当假引用处理要求重答或人肉打开文档记入复盘。Q是否要把所有 Markdown 都索引A否。只索引权威与现行草稿箱不要进。把 FAQ 附在文末方便团队检索也避免重复踩坑。实践记录表可放进团队 Wiki日期问题是否 Docs/README假引用命令是否跑通处理坚持两周你会看到未锚定材料的行更常出现假引用。把表的统计结果发在冲刺周复盘里比空喊「大家注意幻觉」有效。与 Ask 设计评审的衔接设计评审模板里加一行「依据标签文档 / 代码 / 推测」。凡关键选项仅有「推测」标签不得直接进入 Agent 执行必须先补文档或实验。这样文档锚定从「答 API 问题」扩展到「做设计决策」幻觉更难混进方案层。收尾今晚三动作给 README 补上真实可跑的验证命令把本文提问模板存进片段库用一个真实问题走一遍「材料→引用→跑通」。三动作完成你才算接住了「约束幻觉」只读文章不练习幻觉仍会在明天的 PR 里报到。小结Docs与 README 不能消灭幻觉但能把幻觉从「无法审计的自信」变成「可核对的引用」。配置索引、写真话 README、用模板逼出处、用清单做验收——这是编码助手时代的基本识字能力。先锚定材料再释放 Agent。草稿未发布 · 作者 梧桐秋海 · 活动九月创作之星、工具实践 用 @Docs 与项目 README 约束幻觉：Cursor 文档索引配置与提问模板
用 Docs 与项目 README 约束幻觉Cursor 文档索引配置与提问模板Agent 「一本正经地胡说」时观众爱骂模型工程上更常缺的是材料与约束没有版本对齐的文档索引没有当真相源的 README提问又允许它「凭印象补全」。幻觉不是道德失败是检索失败 约束失败。本文实战解决如何用Cursor 的文档索引Docs一类能力与项目 README约束幻觉——配置原则、README 应写什么、提问模板、验收清单。菜单名称随版本可能叫 Docs / Documentation / 索引以你的客户端为准抓住原则即可外置权威材料、提问强制引用、不知就说不知。摘要文档要索引且版本对齐过期文档制造「结构化幻觉」。README 当最小真相源安装、验证、目录、禁区、链接。提问模板四句材料、问题、约束、输出。回答必须可点开验证否则当未完成。冲突时声明以哪份为准禁止静默调和。结论约束幻觉的终点是习惯——每次关键回答都要有出处与命令证据。结论卡手段作用反模式Docs外置权威 API/框架文档只靠模型训练记忆README项目级真相与验证入口空洞徽章墙提问约束强制引用、禁止臆测「你随便看看」验收出处 可跑通看起来很对就合并背景与边界Cursor 支持将文档站点或资源纳入可的文档上下文具体添加入口在设置/文档面板。索引质量取决于 URL 选择、更新频率与问题是否指向正确版本。本文不保证某文档源的爬取覆盖率不讨论建设完整 RAG 平台那是另一条开源工具线。边界内部 Wiki 若含密钥不要一股脑塞进可被模型随意调用的索引先脱敏。原理幻觉从哪来常见三条路径训练先验覆盖了你的项目特例过期文档被当成现行无材料提问鼓励模型补剧情。Docs打的是 1 和部分 2README 与版本钉扎打的是 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 泛文档版本错乱钉 majorREADME 说谎系统性误导把验证命令当测试养要求引用但不验收假引用抽查打开出处把 Wiki 整库塞进 AlwaysToken 税噪音按需冲突时静默调和隐蔽错误强制并列验收标准本工作流至少一个真实问题用模板得到「带出处」的答案至少一次抓住「文档未说明」而不是臆造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不要用模型填补制度空白。QDocs与网页搜索冲突A配置类以索引版本为准搜索仅作发现线索必须回源验证。Q模型给出的出处标题找不到A当假引用处理要求重答或人肉打开文档记入复盘。Q是否要把所有 Markdown 都索引A否。只索引权威与现行草稿箱不要进。把 FAQ 附在文末方便团队检索也避免重复踩坑。实践记录表可放进团队 Wiki日期问题是否 Docs/README假引用命令是否跑通处理坚持两周你会看到未锚定材料的行更常出现假引用。把表的统计结果发在冲刺周复盘里比空喊「大家注意幻觉」有效。与 Ask 设计评审的衔接设计评审模板里加一行「依据标签文档 / 代码 / 推测」。凡关键选项仅有「推测」标签不得直接进入 Agent 执行必须先补文档或实验。这样文档锚定从「答 API 问题」扩展到「做设计决策」幻觉更难混进方案层。收尾今晚三动作给 README 补上真实可跑的验证命令把本文提问模板存进片段库用一个真实问题走一遍「材料→引用→跑通」。三动作完成你才算接住了「约束幻觉」只读文章不练习幻觉仍会在明天的 PR 里报到。小结Docs与 README 不能消灭幻觉但能把幻觉从「无法审计的自信」变成「可核对的引用」。配置索引、写真话 README、用模板逼出处、用清单做验收——这是编码助手时代的基本识字能力。先锚定材料再释放 Agent。草稿未发布 · 作者 梧桐秋海 · 活动九月创作之星、工具实践 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
