通用 AI 协作开发规范

开发流程、执行约束与仓库文档结构。

适用于由人负责产品判断、AI 参与分析和实现的项目。本文提炼可复用的协作约定；技术栈、测试命令、环境权限和业务边界须在具体项目中明确。落地时，根 AGENTS.md 只保留执行规则，笔记格式和详细依据放入对应目录。

整理日期：2026-09-17。

1. 项目边界与协作角色

开始开发前，在项目根 AGENTS.md 中确认以下内容：

AI 负责分析、列方案、设计、实现和自验证；用户负责产品取舍、方案确认和最终验收。

• 需要决策时给出可选项、各自的收益与代价，以及明确推荐。环境中能查到的事实先自行核对。
• 已确认的范围内自主推进；遇到产品取舍、范围变化或新增权限需求时，再请用户决定。
• 未获批准，不改变核心技术选型、数据后端、管理入口或 API 边界。新增网络依赖、运行时依赖或外部服务前，取得明确同意。
• 不把已否决方向反复当成“缺失功能”提出；重议须说明新证据，并由用户重新决定。
• 可行性、技术方案、原型交互、验收的确认不可省略；确认可以合并。用户确认前，不进入依赖该决定的下一环节。
• AI 自验证不能替代用户验收，不将实现完成、测试通过、用户验收和合并混为同一状态。

2. 文档结构与职责

仓库是项目知识的持久来源。新的维护者应能凭契约、当前事实、切片、决策笔记、原型和 Git 历史接手工作，不依赖私有记忆或旧会话。

以下是按需形成的目录结构，不要求开工时全部创建：

项目根目录/
├── AGENTS.md                         # 全仓库执行规则和依据入口
├── CLAUDE.md                         # 可选：指向同一契约，避免重复维护
├── docs/
│   ├── HTTP_API.md                   # 使用 HTTP 时的现行接口契约
│   ├── SCHEMA.md                     # 使用数据库时的现行结构与变更规则
│   ├── DEPLOYMENT.md                 # 安装、配置、安全边界、升级和回滚
│   └── slices/
│       └── <编号>-<名称>.md           # 一个切片的设计、确认、实现和验收
├── designs/
│   └── <项目名>/
│       ├── README.md                 # 原型组织、预览方法和状态覆盖约定
│       └── ...                       # 当前切片的原型与资源
└── .agents/
    └── notes/
        ├── AGENTS.md                 # 本目录的简短执行要求
        ├── README.md                 # 格式、检索、生命周期和检查规则
        ├── proposed/<分类>/          # 未落地的工程提案
        ├── implemented/<分类>/       # 已落地的工程决定
        ├── rejected/<分类>/          # 被明确否决且仍有参考价值的提案
        └── archived/<分类>/          # 冻结的历史决定

文档维护约束：

1. 一个事实或决定只有一份详细记录，其他位置通过链接引用。
2. 根契约保留短规则和入口。出现跨模块或跨切片的长篇理由时，移入对应笔记。
3. 一个切片一份文档，覆盖方案、确认和验收，开头的状态行记录进度。采用此流程时，不另建重复的 PRD、需求追踪表或会话交接文件。
4. 权威文档在第一个需要它的切片验收时创建，随后累计维护；不预建空壳，不收录尚未确认的能力。
5. 会话中形成的用户决定、范围边界和验证教训，当次写入所属文档；代码与相关文档同批维护。
6. 切片验收后，将稳定事实回写权威文档并在同一分支提交。
7. 已验收切片保留原结论；之后只更新状态行或追加“后续调整”“修复记录”，写清日期、原因、改动和对应提交。后续切片推翻原设计时，在状态行注明接替者。
8. 与代码不一致的现行文档当次修正；历史切片以追加记录纠正，归档笔记保持冻结。
9. 章节编号一旦被代码或文档引用，不随意重排。移动文件时，同批修复现行入站链接。

3. 按垂直切片开发

一个切片交付一项可独立理解、实现和验收的用户能力，或一个边界清楚的工程改动。每次只呈现和确认一个切片，不提前铺开后续工作。

流程：可行性与技术方案 → 原型 → 字段与状态 → 接口 → 数据 → 实现与验收。

禁止一次性把整套表或整套接口设计完，再回头补交互。原型阶段充分打磨；进入实现后再调整交互，按当前切片的返工记录处理。

变更分类：

可行性和验收不能因“没有 UI”而跳过。分类不确定时先核对原切片，再请用户明确。

4. 日常实现与分支管理

