Skip to content

Latest commit

 

History

10 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Trio

一个 Claude Code 插件,把 AI 编码从 "凭感觉写代码" 变成 "三大支柱 + 子冲刺闭环" 的可审计工作流。

Trio 是一套 AI coding 的 Harness 机制——但比起"让 AI 更会写代码",它更关注人在其中的过程:怎么让代码、文档、测试用例三者始终保持一致,而不是各跑各的。

工作流围绕三种文档("三大支柱")+ 一个执行单元展开:

  • PRD(Product Requirements Document,产品需求文档)—— 写清楚"要做什么、为什么"
  • TDD(Technical Design Document,技术设计文档)—— 写清楚"怎么实现"
  • Test-Case + Test-Report(测试用例 / 测试报告)—— 验收标准 + 执行证据
  • subsprint(子冲刺)—— 每次代码改动的最小执行单元,自带"代码改动 / 文档改动 / 测试用例改动"三件套清单

配合契约文件和清单复选框,"AI 说做完了" 变成可机械验证的状态。


一、AI 编码现在的痛点

如果你和 AI 真正一起写过几周以上的代码,下面这些大概率都中过:

  1. AI 没有 "为什么"。 没人写 PRD,AI 就只能 "看上去对" 地写代码——能跑、长得像,但和真实需求脱钩。一两个迭代之后开始累积漂移,没人说得清当初为什么这么做。

  2. AI 找不到正确的文件。 跨模块改动时它会臆造路径、改错文件、把同一个东西在两处分别实现。src/... 不一定是 src/

  3. 测试通过 ≠ 没 bug。 AI 写的测试很容易 "把现状当作期望"——失败的代码改一下,断言也跟着改一下,绿条永远在,bug 上线了才发现。

  4. 每次新对话从零开始。 上一次会话里达成的约定、走过的弯路、定下的命名,下一次会话全部消失。AI 重新猜,重新错。

  5. 大计划悄悄缩水。 AI 说 "我来做 X、Y、Z",最后只交付了 X,并宣布完成。没人能机械验证 "Z 到底有没有做"。

  6. 测试执行把上下文打爆。 一个 agent 跑 30+ 条用例,Playwright stdio 断连、context window 溢出、跑到一半就糊涂了,最后还是要人来兜底。

  7. 测试规格被悄悄削弱。 原本断言 "登录失败时显示账号被禁用",后来某次重写之后变成 "返回任何 4xx 即可"。回归测试还在绿,但实际保护已经没了。

Trio 针对的是这些流程问题,不是 "让 AI 更聪明"。


二、Trio 是怎么解决的

痛点 Trio 的应对
AI 没 "为什么" 用 PRD 把"为什么"显式固化下来——先有整体再写模块,AI 做事之前必有依据
找不到正确文件 把项目的"代码地图"(前端路由 / 后端 endpoint / 模块到文件的对应)落成一份契约文档,所有后续动作都从它读起
测试 = 现状 测试用例必须显式列出验收点和禁止状态;后续修改默认只允许"加严",要放松必须走可见的全量重写
新对话从零开始 三大支柱 + 迭代历史本身就是冷启动地图——新会话直接读已有文档,不重新猜测
大计划悄悄缩水 每个子冲刺顶部都有一份固定结构的执行清单(代码 / 文档 / 测试用例),每个框只有唯一一个责任方能勾完;故意跳过必须写明原因。"做完了"是机械可读的状态,不是嘴上说说
测试执行打爆上下文 测试执行按子模块切片,每段结果立刻落盘成结构化文件;主控随时可以丢弃内存、重新读盘
规格被悄悄削弱 测试用例的修改默认只允许"加严"操作集;任何"删条目 / 放宽断言"在校验阶段就被拒绝,要放松必须走可见的全量重写

三、个人版 vs 企业版

这个仓库是 个人版(Personal Edition)——开源(PolyForm Noncommercial 1.0.0),适合个人 / 研究 / 教学等非商业用途。

企业版(Enterprise Edition) 在个人版基础上面向团队协作场景额外提供三块能力,需要单独商业授权。

