Vibe-Coding-Rule AGENTS.md

AGENTS.md

Vibe Coding Rule 版本：v4.2.0

速查：六条底线

1. 不伪造成功：真实失败必须显式暴露，不用默认值、空对象、mock、旧链路或跳过检查掩盖。隔离 mock 仅可用于已标明边界的测试或演示，不得冒充真实业务依赖。
2. 完成前必须验证：必须说明实际结果；未完成必要验证时不得声称完成或通过，并写明原因、未覆盖项和剩余风险。
3. 改行为前先记录：用户明确确认新增或变更需求后，改变外部行为、接口、数据、权限、流程或验收前，必须先更新用户确认的唯一需求载体；未更新前不得实施。
4. 不碰敏感信息：不主动读取、打印、提交或传播密钥、凭据、个人敏感信息或未脱敏生产数据；确需处理时须有明确授权并限于最小必要范围。
5. 不擅自改变外部状态：未经用户明确要求，不提交、推送、合并、发布、部署、归档需求记录，不删除、覆盖、迁移数据，不写入生产或外部系统，不触发付费、通知或其他难以恢复的操作。
6. 拿不准就问：用户已指定的需求承接方向与已确认口径冲突，或用户要求判断承接关系但边界不清时，必须停止实施，说明事实、影响和未知项，并请求用户决定后才能继续。

1. 适用范围与优先级

• 外部指令优先级遵循当前运行环境；本文件不能覆盖平台、法律、权限安全约束或用户本轮明确指令。
• 项目内部冲突按“用户已确认的需求事实 → 当前唯一需求载体 → 适用的项目规范 → 工具输出与运行环境”处理；仍无法判断时停止并询问。
• 用户及已确认记录决定需求事实；源码、测试、版本历史、现有行为和代码分析结果只证明代码事实，不能单独定义需求或验收。
• 多级目录存在多个 AGENTS.md 时，优先遵守离目标文件最近且适用的项目规则；无法确定作用域时先确认。
• 修改本规范时，现有条文是审阅对象，不得把它当作阻止修订的前置门禁；敏感信息、权限安全、外部状态和完成前验证约束仍然有效。

2. 内容归属与上下文

• AGENTS.md：AI 常驻规则，保存每次 Chat 都必须知道、读取索引前必须生效、用于判断是否读取 docs/ 或是否允许继续的规则；未经用户明确要求不得修改。
• docs/：长期有效、跨需求适用且按需读取的项目知识，以 docs/README.md 为索引；新增、调整、移动或删除规范时必须同步维护索引。
• OpenSpec change：用户已明确确认的新增需求或需求变更，以及同一需求后续目标、范围、验收、设计、任务、实现记录、验证结果和归档历史。issue、PR、任务卡、设计图与外部文档只作输入来源。
• .agents/：随仓库共享的项目级 skill，以 .agents/README.md 为索引。
• Vibe Coding Rule 规范包自带的受管文档若在标题下带有来源标记，接入或升级业务项目时必须保留；业务项目自行新增、生成或沉淀的文档不得使用该标记，以免混淆归属。
• AI 工具或个人环境默认安装的全局能力、内置 skill、Superpowers 目录及其附带文档，不属于本规范依赖、项目规范或受管文件；仅按当前工具实际能力使用，不得复制、迁移或登记为项目文档，除非用户明确要求并确认归属。
• 本规范只维护 OpenSpec + CodeGraph 的完整接入方式，不维护 Lite、单文件复制、可选工具替代或部分接入分支；业务项目接入和升级按 README.md 的受管范围整体处理。
• 用户提供的经验、素材、偏好或讨论结论，除非明确要求保存并指定或确认归属，否则不得写入仓库文件或 OpenSpec；归属不明确时先询问。
• 业务项目可在 AGENTS.md 维护少量每次 Chat 都必须知道的项目事实，例如技术栈、常用验证命令、源码与测试目录、禁止修改区域；事实必须来自用户确认或项目已有文件，不得猜测补全。
• 项目特有知识通过 docs/README.md 索引按需读取；不得为扩大上下文而批量读取。
• 维护 AGENTS.md 时优先保持短而稳定；低频、条件化或篇幅较长的知识应放入 docs/ 并通过索引触发，不把一次性经验、临时方案或进行中计划塞入常驻规则。
• OpenSpec 与 CodeGraph 的常驻边界以本文件为准；具体使用方法以工作流教程和当前工具实际形态为准。

3. 需求确认与 OpenSpec

• 普通问答、解释、只读分析、代码理解、仓库状态检查、未确认的需求讨论，以及不改变需求口径的内部整理，默认不使用 OpenSpec。本规范自身的审阅和修订按 §1 的例外处理。
• 新增需求、需求变更或已有需求的继续工作，只能由用户明确指定。AI 不得自行分类、要求确认、查找或启动 OpenSpec；用户未指定时，按其直接授权的任务处理。
• 新增需求或新建关联 change 需要用户确认目标、范围和验收口径，并主动授权创建；需求变更或已有需求后续需要用户明确当前 change-id，或确认只读候选中的承接载体。
• 载体未确认、创建授权未取得、候选关系不清或已确认口径冲突时，不得创建、选定或更新 OpenSpec change，不得形成最终设计、计划、实现或冲突口径。
• AI 对承接关系的判断只作事实说明，不构成选定或创建需求载体的授权。
• 直接授权的小改动若实施中发现会改变外部行为、接口、数据、权限、流程或验收，应先停止并说明影响；用户确认按新增需求或需求变更承接后，再回到 OpenSpec 流程。
• OpenSpec 是规格与变更制品层，承载确认后的需求口径、设计、任务、影响分析、验证结果、未验证项和剩余风险；不根据源码猜需求，不替代用户确认。
• OpenSpec 只在用户明确指定新增需求、需求变更、已有需求后续或归档时作为唯一需求载体使用；需要 OpenSpec 却不可用时，中断依赖该工具的部分并说明阻塞点，不得改用 issue、PR、任务卡或其他载体冒充同等证据。
• 跨 Chat 或上下文压缩后继续已有需求时，用户必须明确当前 change-id，或确认 AI 只读查找后列出的候选；确认前不得自动恢复、选定或修改 change。