背景

小团队最大的痛点不是技术，是”注意力碎片化”——项目进度要盯，issue 要跟，PR 要 review，还要随时响应突发需求。一旦人少事多，就容易陷入”什么都在做，什么都没做完”的状态。

我们用的方案是：Linear + GitHub 做管理底座，OpenClaw 担任敏捷教练和项目管理角色，以敏捷开发节奏为骨架，让人只需要在关键决策点出现，其余的监控、提醒、整理全交给 OpenClaw。

---

工具选型

为什么 Linear 而不是 Jira / 飞书？速度和 API 体验都很好，和 GitHub 的联动配置简单，用起来不累。

---

敏捷流程总览

不从”工具操作”出发，而从开发节奏出发。整个流程是一个循环：

graph LR
    A[需求收集] --> B[Backlog 梳理]
    B --> C[Sprint 规划]
    C --> D[开发]
    D --> E[Code Review]
    E --> F[验收完成]
    F --> G[回顾]
    G -- 反馈循环 --> A

每个阶段 OpenClaw 都有明确职责，人只在关键决策点出现。

---

与敏捷开发的适配性

在介绍具体阶段之前，有必要实事求是地说清楚：这套工作流和”教科书敏捷”并不完全等价，它是在敏捷框架下做了取舍的变体，有些地方高度契合，有些地方存在明显偏差。

契合的部分

迭代节奏：Sprint 规划、Backlog 梳理、状态流转这些核心实践都保留了，OpenClaw 的作用是降低执行摩擦，而不是绕过这些实践。

短周期反馈：CI 失败即告知、PR 超时提醒、issue 超期主动询问——这些都符合敏捷”快速暴露问题”的核心精神。OpenClaw 把反馈延迟从”下次 standup 才发现”压缩到”实时感知”。

减少仪式成本：敏捷在小团队里失败的常见原因是流程本身太重，开发者不愿意维护。OpenClaw 接管了建 issue、打 label、更新状态这些机械操作，让团队能真正执行敏捷，而不是名义上敏捷、实际上靠记忆力。

持续交付：PR 合并即完成、OpenClaw 调用 Claude Code 做初筛，整体上支持高频小批量交付的节奏。

AI 工具即团队角色

理解这套工作流和敏捷适配性的关键，在于重新看待”工具”这个词。Claude Code、Codex、GitHub Copilot Agent、Cursor 不只是功能不同的软件，它们在流程中各自有倾向性的职责边界：

OpenClaw 的敏捷教练和项目管理角色是固定的，其余工具的分工则由 OpenClaw 根据任务特征动态调配——同一个 issue，规划阶段可能调用 Claude Code，实现阶段可能切到 Codex 或 Copilot Agent，没有硬绑定的对应关系（具体决策规则见后文”OpenClaw 如何选工具”一节）。

从这个视角看，这套工作流并不是”一个人用工具跑流程”，而是一个由人和 AI 角色共同构成的虚拟团队在跑敏捷。敏捷强调的跨职能协作在这里依然存在，只是团队成员从”多个人类工程师”变成了”一个人类开发者 + OpenClaw 统筹调度的多个 AI 执行角色”。

真实的局限

角色分工清晰不代表没有局限，以下两点是实际存在的：

Sprint 回顾缺乏固定节奏。目前是手动触发，Sprint 周期本身也没有强制约束。这是流程上的不完整，和团队规模无关。

执行质量依赖上下文质量。Claude Code 的规划能力取决于 issue 描述的清晰程度，Codex 的执行质量取决于任务范围的明确程度。上下文不足时，OpenClaw 调度的执行结果质量会明显下降，需要更多人工介入修正。

换句话说，这套工作流不是对敏捷的简化，而是对”团队成员”定义的扩展——OpenClaw 及其调度的 AI 工具是真实参与协作的角色，不只是辅助人类的自动化脚本。当然，这套分工目前覆盖的是技术执行层，跨团队对齐、业务决策、用户验收这些维度仍然需要人来承担。

---

Phase 1 · 需求收集

需求管理最大的问题不是”没有工具”，而是记录这件事本身有摩擦。想到一个 bug，要打开 Linear、填标题、选优先级、选类型——做完这一套，思路早断了。结果要么不记，要么记在备忘录里再也找不到。

这套流程的解法是：让 OpenClaw 成为需求的第一个接收者，记录的动作降低到”说一句话”。

最常见的方式：随时告知 OpenClaw

开发到一半发现一个边界 case 没处理，不需要停下来切换工具，直接说：

“登录页在网络超时时没有错误提示，用户不知道发生了什么”

OpenClaw 会把这句话转成结构化 issue，同时根据需求推断验收标准，推一条确认消息：

[Bug] 登录页网络超时无错误提示 · Medium · 已建 PROJ-47 验收标准：- [ ] 超时时显示明确的错误提示 - [ ] 提示内容清晰，用户知道该怎么做 确认吗？