能力 个人版 企业版
三大支柱 + subsprint 闭环(PRD / TDD / Test-Case)
/trio:next 智能路由 + Trio Stage 浏览器编辑器
测试用例 strengthen-only patch + 落盘 partials
Azure DevOps 任务与缺陷双向打通
Git Worktree 隔离 + Diff 校验
合回团队分支时自动总结迭代内容

1)Azure DevOps 任务 / 缺陷打通

把 ADO 上的 Work Item 直接拉进 Trio 的工作流:

  • 拉取/trio:subsprint-planner 多一种来源 ado——按 iteration / 标签从 DevOps 取任务和缺陷,自动生成 subsprint plan,task 与 Work Item 一一对应。
  • 回写:runner 完成代码、sync 完成文档与测试用例之后,自动把对应 Work Item 的状态推进到 Resolved / Closed,省掉手工同步。
  • 双向引用:plan 文件里每个 task 带 ADO Work Item ID,DevOps 评论里也会自动出现 plan 文件的反链。

2)Git Worktree 隔离 + Diff 校验

每次 subsprint 执行不在 code/ docs/ 主目录上动手,而是通过 Git Worktree 拉一份隔离副本:

  • runner 在隔离的 worktree 里执行,主目录全程干净
  • 执行完成后产出 code-diff.md / docs-diff.md,与 plan 里声明的 Code Paths / Doc Paths 做交叉校验——任何超出计划范围的改动会被高亮,等你确认。
  • 点头之后才把 worktree 合回主分支;不满意 → 直接丢弃 worktree 重做,code/ docs/ 从未被污染,不存在"改错了不知道怎么恢复"的尴尬。

3)合回团队分支时自动总结

当 subsprint 通过 worktree 校验、准备并入团队主分支时,基于 plan + diff + 测试报告自动生成迭代摘要:

  • 每个 task 一段 changelog
  • 影响到的模块清单
  • 测试结果摘要(通过率、新增 TC、回归发现)

可直接贴进 PR 描述、ADO 评论、站会更新——省掉人工写 release note 的时间。

想用企业版?

联系仓库维护者(@10XTeams)获取商业授权与交付包。


四、核心机制

3.1 三大支柱(Three Pillars)

Trio 把项目分成三个并行追踪的桶:

  • docs/ — 产品文档(PRD / TDD / Test-Case / Test-Report / URS)。独立 git 仓库(docs/.git)。
  • code/ — 实现 + 配置。独立 git 仓库(code/.git)。
  • trio/ — 工作流产物(子冲刺计划、URS-PRD gap-check JSON、subsprint notes)。故意不进 git——这些是过程产物,不属于产品文档历史。

每个新项目第一步就是 /trio:init-project,它会创建这三个文件夹、写好根目录 CLAUDE.md 锁住三桶约定,并落下 tech-stack.md(必要时再生成 code-structure.md)。

3.2 契约文件(不能改名)

文件 谁产出 谁读
docs/TDD/0.common/tech-stack.md /trio:init-project 几乎所有下游 skill
docs/TDD/0.common/code-structure.md trio:tdd-code-structure agent PRD/TDD/TC/test 全部
trio/subsprint/<n>-MMDD-<word>/<n>-subsprint-plan.md /trio:subsprint-planner runner + sync
docs/Test-Report/<n>-MMDD-<word>/bugs.json /trio:test-management bugfix planner + Trio Stage

文件名是合同的一部分,不可重命名;schema(特别是 Bug schema v1.1)也是显式版本化的。

3.3 Skill 编排,Agent 执行

  • Skill = 决策树 + 前置条件检查 + 派单。skill 自己不写文件
  • Agent = 真正读写 docs/ / code/、跑 Playwright、生成 PRD 内容的工作单元。

这种分工的实际价值:当流程要调整时,只动 skill;当生成质量要提升时,只动 agent;不用每次改 prompt 都满地图找。

3.4 落盘的状态,对抗上下文压缩

