Agent 配置

前提条件

配置 agent 之前，你需要：

• bd CLI 已安装且在 PATH 中（快速开始）
• 至少一个已初始化的工作区（在项目目录中运行 bd init）
• Beadbox 正在运行并已连接到该工作区

Agent 身份

每个 agent 需要一个 CLAUDE.md 文件（或等效的系统提示词）来定义：

• agent 负责什么（实现、QA、运维）
• agent 不负责什么（防止越界到其他角色）
• 如何沟通（在 bead 上评论、向协调者报告）

以下是一个工程 agent 的最小身份定义示例：

## Identity
Engineer for MyProject. You implement features, fix bugs,
and write tests. You own implementation quality.

## Boundary with QA
QA validates your work independently. You provide QA with
executable verification steps. If your DONE comment doesn't
let QA verify without reading source code, it's incomplete.

边界部分防止 agent 越俎代庖做 QA 的工作。没有明确边界的话，agent 会自我验证并跳过独立审查。

常用命令

你的 agent 最常用的 bd 命令：

bd create --title="Fix login bug" --type=bug --priority=2

bd show BEAD-ID

bd update BEAD-ID --claim --actor agent-name
bd update BEAD-ID --status in_progress

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

bd list --status=open --assignee=agent-name

bd close BEAD-ID

所有命令都支持 --db 标志来指定特定工作区数据库，适用于 agent 跨多个项目工作的场景。

bd prime 命令

让新 agent 最快了解 bd CLI 的方式：

bd prime

这个命令输出一段为 AI 编程助手设计的上下文块，涵盖完整的命令集、输出格式和常见工作流。将其粘贴到 agent 的系统提示词或上下文窗口中。

在工作区目录内运行 bd prime 可以包含工作区专属的上下文。

Agent 工作流

处理单个 bead 的典型 agent 工作流：

1. 认领 bead
2. 编码前发表计划评论
3. 实现变更
4. 运行测试
5. 发表带验证步骤的完成评论
6. 推送并将状态更新为 ready_for_qa

# Full workflow example
bd update proj-a1b2 --claim --actor eng1
bd comments add proj-a1b2 --author eng1 "PLAN: 1. Fix auth check 2. Add test"

# ... implement and test ...

bd comments add proj-a1b2 --author eng1 "DONE: Fixed auth. Commit: abc123"
git push
bd update proj-a1b2 --status ready_for_qa

DONE 评论应包含验证步骤，让其他 agent（或人类）无需阅读源码即可确认工作完成。

实时反馈

当 agent 执行 bd 命令时，Beadbox 检测到数据库变更并在两秒内更新 UI。无需手动刷新。

这意味着你可以实时观察 agent 工作：看到 bead 从 open 变为 in_progress，看到计划以评论形式出现，在阻塞项浮现的瞬间捕获它们。

在多 agent 场景中，Activity Dashboard 展示哪个 agent 在做什么、pipeline 中哪里积压了工作，以及整个编队刚刚发生了什么。