# ys-team 方法概述

## 定位

ys-team 是一组让 AI coding agent 在项目里可靠落地改动的轻量治理层。

v1.0 面向 loop era：Claude Code / Codex 已经会在本轮任务里 observe → plan → act → verify → repeat。ys-team 不再用重流程约束 agent 的每一步，而是把工程重量放到退出条件：能否给出足够保真的 verifier，并让 agent 在 loop 内跑到真绿。

用户仍然照常描述目标。ys-team 负责在仓库本地完成现实读取、意图澄清、verifier 卡、执行、验证和收口。用户主要看两件事：spec 卡里的验收标准够不够像真人验收，最后证据是否真的通过。

## 四个原则

### 现实先于生成

**保留，但改轻。**

旧版把 `reality.md` 做成结构地图，容易复述目录树。v1.0 只保留 agent 难以从 grep 重建的内容：项目硬约束、风险、术语和本地 SOP。结构能现场读取，就不写进跨会话记忆。

典型内容：

- 热路径约束、并发边界、幂等要求
- 发布、权限、安全、数据迁移等不可逆风险
- 项目本地 SOP 和必须读取的权威文档
- 容易漂移的领域术语

### 规格先于执行

**保留，但从四制品塌缩成一张 verifier 卡。**

非 trivial 改动仍然先规格化，但 spec 的重心不再是流程记录，而是 Write-Scope 与验收。一个合格 spec 必须回答：

- 意图是什么
- 不做什么
- 允许改哪些文件
- 用户目标分别用什么证据证明
- 验收保真度到哪一级
- agent 在 loop 内要跑什么 verifier
- 哪些项目本地交付项不能漏

### 讨论归于收敛

**保留 grill，砍默认五角圆桌。**

v1.0 讨论优先做意图澄清。需求模糊时先 grill 用户，必要时生成 `questions.md` 批量澄清。默认不再启动五角色圆桌；机械漏项用结构 lint 挡住，高价值对抗审阅用一个独立审阅者完成。

关键、不可逆或多模块改动可以启用跨模型对抗审阅：一个模型写，另一个模型只看制品、代码和验证结果来挑问题。

**实现后独立审阅**（v2.2 起 spec 级默认）：实现完成后由新 subagent（不继承实现上下文）做 spec 合规 + 代码质量两阶段 review。单 agent 自审有盲区——实现者既写又审，容易对自己的假设视而不见，常见「测试通过但运行时坏」的缺陷。trivial/patch 跳过。流程要求 agent 中立（「开新 subagent 会话」），不绑定任一方专属 API，Claude/Codex 共用。

### 证据胜于感觉

**升格为系统中枢。**

旧版容易出现“测试绿但功能坏”。v1.0 的完成标准是 verifier 真绿；如果 verifier 只能到 L1 或 L0，必须诚实说明剩余人工风险。没有合格验收的改动不算完成。

## 验收保真度分级

| 级别 | 定义 | 示例 | 适用 |
|------|------|------|------|
| L3 人等价 | 真实输入、点击、上游调用或运行环境 + 断言结果 | Playwright 真实粘贴任务并断言持久化；真实 CLI 探针断言事件流 | UI/交互、关键业务流、集成链路 |
| L2 行为测试 | 覆盖真实业务路径，但不完全等价真人操作或真实上游 | API 集成测试、服务级端到端测试、adapter 行为测试 | 后端逻辑、服务边界、数据流 |
| L1 单测+编译 | 单元测试、类型检查、构建、静态检查 | `cargo test`、`npm run build`、`tsc --noEmit` | 纯函数、文档/模板、低风险工具 |
| L0 人工抽检 | 无充分自动信号，必须明确人工验证剩余项 | 视觉审美、长链路人工审批 | 少数无法自动化场景 |

规则：

- spec 必须声明本次验收够到 L3/L2/L1/L0 哪一级。
- L0/L1 必须写明为什么不能更高，以及剩余人工风险。
- **UI/交互类 < L2 默认 REJECT**。不能用单测、编译或截图存在性冒充交互验收。
- L3 不是永远必需，但只要用户会通过真实操作判断成败，就优先把该操作脚本化。

## 三道闸

v1.0 用三道闸替代旧的排他规则、强制 marker 和每阶段仪式。

| 闸 | 卡什么 | 怎么卡 |
|----|--------|--------|
| 入口闸 | 没有合格 spec 卡，非 trivial 改动不能进入 loop | spec 卡必须含 Write-Scope、保真度等级、人等价验收脚本或降级理由 |
| 出口闸 | verifier 没真绿，不能声明完成 | spec-work 在 loop 内反复跑最快反馈和最终验收；红了继续改 |
| 可见性闸 | 用户要看得出结果状态 | 用原生 todo、状态文件和结果尾缀说明“验收过了几项、是否全绿、是否需要人工抽检” |