1. 开工先检查 Git 状态、当前切片、相关代码、测试面和环境假设。
2. 按模块名、机制名或关键词检索现行笔记及被否方案，沿链接阅读，避免全量加载笔记。
3. 在独立分支实现最小内聚变更，保留用户未提交修改，不混入无关重构。
4. 先运行最窄相关测试，再运行项目约定的全量门禁。自己引入的失败自行修复。
5. 复核错误路径、崩溃点、权限、数据风险和缺失验证；连续修复无进展或需要决策时，说明现状。
6. 同批更新对应切片、权威文档和必要的决策笔记，完成可供用户审阅的结果。
7. 用户验收并明确批准后再合并；确认源提交已包含在主分支且工作区干净，再清理本地源分支。

分支使用 feature/、fix/、docs/、test/ 或 chore/ 前缀，名称使用英文小写 kebab-case。缺陷修复提交可采用 fix: 切片N——具体修复。

本地已合并分支只用 git branch -d 安全删除，不强删未合并分支，不删除当前分支或主分支。远程分支只有用户明确要求时才删除。本文中的主分支指项目约定的默认分支，不强制命名为 main。

5. 真实环境与测试隔离

生产配置、真实业务数据库、活动服务、真实设备、用户数据目录、缓存中的未完成业务数据、锁和日志默认只读。

• 真实环境变更须有明确授权，说明确切命令或操作、目标、影响和恢复方案。
• 项目可预先约定 AI 自验证权限，但必须写清环境前提、允许的操作、禁止的操作、互斥方式和清理责任。一个项目的例外授权不能复制到另一个项目。
• 不擅自停止、重启、替换或重配用户启动的活动实例；不把“排查问题”当成变更授权。
• 数据库测试使用项目确认的隔离方式，例如独立测试库、专用 schema 或严格前缀隔离；不得读写隔离范围外的真实业务数据。
• 测试创建的资源正常结束时自行清理。残留清理只能覆盖明确的测试范围，不得在相关测试仍运行时执行。
• 其他测试使用临时目录、配置、锁、日志和合成资源标识。构建产物放在项目指定且已忽略的目录，不覆盖已安装程序。
• 启动验证实例前检查共享资源和活动实例；不能仅依赖端口冲突判断安全。遇到互斥冲突，不删除锁或停掉对方。
• 验证结束后停止自己启动的实例、清理自己创建的数据；清理不掉时如实交付。删除已有数据、修改已有账号及破坏性操作不属于默认自验证权限。
• 黑盒失败先只读核对活动进程启动时间、运行版本与待验收构建，排除旧进程，不能擅自重启替换。
• 可提供自包含客户端验证脚本，由用户填写目标和凭据后运行；优先使用独立客户端验证，不复用被测实现来证明自己正确。

具体数据库、表前缀、缓存路径、进程停止方式及容器方案由项目约定，不能从某个项目的历史记录推导为通用规则。

6. 验证门禁与证据边界

每个项目在根契约中填入下表对应的真实命令，并保持与构建脚本一致。以下是验证类型，不是假定项目已具备的命令。

验证约束：

• UI 交付前运行真实构建产物并截图，不能只凭原型判断实现正确。
• 浮层用 document.elementFromPoint 等命中检查确认最上层元素，不能只看截图或 iframe 原型。
• 依赖鼠标按下或焦点的交互使用真实输入事件；不能用仅派发 click 的调用替代完整行为。
• mock 响应可验证前端渲染、状态和错误处理，不能据此声称真实请求、数据落地或端到端流程通过。
• 报告区分本次运行结果、历史验证记录、未覆盖场景和待用户验收项；只声称实际执行并通过的检查。
• 测试缓存、临时目录、并发度和超时根据实际环境确定；对内存、磁盘或共享服务的约束写入规则，测量和取舍留在笔记。
• 自动化测试和 AI 自验证不能替代用户黑盒验收，也不能代替真实硬件或外部系统的验证。

7. 工程决策笔记

7.1 何时记录

涉及跨模块契约、架构边界、持久化或协议语义、工具流程、测试策略，或存在容易被后续“简化”破坏的取舍时，先检查已有文档是否足够。

有跨切片复用价值、或尚无归属的重要工程依据时，新增或更新笔记。切片已讲清的局部决定直接引用。纯格式、错字和看 diff 即可理解的局部修改，不单独立笔记。

只记录真实的背景、证据和选择。备选方案先写优势，再说明未选理由；尚未决定的方案不能写成用户已否决。历史理由无法查证时，明确写出缺口。

7.2 路径与状态

文件路径：.agents/notes/<状态>/<分类>/YYYY-MM-DD-主题.md。

