메뉴
Applies reusable Beads writing and update practices in every context. Use whenever reading, creating, updating, commenting on, closing, superseding, or handing off Beads issues, including alongside beads, beads-solo, and plan-to-beads workflows.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/aspiers/ai-config --skill beads-best-practices명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SKILL.md 표시 중
| name | beads-best-practices |
| description | Applies reusable Beads writing and update practices in every context. Use whenever reading, creating, updating, commenting on, closing, superseding, or handing off Beads issues, including alongside beads, beads-solo, and plan-to-beads workflows. |
Apply these practices to every Beads interaction, regardless of repository, storage mode, team policy, or higher-level workflow.
When the repository opts into the solo-maintainer policy, also load and follow
beads-solo. That skill controls authorization,
setup, storage, and governance; this skill controls reusable issue-writing and
update practices. Neither supersedes the other.
Inspect the bead, then claim it before beginning substantive work:
bd show "$id"
bd update "$id" --claim
Do not edit code, change project state, or begin the task while its bead remains unclaimed. Claiming makes ownership visible and prevents duplicated work.
If another worker already owns the bead, do not overwrite the assignee or work
on it in parallel without coordination. Stop and resolve ownership through the
active project workflow. Re-running --claim is acceptable when the bead is
already assigned to the current worker.
Treat in_progress as evidence of work happening now, not as a reservation for
a batch of issues you intend to address later. By default, claim exactly one
bead at a time and leave related or queued work open while you inspect or
sequence it.
Before switching to another bead:
open (or defer it) if work is
pausing.Multiple beads may be in_progress only when work is genuinely concurrent,
such as separate workers actively owning independent tasks, or when the active
workflow explicitly requires overlapping tracked work. Do not bulk-claim a
label, epic, milestone, search result, or requested task set merely because all
items are in scope.
A bead is done by a person or by an agent, never by both. When part of the work needs a person and the rest needs an agent, that is two beads, joined by a dependency.
This holds whichever order they come in:
Split at the point where the doer changes, and give the person's bead only their part. Keep it narrow: one decision, one observation, one approval.
bd human respond closes the bead it answers. If the bead also contains
agent work, answering it closes work nobody did. Split properly and the answer
closes exactly what the person was asked for, while the dependency releases
the rest.
Create the bead, describe what is needed, label it human, and make the
dependent work wait on it:
ask=$(bd create --title="Decide: <the question>" \
--description="<context, options, what turns on each>" \
--type=task --json | jq -r .id)
bd label add "$ask" human
bd dep add "$work" "$ask"
bd human list --json
bd human list is how the user finds these, and it lists exactly the beads
carrying the label. A bead needing a person but carrying no label is
invisible: it looks like every other open issue, and they have no reason to
know they are the blocker.
Leaving the explanation in a comment alone is not enough. A comment reading "awaiting live verification before close" is only found by someone already reading that bead — the one person who is not looking.
Split out a person's bead when:
The last two are where mixed beads usually creep in. A bead written as "implement X and confirm it works on the device" is two beads that were never separated; split it rather than labelling the whole thing.
Write the description for someone with no other context — they see the bead and its comments and nothing else. State what is needed as a checkable list, and where it is a choice, give the real options and what turns on each. A request with no instructions transfers the interruption without transferring the context, leaving the person to reconstruct what the agent already knew.
A person's bead is usually blocked by nothing, so it appears in bd ready
like any other issue. Nothing upstream excludes it — bd ready has no
knowledge of the label.
So every automatic queue read must exclude it explicitly:
bd ready --exclude-label=human
Treat that as an invariant. Miss it in one place and an agent picks up "Choose the storage backend" as ordinary ready work and chooses.
The dependency protects the dependent work; only --exclude-label=human
protects the question itself. Both are needed.
in_progressA bead waiting on a person is not being worked on. Leaving it in_progress
makes blocked work indistinguishable from active work, and from work an agent
abandoned mid-task.
Keep it open, so the status describes reality and the label carries the
reason. Reserve in_progress for work happening now, per
Keep Work-in-Progress Status Honest.
After creating the bead, labelling it, and adding the dependency, run
bd human list --json and verify it appears. This catches an incomplete
handoff before an unattended workflow moves on.
Once labelled, the bead is the user's. Do not answer it yourself, and do not keep checking whether the blocker went away — move on to other ready work.
They drain the queue with the
beads-blocker-review skill, exposed as
the /blockers command, which walks the beads one at a time and answers each
with bd human respond. That closes the bead and releases whatever depended
on it, so the work returns to bd ready on its own.
An answer can arrive at any time, including mid-run. So re-read the queue fresh on every pass: never skip a bead because you remember labelling it, and never assume one you labelled is still waiting. The bead's current state is the only authority.
When the queue is non-empty, point the user at /blockers rather than merely
reporting a count.
Normally you never do this — the user's answer closes the bead through
bd human respond, and the label stays attached as a record of what happened.
bd human stats reads it to report responded and dismissed counts.
Only remove the label when new evidence proves a person was never needed:
bd comments add "$id" "Human attention no longer needed: <evidence>"
bd label remove "$id" human
bd human list --json
Never use bd human respond or bd human dismiss on the user's behalf. Those
record a human's decision; inventing one answers the question they were asked.
Never close a bead by satisfying its criteria a different way than it asks. When a criterion says the change was observed running, reading the code and concluding it must work is not that criterion — it is a substitution, made by the party least able to judge whether it holds.
Split the verification into the person's own bead and let them do it. An agent closing its own unverifiable work is how a bug gets marked fixed several times while the user keeps hitting it.
Never refer to a bead in human-facing prose solely by its opaque ID. Pair the ID with its title or a concise human-readable description so readers do not have to look it up to understand the reference.
Prefer either of these forms:
- `ai-wt0` — **Handle expired sessions**
- Handle expired sessions (`ai-wt0`)
Apply this to conversation responses, progress reports, comments, handoffs,
blocker explanations, commit summaries, and lists of related work. When a bead
has already been introduced in the immediate context, use its readable title
rather than falling back to the bare ID. Bare IDs remain appropriate in
machine-facing commands such as bd show ai-wt0.
All substantive project work must be represented by a bead. Do not perform untracked work merely because it is small, related to the active task, or a tangent discovered along the way.
When a distinct work item emerges during another task:
Create a new bead before pursuing it.
Explain the discovery and the work clearly in its Markdown body.
Link it to the active bead, normally with discovered-from:
bd create --title="Newly discovered work" \
--deps="discovered-from:$active_id" --body-file - <<'EOF'
## Context
Discovered while working on the originating bead.
## Task
Describe the distinct follow-up work.
EOF
Add blocking dependencies when the new work must finish before the active bead can continue.
Return to the active bead, or explicitly claim the new bead before switching to it.
Create the bead even when the work will be deferred or handed to someone else. Do not silently expand the active bead's scope. Routine steps already required by its stated task and acceptance criteria remain in that bead and do not need separate per-command issues.
Labels and epics are different mechanisms, and they compose. Applying a label to every bead in a set is nearly always right; adding an epic parent is a separate decision.
Use a label for an attribute or a perpetual category with no end state,
such as area:auth, tech-debt, or needs-review. A bead can carry several,
they cross-cut unrelated work, and they can be applied retroactively without
restructuring anything.
Use an epic for a bounded deliverable with a done condition. An epic is a
real issue, so it carries status, priority, and a description holding the
feature-level narrative and acceptance criteria; it reports roll-up progress
through bd epic status; and it can itself block or be blocked. In exchange
it is an extra issue to maintain and close, and each bead has only one parent.
An epic whose done condition never arrives is worse than no epic. When a set of work has no feature-level completion state, group it with a label alone.
--parent records presentational hierarchy only. It imposes no ordering
whatsoever.
The value of Beads is an arbitrary dependency graph, so never let a parent
tree stand in for it. Record every real ordering constraint explicitly with
bd dep add, including dependencies between children of the same epic, which
may depend on one another in any shape the work requires.
Note also that epics appear in bd ready alongside actionable work. Filter
them out with bd ready --exclude-type=epic when that is noisy.
When a commit implements, advances, or closes tracked work, name the bead in its message. A commit that leaves no trace of its bead forces readers to reconstruct the link from timestamps, and the rationale recorded in the bead becomes unreachable from the code history.
Use the trailer form unless the repository already uses another convention:
Refs: bead ai-wt0
Determine the convention from the repository rather than assuming, and prefer an explicit documented rule over inference:
Check the project's agent instructions for a stated commit convention.
Otherwise search the history for existing references, rather than reading only the last handful of commits:
git log --format='%h|%s|%b' | grep -iE '\b(refs|closes|fixes)\b.*[a-z]+-[a-z0-9]+' | head
Sampling only recent commits is unreliable: a convention applied inconsistently, or omitted from the most recent work, will look absent. Treat a single documented or historical example as establishing the convention, and raise the inconsistency rather than silently following the omission.
When no convention exists anywhere, add the Refs: trailer and say so, so the
maintainer can confirm or correct it.
Treat every human-facing text field as Markdown:
Use headings, paragraphs, lists, checkboxes, inline code, fenced code blocks, and links where they make the content easier to scan.
Avoid walls of text. Separate sections and paragraphs with blank lines, and turn sequences or sets of facts into lists. Do not rely on renderer word wrap or single newlines inside one paragraph to provide structure.
Keep titles concise plain text; put detail in the Markdown body.
Represent GitHub issues, pull requests, documentation, dashboards, and other relevant web references as descriptive Markdown hyperlinks. Do not leave a bare URL or an unlinked textual reference when its target is available.
Use direct links and labels that identify the destination. Format technical identifiers inside link labels as inline code:
- Issue: [`owner/repository#123`][issue]
- Pull request: [`owner/repository#456`][pull-request]
- Reference: [Beads sync concepts][sync-concepts]
[issue]: https://github.com/owner/repository/issues/123
[pull-request]: https://github.com/owner/repository/pull/456
[sync-concepts]: https://example.com/beads/sync-concepts
Resolve the canonical target before posting. Do not fabricate a URL when the link target is unknown; find it first, or state clearly that it could not be resolved.
Enclose code, technical symbols, and identifiers in backticks. This includes:
Use inline code for short items such as bd update, --claim,
src/auth/session.ts, refreshToken, and ai-wt0. Use a fenced code block
with an appropriate language for multiline commands, code, structured data,
or logs. Do not use backticks merely for emphasis around ordinary prose.
Pass actual newline characters to bd. Do not store literal \n sequences,
and do not compress structured content into a long one-line flag value.
Prefer stdin or file flags when the command supports them:
bd create --title="Handle expired sessions" --type=task --body-file - <<'EOF'
## Context
Expired sessions currently produce an unclear error.
## Acceptance Criteria
- Return an actionable message.
- Cover the expired-session path with a test.
EOF
bd update "$id" --body-file - <<'EOF'
## Context
The failure occurs before token refresh.
## Next Step
Add coverage around the refresh boundary.
EOF
For a multiline comment, preserve the Markdown in a shell variable or file:
comment=$(cat <<'EOF'
## Progress
- Added the regression test.
- Confirmed that it fails before the fix.
## Next Step
Update the refresh path.
EOF
)
bd comments add "$id" "$comment"
Use the same pattern for fields that only accept string flags. Quote every multiline variable expansion.
Append a comment rather than updating notes whenever time, author, order, or
history is relevant. Comments are the durable activity log and preserve the
metadata needed to understand how work evolved.
Use comments for:
Keep every active bead regularly updated. Post a comment at meaningful checkpoints rather than waiting until the task is complete. At minimum, comment:
For long-running work, add periodic checkpoint comments even when no major milestone has completed, so the latest comment still explains the current state and next step. Do not comment after every command or create noise; the cadence should make the work resumable by another person or agent.
Do not append a running journal to notes. The notes field is not
timestamped.
Reserve it, if used at all, for timeless supplementary information that
represents the issue's current state and is safe to replace as a whole. When
in doubt, post a comment.