凡是会跑很久或可能被 auto-compact 截断的流程,Trio 都把中间结果写到磁盘:

  • 测试执行的 partials/<sub#>.json
  • gap-check JSON
  • subsprint plan 本身

主控 skill 在每一步重新从盘里读,从不依赖会话内存里 "我刚才看到的"。

3.5 计划清单契约(Plan Checklist Contract)

每个 subsprint plan 顶部都是这三行(顺序、字面值都不能变):

## Execution Checklist

- [ ] **Execute Coding**`/trio:subsprint-runner` (applies code edits in place)
- [ ] **Update Docs**`/trio:subsprint-sync` (applies doc edits in place)
- [ ] **Update Test Case**`/trio:tc-management` (patch or audit path)

规则:

  • 每个框只有一个 skill 能翻——runner 翻第一个(代码),sync 翻第二个(文档),tc-management 翻第三个(测试用例)。
  • 翻完要写明 trailer:— completed YYYY-MM-DD HH:MM by <skill>
  • [x] N/A 必须附一句原因,且不能再被翻回 [ ]

整个子冲刺 "做没做完" 是一个机械可读的状态——不是 AI 的口头报告。


五、主流程

整个 Trio 工作流就是一个循环:/trio:next 告诉你下一步 → 你跑被推荐的 skill → 产物落到 docs/ code/ trio/ → 再问 /trio:next

下面用一个具体场景走一遍——你刚把 PRD/TDD/TC 都写完了,code/ 还是空仓库,第一步去问 Trio:

4.1 起手:跑 /trio:next 看下一步

Trio — 下一步建议(当前时间 2026-04-26)

最近状态:
  - code/ 源文件数:0
  - URS:存在
  - PRD-Overview:存在
  - PRD / TDD / Test-Case 模块数:5 / 5 / 5
    · docs/PRD/        — 5 模块 / 24 子模块 / 29 PRD 文件 ✓
    · docs/TDD/        — 5 模块 / 34 TDD 文件 + tech-stack + code-structure ✓
    · docs/Test-Case/  — 5 模块 / 332 TCs ✓
  - 最新测试报告:(暂无)
  - 最新 subsprint:(暂无)

主建议(P4):
  三大支柱齐全,code/ 还是空仓库——可以起第一个 iteration 把 P0 TCs(137 条)
  反推成代码任务。建议从 M1 用户注册登录 + M2 PPT 上传/转图入手,作为最薄的
  端到端切片。
  → 运行 /trio:subsprint-planner
  → 关键参数:source=fresh

备选:
  [A] /trio:tdd-management → [3] regenerate code-structure —— 等代码出来再跑
  [B] /trio:test-management —— 现在 332 TCs 全是 BLOCKED,没意义

另一种典型起点——刚跑完 /trio:init-project,PRD/TDD/TC 全空、URS 也没准备,再问 /trio:next

Trio — 下一步建议(当前时间 2026-04-26)

最近状态:
  - code/ 源文件数:0(目录尚未创建)→ P0 基建分支不触发
  - URS:不存在
  - PRD-Overview:缺失
  - PRD / TDD / Test-Case 模块数:0 / 0 / 0
  - tech-stack.md:已存在 ✓
  - 最新测试报告:无(docs/Test-Report/ 为空)→ P0.5 / P1 N/A
  - 最新 subsprint:无 → 无进行中工作
  - URS vs PRD Gap Check:N/A(URS 不存在)

主建议:先准备 PRD 的输入材料
  项目刚完成 bootstrap,三大支柱(PRD/TDD/Test-Case)全空,且既无 URS
  也无 code/。Trio 决策树的所有 P0–P3 分支都不会触发——它们都需要至少
  有 URS 或 code/ 作为输入。
  → 推荐做法:先放一份用户需求说明(URS)进 docs/,再跑 /trio:prd-management
    启动 PRD-Overview 撰写。

注意 /trio:next 在这种"什么都没有"的状态下不会硬塞一个跑不通的 skill 给你——它会讲清楚为什么各分支都不触发,然后指向真正的前置条件(这里是补 URS)。

/trio:next 从不替你按 enter——它只读、只建议,按下面这张路由表挑分支:

你看到的状态 /trio:next 通常会推
code/ 有源码但 PRD 整体缺失 P0/trio:prd-management
PRD 在但 TDD 缺 P0/trio:tdd-management
最新 bugs.json 有 Pending P0.5/trio:view-document(Trio Stage 浏览器三角分类)
有 Accepted 但还没修的 bug P1/trio:subsprint-planner[2] bugfix
URS↔PRD / PRD↔TDD / PRD↔TC 有缺口 P3 — 对应 management skill
全部干净 P4 — 问要不要起新功能

4.2 选项 1 → 起第一个 fresh subsprint(init 阶段)

/trio:subsprint-planner,选 [4] Brand-new (fresh) plan。fresh 是两步——先 init 给你骨架,你填好之后再 finalize:

Plan source: Fresh
Phase: init
Allocated: trio/subsprint/1-0426-aurora/

Created:
  trio/subsprint/1-0426-aurora/1-subsprint-plan.md   (skeleton, <!-- TODO --> 占位)
  trio/subsprint/1-0426-aurora/notes/                (你把参考资料丢这里)

下一步:编辑 1-subsprint-plan.md,把这几节填好——
  - # Goal
  - # Scope(in / out-of-scope)
  - # Tasks(每个 task 的 Code Paths、Verification)
  - # Test Case Impact(这次改动会影响哪些 TC)

填完再跑一次 `/trio:subsprint-planner` → [4],进入 finalize。

填完之后再跑 /trio:subsprint-planner [4]

Phase: finalize
Source folder: trio/subsprint/1-0426-aurora/

Validated:
  - Front-matter ✓ (source: fresh, subsprint_id: 1, docs_changes_expected: true)
  - Execution Checklist ✓ (3 boxes initialized)
  - 7 Tasks parsed
  - Test Case Impact: 14 TCs scoped (M1: 8, M2: 6)

Plan ready: trio/subsprint/1-0426-aurora/1-subsprint-plan.md

Recommended sequence:
  1. /trio:subsprint-runner 1   — 应用 code 改动
  2. /trio:subsprint-sync 1     — 同步 doc 改动 + 回写 14 条 TC patch

4.3 跑 runner,把代码落地

/trio:subsprint-runner 1 按 task 顺序把代码改动写进 code/,每完成一个 task 立刻本地 verify:

Subsprint 1 (1-0426-aurora) executing...

[Task 1/7] Auth · register endpoint scaffold
  Code: code/src/auth/register.ts, code/src/auth/schema.ts
  → applied
  → verify: cd code && pnpm test auth/register → 4/4 PASS
  ✓ Task 1 done

[Task 2/7] Auth · login endpoint
  ...
  ✓ Task 2 done

...

[Task 7/7] PPT · thumbnail conversion worker
  ✓ Task 7 done

Checklist updated:
  - [x] Execute Coding — completed 2026-04-26 14:32 by trio:subsprint-runner
  - [ ] Update Docs    — pending
  - [ ] Update Test Case — pending

下一步:/trio:subsprint-sync 1

任何一个 task 的 verify 失败都会当场停下——不会带着红条跑完七步还假装一切顺利。

4.4 跑 sync,同步文档 + 回写测试用例

/trio:subsprint-sync 1 干两件事:先把 plan 里 doc 改动应用到 docs/,再调 /trio:tc-management(patch 路径)按 Test Case Impact 给受影响的 TC 加严:

Subsprint 1 sync starting...

[1/2] Docs sync
  Doc paths: docs/PRD/1.Auth/1.1.register.md, docs/TDD/2.PPT/2.1.upload.md
  → applied (2 files)
  ✓ Update Docs flipped

[2/2] TC sync · dispatching trio:tc-management (patch path)
  Manifest: trio/subsprint/1-0426-aurora/tc-patches.yml
  14 patches → 14 TCs

  TC-1.1-001 ← add-verification        ✓
  TC-1.1-002 ← add-forbidden-state     ✓
  TC-1.2-007 ← tighten-precondition    ✓
  ...
  TC-2.3-006 ← add-verification        ✓