结果尾缀是可见性工具，不是合规开关。缺少尾缀不表示工作无效；没有验收证据才表示不能完成。

## 路由轴

复杂度判断从“改几个文件”改为“不可逆性 × 不确定性”。

| 判定 | 特征 | 处理 |
|------|------|------|
| trivial | 可逆、低风险、意图明确、验收显然 | 直接执行，必要时简单说明验证 |
| patch | 范围清楚、影响有限、可用快速 verifier 判断 | 直接执行并留痕，仍要跑合适验证 |
| spec | 不可逆、高不确定性、跨边界、用户意图未收敛、验收不清 | grill → verifier 卡 → 审阅 → loop 执行 → 验收 |

举证责任在降级。不确定时先补 verifier 卡，而不是先写代码。

## Verifier 卡

v1.0 的 spec 最小形态是一张 verifier 卡：

```markdown
## 意图

## 非目标

## Write-Scope

## 目的与验收证明

## 验收

### 保真度等级

### 人等价验收脚本

### Feedback Loop

## 交付清单

## 依赖 / 风险
```

`Feedback Loop` 是最快 pass/fail 信号，目标复现成本 < 30 秒。最终验收可以更重，但最快反馈必须足够便宜，方便 agent 在 loop 内反复自修。

`目的与验收证明` 用来把用户目标和证据绑定起来。目的写用户真正想达成的结果，不能写成“修改某文件”；验收证明写可观察结果、命令断言、人工脚本或明确降级理由。

## 结构 Lint

进入 spec-work 前必须做结构检查：

- Write-Scope 非空，且每个交付物能追溯到 Write-Scope。
- 验收段非空，声明 L3/L2/L1/L0。
- UI/交互类改动没有用 L1 冒充退出条件。
- Feedback Loop 存在，或有合理 N/A 理由。
- 交付清单覆盖项目本地 SOP 和文档同步项。
- 依赖、发布、迁移、回滚等不可逆风险已写入。

v1.0 先用文档化必检规则阻断；后续可以脚本化。

## 项目记忆

`.ys_team/` 从治理中心降为跨会话记忆层。只留下 agent 难以从当前仓库重建的信息：

- `rules.md`：项目行为边界
- `reality.md`：约束与风险地图
- `glossary.md`：术语表
- `memory/`：项目错题本
- `templates/`：verifier 卡、questions、交付清单模板
- `status.md`：当前仪表盘，只保留活跃项、queued 项和最近 5 条判断

角色人格壳不再是默认结构。记忆按领域和错误模式组织，例如“UI 交互验收”“发布链路”“数据迁移”，而不是“产品经理”“测试角色”。

任务过程、命令输出、QA 结论和发布证据保存在对应 spec 目录；可复用经验进入 `.ys_team/memory/`。`status.md` 不承担任务日志或长期经验库职责。

## Skill 分层

ys-team 核心只提供用户入口 skill：`ys-team`、`ys-team-init`、`ys-team-spec-talk`、`ys-team-spec-work`。

项目高频、领域强、漏项成本高的工作可以沉淀为项目本地 SOP、references 或 repo-local skill。agent 命中这些场景时加载本地 discipline，但用户不需要额外选择内部工作流。通用治理留在 ys-team，业务知识留在项目本地。

## 交付清单

旧 checklist 拆成两类：

- 流程性待办：交给 agent 原生 todo 和状态更新。
- 项目交付清单：写进 verifier 卡，作为验收定义的一部分。

用户需要确认的主要是两个点：

1. spec 卡签字，尤其目的与验收证明是否对齐、验收标准是否足够像真人会做的检查。
2. 最终抽检证据，确认 verifier 真绿或人工剩余项已诚实标注。

## 用户心智

对外只需要理解 5 个概念：

1. **规则**：AI 的行为边界
2. **约束地图**：项目硬约束和风险
3. **术语表**：避免领域语言漂移
4. **错题本**：跨任务复用的失败模式
5. **verifier 卡**：复杂改动的执行与验收合约

操作仍然是：

1. 安装 ys-team skills，并在项目里初始化一次。
2. 项目形态明显变化后，再 rebuild。

## ys-team 不是什么

- 不是 CI/CD 工具，不替代构建、测试、部署流水线。
- 不是项目管理软件，不做甘特图、看板、工时统计。
- 不是重型流程框架，不要求用户记住内部阶段。
- 不是万能自动验收。无法自动化时必须诚实标注 L0 和人工剩余项。