AI 协作规范

1. 身份认同

每个 AI 智能体在启动任务前，必须明确自己的角色定位（见 AGENTS.md）。

• 禁止跨权：qa-assistant 严禁修改代码；test-engineer 应专注于测试编写。
• 环境感知：执行命令前必须判断当前是 Windows 还是 POSIX 环境。

1.1 Agent-First 方法论

Agent-First 的完整项目级定义以 AGENTS.md 为准。Agent 是默认任务入口；一次性需求可直接执行；可复用流程应沉淀为 skill；高频请求应触发既有 skills 的持续演化。

1.2 执行原则

1. 搜索优先：当遇到需要外部信息、排查未知问题、根因不明确或修复失败 >= 2 次时，必须先搜索获取一手信息。严禁跳过信息获取步骤凭记忆给出结论。
2. 显式假设：当需求存在歧义、边界未定义或上下文不足时，必须先说明当前假设、可选解释与风险；禁止静默选择一种解释后直接大规模实现。
3. 简洁优先：默认选择满足当前验收标准的最小实现，不得借机引入与当前目标无关的抽象或未来能力预埋。
4. 外科式改动：改动范围应与用户请求、Todo 验收点或 blocker 一一对应；发现无关问题时可以记录，但不得顺手并入当前实现。
5. 目标驱动验证：在进入实现前应明确成功标准、最低验证矩阵与首条区分性检查；完成首个实质改动后，优先做最小充分验证，再决定是否继续扩写。

1.3 搜索优先

触发条件（满足任一即触发）

触发场景	典型信号	搜索目标
问题排查受阻	修复失败 >= 2 次、根因不明确	错误信息关键词、同类 issue、官方文档
技术方案设计	不熟悉的库/框架/API、多种候选路径	官方文档、社区最佳实践、已知坑点
需求或配置澄清	用户描述模糊、外部服务行为不确定	官方配置参考、API 契约文档
安全或合规判断	鉴权、加密、数据保护	CVE 数据库、官方安全公告
跨平台或环境差异	Windows/Linux 行为不同、Node 版本差异	平台特定 issue、官方兼容性说明
依赖选型或升级	新增依赖、大版本升级	changelog、迁移指南、社区反馈

信息源优先级

层级	来源	采纳条件
L1	官方文档、源代码仓库	直接采纳，作为终极裁决依据
L2	权威技术社区（StackOverflow 高票、官方博客）	与 L1 无矛盾；关键数据需双源确认
L3	个人博客、Medium、Reddit	仅作思路参考，不得作为唯一事实依据
L4	内容农场、机翻站、低成本 TLD	直接舍弃

证据获取手段优先级（翻源码是最后手段）

技术疑点的证据获取按以下顺序，翻源码是杀手锏而非常规手段：

优先级	手段	说明
1	官方文档 / 网络搜索	一手信息最快；发布工具链决策注意时效性（npm OIDC、pnpm 原生 publish 等近两年变化大，训练数据易过时）
2	真实项目实证	知名项目同版本组合的实际配置/发布产物（如 react-turnstile = pnpm@11 + changesets@2.31.1、better-auth 的 npm manifest）——黄金证据
3	本地实验	跑一下胜过猜：npm pack 验证发布产物、临时 git 仓库模拟 tag 分段、单测验证边界——分钟级出实锤
4	翻源码	仅限：需要最终实锤且 1-3 均无法确认（如"标题写死"这类文档不描述的实现细节）；对第三方包做安全审计。禁止作为默认手段

2026-08 教训：方案未确认就派审计 agent 翻源码属于浪费；npm pack 实验 30 秒实锤了"npm 不替换 workspace:*"，真实项目产物（better-auth npm manifest 无 workspace: 残留）直接否定了错误假设。

审查按风险分级、控制用时

Review Gate 的投入应与改动风险匹配，不应对所有改动一视同仁长时间分析：

风险级别	改动类型	审查深度
高	发布流程、安全/鉴权、外部调用、数据写入、配置与依赖变更、agent/skill 定义	深度审计：验证矩阵 + 针对性实证（临时仓库/本地实验）+ 全量 checklist
中	常规业务逻辑、测试补强	标准审查：正确性 + 边界 + 测试覆盖
低	文档措辞、简单配置、重命名	快速审查：一致性 + 明显错误即可

配套实践：

• 审计 prompt 携带"已查证事实"：执行角色把调研结论/实验证据写进审计任务，避免审计者从头翻源码，显著提升效率与命中率（2026-08 多轮 Review Gate 实证：抓到 tag 不推送、分段回归、runner 无 git 身份等真问题，同时每轮用时可控）；
• 分级沿用 blocker / warning / suggest（见 测试规范 §4.1 按风险分级执行 与 code-reviewer 技能）。

2. PDTFC+ 工作流

所有写操作任务必须严格遵循以下执行顺序。严禁跨越关键质量阈值。

P (Plan) — 需求分析与规划