Checklist updated:
  - [x] Execute Coding
  - [x] Update Docs    — completed 2026-04-26 14:48 by trio:subsprint-sync
  - [x] Update Test Case — completed 2026-04-26 14:48 by trio:tc-management

Subsprint 1 fully synced.

到这步整个清单都是 [x]——这个 subsprint 机械意义上完成了,不是嘴上说说。

4.5 跑测试,出 bug → 回到循环

代码已经落地,/trio:test-management 一次派一个子模块给执行 agent:

Selected: 1.1, 1.2, 2.1
Report folder: docs/Test-Report/1-0426-aurora/

[1/3] sub-module 1.1 — 14 cases
  → wrote partials/1.1.json (14 PASS / 0 FAIL)

[2/3] sub-module 1.2 — 13 cases
  → TC-1.2-007 FAIL: 禁用账号居然路由到 /dashboard
  → wrote partials/1.2.json (12 PASS / 1 FAIL)

[3/3] sub-module 2.1 — 11 cases
  → wrote partials/2.1.json (11 PASS / 0 FAIL)

Assembled:
  docs/Test-Report/1-0426-aurora/report.md
  docs/Test-Report/1-0426-aurora/bugs.json   (1 bug, decision: Pending)

This run found 1 failure. Run /trio:next 看下一步。

再跑一次 /trio:next,因为 bugs.json 里有 Pending,路由到 P0.5

主建议(P0.5):
  docs/Test-Report/1-0426-aurora/bugs.json 里有 1/1 条 bug 处于 Pending。
  → 运行 /trio:view-document(Trio Stage)
  → 在浏览器里打开 bugs.json,把那条 bug 的 decision 从 Pending 改成
    Accepted / Rejected / Duplicate / WontFix
  完成后再跑 /trio:stop 关掉 Trio Stage,然后重新问 /trio:next。

triage 完(这条 bug 决定 Accepted),再问 /trio:next → 路由到 P1

主建议(P1):
  最新报告 1-0426-aurora 有 1 条 Accepted bug 还未闭环。
  → 运行 /trio:subsprint-planner → [2] bugfix
  → 自动选最新 test report 作为来源

—— 然后回到 4.2/4.3/4.4,每条 bug 用一个 subsprint 闭环。整个工作流不需要你记顺序,/trio:next 永远告诉你站在哪一步。


六、Skills 一览

Skill 作用 关键产出
/trio:init-project 项目初始化 docs/ code/ trio/ 骨架、tech-stack.md、根 CLAUDE.md
/trio:prd-management PRD 生命周期编排 PRD-Overview、模块 PRD、URS gap-check JSON
/trio:tdd-management TDD 生命周期编排 code-structure.md、模块 TDD(database / api / per-function)
/trio:tc-management 测试用例编排(audit + patch 双路径) TC 文件、test-script-mapping
/trio:test-management 测试执行(按 sub-module 分批 + 落盘 partials) report.mdbugs.json、screenshots
/trio:subsprint-planner 子冲刺规划(bugfix / gap / fresh) <n>-subsprint-plan.md
/trio:subsprint-runner 子冲刺执行(代码) code/ 内联改动 + 翻 Execute Coding
/trio:subsprint-sync 子冲刺收尾(文档 + TC) docs/ 内联改动、TC patch / 新增 + 翻 Update DocsUpdate Test Case
/trio:next 下一步建议(只读、只推荐) 控制台优先级建议

七、Agents 一览

Agent 作用
trio:prd-overview PRD-Overview.md + 模块文件夹骨架
trio:prd-by-module 写单个模块的 PRD
trio:prd-check-urs-gap URS↔PRD gap 审查,输出 JSON 待人工决策
trio:prd-add-screenshot 用 Playwright 给 PRD 加截图
trio:tdd-code-structure 生成 code-structure.md
trio:tdd-write-all 写整套或单模块 TDD
trio:tc-write 写/改 TC(add / skip / rewrite / patch 四种 decision)
trio:bugfix-plan 从 failing test report 生成 bugfix subsprint plan
trio:urs-gap-plan 从 gap-check JSON 生成 gap subsprint plan
trio:subsprint-fresh-plan 全新 subsprint plan(init / finalize 两阶段)
trio:subsprint-execute 把 plan 内联应用到 code/ docs/
trio:test-testcase-execution-agent Playwright 驱动的子模块级测试执行

