ai-collaboration-workflow

# AI 协作工作流 ## 定位 本 skill 是仓库级人机协作开发流程和 agent 行为规则正文，负责把一次自然语言请求推进到理解、澄清、计划、执行、验证、沉淀、发布和收尾。 协作流程图在 `assets/collaboration-flow.svg`。README 可以引用该图，但规则正文以本文件为准。 ## 分工 | 对象 | 负责 | 不负责 | |------|------|--------| | 本 skill | 人机协作主流程、agent 行为规则、HIL、topic / roadmap、任务拆解、承载位、worktree、验证证据、发布边界、最终交接 | 项目 runtime 命令、具体语言风格、复制 Superpowers 执行细节 | | Superpowers / `using-superpowers` | 具体任务执行方法，例如 brainstorm、writing plans、TDD、debug、review、skill writing、finishing branch | 仓库级真相源、项目事实、PR 发布策略、长期知识承载位裁决 | | 项目文档 | 当前仓库事实、架构、命令、依赖、部署、默认沟通语言 | 跨仓库协作规则或执行方法 | | 团队可见工件 | PR description、topic design、project overview 等协作输出 | 最高优先级 agent 行为规则 | ## 入口流程 仓库会话第一轮先加载本 skill。它是主流程；Superpowers 是具体任务执行体系。 启动顺序： 1. 读取本 skill，建立仓库工作流上下文。 2. 读取当前任务需要的仓库上下文。 3. 按统一决策协议判断是否需要 HIL、plan、topic、worktree 或具体执行 skill。 4. 进入具体任务执行时，交给 `using-superpowers` 或对应 Superpowers skill。 5. Superpowers 执行结束或遇到疑问后，控制权回到本 skill，继续做仓库级判断。 返回规则：任何 Superpowers 执行结束后，都回到本 skill 继续处理用户对齐、工作区、承载位、topic / roadmap、验证、知识收口、发布和最终交接。一个仓库任务可能多次往返：例如先用 workflow 建 topic 和 roadmap，再把 roadmap 子任务交给 Superpowers 执行，执行中若发现需求不清再回到 workflow 做 HIL 判断，随后继续下一批子任务。 具体项目文档路径由消费仓库入口文件或项目总览指定。本模板当前默认路径是： - `AGENTS.md` / `CLAUDE.md`：agent 入口、导航地图和 agent 专属适配。 - `docs/references/project-overview.md`：项目边界、架构、运行命令、依赖策略、部署和默认沟通语言。 - `docs/references/python-code-style.md`：Python 代码、脚本、测试和 review 偏好。 - `.ai/superpowers/plans/active/`：本地单次执行计划。 - `.ai/superpowers/specs/`：本地设计草稿。 - `.ai/topics/<slug>/`：跨轮长期主题。 - `.ai/feedback/<slug>/round<N>.md`：用户反馈原料。 复制到其它仓库时，入口文件和项目总览可以替换这些路径；本 skill 的职责不变。 ## 铁律 以下规则不可绕过。不要把它们混进“质量闸门”里；质量闸门只负责验证、范围、风险和代码质量。 1. **AI-first**：AI 引导流程和下一步；用户提供 context 与关键判断。不要让用户手工驱动 agent 本该恢复、判断和推进的流程。 2. **先判断再行动**：用户表达不确定、征询判断或希望共同探讨时，先给判断和取舍；方向明确、改动可逆且不锁定设计时才直接执行。 3. **输入不是自动 todo**：用户反馈、PR comment、review、CI、工具输出和 agent 建议都要先判定正确性、时效、范围和用户方向。 4. **非琐碎工作必须有 plan**：多文件、跨模块、协作骨架、规则语义或高风险变更，动手前建立本地 active plan；纯 typo / 路径引用 / 格式小修可不建。 5. **写入前必须确认 worktree 隔离**：任何会产生修改的行为之前，先确认当前路径、branch 和 worktree 属于本任务。已有目标 worktree 时，只能在该 worktree 修改。非目标 worktree 只允许只读排查；如果发现自己已经写错位置，立刻停止新改动，把自己的误改迁回目标 worktree，并清理误改工作区。 6. **完成声明前必须验证**：没有本轮新证据，不说完成、已修复、通过或 done。 7. **少文件和单一真相源**：默认合并到现有 owner 清晰的文件；只有读者、生命周期、真相源、权限边界或维护节奏明显不同时才拆文件。同一规则只保留一份正文。 8. **反特例化 / 先搬业界再自造**：新增或修改长期规则、hook、agent、command、skill 时，先查成熟开源方案和官方 docs，优先采用通用抽象；现有方案不满足时才自建。规则必须是 framework 级抽象，不能只覆盖本次症状、句式或关键词。 9. **文档只保存最新状态**：规范、README、project overview、skill 正文只描述当前状态，不写“原本 X 现在 Y”或“第 N 轮新增”。演进历史交给 git、PR、roadmap、Provenance 或 decision log 承载。 ## 统一决策协议 写代码、文档、topic、本地草稿、测试、commit、push、PR body 或回复评论前，先完成一次决策。只读搜索可以先做；任何会改变仓库、外部状态或团队认知的动作都要过本协议。 | 判断项 | 必须回答 | |--------|----------| | 意图 | 用户是在下命令、表达偏好、提出不确定想法，还是要求共同判断？ | | 输入判定 | 输入是否正确、当前、在范围内、与用户方向一致？是接受执行、用户已明确要求、过期 / 错误、有效但不在范围、与用户方向冲突，还是不确定？ | | HIL | 能否用现有文档、topic、PR/git 历史和代码自解？只有语义会实质影响交付物、业务取舍无法解出、需要凭据/外部访问、不可逆或高风险时才停下来问用户。 | | 范围 | 小形式修正、同 PR follow-up、独立 PR、长期规则 / 架构变更、bug fix、review fix，还是高风险变更？是否需要 active plan？ | | 工作区 | 当前路径 / branch / worktree 是否属于本任务？不属于时只能执行只读定位，先切到正确 worktree；禁止在非目标 worktree 写文件。 | | 承载位 | 结论应留在 chat、PR body / comment、project overview、reference doc、tracked topic，还是本地 plan / spec？ | | 文件数 | 现有文件能否承载？只有读者、生命周期、真相源层级、权限边界或维护节奏明显不同时才新建文件。 | | 执行交接 | 是否进入具体任务执行？该交给哪个 Superpowers skill / 执行流程？执行结束后要回写哪些 workflow 承载位？ | | 验证 | 本轮什么新证据能证明改动？ | | 发布 | commit、push、PR 更新、外部通知或破坏性动作是否已有当前范围授权？ | 用户出现“我感觉”“可能”“你觉得呢”“一起看看”“不确定”等探讨信号时，先给判断和取舍；只有方向明确、改动可逆且不锁定设计时才直接执行。 ## Superpowers 交接 交给 Superpowers 前，workflow 要说清： - 任务边界：解决什么，不解决什么。 - 可用上下文：项目文档、topic、plan、PR 评论或反馈路径。 - 期望产物：代码、计划、验证证据、review findings、调试结论等。 - 回传条件：执行完成、发现需求歧义、遇到技术阻塞、命中不可逆动作。 Superpowers 解决不了的问题不要直接甩给用户。先回到 workflow： 1. 查项目文档、topic、PR/git 历史、代码和本 skill。 2. 能自解就继续推进，并把判断写进 plan Decisions 或相关 topic。 3. 解不出且会实质影响交付物，才向用户提出具体问题。 常见往返： - 需求不清或需要设计：workflow 先判断是否要 HIL / topic，再交给 brainstorming 或 planning。 - roadmap 子任务明确：workflow 选定子任务边界，再交给 executing plans、TDD 或 subagent 流程。 - 反馈 / review / PR comment：workflow 先用统一决策协议判定，再交给 review 接收类 skill 做技术核对。 - bug、失败检查或异常：workflow 保持范围和承载位，交给 debug 类 skill 定位根因。 - skill 或规则正文：workflow 判断规则归属和文件边界，交给 skill 写作类 skill 做结构和触发条件检查。 ## 执行闭环 | 阶段 | 要做什么 | 典型承载位 | |------|----------|------------| | 理解 | 确认目标、范围、风险、工作区、承载位、验证和发布边界 | chat、feedback、PR comment | | 修改 | 在统一决策协议和必要 handoff 后做最小正确改动 | code、docs、config | | 验证 | 运行能证明本轮改动的检查，不复用旧结果 | command output、CI、browser/runtime evidence | | 收口 | merge 前保存稳定结论，避免只留在 chat、本地 plan 或 comment | topic docs、PR body、reference docs | | 发布 | 在授权范围内 commit、push、更新 PR、回复 thread | git、GitHub | | 交接 | 明确当前状态、证据、风险和用户下一步；无需用户动作时也要说清 | final response、PR comment | 修复、验证和必要收口完成前，不回复“已修复”，不更新 PR body 声称完成。 ## 承载位 | 名称 | 路径 | 追踪 | 用途 | |------|------|------|------| | Topic | `.ai/topics/<slug>/` | 是 | 跨 session / PR 的长期主题 | | Topic design | `.ai/topics/<slug>/design.md` | 是 | 稳定设计、边界和取舍 | | Topic roadmap | `.ai/topics/<slug>/roadmap.md` | 是 | Done / in-progress / TODO | | Execution plan | `.ai/superpowers/plans/active/<slug>.md` | 否 | 单次执行 checklist 和验证记录 | | Local spec | `.ai/superpowers/specs/<slug>.md` | 否 | 本地设计草稿 | | PR body | GitHub PR | 是 | 当前 PR 的 Goal / Design / Validation / Risk | 稳定结论不能只留在本地 plan / spec。若 topic 决策升级为项目架构真相，先更新消费仓库指定的项目总览或架构文档。 放置边界： - 协作流程和 agent 行为规则：本 skill。 - 项目事实、架构、命令、依赖、部署、默认沟通语言：项目总览或入口文件指定的架构文档。 - 语言 / 框架风格：项目总览或专门的 language style reference。 - 长期主题设计：`.ai/topics/<slug>/design.md`。 - 单次执行 checklist 和验证记录：`.ai/superpowers/plans/active/<slug>.md`。 - 当前 PR 的交付摘要：PR description 的 Goal / Design / Validation / Risk。 发生冲突时，先按本 skill 的 agent 行为规则判断；项目事实以消费仓库指定的项目总览 / 架构文档为准；当前 PR 的特殊决策只在本 PR 范围内生效。 ## 质量与范围闸门 质量闸门不是铁律本身；它们是声明完成前必须满足的检查口径。 - **验证**：测试、lint、type check、运行验证、diff review、frontmatter / Markdown 解析、链接检查等，按改动类型选择。文档措辞不写脆弱字符串测试。 - **范围**：优先最小正确改动；不做未授权的大范围 refactor、跨模块 rename、投机抽象或无关清理。 - **Fail-fast**：不要吞错，不要用默认值替代必填字段，不要在必经流程周围加“缺失就跳过”。防御性处理只属于输入校验、cleanup、cancellation 或兼容 shim。 - **删除**：被替换文件能删就删；只有稳定外部引用合同时才保留薄跳转。 - **完成声明**：最终回复必须说明当前状态、验证证据和用户下一步；真的无事可做时明确说无需用户操作。 ### HIL 默认不打断用户。能用现有文档、topic、PR/git 历史、代码和当前指令自解的，agent 继续推进并在最终交接里说明判断。尤其这些情况不需要 HIL： - 用户方向明确，改动可逆，且不会锁定设计。 - 同一 PR 的 review follow-up、PR body 更新、review thread 回复或普通 PR comment，已在当前任务范围内授权。 - review / CI / 工具输出经过核对后确认为正确、当前、在范围内。 - 只是同步入口表述、路径引用、文档归属、格式或低风险 wording。 - 执行环境弹出常规 sandbox / 网络 / 写入审批，但动作本身已在任务范围内；此时按工具审批流程申请，不把工具权限摩擦升级成产品 HIL。 可以在交接中提醒用户开启适合仓库工作的 auto / auto-approve 模式，让常规文件写入、测试、PR 维护等低风险动作自动通过。 ### Worktree 任何会产生修改的行为之前，都必须检查入口文件要求的启动 / worktree 硬闸门，确认当前路径、branch、远程同步状态和 worktree 属于本任务。会产生修改的行为包括但不限于：编辑文件、格式化、生成文件、删除文件、安装依赖写 lock/cache、stage、commit、push、PR body 更新和评论回复。 独立 PR、高风险工作或长任务使用 linked worktree；同一任务 / 同一 PR follow-up 复用已有目标 worktree。 若当前 shell 不在目标 worktree： 1. 只允许运行只读定位命令，例如 `git status`、`git worktree list`、`git branch --show-current`、`git log`。 2. 切到目标 worktree 后再写文件、运行格式化、生成文件、stage、commit、push 或对 PR 产生状态变更。 3. 如果已经在错误工作区产生修改，先停止继续编辑；确认这些修改是 agent 本轮误改后，迁移到目标 worktree，并清理错误工作区。 ## 收尾交接 仓库工作的最终回复必须包含： - 当前状态：commit、push、PR body / comments，以及相关时的 worktree 干净状态。 - 本轮验证证据。 - 用户的具体下一步；或明确说明无需用户操作，以及下一步由哪个系统 / 人承载。 交接不是礼貌性结尾，而是流程的一部分。每轮完成后都要把下一步说成可执行动作，例如“刷新 PR 看 Files changed”“等 CI 完成”“确认这个讨论项后我再搬目录”“无需操作，下一步由 reviewer / CI 承载”。不要只说“完成”。 ## 常见错误 - 把最高优先级协作规则误解成团队工件层级，又把 PR body、topic design、project overview 当成规则正文。 - 把铁律混进质量闸门，导致“必须怎样协作”和“怎样证明做完”混在一起。 - “项目文档由消费仓库指定”之后只列抽象类别，不告诉当前仓库实际路径。 - Superpowers 一遇到疑问就问用户，没有先回到 workflow 查项目文档、topic、PR/git 历史和代码。 - 把输入判定、review 判定和决策协议拆成多套重复流程。 - 新建文件只是为了显得分类清楚，没有证明读者、生命周期、真相源、权限边界或维护节奏确实不同。 - 没有先确认 worktree 隔离，就在当前 shell 里编辑、格式化、生成文件、stage、commit、push 或回复 PR。