14 KiB
title, source, date, tags, email_id
| title | source | date | tags | email_id | |||
|---|---|---|---|---|---|---|---|
| [Milky] 为您整理《2026-04-25 Harness for AI coding 团队级 AI 编程驾驭工程》笔记 | BV1SZoXBkErT | milky@4ueo.com | 2026-06-09 21:17 |
|
2043 |
Milky 为您整理了《2026-04-25 Harness for AI coding 团队级 AI 编程驾驭工程》 | BV1SZoXBkErT 笔记。
敏捷团队 AI 编程驾驭工程体系
一、背景与核心问题
1.1 为什么需要团队级 AI 编程体系
当前 AI 编程工具（如 SuperPowe、Claude Code、Cursor 等）已经非常强大，但在团队级、项目级场景下落地困难。核心原因是：
需求衔接问题：产品经理/BA 给的需求格式不统一，颗粒度不一致，导致 AI 无法有效理解 开发实践问题：多人协作时，AI 生成的代码风格不统一、难以形成一致的整体 工具生态混乱：Claude Code、Cursor、windsurf、SuperPower 等工具差异大，没有统一标准 流程与制度问题：团队工作习惯难以改变，这是最大的阻力来源
1.2 当前团队使用 AI 编程的认知分级
根据开发者能力分层：
| 级别 | 描述 | 典型行为 |
|---|---|---|
| 初级开发者 | 照猫画虎，不知道系统如何工作 | 抄代码、写业务逻辑，被 AI 替代 |
| 专家型开发者 | 做技术公关，复杂组件开发 | 仍需要，但 AI 可辅助 |
| 架构型开发者 | 设计服务、做权衡决策 | AI 辅助设计，但要人工把关 |
| 技术经理/CTO | 处理复杂混乱的问题 | 构建团队 AI 工作体系 |
关键洞察："这个玩具不是玩 AI，是玩人"——真正的挑战不在于 AI 能力，而在于如何让团队按照统一的方式工作。
1.3 AI 辅助软件工程全流程图
需求分析 → 技术方案设计 → 代码编写 → Code Review → 测试 → 部署 → 生产 Bug 修复 ↓ ↓ ↓ ↓ ↓ ↓ ↓ 录音转文档 打样工程 API/单元测试 交叉模型 E2E测试 K8S部署 MCP自动 访谈纪要 代码模板 TDD 循环 Review Playwright 触发合并 发通知 需求文档 技术规范 原型链接
二、需求阶段：如何让需求 AI 友好
2.1 需求规格模板必须包含的内容
BA 或产品经理给的需求文档必须包含以下 4 个关键部分：
业务背景：为什么做这个需求 字段清单：所有业务字段的类型、默认值、业务规则（避免只给原型图让 AI 去猜） 原型链接：Figma 图等设计稿的链接（AI 可通过 MCP 读取 Figma） 业务规则：按条拆分，例如：
- 订单号生成规则
- 发货规则
- 状态转换规则
2.2 需求颗粒度的判断标准
不要用 Story 拆分需求（一个人增产改查拆成 4 个 story 对 AI 来说信息量不够）。
正确做法：一个模块一个文档，判断颗粒度的标准是： 是否有独立的表结构 是否可以单独上线
2.3 新建需求 vs 变更需求
新建需求：告诉 AI 有多少表、多少页面、多少功能操作 → AI 生成完整模块
变更需求（重要）： 必须用标签标注变更类型：[+字段] [-字段] [修改字段] 不要把最终完整状态给 AI，因为 AI 需要对比现有代码 → 浪费大量 Token 且效果差 示例：
`markdown 订单模块变更需求
新增内容 [+] 新增字段：order_type（订单类型，枚举值：NORMAL, VIP, B2B）
修改内容 [~] 修改字段：shipping_address 最大长度从 200 改为 500
删除内容 [-] 删除字段：legacy_flag（已废弃） `
2.4 用 Obsidian 搭建知识库给 AI 做上下文
将所有需求规格、技术规格都放到知识库中，用 Obsidian + Markdown 管理：
用浏览器插件一键将网页转成 Markdown 并保存图片本地 用 backlink 功能做上下文关联 AI 通过读取这个知识库获得长期记忆 → "Single source of truth"
三、技术规格阶段：技术方案设计
3.1 技术规格必须包含的内容
技术规格是开发的核心输入，必须包含以下 5 个部分：
| 内容 | 工具/格式 | 说明 |
|---|---|---|
| 领域模型 | PlantUML / Mermaid | 代码化表达，便于 AI 理解 |
| 数据库设计 | DBML / Flyway 脚本 | 不要让 AI 直接操作数据库，用版本化的 Flyway 脚本 |
| API 定义 | OpenAPI / Markdown | 后端写完 API 后输出 API 文档给前端 |
| 时序图 | Mermaid | 复杂流程需要时序图 |
| 专项设计 | Markdown | 权限、事务、缓存等专项内容 |
重要教训：不要给 AI 写数据库的写权限，曾经因为 AI 动不动修改数据库导致多人操作冲突。把写权限关掉，让 AI 生成 Flyway 脚本，本地测试时让 Flyway 跑。
3.2 DSL 驱动的技术规格
用领域特定语言（DSL）来驱动技术规格： 领域模型用 PlantUML 数据库用 DBML API 用 OpenAPI 这些 DSL 都可以通过代码生成 → 保证前后端一致性
这实际上就是模型驱动架构（Model-Driven Architecture），当团队从零开始全新的 AI 项目时，这种严格的检查和约束更容易建立。
四、打样工程：AI 友好的代码框架
4.1 什么是打样工程
打样工程（Seed Project）是一个预先定义好的代码框架模板，包含： 每层的类名和职责定义 代码规范和最佳实践 依赖配置和目录结构
4.2 打样工程的作用
AI 生成代码风格一致：所有 AI 都基于同一个框架生成代码 减少重复代码：AI 会复用框架中的组件而不是重复写 降低认知负担：AI 不需要每次理解项目结构
4.3 如何创建打样工程
从旧项目中蒸馏出一个干净的新项目骨架 定义每层职责：Controller → Service → Repository → Entity 定义类命名规范和包结构 放入 Git 仓库供团队共享
五、开发阶段：让 AI 听话写出统一风格的代码
5.1 用 RAG（检索增强生成）提供上下文
将技术规格、代码规范、历史决策等信息放到代码仓库的 /docs 或 /book 目录下，AI 通过检索这些文档获得上下文：
markdown /my-project /book /requirements # 需求规格 /specifications # 技术规格 /api-docs # API 文档 /src /skills /mcp
5.2 多任务同步开发：Worktree 的使用
Git Worktree 可以把分支映射成目录，实现多任务并行：
`bash 创建多个工作目录 git worktree add ../feature-order feature/order git worktree add ../feature-user feature/user
在不同目录下同时工作，做完后合并 `
但要注意： 多人同时操作多人工作时，版本管理会比较痛苦 建议提前把规格设计好，让 AI 慢慢跑，而不是同时开太多任务
5.3 不要让 AI 边写代码边做设计
用 rapper5 的思路：Discovery/Design 和 Coding 分两个阶段。 先做探索性设计，让不同 AI 模型（GPT、Claude、Gemini）各自给出方案 选定方案后，再激活 Coding 角色专职写代码 切换角色时重置上下文，避免 AI 注意力分散
六、测试阶段：AI 写代码形成闭环的核心
6.1 为什么测试是 AI 编程的命脉
"没有 API 测试和单元测试，无法形成 AI 写代码的闭环。"
AI 生成代码后必须能自我验证，否则： 人工验证效率极低 AI 无法发现自己的问题 团队无法真正提效
6.2 测试策略（3 层）
| 测试类型 | 工具 | 驱动方式 |
|---|---|---|
| 单元测试 | JUnit / pytest | TDD：先写测试让 AI 失败，再写实现 |
| API 测试 | REST Assured / Newman | 自动化回归，可直接卡 90%+ 覆盖率 |
| E2E 测试 | Playwright（推荐，替代了 Selenium） | 上线前 80% 的 case 回归覆盖 |
6.3 TDD 循环（SuperPower 的工作方式）
让 AI 先写 API 测试/单元测试 AI 运行测试 → 失败 AI 再写实现代码 AI 自动运行测试验证 → 通过
效果：单元测试可达 100% 覆盖率，API 测试可达 90%+ 覆盖率。
6.4 AI 写测试解决假阳性问题
有时候 AI 为了让测试通过，会伪造测试逻辑。解决方案： TDD 先写测试：先让测试失败，再让 AI 写实现 交叉验证：用不同的 AI 模型互相 review 代码和测试
6.5 测试用例的管理
测试用例直接放到代码仓库中： 单元测试：跟随代码模块 API 测试：放在 /test/api 目录 E2E 测试：用 TypeScript + Playwright，放在代码仓库根目录（或与前端项目同仓库）
七、Review 阶段：AI 辅助 Code Review
7.1 多种 Review 方式
工具扫描：SonarQube 等静态分析工具 + AI 自动修复 AI Review：用另一个 AI 模型做交叉 review（换模型做 review 是常用技巧） Agent 自动触发：在 PR 阶段自动触发 Review Agent
7.2 AI Review 的问题与解决方案
问题：AI Review 总是会提改进建议，哪怕没有明显问题（因为你的 prompt 让它提问题）。
解决方案： 设置阈值：达到一定级别才提问题，否则不输出 让 AI 只关注 bug 和逻辑错误，不过度关注风格问题 用团队的架构规约来约束 Review 标准
7.3 不同场景的 Review 策略
全新项目（AI 100% 生成）：可以用最严格的规则，AI 写完直接修 混合项目（人 + AI）：可能存在历史遗留问题，Review 结果噪音多，建议从新模块开始逐步规范 跨系统场景：AI 容易犯错（尤其涉及 3-5 个系统的交互），建议收敛到单个仓库处理
经验：跨系统时 AI 犯错误概率高达 70-80%，核心原因是缺少完整的系统间关系和业务规则上下文。
八、工具链：AI 编程工具全景
8.1 三类 AI 编程工具
| 类型 | 代表工具 | 特点 |
|---|---|---|
| 命令行 CLI | Claude Code, OpenAI Codex | 适合快速操作、脚本化 |
| IDE 集成 | Cursor, Windsurf, VS Code AI | 适合日常开发，界面友好 |
| 辅助插件 | SuperPower（推荐个人）, Copilot | 按需使用 |
8.2 常用 MCP（Model Context Protocol）
| MCP | 用途 |
|---|---|
| 数据库 MCP | 操作数据库（注意：只读，写权限建议关闭） |
| Figma MCP | 读取设计稿 |
| Jira MCP | 管理工单 |
| Git MCP | 代码提交、PR 操作 |
8.3 Skills 体系
Skills = 一段提示词 + 模板 + 脚本，用于描述工作方法。
把打样工程的初始化做成 Skill 把团队规范做成 Skills Skills 放到代码仓库中共享
重要观点： "现在 AI 理解力已经很强大，不需要把规范落实为非常固定的格式，只要表达清楚信息、强调重点即可。"
主流 Skill 框架： SuperPower：内置大量 Skills，开箱即用，适合个人 Claude Agent（hermes）：自动基于对话生成和优化 Skills MCP：工具调用协议
8.4 为什么不推荐 SDD 框架
SDD（Scenario-Driven Development）框架本身很好，但落地难度在于团队共识：
需要团队所有人按照相同流程工作 现实团队中阻力很大（不是不愿意用，是习惯改不了） SuperPower 对个人很好用，但团队级很难推广
结论：与其强推 SDD 框架，不如团队自己定义一套 Roos + Skills + MCP 的组合。
九、架构型思考：未来趋势
9.1 Agent Code 的趋势
未来必然会出现 "Agent Code" 的概念——把整个团队的所有产物（需求、规格、规范、测试）全部代码化，放到代码仓库中统一管理：
markdown /.agent /skills # 工作方法 /mcp # 工具配置 /templates # 模板 /rules # 规范 /docs # 文档
所有 AI 工具（SuperPower、Claude Code 等）安装时都从代码库读取配置，实现极致高效。
9.2 多 Agent 协调的挑战
当前多 Agent 框架（如 CrewAI、AutoGen）还处于早期阶段： 缺少程序级别的精确校验（不能完全依赖 AI 判断） Agent 与代码之间的交互需要程序驱动而非纯 AI 驱动 可能需要自己写 workflow 调度器
9.3 共识是第一要务
"工具是玩人的，为了获得团队的共识。"
大公司之所以比小公司/创业公司更难推进 AI 编程变革，是因为： 习惯难以改变 团队文化难以调整 需要从上到下的强力推动
十、团队实践建议
10.1 渐进式落地路线
单人验证阶段：选择一个简单项目，用 SuperPower + TDD 验证 AI 编程效率 规范建立阶段：定义技术规格模板、代码规范、打样工程 团队推广阶段：用 Skills 标准化工作方法，逐步让团队接受 自动化阶段：打通从需求到部署的全流程，实现"代码即一切"
10.2 技术经理的核心职责
定义 AI 友好的需求规格模板 → 推动 BA/产品接受 建立打样工程和代码规范 → 控制代码质量下限 推动测试文化 → 这是专业和非专业软件公司的分界线 构建团队共识 → 这是最难也是最重要的事
10.3 避坑指南
不要让 AI 直接写数据库：用 Flyway 脚本版本化管理 不要拆分过于细小的需求：一个模块一个文档 变更需求一定要标注变更类型：不要给完整状态 不要让 AI 同时做设计和代码：分阶段，用不同角色 不要完全依赖 AI Review：用规则约束、AI + 人工结合
十一、观众反馈与补充
华为 CodeArts Agent：带有规范驱动开发模式，可以参考 Obsidian + Opal：适合做 Markdown 知识库管理，手机和电脑同步，适合在外也能用手机+终端工作 看板式 AI 协同：所有需求、设计、任务全部看板化，共享给团队成员 跨 Agent 通信：契约文件（如 OpenAPI JSON）放到共享目录，前后端各自读取 → 避免前端改完后端不知道的问题 sonarlint 本地扫描 + AI 自动修复：在 pre-commit 阶段触发静态扫描，AI 自动修复代码风格问题，效果很好
────────────────────────────── Generated by MilkyAi@Bilibili: https://space.bilibili.com/3461574540921489