# ys-team v1.0 换代设计:Loop Era 适配

**状态:** 讨论稿  
**日期:** 2026-06-11  
**版本:** 草稿  
**目标:** 为 loop engineering 时代重新设计 ys-team,保留验证价值、去除流程税

---

## 一、为什么要换代

### 背景:Loop Engineering 改变了优化对象

**Prompt Engineering 时代(2024):** 优化"怎么告诉 AI 做事"。  
**Loop Engineering 时代(2026):** 优化"怎么让 AI 自己持续干活直到完成"。

核心变化:**agent 原生就会在循环里 observe → plan → act → verify → repeat,直到退出条件满足。** Claude Code / Codex 自带这能力,不需要外置状态机去驱动。

### ys-team 当前的错配

ys-team 设计于 prompt era,用**过程层流程仪式**(强制 marker、五角圆桌、四制品、每阶段暂停)来约束 agent 行为。但在 loop era:

- **agent 已经自带的能力**(plan、读码、测试反馈、自我纠错),系统还在用重流程强制 → **纯税**。
- **agent 供给不了的能力**(跨会话记忆、人类级验收、硬约束),系统反而投入不够 → **漏**。

### 实测数据支持换代

**ai-gateway / jarvis 两项目的失败模式分析:**

| 项目 | Spec | 流程合规? | 验收信号 | 结果 |
|---|---|---|---|---|
| jarvis | `todo-outline-editor` | ✓ 全流程走完 | cargo test + npm build | ✗ 交付后 3 个 user-reported bug(粘贴失败、Enter/Tab 不可用、Markdown 解析失败)|
| jarvis | `codex-agent-drawer` | ✓ 走完 + 2 轮审阅 | 真实 codex exec 探针 + JSONL 事件断言 | ✓ 一次通过 |

**结论:一次通过率的瓶颈不在流程重不重,在验收信号保不保真。**

**Spec 重量实测(ai-gateway):**
- 平均 spec.md: 200-300 行
- 配套制品: review.md(~100 行)+ qa-report.md(~100 行)+ checklist.md(模板)+ evidence/(数百行)
- 总重: 单个 spec 约 10-50KB 文本 + 多轮审阅/QA subagent
- **20% 的 spec 被 REJECT 后重写**(6/30),典型理由:"Write-Scope 缺、验收不清、模型矩阵不清"——这些是**机械可检的结构问题**,不需要五角讨论才能发现。

**五角圆桌的真实产出:**
- 四角(后端/供应商/文档/测试)经常一致 PASS,贡献主要是"补全 spec 漏项"。
- **挑战者**抓到真 bug(k8s multi-worker 并发缺陷、rpm-limit fail-open 语义冲突),是唯一高价值的对抗视角。
- 结论:五角里只有一角在抓 bug,其余四角的"补漏项"有更便宜的办法(结构 lint)。

### 参考项目验证(obra/superpowers、mattpocock/skills、garrytan/gstack、karpathy-skills)

四个当前流行的 agent workflow 项目,共识高度一致:

1. **验证是地基,而且要人等价保真:**
   - karpathy: "把命令式任务改写成可验证目标,test-first,loop 到满足"
   - mattpocock: "broken code = 反馈环弱,解药是 static types + **browser access** + red-green"(browser access = UI 真去点)
   - superpowers: "verification-before-completion"、mandatory RED-GREEN-REFACTOR
   - gstack: `/codex` 跨模型独立审查

2. **轻框架 vs 重流程,风向偏轻:**
   - mattpocock **指名道姓反对 GSD/BMAD/Spec-Kit**:"夺走控制权、流程里的 bug 难修"
   - karpathy: 一个 CLAUDE.md 四原则,反对重框架
   - superpowers 和 gstack 虽重,但靠真隔离(worktree、并行 sprint、跨模型)换价值,不是"同一 agent 戴五顶帽子"

3. **grill 被反复验证为高价值原语:**
   - mattpocock: "grill 是最受欢迎,grill-with-docs 可能是整个 repo 最酷的技术"
   - ys-team 的 grill + questions.md 对齐这个,实测有效(jarvis 271 行 questions.md 是真澄清),**应保留并前置**。

---

## 二、换代的一句话定义

> **把全部工程重量从"约束执行过程的流程仪式",搬迁到"供给一个人类级保真、且能在 agent loop 内自跑的退出判定(verifier)";流程结构降到能托住这个 verifier 的最小集。**

---

## 三、四原则在 Loop Era 的重新定位

| 原则 | 以前(过程层) | 以后(结果层) | 数据依据 |
|---|---|---|---|
| **现实先于生成** | 维护完整模块结构地图(reality.md / module-index.md) | 砍成**约束与风险地图**:只留 agent 推不出来的硬约束("热路径禁同步 DB""多实例幂等"),结构能 grep 的不存 | ai-gateway reality.md 10.8KB,大部分是目录树复述 → 可瘦身到 2-3KB 只留约束 |
| **规格先于执行** | 四制品(spec/review/qa-report/checklist)+ 五阶段门控 | **一张 verifier 卡**:意图 + 非目标 + Write-Scope + **人等价验收**;<br>触发轴从"文件数/模块数"改为"不可逆性 × 不确定性" | Spec 平均 200-300 行 + 配套 300 行 → 可塌缩到 80-120 行卡;<br>jarvis 单文件改动(UI)因"不可逆"应走 spec,多文件后端改动因"确定性高"可不走 |
| **讨论归于收敛** | 五角圆桌 subagent 讨论 + 结果卡 | 保留:**grill**(对齐人的意图,前置)+ **一个跨模型对抗审阅**(claude 验 codex 写的,真独立);<br>砍掉:五角圆桌默认开(四角贡献=补漏项,改用结构 lint) | 挑战者抓到真 bug(k8s 并发、rpm fail-open),四角经常一致 PASS;<br>mattpocock/karpathy 都把 grill 列为核心 |
| **证据胜于感觉** | evidence/ 目录 + 人工复查 | **升格为系统脊柱:Verifier 工程**<br>验收脚本 = 人会做的操作,在 loop 内自跑,红了继续改,绿了才停;<br>分级标准:L3 人等价(真实交互+断言)> L2 行为测试 > L1 单测编译(UI 类禁止) > L0 人工 | jarvis `todo-outline-editor`: cargo test 绿 → 交付后 3 bug;<br>codex spec: 真实探针断言 → 一次通过 |

---

## 四、核心改动清单

### 4.1 Verifier 工程(新增,系统中枢)

**问题:** 当前验收信号经常不保真(单测/编译冒充人等价验收),导致"流程绿、功能坏"。

**方案:** 建立验收保真度分级标准,强制 spec 卡声明够到哪级:

| 级别 | 定义 | 示例 | 适用 |
|---|---|---|---|
| **L3 人等价** | 真实输入/点击/上游调用 + 断言,脚本化人会做的操作 | Playwright 真实粘贴 `- [ ] 任务` + 断言持久化;<br>codex exec 探针抓 JSONL 事件 + 断言 token 消耗 | UI/交互、关键业务流、集成 |
| **L2 行为测试** | 集成测试覆盖真实路径,但非人等价 | pytest 覆盖 API 端到端,但不调真实上游 | 后端逻辑、adapter |
| **L1 单测+编译** | 单测 + 类型检查 + 编译,**UI/交互类禁止单独作为退出条件** | cargo test + tsc --noEmit | 纯函数、工具类 |
| **L0 无自动信号** | 必须人工抽检,显式标注"验收到 X,剩余需人工 Y" | 视觉审美、长链路端到端 | 少数无法自动化场景 |

**强制要求:**
- Spec 卡的 Verification 段必须声明够到哪级,L0/L1 必须诚实写"为什么不能更高"。
- UI/交互类改动,验收 < L2 默认 REJECT。
- 验收脚本在 spec-work loop 内跑,红了 agent 继续改,绿了才算完成。

**工具支持(可选,不强制):**
- Playwright / Tauri 脚本化交互 harness(jarvis)
- 截图基线 diff(视觉回归)
- 真实上游调用 stub + 事件断言(ai-gateway)

---

### 4.2 三道闸(替代排他规则)

**问题:** 排他规则(强制 marker + 禁用其他 skill)逆着 harness 原生 loop,每轮抢注意力,而且只保证"形式合规"不保证"落地质量"。

**方案:** 去掉排他规则,用三道闸 + 软约束保证:

| 闸 | 卡什么 | 怎么卡 | 替代了什么 |
|---|---|---|---|
| **闸一:入口** | 没有 spec 卡,进不了 loop | 非 trivial 改动,agent 必须先产出你签字的 spec 卡(含 Write-Scope + 验收标准)才能动手 | "禁用其他 skill" |
| **闸二:出口** | 验收脚本不真绿,不算完成 | Loop 内反复跑验收,红了继续改,绿了才能声明 done | "每阶段 marker" |
| **闸三:可见性** | 用原生 todo + 结果状态表达进度 | `spec 卡已签 · loop 3/5 验收项过 · 未全绿` 取代 `` `ys-team` · [阶段] → [下一步] `` | "强制 marker 机制" |

**CLAUDE.md 软约束(保留,轻量化):**
```markdown
## 工作流

本仓非 trivial 改动走:grill → spec 卡(你签字)→ loop 自跑 → 验收闸(人等价脚本真绿)→ 你抽检证据。

Spec 卡重心:Write-Scope + 人等价验收标准(声明保真度等级)。

不排他,但没有合格验收的改动不算完成。
```

**关键:** 入口靠软提醒,出口靠硬证据(验收不绿就打回)。

---

### 4.3 Spec 卡塌缩(制品瘦身)

**问题:** 四制品(spec 200-300 行 + review ~100 + qa-report ~100 + checklist 模板)重,而且 20% REJECT 理由是机械可检的结构问题。

**方案:** 塌缩为一张 verifier 卡 + 结构 lint 前置:

**Verifier 卡结构(80-120 行):**
```markdown
## 意图
[一句话 + 背景]

## 非目标
[明确不做什么]

## Write-Scope
[允许修改的文件清单,spec-work 的硬边界]

## 验收
### 保真度等级
[L3/L2/L1/L0,诚实声明]

### 人等价验收脚本
[能直接跑的命令/步骤,模拟人会做的操作]
- 命令:`playwright test paste-task.spec.ts`
- 期望:粘贴 `- [ ] 任务` 后列表新增、刷新后仍存在
- 复现成本:< 30s

### Feedback Loop
[最快的 pass/fail 信号,< 30s;允许 N/A 但要说理由]

## 交付清单(项目本地 SOP,可选)
- [ ] 部署模板已更新(K8s YAML)
- [ ] README 同步
- [ ] Alembic 迁移已跑

## 依赖 / 风险(可选)
```

**结构 lint(前置,替代四角"补漏项"):**
v1.0 先落成文档化必检规则,由 spec-talk / spec-review 按规则阻断;后续可再脚本化。不通过不能进 loop:
- Write-Scope 非空,每个 Deliverable 可追溯到 Write-Scope 文件
- 验收段非空,且非"cargo test + npm build"冒充 UI 验收
- Feedback Loop < 30s 真实存在或有合理 N/A 理由
- 保真度等级已声明

**review.md / qa-report.md / checklist.md:** 不再是独立制品,折叠进 loop 状态 + 证据。

---

### 4.4 跨模型对抗审阅(gstack 增量)

**问题:** 五角圆桌,同一模型戴帽子 = 假独立;manual 模式同一 context 扮角色 = 纯表演。

**方案:** 保留一个对抗审阅,但用**跨模型**(claude 写 → codex 验,或反之):
- 真不同模型 = 真不同训练分布 = 能抓系统性盲区
- 隔离:审阅者只看制品(spec + 代码 + 验收运行结果),不看实现推理过程
- 替代五角圆桌,成本降到 1/5

**触发:** 关键改动(不可逆、安全、多模块)可选启用跨模型审阅;trivial 跳过。

---

### 4.5 `.ys_team` 瘦身(从治理中心 → 跨会话记忆层)

**判断标准:** 跨会话且 agent 重建不出来 → 留;否则 → 删。

| 文件 | 去留 | 改动 | 理由 |
|---|---|---|---|
| `reality.md` | 保留 | 从"模块结构地图"砍成"约束与风险地图"(只留硬约束) | 结构能 grep,约束推不出来 |
| `status.md` | 保留 | 管住体积(跨月统计挪 history) | 跨会话项目状态 |
| `rules.md` | 保留 | 去重(与 overview/SKILL 收敛) | 行为边界跨会话 |
| `glossary.md` | 保留 | - | 术语漂移 agent 推不出(对齐 mattpocock CONTEXT.md) |
| `config.yaml` | 大幅缩 | 砍五角/槽位绑定,只留验收策略开关 | 五角圆桌没了 |
| `templates/` | 塌缩 | spec.md → verifier 卡;保留 questions.md(grill 用) | 制品瘦身 |
| `memory/` | 改性质 | 拍平成项目级"错题本"(按领域打标签,不按人格分) | 经验留、人格壳去 |
| `VERSION` / `history/` | 保留 | - | 归档 |

v1 baseline 不再默认包含 `role-pool.yaml` 和 `templates/monthly-summary.md`。

---

### 4.6 CheckList 拆解(流程打勾 vs 交付清单)

**问题:** 现在 checklist 混了流程性打勾(talk/review/work 做了没)和交付性清单(README 同步了没)。

**方案:** 拆成两半:
- **流程性打勾 → 折叠进 harness 原生 todo**("还剩什么"用 todo 表达,信息量更大)
- **交付清单(项目本地 SOP)→ 升级成验收定义的一部分**,写进 verifier 卡的"交付清单"段,喂给验收脚本

**确认点压缩:** 从每阶段确认,压缩到两个真决策点:
1. **Spec 卡签字**(尤其验收标准够不够人类级)
2. **最终抽检证据**

中间过程(要不要进 spec-work、要不要 close)agent 靠 verifier 自收敛。

---

### 4.7 尾缀改性质(合规标记 → 结果状态)

**保留:** 尾缀这个东西本身(成本低、用户爱、有收尾感)。  
**砍掉:** 强制 marker 机制(CLAUDE.md "缺 marker 就切回"的硬规则)。  
**改内容:** 从流程口号换成结果状态,不可伪造。

**Before:**
```
`ys-team` · spec-work → qa
```
(只能看出"我声明我在流程里",不知道真做到哪)

**After:**
```
spec 卡已签 · loop 执行中(3/5 验收项已过) · 验收未全绿,未完成
```
(能看出:哪道闸、具体进度、验收真没真对)

**机制:** agent 自愿输出(方便你看),不强制(缺了也不报错切回)。

---

## 五、你的使用方式变化

### Before(现在)
1. 你说需求 → agent 吐路由 marker
2. 五角讨论 → 写四份制品
3. 每阶段暂停等你确认
4. 你全程盯
5. close 还要你点头

**你要理解:** 8 条 ban + 五角色 + 五阶段 + 四制品 + marker 合规

---

### After(换代后)
1. 你照常说需求,agent 内部判复杂度(无 marker、无排他)
2. 非 trivial → **agent 先 grill 你**(对齐意图)
3. Agent 写一张 **verifier 卡**给你过目,**重心在验收标准**(够不够人类级)
4. **你只在这签一次字**(看验收标准,尤其 UI 类是不是真去点)
5. Agent 进 loop 自跑,改完真跑那个验收,红了自己继续,绿了才停
6. 需要时拉 **codex 做跨模型审阅**(真独立)
7. **你最后看证据抽检**

**你要理解:** 规则(轻量)+ 现实索引(约束版)+ 术语表 + 错题本 + 一张 verifier 卡

**操作:** 还是"装一次、项目变形后重估一次"。

---

## 六、换代路径(迁移策略)

### 6.1 新老并存期

- **v0.x 不下线**,用户可通过 npm `legacy` tag 安装旧包版本。
- **v1.0 作为 latest**,包内现有 `ys-team` / `ys-team-*` skill 原地替换为 v1 语义,新项目默认使用新版。
- 新老共存发生在 npm 版本/tag 层,不在同一个包内维护 `ys-team-v1` / `ys-team-legacy` 两套 skill 名。

### 6.2 存量项目迁移

**ai-gateway / jarvis 迁移分两步:**

**步骤 1: 无痛切换(1 天)**
- 保留现有 `.ys_team/` 结构
- 只改 CLAUDE.md:去排他、改 marker 为可选、加验收保真度要求
- 体验:**立刻去掉 marker 税,原有 spec 继续能用**

**步骤 2: 深度瘦身(1-2 周)**
- Reality.md 瘦身(砍结构复述,只留约束)
- Spec 模板换成 verifier 卡
- 角色记忆拍平成错题本
- 为关键 UI 功能补 L3 验收 harness(Playwright / Tauri 脚本)

### 6.3 工具支持

**新增(可选):**
- `ys-team-init --v1`:初始化 v1 baseline
- `ys-team-migrate`:扫描 v0.x 项目,生成迁移清单(哪些 spec 验收不保真、哪些 reality 可瘦身)
- Verifier harness 模板(Playwright / pytest fixture)

