My-Skills-team
我为什么做了一个四角色 AI 编程团队
现在openspec应用的很广泛，但是我觉得他比较“重”，我每次只想改一小点东西的时候，他老是写很多文档，比较慢（并不是说不好，这当然有利于项目的长期维护），但是有时候追求速度的时候，总是感觉心里比较“急”，于是，最近整理了一个小仓库：[ttt-aiteam](田广伟/TTT-aiteam)，用来做一些小需求，去解决前面的问题，也算是自己aicoding的一些心得
它没有网页界面，也没有自己训练模型，核心文件基本都是 Markdown、YAML 和两个 Shell 脚本。说得直白一点，它不是一个新的 AI 编程工具，而是一套给 Claude Code 使用的工作流程。
我想解决的问题也不复杂：不要让 AI 一上来就写代码。
很多时候，我们只说一句“帮我加个登录功能”，模型马上开始改文件。代码可能写得很快，但需求边界、接口设计、异常情况，往往都没有真正想清楚。等到测试失败，才发现最开始的理解就偏了。
所以我把这个过程拆成了四个角色：
– Story：先把需求问清楚，拆成可以验收的功能。
– Arch：确定技术方案、文件结构和接口。
– Dev：按照设计实现代码。
– QA：写测试、真正执行测试，并反馈问题。
整个流程大概是这样：
用户需求
↓
Story 拆解需求
↓
Arch 输出设计方案
↓
用户确认设计
↓
Dev 实现代码
↓
QA 编写并执行测试
↓
失败则修复，最多循环 3 轮
↓
完成交付
“`
先把需求写下来
Story 阶段对应的是 `requirement.yaml`。
它不负责决定用 Go 还是 Python，而是负责回答几个问题：到底要做什么、谁会使用、什么结果算完成、哪些内容不在范围内。
仓库里还规定了一条比较实用的规则：如果验收标准超过 5 条，或者需求里包含多个独立功能，就必须拆成多个模块。每个模块单独实现、单独测试，避免一个大需求从头到尾混在一起。
需求不清楚时，Story 不能直接猜。它需要继续向用户提问，直到有足够把握再开始写文档。
这个规则看起来有点啰嗦，但确实能挡住不少返工。很多代码问题，最早并不是代码写错了，而是需求根本没有说清楚。
设计完成后，先让人看一眼
Arch 阶段会读取需求文档，生成 `design.yaml`。
里面需要写清楚技术栈、项目结构、函数签名、接口、依赖、设计取舍和潜在风险。Dev 不应该拿到一句“你自己看着办”，而是拿到一份尽可能明确的施工图。
这里有一个我比较坚持的点：Arch 设计完成后，必须等用户确认，不能直接进入开发。
AI 的速度很快，但快不代表方向一定对。技术方案如果一开始就选错了，后面写得越快，返工越多。让人先看一眼，至少可以在代码产生之前发现问题。
Dev 不能自由发挥
Dev 的约束比较严格。
设计文档里定义了什么文件路径，就按什么路径创建；接口里写了什么函数签名，就不能自己改成另一种写法。多模块需求也要按照顺序处理，当前模块没完成之前，不提前修改后面的模块。
这可能会让开发过程显得没那么“聪明”，但我觉得这是有必要的。一个角色负责做设计，另一个角色负责落地，如果 Dev 一边实现一边重新设计，前面的文档就失去了意义。
QA 必须真的跑测试
QA 阶段不是简单地看一遍代码，然后说“应该没问题”。
它需要根据验收标准写测试，执行项目实际的测试命令，并把结果写进 `test-report.yaml`。测试报告里除了通过和失败数量，还要求记录错误输出、相关文件、运行环境和修复建议。
测试失败之后，结果会交回 Dev 修复，再由 QA 重新执行。最多循环三轮，三轮之后还没解决，就停止并报告问题。
这里的“四角色”并不是四个独立运行的程序，实际上还是 Claude Code 在不同阶段读取不同的角色说明。更准确地说，这是给 AI 加了一套比较明确的工作纪律。
用一个命令把 Skill 放进项目
为了方便使用，我又写了两个 Shell 脚本。
安装：
“`bash
chmod +x install.sh team
./install.sh
“`
安装脚本会把 `.claude` 目录复制到：
“`text
~/.local/share/ai-coding-team
“`
同时把 `team` 命令安装到：
“`text
~/.local/bin/team
“`
进入任意项目根目录后，可以执行：
“`bash
team init
“`
它会把 Skill 复制到当前项目的 `.claude/` 下，而且使用的是不覆盖策略，已经存在的文件会保留。
另外还有两个命令：
“`bash
team list
team clean
“`
一个用来查看 Skill 文件，一个用来清理当前项目的 `.claude/` 目录。清理前会要求确认，不会直接删除。
我更看重中间产物
这个项目里我比较看重的，其实不是 `team init` 这个命令，而是过程中的几个文件：
“`text
.ai-team/
├── requirement.yaml
├── design.yaml
├── test-report.yaml
└── logs/
“`
以前很多决定都散落在聊天记录里，过几天再回头看，很难知道当时为什么这么设计。现在至少可以留下需求、方案和测试结果，出了问题也有地方可查。
说白了，就是把容易飘走的对话，变成项目里能留下来的文件。
目前还不算完美
这个仓库现在还比较像一个可用的原型。
另外，仓库本身没有单独的自动化测试。QA 的测试能力取决于目标项目有没有合适的测试命令。对于一个 Go 项目，可以跑 `go test ./… -v`；对于 Python、JavaScript 项目，则需要根据项目自身情况处理。
还有一点，小需求不一定值得完整走完四个角色。改一个按钮颜色，没必要先写需求文档再出架构方案。但当功能开始变复杂，或者多人一起协作时，这套流程就有价值了。
最后
我不觉得 AI 编程一定要设计成很复杂的系统。相反，我做这个工具时一直在想，能不能只增加一些必要的步骤，让 AI 少一点跳跃，多一点确认。
`ttt-aiteam` 现在做的事情很朴素：先问清楚，再设计；先确认，再编码；写完代码，真的跑测试。
它不能替我思考，也不能保证每次都写对。但至少会提醒我，把那些本来容易被忽略的事情，放到代码之前处理掉。