八、快速开始

安装

在 Claude Code 终端里依次跑:

/plugin marketplace add https://github.com/10XTeams/trio
/plugin install trio@trio

注意:直接用 /plugin marketplace add 10XTeams/trio 简写形式 Claude Code 会按 SSH 解析(git@github.com:...),如果你这台机器没配过 GitHub SSH key 就会失败。显式给完整 HTTPS URL 最稳。

第二步里的两个 trio 不是写错——左边是 plugin 名,右边是 marketplace 名,本仓库恰好同名。

验证:

  • /plugin 进交互菜单,切到 Installed 标签页能看到 trio
  • 或者 /help,看 /trio:* 命令是否出现

更新 / 卸载:

/plugin marketplace update trio
/plugin uninstall trio@trio

最短路径示例

新项目从零开始:

/trio:init-project          # 拉骨架
/trio:prd-management        # 写 PRD-Overview + 模块 PRD
/trio:tdd-management        # 写 TDD
/trio:tc-management         # 写 TC
/trio:test-management       # 跑测试
/trio:next                  # 看下一步

已有代码库接入:

/trio:init-project          # Case A:自动从 code/ 反推 tech-stack.md + code-structure.md
/trio:next                  # 跟着 P0 建议补支柱

要求

  • macOS(Trio Stage 浏览器查看用到本地 Python HTTP 服务器)
  • Python 3 在 PATH(仅 Trio Stage 需要)
  • Google Chrome(Trio Stage 优先用 Chrome,找不到时回退到默认浏览器)

Trio Stage/trio:view-document)是一个本地 Markdown wiki,把当前文件夹当 wiki 浏览:文件树、Markdown 预览、便签高亮、Risk 跳转、轮廓面板。日常用法是浏览 PRD/TDD/TC,以及在 P0.5 阶段逐条改 bugs.jsondecision


九、目录布局

你的项目/
├── code/                      # 实现(独立 git)
├── docs/                      # 产品文档(独立 git)
│   ├── URS*.md
│   ├── PRD/
│   ├── TDD/
│   │   └── 0.common/
│   │       ├── tech-stack.md
│   │       └── code-structure.md
│   ├── Test-Case/
│   └── Test-Report/
│       └── <n>-MMDD-<word>/
│           ├── report.md
│           ├── bugs.json
│           ├── screenshots/
│           └── partials/
├── trio/                      # 工作流产物(不进 git)
│   ├── iteration/gap-check/
│   └── subsprint/
│       └── <n>-MMDD-<word>/
│           └── <n>-subsprint-plan.md
└── CLAUDE.md                  # 三桶约定

十、设计原则总结

  • Plan, run, sync 三段分离。 不让规划阶段偷偷动代码,不让执行阶段偷偷加用例。每段责任单一。
  • 契约文件 > 自由文本。 关键流转点都是固定文件名 + 固定 schema;想改先升 schema 版本。
  • 磁盘是真相,不是 chat memory。 任何长流程的中间结果都落盘,下一步从盘读。
  • 机械可验证的 "做完了"。 Checklist [x] + trailer = 完成证据;[x] N/A + 原因 = 故意跳过。两者都不是嘴说的。
  • Strengthen-only。 TC、Verification、Forbidden State 只能加严,不能放松;要放松必须走可见的 rewrite。
  • Skills 只编排,agents 只执行。 想改流程改 skill;想改产出改 agent。

License

PolyForm Noncommercial 1.0.0。允许个人、教育、研究、慈善 / 政府机构等非商业用途自由使用、修改、分发;不允许商业使用。商业授权请联系仓库拥有者。

About

Trio Claude Code plugin: 9 skills + 12 agents for PRD/TDD/test-case authoring and subsprint planning/execution

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages