How to Handle Beads That I've Come to Understand After Using It for About a Month: Priority Judgment and Notes Operation
This page has been translated by machine translation. View original
Introduction
Previously, I verified how to manage AI coding agent task states using Beads and how far automation could be taken.
In the previous article, I wrote that while state at session start can be restored automatically, updating the state requires human intervention.
After about one month of continued use across multiple repositories, I can share the following. On the positive side, since blockers and other dependencies are registered, I feel that the AI coding agent has gotten better at selecting higher-priority tasks. On the other hand, a problem emerged where continuously appending progress notes to Beads caused old and current information to become mixed together. Currently, I have switched to an approach of consolidating notes into a snapshot of the current state.
What is Beads
Beads is a task management tool designed for AI coding agents. It manages task states, priorities, and dependencies, and allows you to retrieve tasks without blockers using bd ready. The basic mechanism and how to get started are introduced in the previous article.
Operating Environment
- bd 1.1.2
- Claude Code 2.1.236
Target Audience
- Those who want to know how to operate Beads after getting started
- Those who want AI coding agents to decide the order in which to tackle multiple tasks
- Those whose Beads notes have grown long and are finding it hard to track the current state
References
Background
In the previous verification, I showed that by migrating from a handoff document (e.g., HANDOFF.md) to Beads, incomplete tasks could be restored at the start of a session. Since then, I began managing not just work state, but also post-investigation policy decisions and implementation order in Beads.
For example, when investigation reveals new constraints, it sometimes becomes impossible to immediately start on a planned implementation. This is because tasks such as finalizing a design, obtaining a decision from stakeholders, or completing another verification become necessary first.
With handoffs using HANDOFF.md, the reader has to reconstruct this order themselves. With Beads, however, it can be registered as dependencies and priorities between tasks. I now use Beads for the flow from information gathering through to implementation, and have the AI coding agent select the next candidate to work on.
Current Operation
bd ready extracts tasks that have no unresolved blockers and are not yet started, displaying them in priority order by default.
bd blocked lets you check tasks that cannot be started due to blockers.
bd ready
bd blocked
Using these two commands, you can separately retrieve tasks that can be started and blockers that should be resolved first.
When asking the agent what to do next, the agent became able to list actionable candidates in priority order and explain the blockers that are prerequisites for them. Compared to when we had to reconstruct dependencies from conversations and handoff documents each time, we can now start the conversation from comparing candidates.
I request state updates in the following order.
- Ask the agent to gather information
- Have the agent reflect the investigation results in Beads (for now, this is something I proactively instruct)
- Ask the agent to align priorities and dependencies with me
- I make the policy decision
- Have the agent record my decision in Beads (for now, this is also something I proactively instruct)
- ※ This is necessary to avoid rehashing the same discussion
- Have the agent begin implementation
Beads and the agent don't decide all policies on their own. By recording investigation results, stakeholder decisions, and task dependencies in the same place, the agent has the information it needs to select the next candidate.
The timing of updating Beads is still decided by me. The right point to organize tasks varies depending on the work—such as when new facts have emerged, when all options have been laid out, or when I want to finalize a policy before implementation. In my case, at these points I explicitly request:
Update Beads
Over the roughly one month of use, the arrangement that worked well was having me decide the timing and policy of updates, while the agent handles structuring investigation results, registering dependencies, and extracting candidates to work on.
Problem
As I continued operating this way, I fell into a pattern of continuously appending progress updates to a single task using bd note.
This turned out to be a poor practice.
When I aggregated data across the 25 repositories I had been working in, the total character count for notes reached 550,793 characters. Looking at individual tasks, the median was 1,011 characters, with a maximum of 49,216 characters.
There were also issues beyond just character count. For example, in one aggregation task, a value of 894 that had been recorded initially turned out to be wrong, and the correct value of 216 was appended later. The notes ended up containing both of the following:
Number of Stop hook fires: 894
[Correction] 894 was incorrect. The correct value is 216
The first line should not have remained at all. An agent reading the notes would need to read both and interpret the correction relationship. Disproven hypotheses and superseded policies were similarly left in as appended entries, causing the same problem.
Solution
I have now changed the rule to treat notes not as a history, but as a snapshot of the currently valid state.
When facts are confirmed through investigation or verification belonging to that task, I still use bd note to record progress as before. Subsequent tasks are registered as separate issues, and decisions and knowledge shared across multiple tasks are separated into persistent memory.
bd note <issue-id> "Confirmed fact and how it was confirmed"
When new facts make existing descriptions outdated, rather than appending a correction at the end, I use bd update --notes to consolidate the entire notes into the current state.
bd update <issue-id> --notes "Currently valid investigation results, decisions, and remaining work"
The targets for rewriting are descriptions found to be incorrect, disproven hypotheses, and superseded policies. Failures or decision processes that have value for future reference are moved to a report before being rewritten.
| Information | Storage Location |
|---|---|
| Currently valid state and remaining work | Beads notes |
| Failures and decision processes worth referencing later | Reports in docs/reports |
| Decisions and knowledge that will be needed repeatedly in the future | Beads persistent memory |
When updating persistent memory as well, I specify an existing key to overwrite it. This is because omitting --key and adding it as a new record would leave the old content behind.
bd remember "Currently valid decision or knowledge" --key <key>
With this approach, appending at the time facts are confirmed and consolidating when outdated descriptions arise are treated as separate actions. Progress is not lost, and the current valid state can be passed to the next session.
Summary
After operating Beads for about one month, the AI coding agent became able to suggest the next candidate to work on based on dependencies. On the other hand, continuously appending corrections to notes causes past and current information to become mixed together. As a countermeasure, I now append notes when facts are confirmed, and consolidate the entire notes into the current state when outdated descriptions arise. I hope this serves as a useful reference for anyone struggling with task management in AI-assisted development.