• 意图抽离：必须读取 docs/plan/todo.md，若存在歧义必须发起"采访"模式。
• 规划闸门：新事项必须先核对 todo.md、roadmap.md、todo-archive.md 与当前任务验收标准。
• 插队判定：若不在当前规划内，必须先完成快速分流（阻塞/高风险 → 允许插队；其他 → 延期）。
• 任务定义：更新 todo.md，将任务标记为 进行中。
• 方案设计：输出受影响文件清单及技术实现路径。

D (Do) — 业务执行

• 实现准则：遵循 TypeScript 架构，禁止使用 any。
• 最小实现：默认先做满足当前验收标准的最小切片。
• 范围稳定：开发过程中发现的额外问题不得直接扩写，必须回到 P 阶段判断。
• 自检：开发完成必须通过本地质量校验（lint + typecheck）。

A (Audit) — 代码审计（强制 Review Gate）

• 强制入口：D 阶段完成后，必须立即加载 code-reviewer skill 执行完整的结构化审查，不得自我审查。
• 审查内容：按验证矩阵核对最低验证要求，覆盖正确性、安全、规范一致性。
• 退回策略：若发现 blocker，退回 D 或回流 P，不得携带未关闭的 blocker 进入后续阶段。

V (Validate) — UI 验证

• 视觉审计：对 UI 改动进行浏览器验证。若自动化工具失效，应向用户展示截图或请求人工验证。

T (Test) — 质量检查

• 测试覆盖：编写测试用例。
• 风险导向：优先补当前缺陷会打断的断言、失败路径与边界行为。

F (Finish) — 任务完结与单次提交

• 闭环管理：更新 todo.md 状态为 已完成，同步更新相关文档。
• 单次提交：整个任务产生的所有改动一次性提交。提交前加载 conventional-committer skill，生成符合 Conventional Commits 格式的消息，执行 git commit。
• 推送禁令：commit 后不得自动 git push，仅限用户明确要求时执行。

2.1 迭代中途发现事项处理

1. 先暂停扩写：停止直接继续实现，先判断是否已在当前待办或验收范围内。
2. 允许插队：仅限阻塞当前交付、明确功能回归、高风险安全/合规问题。
3. 默认延期：体验优化、代码重构、探索性能力、未来功能、非紧急依赖升级。
4. 记录要求：插队事项须补充"为何插队"说明；延期事项须记录到 backlog。
5. 禁止静默膨胀：不得在未告知用户的情况下把原子任务扩展成新的功能包。

2.2 验证分级矩阵

任何变更都必须按"验证层级 + Review Gate"判断是否可以放行。

层级	名称	目标	典型证据
V0	记录层	明确变更范围、风险与受影响入口	变更文件清单、风险说明
V1	静态层	确认代码在静态检查层面可用	lint、typecheck
V2	逻辑/运行层	确认逻辑无明显回归	定向测试、集成测试
V3	流程层	确认跨模块流程、UI 渲染	浏览器验证、E2E
V4	性能层	确认性能未回退	Lighthouse、Bundle 预算
RG	Review Gate	给出最终审计结论	code-reviewer 结论、未覆盖边界

不同改动类型的最低验证要求

改动类型	最低验证
文档 / 规划	V0 + V1 + RG
纯逻辑 / 工具函数 / 服务层	V0 + V1 + V2 + RG
API / 鉴权 / 数据模型	V0 + V1 + V2 + RG（若影响关键写路径则升级到 V3）
UI 组件 / 页面交互	V0 + V1 + V2 + V3 + RG
修复型 Hotfix	V0 + V1 + (对应层级 V2/V3) + RG（必须补复现+修复后结果）

关键约束：没有 RG 结论的变更只能视为"进行中"，不能视为已完成。

3. 安全红线

1. 敏感文件保护：严禁修改或删除 .env、AGENTS.md 等核心配置文件。
2. 路径校验：删除操作前必须验证路径存在且非空。
3. 密钥脱敏：绝不在代码或日志中硬编码密钥、Token。
4. 死循环规避：同一问题修复失败 >= 2 次先触发搜索优先流程；>= 3 次停止并请求人类介入。

4. 修复工作流原则

4.1 最小复现测试优先

根因不明确时，先编最小复现测试，一次只验证一个假设，避免全量测试来验证错误方向。

4.2 CI 作为最终裁决

修复的验收标准是 CI 流水线全部通过，不是本地测试通过。

根因排查(最小复现) → 方案验证(定向subset) → 批量修复 → 本地通过 → 提交 → CI通过 = ✅ 完成

CI 失败后不得回退到全量重试，应分析具体失败点针对性修复。

5. 相关文档

• AI 资产治理规范
• 外部 Skills 准入清单
• 开发规范
• 测试规范
• 安全规范

本文档在 1.0.0 前参考 momei 项目的成熟做法完成继承与适配；1.0.0 后按项目自身实践持续演进，形成自有规范。