pullboard-dev/pullboard · 上手攻略

• 仓库：pullboard-dev/pullboard
• 链接：https://github.com/pullboard-dev/pullboard
• 分类：AI Agent 协作流程
• 作者：Tom
• 更新：2026-10-09

---

一、是什么

Pullboard 是一个基于 Git 仓库的 AI Agent 协作队列工具。它的核心理念是：人类制定规范（Spec），多个 AI Agent 在独立的工作分支（lane/worktree）中实现，提交前必须经过另一个 Agent 的验证（verify），人类只需做最高层的决策。

官方 tagline："Vibe code a real product. Agents build from the spec you approved."

与传统 Agent 开发框架不同，Pullboard 不调用任何 LLM——它只是一个结构化的协调层，运行在本地 Git 仓库内，不依赖任何外部账号或云服务。

五个核心原语

原语	作用
Items	任务本身，每项有明确的验收门槛（gate），同一时间只有一个 Agent 处理
Shouts	Agent 之间互相提问/通知的通信机制
Spec	需求规范，存放于 SPEC.md，只有人类批准的 rows 才算数
Doctrine	开发守则，存放于 DOCTRINE.md，每条规则都有强制执行者（git hook / review 等）
Activity	全局活动日志，所有 claim/submit/reject/accept 操作全部留痕

---

二、解决什么问题

传统多 Agent 开发中常见四类问题：

1. Agent 声称完成但实际未完成 — Pullboard 要求第二个 Agent 在同一 commit 上验证，不接受"看起来没问题"
2. 决策在聊天中丢失 — 所有决策写入 SPEC.md，不依赖聊天上下文
3. 两个 Agent 同时改同一文件 — 每个 Agent 分配独立 git worktree（lane），物理隔离
4. 修复引入新问题 — 提交必须 gate 变绿，测试通过才能进入验证流程

---

三、快速安装

环境要求

• Node.js ≥ 22.13（README 明确标注，更低版本未测试）
• Git
• 支持 Claude Code、Codex、OpenCode 或任意 shell 内运行的 Agent

安装

npm i -g pullboard

体验 Tour（30 秒快速演示）

pullboard tour

Tour 会创建一个临时仓库，你批准一条规范（"空名字问候 world"），协调者（coordinator）Agent 分配任务，构建者（builder）实现，验证者（verifier）尝试用空名字触发 bug 并 reject，构建者修复并加测试，验证者故意破坏测试确认测试有效，最终接受并合并。完整演示了 ADLC（Agentic Development Lifecycle）。

项目初始化

cd your-project
pullboard init
git add -A && git commit -m "chore(repo): set up pullboard"

init 会写入： - SPEC.md — 需求规范模板 - DOCTRINE.md — 开发守则 - Agent 指令文件 - Git hooks（lane 隔离、commit-msg 规范） - pullboard.json — 看板配置

---

四、核心用法

4.1 编写规范（Spec）

SPEC.md 每行格式：

- <id> [<status>, <priority>] <需求描述> | gate: <验收方式>

示例：

## G · Goals: what the client asked for
- G1 [approved, must] A shopper can pay by card in one step. | gate: test/checkout.test.js
- G2 [draft, aim] Saved carts follow a shopper across devices. | serves: G1

状态 [draft/approved] 决定是否激活。| serves: 声明依赖关系。

4.2 添加任务项（Items）

# 添加一个 Web lane 的任务
pullboard add web "Checkout" --specs G1 --criterion "card payment takes one step"

每个 Item 有自己的 bar（验收门槛），claim 后冻结。

4.3 工作流程核心命令

# 创建 lane worktree，进入 builder 角色
pullboard worktree web
cd ../myapp-web-1
pullboard next          # 认领下一个空闲 item
# ... 实现代码 ...
pullboard submit 1      # 提交（要求 gate 变绿）

# 进入 review lane，切换 verifier 角色
pullboard worktree review
cd ../myapp-review-1
pullboard next --verify # 认领待验证 item
pullboard verify 1 accept --note "paid in one step; without the fix the test fails"
# 或 reject:
# pullboard verify 1 reject --note "<reason>"

4.4 看板视图

pullboard view          # 启动本地看板（浏览器查看）

显示：待处理 / 已认领 / 已提交 / 已接受 / 需要人类决策 的任务。

pullboard view --export # 导出静态快照

4.5 与 Agent 协作

# 恢复 Agent 状态（断线后）
pullboard resume

# 让轻量模型处理简单任务（无需人工监督）
pullboard run

# 查看状态
pullboard status

4.6 pullboard.json 配置示例

{
  "lanes": ["web", "api", "review"],
  "gate": "npm test",
  "coordination": {
    "coordinator": "claude-code"
  }
}

---

五、典型适用场景

场景	适合度	说明
多 Agent 并行开发同一项目	⭐⭐⭐⭐⭐	物理隔离的 worktree 避免文件冲突
需要可审计的开发流程	⭐⭐⭐⭐⭐	所有决策在 SPEC.md，Activity 全日志
Spec-Driven 开发（先规范后实现）	⭐⭐⭐⭐⭐	规范即合同，Agent 不能自行发挥
定量/金融系统（不能容忍幻觉代码）	⭐⭐⭐⭐	verify 强制二次确认
单 Agent 快速原型	⭐⭐	流程偏重，轻量场景不如直接对话

---

六、坑与注意

1. Node 版本要求严格：必须 ≥ 22.13，macOS 系统 Node 可能较老，需要用 nvm 管理
2. Gate 测试必须真实存在：| gate: test/checkout.test.js 指向的测试文件如果不存在，submit 会失败——这实际上是好事，但新玩家容易踩到
3. Worktree 路径管理：每个 lane 是独立的 git worktree，注意 ../myapp-web-1 这样的相对路径不要混淆
4. Verifier 不能是自己构建的 commit：review lane 的 Agent 必须 checkout 被验证的 exact commit，实践中这点容易搞混
5. DOCTRINE.md 是强制约束：每条 doctrine 的 "enforced by" 如果写的是 review，则依赖人工 code review，不是自动化的——需要配合 git hooks 才能自动化
6. 不调用模型：Pullboard 本身只是协调层，Agent（Claude Code 等）需要单独配置，不开箱即用

---

七、与同类对比

工具	定位	调用 LLM	存储	验证机制
Pullboard	多 Agent 协作队列	❌（纯协调）	Git 仓库	二次 Agent verify
CrewAI	多 Agent 角色扮演流水线	✅	云端	Agent 自验
LangGraph	DAG 工作流编排	✅	自选	自定义节点
AutoGen	Agent 对话协作	✅	自选	人工反馈
SWE-agent	单 Agent PR 任务	✅	云端	CI + 人工

Pullboard 的独特价值：唯一不调用模型、纯依赖 Git 结构的 Agent 协调工具。适合已经在用 Claude Code/Codex、想把多个实例串成有审批流程的开发团队的进阶用户。

---

八、一句话推荐结论

如果你在用 Claude Code 想做多 Agent 协作、但又受不了"都这样说好了但实际没验证"的那种无力感——Pullboard 用 Git worktree 物理隔离 + Spec 合同 + 二次 verify，把 AI 开发的"说了等于做了"变成真的做完了。上手略陡，但值得。