beans

Beans - 任务管理

基于 CLI 的扁平文件问题跟踪器。任务以 Markdown 文件的形式保存在 .beans/ 中，并与代码一起进行版本控制。

仓库： https://github.com/hmans/beans（760+ 个 star）

安装、beans init 和 Agent 集成步骤请参阅 references/setup.md。

何时使用此技能

• 通过 CLI 管理项目任务、错误和功能
• 让编码 Agent 跟踪自己的工作
• 创建、列出、更新和关闭 beans
• 使用史诗、标签和优先级组织工作（绝不使用 milestone 类型）
• 使用 beans list 筛选条件查询项目状态

---

工作流模型

生命周期分为三个层级，状态推进顺序严格。创建 beans 前请先阅读本节。

树形结构

每个 bean 都位于一个三级树形结构中。下方名称是惯例，不是 bean 的 type 值——type 仍为 task / bug / feature / idea。

层级	含义	Bean type	子项
史诗	一个目标。会话持续围绕此目标推进，直至达成。	epic（多史诗计划的根节点：无父级的 epic）	N 个任务
任务	达成目标所需的一项需求、问题或能力。	task 或 bug	无——叶节点
子任务	一项范围明确、约 10 分钟即可完成、可委派的工作。交给一个小型子 Agent。	所属任务中的验收标准复选框（不是 bean——CLI 会拒绝在任务下创建任务）	无

层级由 parent 字段强制执行，也由 CLI 强制执行；创建时遇到非法的父级／类型组合，CLI 会明确报错并拒绝。已验证的限制矩阵（批量导入前，每个层级先用一个临时创建操作进行探测；CLI 报错才是判定依据，优先于任何文档惯例）：epic 的父级 ∈ {无}；feature 的父级 ∈ {epic}；task 的父级 ∈ {epic, feature}；task 绝不能作为父级。如果一个扁平任务后来确实需要 bean 子项，可原地转换——beans update <id> -t epic 会切换类型并保留 id 和历史记录（已通过 CLI 验证），之后即可合法创建子项。依赖任何层级规则前都要先进行探测。CLI 会拒绝的文档惯例，会破坏所有依赖它的操作方案。不要使用 milestone 类型（团队规则：这是上游 CLI 遗留包袱，绝不创建）；确实需要按发布版本分组时，改为给 beans 添加标签（--tag rel-v1）。如果 CLI 不允许增加层级，就在所属任务中用可计数的验收标准复选框保持 10 分钟的粒度，而不要创建单独的 bean。

批量导入方案（id 由 CLI 生成，切勿预设）：第 1 轮创建所有 beans，并将返回的 id 记录到映射表；第 2 轮根据映射表设置 --parent / --blocked-by。如果某些类型／父级错误导致批次中的部分创建失败，请重新运行一个幂等修复脚本：读取 id 映射表并跳过已创建的 beans。

epic (GOAL)
├─ task (requirement)
├─ task
└─ task

子任务不是 beans（CLI 会拒绝在任务下创建任务）——可在任务正文中添加验收标准复选框来拆分任务；如果某项需求确实需要 bean 子项，则创建一个 feature 分组。

每个会话一个目标

史诗就是会话的目标。最多选择一个进行中的史诗，并围绕它持续推进，直到达成或放弃目标。两个未关闭的史诗会分散注意力，拖慢进度。beans list --ready 是自然的进度检查点；当验收标准全部勾选且最后一个子项的状态为 completed 时，即可将史诗视为完成。

状态流转：每个 bean 都从 draft 开始

默认初始状态：draft。 不会直接将任何 bean 创建为 todo。bean 必须通过分流（深入研究）后才能执行。

draft  →  todo  →  in-progress  →  completed
                 ↘  scrapped

