ys-team

给 AI coding agent 装一层 verifier-first 的项目纪律。安装一次，正常开发。

为什么需要它

AI agent 已经会自己循环读代码、改代码、跑命令。但它经常败在退出条件：

• 编译绿了，真实交互仍然坏
• 测试跑了，但没覆盖用户真正会做的操作
• 改动范围越扩越大，最后没人能说清验收标准
• 交付后才发现文档、发布或迁移步骤漏了

ys-team v1 的核心是把流程重量搬到 verifier：复杂改动先写一张 verifier 卡，说明怎么用接近真人的方式判断成败；agent 在 loop 里跑到 verifier 真绿，才算完成。

它怎么工作

四个原则：

• 现实先于生成：先读项目事实和硬约束
• 规格先于执行：非 trivial 改动先写 verifier 卡
• 讨论归于收敛：先 grill 澄清意图，必要时跨模型对抗审阅
• 证据胜于感觉：验收不真绿，不声明完成

v1 不再排他，也不靠强制尾标证明“进入流程”。真正的 gate 是三道闸：

• 入口闸：没有合格 verifier 卡，复杂改动不进入实现
• 出口闸：verifier 不真绿，不算完成
• 可见性闸：用 todo、status 和结果状态说明进度

你只需要理解 5 个概念

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

两个真决策点：

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

30 秒开始

npx ys-team install-skills --force

然后在你的项目里对 agent 说：

用 ys-team-init 初始化这个项目

Python / Java 项目低成本开始方式：

1. 先 init，生成 .ys_team/ 骨架。
2. 第一次复杂改动用 verifier 卡收敛。
3. 等同类任务重复出现、且每次容易漏同类验收时，再沉淀项目本地 SOP。

日常使用

照常描述需求。

简单、可逆、验收显然的改动会直接做，并说明最小验证。

非 trivial 改动会先进入：

grill → verifier 卡 → loop 自跑 → 独立审阅 → 抽检证据

spec 级改动实现后默认由新 subagent（不继承实现上下文）做独立审阅：spec 合规 + 代码质量两阶段。单 agent 自审有盲区，独立审阅能抓「测试通过但运行时坏」的缺陷。trivial/patch 跳过。流程 agent 中立，Claude/Codex 共用。

verifier 卡会写清：

• 意图和非目标
• Write-Scope / Delete-Scope
• 目的与验收证明
• 验收保真度等级 L3/L2/L1/L0
• 人等价验收脚本或降级理由
• Feedback Loop
• 项目交付清单

UI/交互类改动低于 L2 默认不通过。也就是说，不能只靠单测或编译来证明一个真实交互已经好用。

status.md 只做当前仪表盘。任务过程、命令输出、QA 结论和发布证据留在 spec；项目经验和失败模式留在 .ys_team/memory/。

输出模式

默认是技术输出：

output_mode: technical

如果希望保留技术细节的同时追加一段普通语言说明：

output_mode: friendly

友好总结不改变验收门槛，也不替代 evidence。

CLI 参考

npx ys-team install-skills [--dest <dir>] [--force] [--dry-run]
npx ys-team init-project [--dir <project-dir>] [--force] [--dry-run]
npx ys-team check-update

install-skills --force 会替换当前 ys-team 已安装的同名 skill，并清理当前 npm 包不再提供的旧 ys-team skill。

init-project 会安全刷新项目内 .agents/skills，并更新 AGENTS.md / CLAUDE.md 的 ys-team:managed 托管块。已有项目规则应写在托管块外；升级时只替换托管块，不覆盖项目本地约束。旧项目如果仍有 L0/L1/L2、固定尾标或 role/slot 入口段，init-project 会尽量替换为 v1 direct / patch / spec 入口。

仓库发版约束

ys-team 本仓是 npm 分发产品。本仓所有非 trivial 可交付改动都按 release-first close：

1. spec-review 通过后切到 release/<version> 或 work/<spec-id> 分支。
2. spec-work 和 QA 在分支上完成。
3. close 完成版本一致性检查、npm pack、npm publish、合回 main、创建并 push 同版本 git tag。

版本线：

• npm 发布线：package.json + baseline .ys_team/VERSION
• 方法论线：docs/methodology/VERSION

v1 原地替换现有 ys-team skill；旧版 npm 包通过 legacy tag 保留。

文档地图

| 文档 | 说明 | |------|------| | 为什么需要 ys-team | 问题、解法、反模式案例 | | 开始使用 | 安装、初始化、日常使用、常见问题 | | 短示例 | direct / patch、目的-验收 spec、本地 SOP 的 curated examples | | 方法论规范 | 形式化规则与协议 |