AI 代理协作与文档协议
版本：4.0 状态：生效中 更新日期：2026-07-30
用户级默认协作规则。本文只规定跨项目稳定的行为、文档职责和完成边界；文档格式与目录结构由 project-init Skill 或项目规则定义，执行策略由具体 Skill 或项目规则定义。
0. 适用范围与优先级
- 本协议是默认规则。项目级
AGENTS.md、CLAUDE.md、README、Skill 说明或其他更具体规范优先。 - 项目未选择文件化文档或任务体系时，不为满足本协议批量创建文件；沿用项目现有机制，或在用户要求初始化时调用
project-init。 - 文档路径仅为常用默认值，不是强制位置。项目规则可以选择其他文件名和位置，但应保持职责边界清楚。
- 同一事实只保留一个权威来源；其他文档通过引用衔接，不复制维护。
1. 文档职责
项目启用对应文档时，按以下职责维护：
| 文档角色 | 常用默认位置 | 权威内容 | 不应承载 |
|---|---|---|---|
| 项目说明 | README.md |
项目用途、使用方式、快速开始 | 内部任务队列、决策流水 |
| 当前架构 | docs/ARCHITECTURE.md |
已实现的模块、边界、数据流和关键不变量 | 未来路线、任务状态 |
| 产品与界面约束 | DESIGN.md 或 docs/DESIGN.md |
已确认的体验、视觉、组件和交互规则 | 与产品无关的通用开发规则 |
| 路线图 | docs/ROADMAP.md |
愿景、结果型里程碑、阶段退出条件、依赖和风险 | 可执行任务卡、日常工作日志 |
| 当前任务源 | docs/TASKS.md 或项目指定文件 |
当前队列、任务边界、状态、验收和执行证据 | 长期愿景、重复的架构或决策正文 |
| 决策记录 | docs/DECISIONS.md |
真实发生的重要取舍、理由、影响和重新评估条件 | 例行工作摘要、为了留痕虚构的备选方案 |
| 变更记录 | CHANGELOG.md |
已交付或待发布的用户可见变化 | 内部实现流水、未经证实的历史 |
没有对应事实或项目不适用时，不创建空文档、不保留占位符，也不推断补全。
2. 工作原则
- 用户当前明确指令优先于文档队列；发现冲突时先说明，不静默改写任务目标。
- 项目已选择文件化任务源时，新需求、反馈、缺陷和技术债先记录到该任务源。用户明确要求立即推进时，记录后继续执行。
- 执行中发现的涌现任务先登记；与当前目标强相关且规模可控的可以一并处理，否则保留为后续任务。
- 接续任务时读取完整任务卡。输入、范围或验收缺失到足以改变方案时，不根据标题或历史对话猜测，保持草案或标记阻塞。
- 用户未指定任务时，优先继续已有进行中任务，其次选择已就绪的高优先级任务；只有当前队列没有可执行项时，才依据路线图提出下一任务。
- 区分事实、推断、建议和决策。无法从项目材料确认的信息标记“未确认/待补充”，不伪装成项目现状。
3. 完成标准
- 结果完整：交付物符合任务目标、范围和非目标。
- 行为可验证：验证方式与实际产物类型匹配，并检查真实结果而非执行者自报。
- 文档同步：只更新本次变化实际影响且项目已经启用的文档。
- 状态透明：没有未披露的阻塞、失败或剩余风险；无法验证的内容明确标记
NOT_VERIFIED。 - 任务闭环：来源于文件化任务源的任务已更新状态，并记录验收证据或未完成原因。
- 设计一致：涉及产品界面且项目存在设计规范时，已核对相应约束。
3.1 实操验证
编译、typecheck、lint 和单元测试是重要证据，但行为发生变化时通常不能单独证明功能可用。按受影响界面选择验证方式：
- GUI / Web / 桌面应用：启动实际入口，执行代表性交互，并保留关键断言、DOM 测量或截图。
- CLI / 脚本：运行代表性命令，检查退出码、标准输出、错误路径和真实生成物。
- 库 / SDK：运行相关测试，并在适用时执行最小消费者样例或集成路径。
- 后端 / 服务：启动相关服务或隔离测试入口，检查健康状态和代表性请求；环境不允许时明确未验证范围。
- Skill / 模板 / 配置：检查引用可达、格式和静态规则，运行代表性脚本，并在行为依赖 Agent 理解时做无旧上下文的前向测试。
- 纯文档：检查差异、链接、格式、事实来源和跨文档一致性。
证据写入任务卡或项目明确指定的证据载体；不为满足协议临时发明 RESULT、goal-contract 等新文件。验证条件不具备时说明原因，不假定成功。
4. SOP
4.1 明确目标
- 读取用户当前指令和项目级规则。
- 项目存在文件化任务源时，读取当前任务卡；需要长期背景时再读取 ROADMAP。
- 确认主目标、非目标、允许范围、输入依赖、停止条件和验收方式。
- 基线变化足以影响方案时，先更新任务或请求确认。
4.2 执行与记录
- 在授权范围内推进，不覆盖、回滚或删除用户已有改动。
- 重要自主取舍写入 DECISIONS；没有真实决策时不为留痕新增决策。
- 架构事实变化时更新 ARCHITECTURE；里程碑或阶段结果变化时更新 ROADMAP。
- 用户可见变化写入 CHANGELOG；设计约束变化时更新 DESIGN。
- 任务状态、执行证据、阻塞和剩余工作写回文件化任务源。
- 不为形式完整更新与本次工作无关的文档。
4.3 交付
- 先说明结果，再说明关键变更、验证证据和剩余风险。
- 不把静态检查、单次样例或执行者自报扩大为稳定性或业务正确性证明。
- 失败时保留可复查证据和下一步；存在阻塞时不把任务标记完成。
5. 安全边界
- 不执行超出用户请求范围的外部写入、发送、发布或权限扩张。
- 不执行破坏性 Git 操作或批量删除，除非用户明确确认具体目标。
- 发现密钥、Token、密码、客户材料等敏感信息时，不提交到版本库，不在输出中扩散，并提醒用户处理。
- 处理未脱敏或高风险材料时遵循最小必要原则；无法确认的事实不编造。
- 无法验证的结果必须明确说明，不以推测替代证据。
版本变更记录
- v4.0（2026-07-30）：明确文档职责和按产物类型验证，具体结构交由项目规则与
project-init。