• draft - 需要分流。晋升状态前先进行研究。正文中包含问题、链接、未知事项和分流研究结果。
• todo - 可执行。分流已回答相关问题：范围明确，已编写验收标准，且有参考资料。可以认领。
• in-progress - 已认领。同一时间恰好由一个 Agent 或人类负责。
• completed - 已验证。正文包含 ## Summary of Changes + ## Proof of Work。
• scrapped - 已废弃。正文包含 ## Reasons for Scrapping。

beans list --ready 会返回 todo 和 in-progress 状态的 bean。如果你发现自己正要认领一个 draft，说明你跳过了分流——请返回上一步。

分流 = 深入研究

draft bean 是一个假设。在将其改为 todo 之前，负责分流的 Agent 或人类必须：

1. 重新阅读原始请求 - 实际上要做什么？

2. 深入研究 - 阅读受影响的代码、相关文档、规范和先例。当仓库内的证据不足时，进行在线研究（网页搜索、Context7、供应商文档）。在正文中注明来源。

3. 界定工作范围 - 拆分为任务 / 子任务。把一项需求全塞进一个臃肿的 bean 是个危险信号；应该将其拆分为一个史诗任务及其子任务。

4. 编写验收标准 - 使用 - [ ] 复选框，确保外部审核者可以独立验证。

5. 为编码 Agent 找到适用技能 - 如果叶子任务将由编码人员实现，请扫描项目和用户的技能根目录（.agents/skills/、~/.agents/skills/，以及运行时使用的任何 Agent 专属技能目录），并根据技能的描述与此技术栈和任务进行匹配。将技能写入 bean 正文，格式如下：

   ## Skills for coder
   
   - `~/.agents/skills/<name>/SKILL.md` - why this leaf needs it
   

   不要硬编码语言或项目包。每个叶子任务都要重新发现。没有此部分的编码子任务尚未准备好进入 todo。传递技能意味着在分派内容中注明其 PATH，并指示执行者在编辑前完整阅读。将技能规则总结到任务上下文中不等于传递技能：总结会丢掉总结者未想到要纳入的内容，而这一缺口正是被清除的规则类别在通过绿色门禁后重新引入的方式。门禁必须验证的技能规则要作为明确、可检查的事项复制到约定中——即使违反了风格规则，构建 / lint / gofmt 仍可能保持绿色，因此未检查的风格规则会导致错误内容上线。

6. 确定阻塞项和依赖项 - 对尚无法开始的子任务使用 --blocked-by。

7. 晋升状态 - 只有当正文有研究作为依据、已编写验收标准、编码任务已列出编码人员所需技能，且 bean 足够小、可以认领时，才使用 beans update <id> -s todo。

如果 draft 暴露出无法回答的问题，则应将其废弃，并将这些问题写入 ## Reasons for Scrapping。

由谁进行分诊（强制）

分诊由当前可用的最佳研究子 Agent完成，而不是由碰巧有空的人，也不是由主会话快速浏览工单：

• 在分诊时动态选择最强的可用模型——查询 Agent 运行时自身的模型选择机制（模型列表、路由器或提供商目录），找出当前可连接的最佳推理模型，并将任务委派给它。不要硬编码模型名称：最佳选择会随时间变化，而且不同环境下可连接的模型也不同。
• 分诊子 Agent 对仓库进行只读操作（研究而非实现），并将发现写入 bean 正文。
• 分诊输出要求——草稿正文最终必须包含：
  1. 根本原因／对待解决问题的回答——附文件:行号引用或引用的 URL；“未知”不算分诊结果。
  2. 本地研究——受影响的代码路径、配置和已阅读的契约，并附路径摘要。
  3. 在线研究——当仓库内证据不足时，查阅上游文档／问题／规范，并记录链接。
  4. 范围——拆分任务／子任务，最小粒度约 10 分钟，并通过 --blocked-by 设置阻塞关系。
  5. 验收标准——使用 - [ ] 复选框，且可独立验证。
  6. 编码者所需技能——当叶子任务面向编码 Agent 时，添加 ## Skills for coder，列出发现的技能路径（参见分诊步骤 5）。仅当纯文档／运维叶子任务不涉及代码修改时，才可省略。

