Skip to content

Latest commit

 

History

History
83 lines (59 loc) · 5.17 KB

TEAM-PLAYBOOK.zh-CN.md

File metadata and controls

83 lines (59 loc) · 5.17 KB

团队落地指南(Team Playbook)

这份文档总结了在真实生产仓库中推广 AI Coding Agent 时的核心方法论、常见踩坑和低阻力试点方案,可直接作为团队内部分享或试点对齐材料。


一、核心共识:我们要的不是“写得快”,而是“质量可控地快”

多数团队在引入 AI 编程工具后,很快会进入一个尴尬阶段:

  • 写 Demo、补单测、查文档确实快了;
  • 但一上核心业务需求,AI 经常“改了一堆不该改的文件”“顺手弱化测试断言”“看起来很合理却藏着边界 Bug”,最后 Review 和返工成本把省下来的时间全吃掉了。

解决这个问题的关键,不是换更玄学的 Prompt,而是建立四条工程基线:

  1. 轻量、高信噪比的约束:只写 AI 靠读代码猜不出来的项目约定,避免长篇大论稀释注意力甚至触发宿主截断。
  2. 先对齐计划,再动代码:跨模块改动先花 3 分钟对齐一页纸计划,远比写完 500 行再推倒重来便宜。
  3. 写与审隔离(Producer != Reviewer):不要让刚写完代码的同一个会话自查通过;换一个干净上下文按 diff 独立审查,拦截率会显著提升。
  4. 确定性检查兜底:Build / TypeCheck / Lint / Test 是硬门禁,绝不靠模型口头保证“应该没问题”。

二、生产交付 4 步闭环

阶段 使用工具 目标 谁来拍板
1. 对齐方案 write-plan 明确目标、非目标、改动文件、接口取舍与验证方案 工程师确认范围与契约
2. 编码实现 Agent + 项目 AGENTS.md 按切片最小修改,同步补测试 Agent 执行,遇阻塞回问
3. 排障(按需) debug 复现 → 假说 → 取证 → 最小根因修复 Agent 取证,复杂根因人协同
4. 独立审查 & 收口 review-code + feature-ready 独立会话查 P0/P1 证据,过门禁并出 PR 摘要 工程师最终审核并合并

节奏建议:10 行以内明确小改动可直接“实现 → 验证”;涉及多文件、接口或核心逻辑的改动再走完整闭环,不要为了流程而流程。


三、人机分工红线

归工程师拍板(价值与责任) 放心交给 AI(查证与执行)
需求取舍与非目标划界 梳理既有代码调用链与影响面
公共 API / 数据库 Schema / 外部契约变更 按已确认计划分步编码与补齐测试
风险接受(某个 P1 这次修不修) 按证据清单执行独立视角 diff 审查
最终代码合入、发布与回滚决策 复现问题、定位日志、跑通 Build/Test/Lint

四、团队最容易踩的 5 个坑

  1. 把规则文件写成“团队百科全书”

    • 现象:往 AGENTS.md 塞进上万字编码规范,结果上下文税暴涨、尾部被截断、关键条款反而失效。
    • 对策:项目规则控制在 150 行以内;格式、命名、import 顺序全部交给 Linter/Formatter,不写进 Prompt。
  2. 直接复制粘贴别人的全套 Skills

    • 现象:一次性装几十上百个 Skill,触发词互相打架,团队成员根本记不住何时用哪个。
    • 对策:从本仓库这 4 个最高频 Skill 起步;只有团队里某个痛点真实反复出现 3 次以上,才沉淀新的团队 Skill。
  3. 同一会话里自写自审

    • 现象:写完代码顺口问一句“帮我 review 一下有没有问题”,模型顺着刚生成的思路自我肯定。
    • 对策:关键改动必须开新会话或用独立 sub-agent 跑 review-code,只给 diff 和源码,不喂自我表扬。
  4. 允许 AI “顺手优化”无关代码

    • 现象:改一个小功能,diff 里顺带重构了半个目录,Review 极痛苦且容易引入隐蔽回归。
    • 对策:严格执行“范围外问题只记录、不顺手修”;feature-ready 阶段必看 git diff --stat。
  5. 测试失败时默许 AI 改断言或跳过用例

    • 现象:测试红了,模型为了交差把断言放宽或加 skip,表面全绿实际埋雷。
    • 对策:把“禁止弱化断言/删除测试变绿”写进全局规则和 PR 审查红线。

五、两周低阻力试点方案(推荐给 TL / 团队推广)

不要全组一刀切,建议按两周小闭环推进:

  • 第 1 周:单仓库打样
    • 选 1 个测试体系较健全的核心仓库,补齐精简版 AGENTS.md(参考 templates/PROJECT-AGENTS.md 与 examples/project-agents-example.md)。
    • 由 1 位主推人用“计划 → 实现 → 独立审查 → 交付体检”跑完 2–3 个真实需求,沉淀 1–2 个真实拦截案例(例如独立 Review 拦下的 P0/P1)。
  • 第 2 周:2–3 人跟跑复盘
    • 拉 2–3 位同学一起按同一套模板跑真实需求,重点记录:
      • 哪些规则真的帮到了?哪些是废话?
      • 独立 Review 拦下了什么问题?有没有误报?
      • 在哪些环节还是容易卡壳(如本地测试慢、上下文缺关键业务背景)?
  • 第 2 周末:裁剪固化
    • 删掉没用的规则,把高频真实痛点补进项目 AGENTS.md,再决定是否推广到更多仓库。