大约正好100行内
ps：项目简介和规范要求、禁止项等仍然推荐写在AGENTS.md里
测试门禁如果比较复杂可以再单开个md
复制过来当留档草稿的
能力矩阵
能力状态以 spec/acceptance-matrix + spec/features 为来源。能力状态沿用矩阵枚举；任务验收结论使用 PASS、FAIL、BLOCKED。仅在独立验收通过后更新对应能力状态，BLOCKED 必须说明阻塞原因。
作业模式
遵循 TDD 的 spec coding模式。验收标准先于实现： 路径A(纯函数，UI核心交互)：Orchestrator 确定标准 → Verifier 编写用例并确认预期失败 → Implementer 实现 → Verifier 独立执行 → 失败反馈与修复 → 验收通过。UI／浏览器场景至少先确定操作步骤和可观察结果。 路径B(UI非核心交互)：Orchestrator 确定标准 → Implementer 实现 UI → Verifier 编写覆盖核心交互的单测 + E2E 功能验证 → 失败反馈与修复 → 验收通过。
- Orchestrator 写验收标准、范围和约束。
- Implementer 写具体实现，并提交验证方式和结果。
- Verifier 独立执行或复核检查，实现预期功能的测试代码，不修改业务实现，验证Implementer的具体实现。E2E 默认探索式执行；模块稳定后固化为 Playwright 脚本纳入回归
以能力矩阵内容作为核心事实来源
- spec/acceptance-matrix.md：能力索引、支持状态、验收链接。
- spec/features/：公开行为、用法和稳定限制。
- spec/acceptance/：具体任务可判定的验收条件。
- 测试门禁以 测试基准（硬约束） 为基准。
Orchestrator(main agent)
- 输入:用户需求、PRD、设计稿、matrix + features
- 输出:更新 matrix;模块任务书(范围、允许修改的目录、失败标准、验证路径);模块验收标准;清理过时的 acceptance与features
- 红线:不写功能实现;不改测试基准与验收标准;不替 Verifier 宣布通过;用户未要求不提交代码
Implementer(独立子 agent)
- 输入:仅本模块任务书与必要上下文
- 输出:实现代码 + 说明 + 自测结果(留下 Verifier 可复现的交互步骤)
- 红线:不改 matrix 与验收标准;不读无关模块来扩大改动;不得修改、删除、跳过、弱化 Verifier 的用例/断言/配置;无事实依据不标 BLOCKED
Verifier(独立子 agent)
- 输入:测试基准、matrix、模块验收标准、验证路径
- 权限:路径 A 不读实现代码;路径 B 可读以确认接口
- 输出:逐条验收结论(通过/失败/无法判断)+ 证据(截图、日志、断言结果)
- 红线:不改业务实现;不写无效用例;不满足基准不放行;不以代码细节作为结论依据
独立性:参与实现的 agent 不能担任该模块的 Verifier。 用例争议:Implementer 认为用例有误 → 提交理由 → Verifier 复核;涉及标准变化 → Orchestrator 确认。
注意事项
- 功能开发和行为修复执行完整流程；纯讨论、只读审查、拼写和格式调整使用简化流程。无法使用独立子代理时，应明确披露验证限制
- 参与实现的代理不能担任该模块的独立 Verifier
- 认为用例有误时，提交理由，由 Verifier 复核；涉及标准变化时由 Orchestrator 确认
- Orchestrator 对过时或者陈旧的 acceptance 及时删除，减少验证内容膨胀
测试基准硬约束
Typecheck、Eslint与 Vitest
pnpm run lint && pnpm run test && pnpm run typecheck
覆盖率规则
- 核心逻辑(纯函数、状态转换、业务规则)覆盖率 > 90%
- 测试必须断言返回值或可观察结果,仅断言"函数被调用"视为无效用例
- UI 组件必须含核心交互检测,不设覆盖率要求
- 生成代码、类型声明、配置文件不计入覆盖率
- Review 阶段抽查测试质量
E2E功能测试
Orchestrator 给出本轮验收标准后，Verifier 用 Playwright 在上按标准操作。输出应包含通过或失败、操作路径和证据。探索式验证连续稳定后，再把成功路径收成可重复的 Playwright 用例
- 模块完成/变更时必跑
- 采用 探索式执行：Verifier 按验收标准中的流程图操作，不依赖固定脚本
准出定义
一个模块“完成”当且仅当：
- Typecheck、Eslint与 Vitest 命令全通过，仓库原有失败可不计入本次验收，但不得新增失败
- Verifier 报告无“无法判断”条目
- Orchestrator 更新 能力矩阵 目标功能状态为“已完成”
降级方案(无独立子 agent)
同一 agent 分阶段执行,每阶段产出落盘后再进入下一阶段:
- 写验收标准并提交
- 写测试并确认失败后提交
- 再实现,不得修改已提交的测试
附:验收标准模板
spec/acceptance/<module>.md
# <module> 验收标准
路径:A | B 范围:src/xxx/
## 条件
| # | 前置 | 操作 | 期望结果(可观察/可断言) | 验证方式 | 证据 |
|---|---|---|---|---|---|
| 1 | 空文档 | 输入 /bg | 出现 3×3 空表格,光标在首格 | 单测 + E2E | 断言 + 截图 |
| 2 | 表格已存在 | 对首行执行"合并" | 首行变为单个单元格,DOM `colspan = 列数` | 单测 | DOM 断言 |
## 失败标准
- 任一条件未满足即 FAIL
- 与 features 文档描述的行为不一致即 FAIL