只有正文包含以上内容后，分诊人员才能运行 beans update <id> -s todo。缺少根本原因或验收标准的 todo bean 属于分诊失败——应将其退回 draft。 缺少 ## Skills for coder 的编码叶子任务也属于分诊失败。

发现 Bug（强制）

如果发现 Bug，必须遵循正确的 beans 流程。必须先记录，再进行分诊。

不要先打补丁。不要直接跳到 todo 或 in-progress。不要因为测试发现问题就“顺手修一下”。

1. 停止编码。 保留证据（httpyac 日志、工作进程日志、失败测试输出）。
2. 记录——运行 beans create "<short title>" -t bug -s draft。正文应说明失败情况、预期与实际结果、ID、时间、堆栈信息和证据路径。
3. 分诊——深入研究（代码、契约、文档）。编写验收标准。如有必要，拆分任务。然后运行 beans update <id> -s todo。
4. 认领——仅在分诊之后：运行 beans update <id> -s in-progress。然后实现。

在分诊确认它是真实、范围明确且可执行的 Bug 之前，实际发现的不一致仍处于 draft 状态。错误的环境、空数据或不支持的类型，都不能成为悄悄修改代码的理由。

操作指南：references/patterns.md。

---

详情请参阅 Reopen pattern (user finding contradicts completed bean)。

详情请参阅 Bean creation for code-fix tasks (ALL-CODE-DELEGATED)。

CLI 命令

所有子命令和标志的文档见 references/cli.md。本节是一个快速索引，列出 Agent 在 95% 的会话中会用到的四个命令。

命令	适用场景
beans prime	会话开始时——加载项目当前的 bean 状态。
beans list --json	浏览／筛选。分诊后的工作使用 --ready，分诊队列使用 -s draft，顶层任务（史诗）使用 --no-parent。
beans create	新建 bean。默认状态为 -s draft；分诊后使用 update -s todo 将其推进。
beans update	认领、更新进度、追加 PoW、关闭。针对性编辑使用 --body-replace-old/new，为 ## Summary of Changes 和 ## Proof of Work 追加内容使用 --body-append。
beans show	检查。管道传递时使用 --body-only，安全并发更新时使用 --etag-only。