文件名日期取首次提出日；历史补录用补录日，正文注明原决定日期和来源。主题使用英文小写 kebab-case，目录按需创建。

分类使用 architecture、process、testing、bug-fix、feature、simplification，分别对应架构、流程、测试、修复、功能约束和实现收窄。不维护全局 INDEX.md、逐篇计数或重复进度表。

7.3 更新与替代

• 路径、符号等事实变化，但理由不变：同批原地更新现行笔记和链接。
• 决定或核心理由改变：新建笔记，保留原论证，说明新证据及接替关系。
• 部分取代：两篇保留并互链，写清各自适用范围；仍约束旧数据或兼容行为的决定不完全归档。
• 完全退出现行用途：移入 archived/<分类>/，保留 Status: implemented，紧接着增加 Archived: YYYY-MM-DD，现行入站链接同批修正。
• 归档后不改正文、不修出站链接、不删除原论证；勘误和新决定写在现行记录中。
• 废弃提案经明确否决后转入 rejected，不能当成已经实施的历史归档。

新建笔记前检查同主题记录，确认是补充、部分接替还是完全接替，避免两篇同时声称持有同一决定。格式、链接可由项目已有工具检查，用户确认与真实理由不能由状态字段代替。

7.4 按需检索

在仓库根目录执行，替换其中的关键词：

rg --hidden -n --glob '*.md' --glob '!.agents/notes/archived/**' '机制名或关键词' .agents/notes/
rg -n '机制名或关键词' docs/slices/
rg --files --hidden .agents/notes/

先看现行决定，需要追溯时再读归档。沿切片、模块文档或已有代码注释中的链接阅读，不把所有笔记一次性塞入上下文。

8. 可复制的文档模板

模板中的“待填写”是占位说明，使用时替换为实际内容；不适用的章节说明原因，不编造事实来填满格式。

8.1 切片文档

# 切片 <编号>：<名称>

状态：待可行性确认
分支：待创建

## 1. 可行性与技术方案
用户问题、边界、范围、备选方案、推荐和代价：待填写。
用户确认：待填写，不把推荐当成确认。
跳过的步骤与原因：无；如需跳过，随可行性确认。

## 2. 原型
本地路径、预览方法、正常/空/错误态及用户确认：待填写。

## 3. 字段与状态
字段、校验、状态变化、跳转及确认：待填写。

## 4. 接口
路径、请求、响应、权限、错误情况及确认：待填写。

## 5. 数据
当前接口需要的结构、迁移方式及确认：待填写。

## 6. 实现与验收
验收标准：待填写。
实际实现和提交：待填写。
本次验证命令、结果、覆盖缺口：待填写。
真实环境操作与清理：待填写。
用户验收结论：待确认。

## 7. 后续调整与修复记录
验收后按日期追加原因、改动和对应提交，不覆盖原决定。

8.2 已落地的工程决策笔记

# Agent Note: <标题>

Status: implemented

关联：待填写切片相对链接与具体章节，或跨切片适用范围。
依据：待填写确认来源、原始提交和验证记录。

## Problem
独立说明问题、约束与适用范围。

## Decision
已经落地的选择与理由，引用当前代码、测试或权威文档。

## Alternatives considered
真实考虑过的备选方案、各自优势、未选理由；有证据时写重议条件。

## Consequences
收益、代价、已知局限、验证依据和未覆盖范围。

提案使用 Status: proposed 和 ## Proposal，并增加 ## Acceptance criteria、## Risks。落地时转为实际结果，验收步骤和用户确认仍留在切片。被否决时保留提案内容，状态行改成 Status: rejected — 原因 并注明否决来源。

9. 交付与项目落地

每次交付简要说明：对应切片、实际改动、分支与提交、运行过的检查、未覆盖项、已经确认和待确认的事项，以及真实环境操作与清理情况。

把本文应用到新项目时：

1. 确认第 1 节的项目配置项，将执行规则写入根 AGENTS.md；其他工具入口引用同一契约。
2. 在原型目录说明产物和预览约定；把第 7 节的笔记规则与第 8.2 节模板放入 .agents/notes/README.md。
3. 按第 8.1 节建立第一个实际切片，从可行性确认开始推进。
4. 第一个涉及相应事实的切片验收后，再创建 API、数据或部署权威文档。
5. 后续随实现补充必要笔记，使用已有验证入口；不用为了采用文档结构而引入整套外部工具。

提取依据：ZoneVault 仓库已确认的 AGENTS.md、.agents/notes/README.md 及相关决策笔记，基线提交 e364cfb。本文未继承该项目的具体技术栈、业务排除项、资源路径、数据库测试前缀或生产配置自验证授权。