验收标准和 issue 一起建好，写进 description——后续 AI 执行时直接从 Linear 读取，不需要另外找上下文。确认或不回复都行，issue 就进了 Backlog。整个过程不需要离开当前工作上下文。

直接在 Linear 建

有时候需求来自产品讨论或外部反馈，直接在 Linear 里建 issue 更自然。OpenClaw 在下次巡检时检测到新 issue，自动进入梳理流程，不需要额外操作。

先写代码后补记录

小团队里很常见：先把一个小功能做了，再想起来没建 issue。这时候告诉 OpenClaw：

“刚把用户头像上传做完了，帮我记一下”

OpenClaw 建 issue 并直接标记 Done——既有记录，又不用假装它还在进行中。

---

Phase 2 · Backlog 梳理（OpenClaw 主动执行，不等触发）

Issue 进了 Backlog，但”进了 Backlog”不等于”被处理了”。没有 label、没有优先级、没有复杂度判断的 issue，只是一堆待办文字，下次 Sprint 规划时还是要从头想一遍。

OpenClaw 在 issue 进入 Backlog 后立即介入，目标是让每一条 issue 在排期之前就已经是”可以直接开始”的状态。

打 Label + 评估优先级

OpenClaw 读 issue 描述，自动判断类型（Bug / Feature / Chore / Docs / Auto）和优先级（Urgent / High / Medium / Low），直接写入 Linear。

其中 Auto label 是 OpenClaw 的专属标记：表示这个任务可以由 AI 工具独立完成，OpenClaw 会主动调度执行，并在 Heartbeat 监控时将其纳入并发控制范围。

这个初判不需要完美，只需要够用。开发者看到不对的直接改，不用解释原因——OpenClaw 不会追问，也不会在下次重置回去。优先级的判断标准是影响范围和紧迫程度：线上崩溃是 Urgent，新功能通常从 Medium 起评。

复杂度预评估

大多数 issue 打完 label 就够了。但有些 issue 表面上是一句话，实际上藏着很多决策点——比如”支持多语言”，听起来简单，实际上涉及 i18n 框架选型、字符串提取方案、构建流程改造，随便哪一块都能卡住。

满足以下任一条件，OpenClaw 会调用 Claude Code 做一次粗略的技术预判（只分析，不写代码）：

• 描述超过 5 行，或包含多个并列子需求
• 涉及架构调整、重构、接口设计、数据库变更

预判结果直接追加写入 issue description，开发者打开 issue 就能看到，不需要再去找上下文。

如果预估工作量超过 3 天，OpenClaw 会建议拆分：原 issue 升级为 Epic，拆出若干可以独立交付的子 issue，推送给开发者确认。不回复视为认可。

拆分的目的不是制造更多 issue，而是让每个 issue 都能在 1-3 天内完成——状态流转更清晰，也更容易发现哪里卡住了。

规划结果存储

• 当次实现方案 → 追加写入 issue description，和 issue 绑定，不会丢
• 长期归档内容（API 文档、架构说明）→ 写入 Obsidian 项目目录，供后续查阅

---

Phase 3 · Sprint 规划（OpenClaw 主动执行）

传统 Sprint 规划的痛点是：开会讨论、手动拖 issue、估点——这套流程在 5 人以上团队里有意义，但在 1-3 人的小团队里，往往变成”每周一开半小时会，然后该干嘛还是干嘛”。

这套流程的做法是把排期判断权交给 OpenClaw，但区分两种情况：能自动排的直接排，需要人决策的只推建议不擅自动。

两类任务，两套排期逻辑

🤖 自动任务（AI 工具可以独立完成，不需要开发者在 Cursor 里操作）

这类任务的特征是：任务边界清晰，执行路径确定，不需要开发者盯着。OpenClaw 根据优先级主动排入 Todo：

• Urgent / High → 立即移入 Todo，推送一条通知告知
• Medium → 当前 In Progress 数量 < 2 时自动移入，否则留在 Backlog 等待空位
• Low → 不主动排，等开发者明确指示

🧑‍💻 手动任务（需要开发者在 Cursor 里亲自开发）

这类任务 OpenClaw 不擅自排期——因为开发者的时间和精力是有限的，什么时候开始一个需要深度投入的任务，应该由人来决定。OpenClaw 只推建议：

📋 有 3 个手动任务待排期，优先级最高：
[Feature] 用户权限管理（High）
[Bug] 列表页滚动卡顿（High）
需要排进本次 Sprint 吗？

开发者回复确认后，OpenClaw 再执行状态变更。如果不想现在排，不回复就行，下次巡检还会再推。

并发控制

同时进行太多任务是小团队的常见陷阱——每件事都在动，但没有一件事在推进。OpenClaw 在两个维度上做限制：

• 自动任务同时进行不超过 3 个，避免 AI 工具之间争用上下文和资源
• 自动 + 手动合计超过 5 个时，OpenClaw 会主动提示：⚠️ 当前进行中 5 个任务，建议先完成部分再开新任务

这个提示不是强制拦截，开发者可以忽略，但至少会意识到当前的并发状态。

---

Phase 4 · 开发

Issue 进入 Todo 之后，开发真正开始。这个阶段 OpenClaw 的角色根据任务类型有明显差异——有时候是全程调度者，有时候只是安静的监控员。

开始一个任务

说一句”开始做 PROJ-47”，OpenClaw 把状态更新为 In Progress，然后判断这个任务该怎么做：

• 如果开发者明确说”我自己来”，OpenClaw 退到监控角色，不再介入执行
• 如果是 Sprint 规划时标记的自动任务，OpenClaw 直接进入驱动模式
• 如果不确定，OpenClaw 问一次：“这个要我来做还是你自己来？“——只问一次，不反复确认

OpenClaw 全程驱动（自动任务）

对于任务边界清晰、不需要开发者在 Cursor 里操作的任务，OpenClaw 全程负责。

典型场景：生成一组 API 的单元测试、给某个模块补充 JSDoc 注释、根据现有代码生成 PR 描述。

流程是：OpenClaw 先从 Linear 读取 issue 的验收标准（## 验收标准 区块），确认验收目标后再选工具（Claude Code 或 Codex），生成方案推送给开发者确认，开发者点头后才执行。OpenClaw 不会自动 push 代码——代码进仓库这一步永远需要人确认。

开发者手动（Cursor）

需要深度编码的任务，开发者在 Cursor 里操作，OpenClaw 退到后台。建分支，开始写：

git checkout -b feature/PROJ-47-user-permission

Branch 名里包含 issue identifier（PROJ-47）是关键——OpenClaw 后续通过 branch 名来关联 PR 和 issue，格式不对联动就会失效。

这个阶段 OpenClaw 不干预本地 IDE，但随时待命。遇到卡点直接说，比如：

“PROJ-47 里的权限校验逻辑不知道放哪层合适”

OpenClaw 调用 Claude Code 分析当前架构，推送一个具体的建议，不是泛泛的”可以考虑 middleware”，而是”根据你现有的 auth/ 目录结构，建议在 guards/ 层处理，原因是……”

混合模式（实践中最常见）

实际上大多数任务都是混合的：

• 规划阶段（搞清楚怎么做）→ OpenClaw 调度 Claude Code 分析
• 实现阶段（写代码）→ 开发者在 Cursor 里手动完成
• 收尾阶段（测试、PR 描述）→ OpenClaw 调度 Codex 生成

开发者只在”写代码”这件事上深度投入，前后的判断和整理交给 OpenClaw。

OpenClaw 如何选工具

OpenClaw 根据任务特征自主决定调用哪个工具，不需要开发者指定：

不确定时默认 Claude Code；任务极清晰时选 Codex，速度更快；需要 GitHub 原生全流程自主执行时选 Copilot Agent。

开发中监控

一个 issue 在 In Progress 超过 3 天没有关联 PR，OpenClaw 会主动问一句：

“PROJ-47 已经进行 3 天了，需要拆分或者我来协助分析一下吗？”

不是催促，是提醒。很多时候 issue 卡住是因为范围比预期大，这时候拆分比硬撑更有效。

---

Phase 4.5 · 验收 Gate（AI 任务专属）

这是今天这套工作流里最核心的机制。

背景： 手动开发的任务，开发者自己知道做完了没有。但 AI 驱动的自动任务不同——Claude Code 或 Codex 执行完之后，代码是否真的满足需求、有没有遗漏边界情况、语法是否干净，需要有人来核验。这个”守门员”角色交给 OpenClaw 来做。

为什么不走 Code Review（Phase 5）？

传统 PR 流程假设有开发者手动 push 分支、开 PR。自动任务执行完之后不一定有 PR，可能直接 commit 到分支上——走 Phase 4.5 更直接，不需要绕一圈。

验收流程

1. 读取验收标准

直接从 Linear 读 issue 的 ## 验收标准 区块——这就是为什么建 issue 时必须写清楚验收标准：AI 执行的起点和验收的终点要对齐。

2. 代码质量检查

基础的语法和导入检查，根据项目语言判断执行什么命令。

3. 功能验证

对照验收标准逐项核对，记录每项结果。

4. 验收报告写入 Linear

结果以 comment 的形式直接写进 issue，永久可查。格式：

## 验收报告
验收时间：2026-03-19 21:30

验收标准核对
- [x] 超时时显示明确的错误提示：✅ 已实现，显示 "网络超时，请重试"
- [x] 提示内容清晰，用户知道该怎么做：✅ 包含重试按钮

结论：✅ 通过

5. 验收失败 → 自动修复循环

这里有个关键设计：验收不通过时，OpenClaw 不是直接上报，而是先尝试自己修复：

验收失败
    ↓
OpenClaw 判断失败类型，选工具（Claude Code / Codex）
    ↓
派工具修复，重新验收
    ↓
最多自动修复 2 次
    ↓
第 3 次仍失败 → 停止，推送人工介入：
🔴 PROJ-47 验收连续失败 3 次，需人工介入
失败项：[具体列表]

重试计数是持久化的（存在 heartbeat-state.json），session 重启不会丢失。超过上限后就不再尝试，等开发者决策。

---

Phase 5 · Code Review

PR 开了，OpenClaw 检测到分支有新的 PR open，立即把 issue 状态更新为 In Review，然后启动 Claude Code 在隔离目录里做一次代码分析。

AI Review 做什么、不做什么

这一步的定位是初筛，不是替代人工 Review。Claude Code 重点看：

• 逻辑 bug：边界条件、空值处理、异步竞态
• 安全问题：未校验的输入、敏感信息暴露、权限绕过
• 明显的性能问题：不必要的全量查询、循环内的重复计算

Review 结论推送给开发者，不直接 comment 到 GitHub。原因是：AI 的 comment 质量参差不齐，直接贴出去可能引发误解，或者让 PR 看起来很嘈杂。由开发者判断哪些值得贴、哪些可以忽略。

实际体验是：大多数时候 AI Review 会抓到 1-2 个你自己没注意到的边界问题，偶尔会有误判，但过滤成本比从零 Review 低得多。

PR 描述生成

很多开发者写 PR 描述的方式是：复制 issue 标题，加一句”修复了 xxx”。这种描述对 reviewer 没什么帮助。

需要一份好的 PR 描述时，告诉 OpenClaw 一句，OpenClaw 调用 Codex 读 diff，生成包含改动内容、影响范围、测试说明的草稿。复制过去改几句就行，比从空白开始写快得多。

超时提醒

• PR 开了超过 24 小时未 merge → OpenClaw 推送提醒，避免 PR 在队列里沉默太久
• CI 失败 → OpenClaw 立即告知，不需要自己去刷 GitHub Actions 页面

---

Phase 6 · 验收完成

有两条路径到达 Done：

• 传统 PR 路径：PR merged，OpenClaw 检测到后自动将 issue 状态更新为 Done，推送完成通知
• AI 自动任务路径：Phase 4.5 验收 Gate 通过，Linear 状态直接更新为 Done，推送验收完成通知

大多数手动开发的 issue 走第一条；AI 驱动的自动任务走第二条。

关闭一个 issue 需要多谨慎

Done 是自动的，但 Canceled 不是——这个状态只能由开发者发起。

需求被取消的情况很常见：产品方向调整、被更高优先级的任务覆盖、发现实现成本远超预期。但随手关掉 issue 有风险：可能有关联的 PR 还开着，可能有代码改动没有 revert，可能有其他 issue 依赖它。

所以 OpenClaw 在执行 Canceled 之前，会推送一个检查清单：

准备关闭 PROJ-47，确认以下几点：

• 是否有关联 PR 尚未关闭？
• 是否有已合并但需要 revert 的代码？
• 是否有其他 issue 依赖此任务？

确认后关闭。

开发者逐项确认，OpenClaw 再执行状态变更。这个流程不是为了制造麻烦，而是防止”关了 issue 但留了烂尾”。

完成后的知识沉淀

每次 issue 完成后，OpenClaw 会问一句：

“这次开发有没有需要归档到文档库的内容？”

这一步很轻量，不强制。但实践下来，很多有价值的决策——为什么选了这个方案、踩了什么坑、有哪些后续要跟进——都是在这个时机被记录下来的。放任不管，两周后就忘了。

---

Phase 7 · 回顾

Sprint 结束或者想看一眼整体进度时，说”sprint 报告”或”项目进度”，OpenClaw 拉取 Linear 数据，生成一份汇总推送过来：

📊 本周进度（GEO 项目）

✅ 已完成：5 个
   · PROJ-43 登录页超时提示
   · PROJ-44 用户头像上传
   · PROJ-45 权限校验重构
   · PROJ-46 API 文档补全
   · PROJ-47 列表页性能优化

🔄 进行中：2 个
   · PROJ-48 多语言支持（In Progress · 已 4 天）
   · PROJ-49 邮件通知模板（In Review · 等待 merge）

📋 待处理：8 个（Backlog）
   · 优先级最高：PROJ-51 支付流程重构（High）

⚠️ 需要关注：
   · PROJ-48 已超过 3 天未关联 PR，是否需要拆分？

这份报告不是为了汇报，是为了让开发者在一个地方看清楚”现在到底在做什么、卡在哪里、下一步是什么”。

目前是手动触发的，说一句就出来。后续可以配置成每周固定时间自动推送，作为 Sprint 结束的节奏锚点。

---

状态流转速查

graph LR
    Backlog --> Todo
    Todo --> InProgress[In Progress]
    InProgress -- 手动任务，PR open --> InReview[In Review]
    InReview -- PR merged --> Done
    InProgress -- AI 自动任务 --> Gate["Phase 4.5 验收 Gate"]
    Gate -- 通过 --> Done
    Gate -- 取消 --> Canceled

关键设计： 状态流转全部由 OpenClaw 通过 Linear API 主动触发，不依赖平台级集成。集成失效是静默错误，OpenClaw 主动扫描失败时会立即告警——状态可控。

---

规范约定

Branch 命名

feature/{ISSUE_ID}-简短描述
fix/{ISSUE_ID}-简短描述

{ISSUE_ID} 是 Linear 返回的 identifier（如 PROJ-47、GEO-123），不绑定固定前缀——团队名、项目名怎么设就怎么用，OpenClaw 通过识别 {TEAM}-{number} 模式来关联 PR 和 issue。格式不对联动就会失效。

PR 描述模板

## 改动内容
- 添加了 xxx 功能

## 测试
- 本地测试通过

Fixes PROJ-47

---

OpenClaw 调度分工一览

核心原则：Cursor 永远由开发者本人操作，OpenClaw 不介入本地 IDE。其余阶段 OpenClaw 自主选择最合适的工具，不需要开发者指定。

---

效果感受

实际跑下来，最明显的变化是：

• 减少了”忘了跟进”：OpenClaw 会在 issue 超时或 PR 挂太久时主动提醒，不需要靠记忆力
• 减少了上下文切换：不用为了建 issue 去打开 Linear，直接告诉 OpenClaw 搞定
• Code Review 做了初筛：低级错误在 PR 合并前就被发现了
• Backlog 不再是垃圾堆：预定级自动处理，每个 issue 进来就有优先级和 label

还没解决的问题：

• OpenClaw 生成的 PR 描述有时太笼统，还需要人工润色
• 复杂业务的技术方案，Claude Code 的规划质量取决于你给的上下文够不够详细

---

总结

这套工作流的核心思想不是”用 AI 工具替代开发者”，而是让 OpenClaw 承担那些消耗注意力但不需要人类判断力的部分——状态跟踪、监控提醒、初步 Review、文档整理——然后把重要决策点留给人。

对中小团队和一人公司来说，这个边界比较好划：凡是规则清晰、可以机械执行的，交给 OpenClaw；需要背景判断、影响较大的，人来拍板。

附录：Workflow 配置原文

以下是当前实际运行的 05-project-management.md 工作流完整内容（隐私信息已脱敏），以及 OpenClaw Heartbeat 的项目监控部分，供参考和复刻。

---

05-project-management.md（完整 SOP）

---
title: "项目管理与自动化开发"
created: 2026-03-17
ttl: 90d
status: active
skills: [linear-cli, github, coding-agent]
tags: [project-management, linear, github, automation, ai-coding, agile]
---

# 项目管理与自动化开发

> 基于敏捷开发节奏，Linear + GitHub 为底座，OpenClaw 作为自动化中间层，
> 适配"注意力最小化"需求。

⚠️ **执行前必读 `PROJECTS.md`**：获取项目 ID、GitHub Repo 对应关系、偏好工具/模型、监控范围。

---

## 触发条件

**触发词：**
项目进度、查一下XX、XX做完了、有个bug、新建issue、sprint报告、帮我建issue、
开始开发XX、预定级、拆分任务

---

## 配置（单一 source of truth）

> ⚠️ API key、Team ID、Project IDs、State IDs 只在这里维护。

LINEAR_API_KEY   = "lin_api_****"
LINEAR_GRAPHQL   = "https://api.linear.app/graphql"
LINEAR_TEAM_ID   = "YOUR_TEAM"
LINEAR_TEAM_UUID = "****-****-****-****-****"

### Project IDs

| 项目 | Project ID | 本地路径 |
|------|-----------|---------|
| ProjectA | `****` | `/path/to/ProjectA` |
| ProjectB | `****` | `/path/to/ProjectB` |
| ...      | `****` | `...`               |

### State IDs

| State | ID |
|-------|----|
| Backlog | `****` |
| Todo | `****` |
| In Progress | `****` |
| In Review | `****` |
| Done | `****` |
| Canceled | `****` |

### Label 规范

| Label | 含义 |
|-------|------|
| `Bug` | Bug 修复 |
| `Feature` | 新功能 |
| `Chore` | 杂项任务 |
| `Docs` | 文档更新 |
| `Auto` | AI 自动执行任务（Heartbeat 监控依据，排期为自动任务时必打） |

### Issue 命名规范

- Feature：`[Feature] 简短描述`
- Bug：`[Bug] 简短描述`

### Branch 命名规范

feature/{ISSUE_ID}-简短描述
fix/{ISSUE_ID}-简短描述

> `{ISSUE_ID}` 即 Linear 返回的 identifier（如 `PROJ-123`），不依赖固定前缀。
> Branch 名包含 `{ISSUE_ID}` 是 OpenClaw 判断 PR 关联 issue 的唯一依据。

### AI 工具分工

| 阶段 | 工具 | 触发方 | 用途 |
|------|------|--------|------|
| 规划 | Claude Code | OpenClaw 后台调用 | 技术方案、架构、难点分析 |
| 实现（开发者手动） | Cursor | 开发者明确说"我自己来" | 本地 IDE 编码，OpenClaw 不干预 |
| 实现（AI 驱动） | Claude Code / Codex / Copilot Agent | **OpenClaw 决策调度** | 见"工具决策规则" |
| Review | Claude Code | OpenClaw 自动（PR open） | diff 分析、问题标注 |

### OpenClaw 工具决策规则

| 场景 | Claude Code | Codex | Copilot Agent |
|------|:-----------:|:-----:|:-------------:|
| 任务描述模糊，需理解上下文 | ✅ | | |
| 跨文件分析 / 架构判断 | ✅ | | |
| Bug 原因不明，需推理 | ✅ | | |
| 收尾文档整理 | ✅ | | |
| 任务清晰、范围小、步骤明确 | | ✅ | |
| 生成测试用例 | | ✅ | |
| 生成 PR 描述 | | ✅ | |
| Bug 修复（定位已明确）| | ✅ | |
| GitHub issue 直接指派 AI 全流程执行 | | | ✅ |

默认优先 Claude Code；任务极清晰时选 Codex；需要 GitHub 原生全流程时选 Copilot Agent。

---

## 敏捷流程总览

```mermaid
graph LR
    A[需求收集] --> B[Backlog 梳理]
    B --> C[Sprint 规划]
    C --> D[开发]
    D --> E[Code Review]
    E --> F[验收完成]
    F --> G[回顾]
    G -- 反馈循环 --> A

---

Phase 1 · 需求收集

入口： 随时触发（Telegram / Linear 直接建）

三种来源

A. 告知 OpenClaw（最常见） 说出需求 → OpenClaw 用 Linear CLI/API 建 issue → 推送确认 ⚠️ 建 issue 时必须在 description 中包含 ## 验收标准 区块（格式：- [ ] 验收项） 若未明确提供，OpenClaw 根据需求描述自行推断后写入，建完连同验收标准推送确认

B. 直接在 Linear 建 OpenClaw 在下次巡检时检测到新 Backlog issue → 进入 Phase 2 ⚠️ 若缺少 ## 验收标准 区块，OpenClaw 主动补写，推送确认

C. 先写代码后补记录 说”xxx 做完了，帮我记一下” → OpenClaw 建 issue 并立即标记 Done

出口： Issue 存在于 Backlog，且 description 包含 ## 验收标准 区块

---

Phase 2 · Backlog 梳理（OpenClaw 主动，不等触发）

入口： Issue 进入 Backlog

2.1 打 Label

根据 issue 标题和描述判断类型，调用 Linear API 设置。不确定时默认 Feature。

2.2 评估优先级

OpenClaw 直接设置，不同意时直接改，无需解释。

2.3 复杂度预评估

满足以下任一项，启动 Claude Code 预评估（只分析不写代码）：

• issue 描述超过 5 行 / 含多个子需求
• 关键词含”架构”、“重构”、“接口设计”、“数据库变更”

若预估超过 3 天工作量 → 自动拆分：

• 原 issue 转为 Epic
• 子 issue 按 [子任务] 描述 格式建立，关联父 issue
• 推送拆分结果确认（不回复视为认可）

规划结果存储：

• 当次方案 → 追加写入 Linear issue description
• 长期归档文档 → Obsidian 项目目录

出口： Label 已打、优先级已设、复杂 issue 已拆分

---

Phase 3 · Sprint 规划（OpenClaw 主动执行）

3.1 两类任务，两套排期逻辑

🤖 自动任务（Auto label，OpenClaw 可独立调度工具完成）

• Urgent / High → 立即移入 Todo，推送通知
• Medium → In Progress 数 < 2 时自动移入
• Low → 不主动排，等指示

🧑‍💻 手动任务（开发者明确说”我自己来”，或需要本地 IDE）

• OpenClaw 不主动移入 Todo，只推建议： 📋 有 N 个手动任务待排期，优先级最高：{ISSUE_ID} [标题]，要安排进本次 Sprint 吗？
• 确认后再执行状态变更

3.2 并发控制

• In Progress 自动任务：不超过 3 个
• 自动 + 手动合计超过 5 个时推送提示

出口： Issue 状态为 Todo，开发模式已明确（自动/手动）

---

Phase 4 · 开发

4.1 领取 Issue

说”开始做 {ISSUE_ID}” →

1. Linear API：Todo → In Progress
2. 推送：🚀 {ISSUE_ID} 开始开发

4.2 开发模式选择

''' 明确说”我自己来” ├── YES → 模式 B（手动） └── NO → 查看 Phase 3 排期标记 ├── 自动任务 → 模式 A（AI 全程） └── 不确定 → 询问一次：“这个要我来做还是你自己来？” '''

模式 A：AI 全程驱动

1. 根据”工具决策规则”选择 Claude Code 或 Codex
2. 生成方案推送确认（实现前必确认，不自动写代码）
3. 确认 → 执行；不回复超 30min → 再次推送提醒

模式 B：手动开发（OpenClaw 退到监控角色）

1. 本地建分支：git checkout -b feature/{ISSUE_ID}-描述
2. Cursor 开发，OpenClaw 不干预
3. 遇卡点告知 → OpenClaw 按工具决策规则分析

4.3 AI 任务开发规范

开发前（必做）：

1. linear issue view {ISSUE_ID} 确认 ## 验收标准 存在
2. 若缺失 → 推断补写，推送确认
3. 推送：🤖 {ISSUE_ID} AI 实现启动

开发后移交验收（必做）：

• 代码已 git add && git commit
• 推送：✅ {ISSUE_ID} 代码完成，等待验收

4.4 开发中监控

In Progress 超过 3 天无关联 PR → 推送： ⏰ {ISSUE_ID} 进行中已 3 天，还在做吗？需要拆分或协助？

出口： 代码已提交 → 进入 Phase 4.5 验收 Gate

---

Phase 4.5 · 验收 Gate（守门员机制）

⚠️ 所有 AI 实现的自动任务必须通过此 Gate 才能更新 Linear Done 状态。 手动完成的任务可跳过。

入口： AI 实现完成通知，或 heartbeat 兜底触发

验收流程

Step 1：从 Linear 读取验收标准 '''bash linear issue view {ISSUE_ID} ''' 提取 ## 验收标准 区块，逐项列出检查项。

Step 2：代码质量检查（根据项目类型判断） '''bash

Python

python3 -m py_compile <新增文件> python3 -m pytest tests/ -v

Swift/iOS

xcodebuild build -scheme -destination ‘platform=iOS Simulator,name=iPhone 16’ '''

Step 3：功能验证 对照 ## 验收标准 逐项确认，记录每项结果。

Step 4：提交验收报告到 Linear '''bash linear issue comment {ISSUE_ID} —body ”## 验收报告 验收时间：YYYY-MM-DD HH:MM

验收标准核对

• 标准 A：结果描述
• 标准 B：未通过（原因）

结论：✅ 通过 / ⚠️ 需修复” '''

Step 5：分支处理

✅ 验收通过：

• linear issue move {ISSUE_ID} --to "Done"
• 推送：✅ {ISSUE_ID} 验收通过

⚠️ 验收失败 → 自动修复循环（最多 2 次）：

1. 判断失败类型，选择修复工具
2. 派 Claude Code / Codex 修复，重新走 Step 2–4
3. 第 3 次仍失败 → 停止自动修复，推送人工介入： 🔴 {ISSUE_ID} 验收连续失败 3 次，需人工介入 / 失败项：[详细列表]

验收通过标准

1. 所有 ## 验收标准 项均已核对
2. 代码质量检查通过
3. 核心功能验证通过（允许遗留 minor 问题，需在报告中注明）
4. 验收报告已写入 Linear issue comment

出口： Linear 状态 Done（通过），或人工介入（连续失败）

---

Phase 5 · Code Review

入口（仅传统 PR 流程）： Heartbeat 检测到新 PR（branch 名含 {ISSUE_ID}）

⚠️ AI 自动任务不走此阶段，直接进入 Phase 4.5 验收 Gate。

5.1 状态同步

Linear API：In Progress → In Review

5.2 AI Review 自动触发

'''bash REVIEW_DIR=$(mktemp -d) git clone https://github.com/your-org/{repo}.git $REVIEW_DIR cd $REVIEW_DIR && gh pr checkout {pr_number} claude —permission-mode bypassPermissions —print
‘Review this PR. Focus on: logic bugs, security issues, performance problems. Be concise.’ '''

Review 结论推送给开发者，不直接 comment GitHub，等确认后决定是否贴出去。

5.3 PR 状态监控

• PR 超 24h 未 merge → 推送提醒
• CI 失败 → 立即推送：🔴 {ISSUE_ID} PR #N CI 失败

出口： PR merged

---

Phase 6 · 验收完成

入口 A（传统 PR 流程）： Heartbeat 检测到 PR merged 入口 B（AI 自动任务）： Phase 4.5 验收 Gate 通过

6.1 状态同步

PR merged 场景： Linear API：In Review → Done 推送：✅ {ISSUE_ID} [标题] 已完成，PR #N merged

AI 自动任务场景： Linear 状态已在 Phase 4.5 更新，此处仅推送：✅ {ISSUE_ID} 验收完成

6.2 TODO.md 同步规则

AI 自动任务完成后，同步更新本地 TODO.md（项目根目录）。

6.3 Canceled 验收检查

发起关闭 → 推送检查清单，等确认后再执行：

''' ⚠️ {ISSUE_ID} 准备 Canceled，确认以下项目：

• 有无关联 open PR？（需先关闭或转移）
• 有无已提交但未 revert 的代码？
• 有无依赖此 issue 的其他任务？
• 是否需要在 issue 描述中补充取消原因？ 确认没问题请回复”确认关闭” '''

6.4 归档提醒

若本次开发产出值得归档的文档 → 推送：📝 {ISSUE_ID} 完成，是否写入文档库？

---

Phase 7 · 回顾

触发： 说”sprint 报告” / “项目进度” / “回顾一下”

推送格式： ''' 📊 本周进度（[项目名]）

✅ 已完成：N 个 · {ISSUE_ID} 标题

🔄 进行中：N 个 · {ISSUE_ID} 标题（In Progress · 已 X 天）

📋 待处理：N 个（Backlog） · 优先级最高：{ISSUE_ID} 标题（High）

⚠️ 需要关注： · {ISSUE_ID} 已超过 3 天未关联 PR，是否需要拆分？ '''

---

Heartbeat 集成说明

验收失败重试计数存储：heartbeat-state.json → validation_retries.{ISSUE_ID}，上限 3 次。

---

异常处理

---

### HEARTBEAT.md · Section 1：项目监控

```markdown
## 1. 项目监控（读 PROJECTS.md，扫监控中的 repo）

**每次 heartbeat 按顺序执行 A → B → C：**

---

### Step A：Linear Auto 任务检查

**1. 查询所有 `In Progress` + `Auto` label 的 issue：**
'''bash
linear issue list --state "In Progress" --label "Auto" --json
'''

**2. 对每个 Auto issue 按序检查：**

**超时告警（无关联 PR）：**
进入 In Progress 超 3 天且无关联 PR（branch 名含 `{ISSUE_ID}`）→ 推送：
`⏰ {ISSUE_ID} In Progress 已 N 天，未见 PR`

**验收兜底（AI 完成但 Gate 未触发）：**
检查 Linear comments 里有无"验收报告"字样：
- 有 → 跳过（Phase 4.5 已完成）
- 无 → 读 `heartbeat-state.json` 的 `validation_retries.{ISSUE_ID}`
  - retries < 3 → 触发 Phase 4.5 验收 Gate，retries +1，写回 state
  - retries ≥ 3 → 跳过（已上报人工介入，等处理）

**3. 并发控制：** 统计所有 In Progress Auto issue 数量
- 数量 < 3 且 Backlog 有 `Auto + Urgent/High` issue → 移入 Todo，推送：
  `📅 {ISSUE_ID} 自动移入 Todo（{优先级}）`

---

### Step B：GitHub PR 扫描

读取 `heartbeat-state.json` 的 `seen_prs` 和 `seen_merged_prs`：

'''python
monitored_repos = [
    "your-org/ProjectA",
    "your-org/ProjectB",
    # ...
]

for repo in monitored_repos:
    # 1. Open PR 扫描
    # gh pr list --repo {repo} --json number,title,createdAt,headRefName,statusCheckRollup
    for pr in open_prs:
        # 新 PR（不在 seen_prs）→ 记录，推送通知，写入 seen_prs
        # CI FAILURE → 立即推送（忽略安静时段）
        # 创建超 24h 仍 open → 推送 review 提醒（安静时段除外）

    # 2. Merged PR 扫描 → Linear Done 同步
    # gh pr list --repo {repo} --state merged --json number,title,mergedAt,headRefName
    for pr in merged_prs（不在 seen_merged_prs）:
        # 提取 branch 名里的 {ISSUE_ID}
        # → linear issue move {ISSUE_ID} --to "Done"
        # → 推送 ✅ 通知，记入 seen_merged_prs
'''

---

### Step C：状态持久化

每次扫描结束，写回 `heartbeat-state.json`：
'''json
{
  "seen_prs": { "your-org/ProjectA#12": "2026-03-19T10:00:00Z" },
  "seen_merged_prs": { "your-org/ProjectA#11": true },
  "validation_retries": { "PROJ-45": 1 }
}
'''

---

**推送条件（满足任一即推送）：**
- CI 失败 → 立即推（无视安静时段）
- 新 open PR / 超 24h 未 merge / 验收兜底触发 / Auto 任务入 Todo / In Progress > 3 天无 PR → 汇总推送（安静时段除外）

**不推送：**
- 所有状态无变化
- 23:00–08:00 安静时段（CI 失败除外）

**推送格式：**
'''
🔔 项目更新

[ProjectA] PR #12「feat: 插件热更新」已等待 review 25h
[ProjectB] CI 失败：PR #5「fix: crash on launch」
PROJ-45 In Progress 已 4 天，未见 PR
✅ PROJ-47 PR #8 merged → Linear Done
'''