---

## 七、换代收益预估

| 维度 | Before | After | 依据 |
|---|---|---|---|
| **一次通过率** | 80%(ai-gateway 6/30 bounced) | 目标 95%+ | jarvis codex spec(L3 验收)一次过 vs todo-outline(L1 验收)3 次 bug |
| **Token 成本** | 单 spec 10-50KB 制品 + 五角 subagent | 单 spec 3-10KB 卡 + 1 跨模型审阅 | Spec 塌缩 60%-80%、圆桌降 80% |
| **墙钟时间** | 五角讨论 + 多轮 review + 每阶段等确认 | grill(前置)+ loop 自跑 + 两次签字 | 确认点从 5 个压到 2 个 |
| **人类复查成本** | 每 spec 全程盯 + 逐行 review | 只签 spec 卡(1 次)+ 抽检证据(1 次) | 验收脚本 = 人会做的,人只抽检 |
| **学习成本** | 8 ban + 五角色 + 五阶段 + 四制品 + marker | 规则(轻)+ 约束地图 + verifier 卡 | 概念从 20+ 压到 5 |

**关键指标:** "写完 spec 基本就能落地、验收即真实验收、人只抽检" = verifier 保真度决定的,不是流程重不重决定的。

---

## 八、风险与取舍

### 8.1 诚实的成本

**写人等价验收脚本本身要花 token 和时间**(尤其 UI harness 首次搭建)。

**但 jarvis 数据说明这笔投入划算:**
- 三次 user-reported bug 的来回(修复 + 重新构建 + 打包),每次半天 = 1.5 天
- 一次把 Playwright 验收脚本写对 ≈ 0.5 天
- **投入 1:3,且后续复用**

**对无法自动化的场景**(纯视觉审美、长链路),诚实标注 L0"剩余需人工 Y",不假装全自动。

### 8.2 "不排他"的边界

去掉强制 marker 后,agent **偶尔会忽略 CLAUDE.md 的软约束**,野生直接改。

**但这不是问题:**
- 入口软约束被忽略 → 出口验收闸兜底:没证据的改动不算完成,你抽检时打回
- 你想要的不是"它嘴上按流程",是"它手上做对了"

### 8.3 跨模型审阅的依赖

需要你的项目同时有 claude code 和 codex 接入。如果只有一个模型,退化为"同模型独立 subagent 审阅"(次优,但仍比五角强)。

---

## 九、下一步

1. **你过目这份设计文档**,拍板方向(同意 / 哪条要调整)
2. 我起正式换代 spec(走 ys-team 本仓 release-first 流程)
3. Spec 包含:
   - 四原则重新定位(逐条 + 实测依据)
   - Verifier 分级标准(体系化)
   - 三道闸机制
   - Spec 卡模板
   - 结构 lint 规则
   - `.ys_team` 瘦身清单
   - 迁移路径(ai-gateway / jarvis)
   - Harness 对齐改动(去 marker、原生 subagent)
4. 实现 v1.0 baseline
5. ai-gateway / jarvis 试点迁移

---

## 附录:参考项目对比

| 项目 | 核心主张 | 验证态度 | 流程重量 | 对 ys-team 的启发 |
|---|---|---|---|---|
| **superpowers** | 7 阶段 mandatory workflow,TDD 地基 | RED-GREEN-REFACTOR、verification-before-completion | 重,但靠 worktree 真隔离 | TDD 是验证的具体形式,我们要抽象成"人等价 verifier" |
| **karpathy-skills** | 一个 CLAUDE.md 四原则 | "改写成可验证目标,test-first,loop 到满足" | 极轻,反重框架 | 验证是 loop 退出条件,不是事后补证据 |
| **mattpocock/skills** | 小、可组合,指名反 GSD/BMAD | **broken code = 反馈环弱,解药 browser access + red-green** | 明确反重框架 | browser access = 人等价验收(UI 真去点),不是单测冒充 |
| **gstack** | 23 角色虚拟团队 | `/codex` 跨模型独立审查 | 最重,但靠并行 sprint + 跨模型换价值 | 跨模型审阅破"同模戴帽=假独立",是五角圆桌的真替代 |

**共识:** 四个项目无一例外把验证当地基,且都在解决"假绿"问题。轻框架风向明显,但验证不能轻。

---

**文档状态:** 讨论稿,待你过目拍板。