磁盘上的文件格式（YAML frontmatter、文件名约定、字段架构）请参阅 references/bean-file-format.md。 该文件由 CLI 管理——切勿手动编辑 .beans/*.md。

写回注释（审计结论、审查备注）

没有 beans comment 子命令。使用 CLI 为 bean 添加带日期的备注：

beans update <id> --body-append "## AUDIT (brainer, scope): verdict + evidence"

初始化上下文

beans prime

输出有关项目当前 beans、优先级和建议后续操作的上下文。Agent 应在会话开始时运行此命令。

委派模式

将 bean 工作分派给子 Agent 时（尤其是小型或免费模型）：

• 提示词要简短。 一个目标、准确的命令和文件路径。内联设计会损失保真度。
• 设计决策写入 bean 正文。 通过 --body-replace-old/new 将完整设计保留在任务中；bean 是唯一事实来源。不要将设计分散到临时文件中。
• 卡住一次就换策略。 挂起和仅返回文本都是信号——不要用同一提示词重试。改用不同的任务规模、Agent 或工具集。失败两次就停止委派该步骤。
• 诊断时绕过封装工具。 读取确切错误或 lint 位置时使用原始命令。

Agent 任务生命周期

1. beans prime                          → Get project context
2. beans list --json -s draft           → Find beans awaiting triage
3. Research the draft, scope it, write  → Triage the bean
   acceptance criteria, then promote
   with `beans update <id> -s todo`
4. beans list --json --ready            → Find actionable work
5. beans update <id> -s in-progress     → Claim the task
6. ... implement the change ...
7. beans update <id> --body-replace-*   → Check off acceptance criteria
8. VERIFY: run the project's tests/build/lint and observe results   ← gate
9. beans update <id> --body-append      → Add ## Proof of Work (commands + results + residual)
10. beans update <id> -s completed      → Mark done (only after verify + proof are present)

第 7–10 步由编排者而非执行者负责：执行者的报告只是一个声明。你需要自己重新运行各项检查，阅读差异，然后将工作证明（PoW）写入 bean 正文——只在聊天中记录完成不算在跟踪器中完成，而下一次会话也无法验证跟踪器中没有记录的内容。对于涉及所有文件的任务，PoW 应写明当前文件数、结论数，以及能够证明两组相匹配的命令。数量一致且检查通过，只能证明覆盖范围，不能证明内容合格。关闭全面检查前，重新阅读每个已修复文件的差异，并抽查一些未修改的文件。执行者可能在破坏样式规则的同时盖上结论标记，而由于样式不会由机器检查，各项检查仍会通过。仅凭结论数量关闭任务，之后会被重新打开。

仓库可以添加自己的 beans lint，检查范围可能超出 CLI。如果有，请在每次修改 bean 后运行。

将技能路径写入 bean 正文之前，先确认该路径在磁盘上存在。

类型错误的 bean（需要有子项的 task）可通过 beans update <id> -t epic 原地转换。ID、正文和历史记录都会保留。删除并重建会导致审计记录成为孤立记录，因此只有在目标确实已失效时才删除。

如果分诊结论在修复流程已交付后才到达，请将其追加到同一个 bean 正文中，并在该 bean 下将增量工作作为后续流程执行。不要为相同范围新建第二个 bean，也不要因为第一轮已通过就忽略更严格的结论。

对于 epic，第 8–9 步替换为：涵盖整个 epic 的端到端测试，以及一个以用户方式验证目标的 ## Proof of Work 部分。 请参阅下文的 关闭门槛（强制）。

从分诊到认领（强制）

• draft 不会出现在 beans list --ready 中。你不能认领它。
• 要处理它：先进行分诊（研究、确定范围、制定验收标准、在子项上设置 --blocked-by），然后运行 beans update <id> -s todo。只有这样它才可被认领。
• 跳过分诊，直接将 bean 改为 todo，属于流程违规——与未测试就标记为 completed 属于同一类违规。

关闭门槛（强制）

两条规则。每次调用 beans update -s completed 时都必须遵守。未通过任一规则的 bean 都必须保持在 in-progress（如果分诊尚未完成，则保持在 draft/todo）；如果工作无法完成，唯一诚实的退出方式是 scrapped。

1. 任务／子任务关闭

任务或子任务的正文中没有 ## Proof of Work 部分，就不能关闭。 该部分是验证关卡已运行的证据，与记录变更内容的 ## Summary of Changes 分开。至少必须包含：

• 实际运行的确切命令（构建、测试、lint、冒烟检查——视情况而定）。
• 每条命令的观测结果（退出状态、关键信号：计数、通过／失败、输出指纹）。
• 一行 Residual:——列出有名称的遗留事项，或填写 none。

如果缺少 ## Proof of Work，关闭操作将被拒绝。请先添加该部分，再标记为已完成：

beans update myproj-a3x1 --body-append "## Proof of Work

\
make vet   → 0\n\
make test  → PASS (unit + integration + e2e, 148s)\n\
make lint  → 0 issues (452 → 0)

Residual: none."

beans update myproj-a3x1 -s completed

生成证明的验证关卡本身也具有约束力。“我觉得它能用”不算完成。运行项目的测试／构建／lint，并观察结果。如果关卡未通过，请修复根本原因；如果无法验证，就将 bean 保持为 in-progress，并说明原因。

2. Epic 关闭

只要 epic 下仍有任何任务或子任务未关闭，就不能关闭该 epic；此外，关闭前必须完成完整的端到端测试并提供 ## Proof of Work。 需通过两部分关卡：

• 没有未关闭的子项。 epic 下的每个任务和子任务都必须先标记为 completed 或 scrapped，epic 本身才能转为 completed。使用以下命令检查：

  # Find any non-terminal child of the epic
  beans list --json --parent myproj-epic --no-status completed --no-status scrapped
  # Empty output → safe to close the epic.
  

• 完整的端到端测试和 ## Proof of Work。 epic 的证明属于集成级别：不能只说“单元测试通过了”，而必须提供目标整体已通过端到端方式实现的证据。添加一个 ## Proof of Work 部分，其中的命令应涵盖：

  • 完整的测试套件（包括单元测试、集成测试和 e2e 测试，如有）。
  • 能像用户实际使用那样验证目标的任何端到端／冒烟检查（浏览器、CLI 调用、API 往返等）。
  • 对于构建／部署类 epic，提供线上产物及其可访问 URL 或版本。

如果目标写着“交付功能 X”，却没有端到端验证 X，就不能算已证明。如果无法运行某个关卡（例如项目没有 e2e 测试框架），请在 ## Proof of Work 的 Residual: 下明确写明原因——不作说明地省略属于违规行为。

在子项仍未关闭时关闭 epic，或在未完成完整端到端测试并提供 Proof of Work 时关闭 epic，都属于流程违规——与未提供 ## Proof of Work 就关闭任务属于同一类别。

---

没有 Proof of Work，就不能标记为 completed

适用于所有 bean 类型。上面两个小节分别定义了任务／子任务与 epic 的证明要求；这条底层规则适用于所有 bean，无一例外。

提交信息约定

在提交信息中包含 bean ID：

feat(auth): add OAuth PKCE support

Refs: myproj-a3x1

---

反模式

流程和 CLI 规范——并非闭合规则，闭合规则见上文的 闭合门槛（强制）。

不要	应当
在会话开始时跳过 beans prime	始终先运行 beans prime
在脚本中使用不带 --json 的 beans list	始终使用 --json 获取机器可读的输出
不通过 CLI 直接编辑 .beans/ 文件	使用 CLI 命令以确保一致性
忽略并发更新的 etag	使用 --if-match 安全地进行并发编辑
对小改动使用 --body-file	使用 --body-replace-old/new 进行定向编辑
开始工作时忘记更新状态	认领任务时设置 -s in-progress
完成后仍让 bean 处于 in-progress 状态	始终使用 -s completed 或 -s scrapped 关闭
在一个会话中开启两个活跃 epic	每个会话选定一个 GOAL，围绕它持续推进直至达成
发现 bug 后立即修复	使用 beans create -t bug -s draft，记录证据并进行分诊，然后再认领
结束工作后遗留状态产物	会话结束前：PR 标题和正文与 HEAD 相符；所有已修改的 bean 均处于终态（completed/scrapped）；epic 标题非空；没有孤立的草稿
不通过 CLI 设置 bean 状态，或让已交付的 epic 仍处于 todo 状态	会话结束时检查：运行 beans list，关闭或废弃所有涵盖已交付工作的 bean；epic 状态应反映工作，而非计划
在核实工作者的声明前就追加 --body-append PoW	父级先重新运行门槛检查并阅读差异；PoW 记录的是你自己的门槛检查输出，而非工作者的报告
手动编辑 .beans/*.md 以添加评论	使用 beans update --body-append "## LABEL (context): ..."——没有评论子命令；文件由 CLI 管理
创建时只提供 -d，之后再修正标题	创建时将标题作为位置参数传入——文件名 slug 是永久的，之后通过 --title 编辑不会重命名文件

---

参考

• 仓库： https://github.com/hmans/beans
• 发布版本： https://github.com/hmans/beans/releases
• 文档（Context7）： https://context7.com/hmans/beans/llms.txt

---

请记住： 始终先运行 beans prime。脚本中使用 --json。关闭你的 beans。