Back to Details

design-to-beads

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design to Beads Conversion

设计文档到Beads任务的转换

Overview

概述

Convert design documents into fully-structured beads issues with lossless information transfer, proper epic hierarchy, and validated dependencies.
Core principle: Every piece of actionable content in the source document must map to a beads issue. Nothing gets lost. Dependencies must enable maximum parallelization. Three independent subagent reviews catch what self-review misses.
将设计文档转换为结构完整的beads任务，确保信息无丢失、Epic层级合理且依赖关系经过验证。
核心原则： 源文档中的每一项可执行内容都必须对应一个beads任务，确保无信息遗漏。依赖关系的设置需支持最大程度的并行化。三轮独立的Subagent审核可发现自我审核遗漏的问题。

When to Use

适用场景

  • Converting finalized design docs to trackable work
  • Breaking down PRDs into implementation tasks
  • Creating beads structure from any markdown plan
  • 将定稿的设计文档转换为可追踪的工作任务
  • 将PRD拆解为可落地的实施任务
  • 基于任何Markdown规划文档构建beads任务结构

When NOT to Use

不适用场景

  • Design isn't finalized (use brainstorming skill first)
  • Simple single-task work (just create issue directly)
  • 设计文档尚未定稿（请先使用头脑风暴工具）
  • 简单的单一任务（直接创建任务即可）

Critical Rules

关键规则

DO NOT rush under time pressure. Quality conversion takes time. A poorly-structured beads hierarchy causes more delay than taking 30 extra minutes upfront.
DO NOT skip review passes. Single-pass creation misses gaps, creates false dependencies, loses information.
DO NOT self-review. Launch subagents for review passes. Self-review misses what independent reviewers catch.
DO NOT create flat issue lists. Use epics with parent-child relationships.
DO NOT assume sequential ordering. Question every dependency: "Does A truly BLOCK B, or could they run in parallel?"
DO NOT create sparse issues. If the source has detail, the issue must have detail. Brief descriptions = lost information = implementation failures.
切勿因时间仓促而敷衍。 高质量的转换需要时间投入。结构混乱的beads层级比多花30分钟做前期准备造成的延误更大。
切勿跳过审核环节。 单次创建会遗漏信息缺口、设置错误依赖，导致信息丢失。
切勿自我审核。 请启动Subagent进行审核。自我审核无法发现独立审核人员能捕捉到的问题。
切勿创建扁平化任务列表。 请使用带有父子关系的Epic结构。
切勿默认采用顺序执行。 对每一个依赖关系提出质疑：“A是否真的会阻碍B启动，还是两者可以并行执行？”
切勿创建内容稀疏的任务。 如果源文档包含细节，任务中也必须保留对应细节。描述过于简略会导致信息丢失，进而引发实施失败。

The Process

转换流程

Phase 1: Analyze Input Document

第一阶段：分析输入文档

  1. Read the entire document
  2. Identify natural groupings (phases, features, components) → epics
  3. Identify actionable items within each grouping → issues
  4. Note explicit dependencies mentioned in text
  5. Note technical details, acceptance criteria, edge cases
  1. 通读整个文档
  2. 识别自然分组（阶段、功能、组件）→ Epic
  3. 识别每个分组内的可执行项 → 任务
  4. 记录文档中明确提及的依赖关系
  5. 记录技术细节、验收标准和边缘情况

Phase 2: Draft Structure (DO NOT EXECUTE YET)

第二阶段：草拟任务结构（暂不执行）

Create a written draft:
Epic: [Name]
  - Issue: [Title]
    Dependencies: [list or "none - can start immediately"]
    Key details: [from source doc]
Coverage matrix (REQUIRED):
Source Section → Beads Location
────────────────────────────────
"Phase 1.1 Stripe Setup" → Epic 1, Issue 1.1
"Technical note: 30s timeout" → Issue 1.1 (acceptance criteria)
Every source section MUST appear. Gaps = work not captured = failure.
Detail density tracking (REQUIRED):
Phase/Section     | Source Detail | Beads Detail | Status
──────────────────|───────────────|──────────────|────────
Phase 1 (4 items) | 450 words     | 380 words    | ✓ OK
Phase 2 (6 items) | 600 words     | 120 words    | ⚠️ SPARSE
Phase 3 (3 items) | 200 words     | 190 words    | ✓ OK
Sparse phase = red flag. If beads detail is <50% of source detail, the conversion lost information. Go back and capture missing details before proceeding.
创建书面草稿：
Epic: [Name]
  - Issue: [Title]
    Dependencies: [list or "none - can start immediately"]
    Key details: [from source doc]
覆盖矩阵（必填）：
Source Section → Beads Location
────────────────────────────────
"Phase 1.1 Stripe Setup" → Epic 1, Issue 1.1
"Technical note: 30s timeout" → Issue 1.1 (acceptance criteria)
每一个源文档章节都必须被覆盖。 存在缺口意味着工作未被完整捕捉，属于转换失败。
细节密度跟踪（必填）：
Phase/Section     | Source Detail | Beads Detail | Status
──────────────────|───────────────|──────────────|────────
Phase 1 (4 items) | 450 words     | 380 words    | ✓ OK
Phase 2 (6 items) | 600 words     | 120 words    | ⚠️ SPARSE
Phase 3 (3 items) | 200 words     | 190 words    | ✓ OK
稀疏阶段属于红色预警。 如果beads任务的细节内容不足源文档的50%，说明转换过程中存在信息丢失。返回并补充缺失细节后再继续。

Phase 3: Subagent Review Passes (MANDATORY)

第三阶段：Subagent审核环节（强制要求）

DO NOT self-review. Launch independent subagents for each pass using the Task tool. Self-review is biased; subagents catch what you miss.
If Task tool unavailable: Present full draft to user for manual review at each pass checkpoint. Do NOT substitute self-review for subagent review.
Pass 1: Completeness + Detail Density Review (launch subagent with Task tool)
Subagent mandate:
"Review this beads structure against the source document. Verify: (1) every actionable item has a corresponding issue, (2) every technical note is captured, (3) every acceptance criterion is attached, (4) coverage matrix has no gaps, (5) detail density check: for each phase, compare word count of source vs beads - flag any phase where beads is <50% of source as SPARSE. Report any missing content or sparse phases."
Detail density criteria for each issue:
  • Description must be substantive (>50 words) OR source item was genuinely simple
  • Acceptance criteria count should roughly match source complexity
  • Technical notes from source preserved verbatim, not summarized
  • If source bullet has sub-bullets, issue must capture them all
Apply fixes from Pass 1 before proceeding.
Pass 2: Dependencies Review (launch subagent)
Subagent mandate:
"Review dependencies in this beads structure. Identify: false sequential ordering (could be parallel), missing blockers, incorrect dependency direction, backward phase dependencies (Phase N task depending on Phase N+M task), over-constrained chains. For each dependency, answer: Does A truly BLOCK B from starting?"
Backward phase dependency = structural error. If a Phase 1 task depends on a Phase 3 task, something is wrong:
  • The phases are ordered incorrectly in the source document
  • The task belongs in a different phase
  • The dependency is incorrect
When backward phase dependencies are found, ask the user: "Should I update the source spec/design document to fix the phase ordering, or should we adjust the task placement?"
Apply fixes from Pass 2 before proceeding.
Pass 3: Clarity + Density Review (launch subagent)
Subagent mandate:
"Review each issue for implementation readiness. Check: title clarity, description completeness, acceptance criteria verifiability. Flag: vague language, assumed knowledge, missing context. Also flag any issue where description is <50 words but the corresponding source section had >100 words - this indicates lost detail. Could a fresh agent execute each issue without referring back to the source document?"
Apply fixes from Pass 3 before proceeding.
Optional Pass 4: Implementation Readiness (for complex projects)
Subagent mandate:
"For each issue: Could a fresh agent with zero codebase context pick this up and execute? Flag: missing file paths, assumed knowledge, vague verbs like 'update the thing'."
切勿自我审核。 使用任务工具启动独立Subagent进行每一轮审核。自我审核存在偏见，Subagent能发现你遗漏的问题。
若任务工具不可用： 在每一轮审核节点将完整草稿提交给用户进行人工审核。切勿用自我审核替代Subagent审核。
第一轮审核：完整性+细节密度审核（通过任务工具启动Subagent）
Subagent任务要求：
"对比源文档审核此beads任务结构。验证：(1) 每一个可执行项都有对应的任务，(2) 每一条技术说明都被捕捉，(3) 每一项验收标准都已关联，(4) 覆盖矩阵无缺口，(5) 细节密度检查：针对每个阶段，对比源文档与beads任务的字数占比——若beads任务字数不足源文档的50%，标记为SPARSE。报告任何缺失内容或稀疏阶段。"
单个任务的细节密度标准：
  • 描述内容必须详实（>50词），或源文档中的对应项确实简单
  • 验收标准的数量应与源文档的复杂度大致匹配
  • 源文档中的技术说明需完整保留，不可简化
  • 若源文档的项目包含子项目，任务中必须完整捕捉所有子项
完成第一轮审核的修复后再进入下一阶段。
第二轮审核：依赖关系审核（启动Subagent）
Subagent任务要求：
"审核此beads任务结构中的依赖关系。识别：错误的顺序设置（本可并行）、缺失的阻塞项、错误的依赖方向、跨阶段反向依赖（第N阶段任务依赖第N+M阶段任务）、过度约束的依赖链。针对每一个依赖关系，回答：A是否真的会阻碍B启动？"
跨阶段反向依赖属于结构错误。 如果第一阶段的任务依赖第三阶段的任务，说明存在问题：
  • 源文档中的阶段顺序设置错误
  • 任务所属阶段不正确
  • 依赖关系设置错误
发现跨阶段反向依赖时，询问用户：“我是否需要更新源规格/设计文档以修正阶段顺序，还是调整任务的所属阶段？”
完成第二轮审核的修复后再进入下一阶段。
第三轮审核：清晰度+密度审核（启动Subagent）
Subagent任务要求：
"审核每个任务的实施就绪度。检查：标题清晰度、描述完整性、验收标准可验证性。标记：模糊表述、默认已知的信息、缺失的上下文。同时标记任何描述内容<50词但对应源文档章节>100词的任务——这表明存在信息丢失。新接手的Agent无需参考源文档即可执行每个任务吗？"
完成第三轮审核的修复后再进入下一阶段。
可选第四轮审核：实施就绪度审核（针对复杂项目）
Subagent任务要求：
"针对每个任务：完全不了解代码库的新Agent能否接手并执行？标记：缺失文件路径、默认已知的信息、模糊动词如'update the thing'。"

Phase 4: User Checkpoint

第四阶段：用户确认节点

Before executing bd commands, present the final structure to the user:
Ready to create:
- X epics
- Y issues
- Z blocking dependencies
- W items ready immediately (parallel start)

Coverage: All N source sections mapped ✓

Detail Density:
  Phase 1: 450 → 380 words (84%) ✓
  Phase 2: 600 → 550 words (92%) ✓
  Phase 3: 200 → 190 words (95%) ✓
  Overall: 1250 → 1120 words (90%) ✓

Proceed with creation? [User must confirm]
If any phase shows <50% density, DO NOT proceed. Go back and flesh out the sparse phases before asking for confirmation.
DO NOT skip this checkpoint. User approval prevents creating wrong structure.
在执行bd命令前，向用户展示最终的任务结构：
准备创建以下内容：
- X个Epic
- Y个任务
- Z个阻塞依赖
- W个可立即启动的任务（并行执行）

覆盖情况：所有N个源文档章节已完成映射 ✓

细节密度：
  第一阶段：450 → 380词（84%） ✓
  第二阶段：600 → 550词（92%） ✓
  第三阶段：200 → 190词（95%） ✓
  整体：1250 → 1120词（90%） ✓

是否继续创建？[需用户确认]
若任何阶段的细节密度<50%，切勿继续。 返回并补充稀疏阶段的内容后再请求用户确认。
切勿跳过此确认节点。 用户确认可避免创建错误的任务结构。

Phase 5: Execute

第五阶段：执行创建

Only after user confirmation:
  1. Create epics first:
    bash
    bd create "Epic title" -t epic -p <priority> -d "Description"
# Returns: <epic-id>
  2. Create issues with --parent (preferred):
    bash
    bd create "Issue title" -t task -d "Description" \
  --parent <epic-id> \
  --acceptance "- [ ] Criterion 1"
    Backup (when epic ID isn't known at create time):
    bash
    # bd dep add <child-id> <parent-id> = "child depends on parent"
bd dep add <issue-id> <epic-id> --type parent-child
  3. Add blocker dependencies (only TRUE blockers):
    bash
    # bd dep add <dependent-id> <prerequisite-id> = "dependent depends on prerequisite"
bd dep add <dependent-id> <prerequisite-id>
  4. Verify:
    bash
    bd dep cycles          # Must return empty
bd ready --json        # Check expected items ready
仅在用户确认后执行以下操作：
  1. 先创建Epic：
    bash
    bd create "Epic title" -t epic -p <priority> -d "Description"
# Returns: <epic-id>
  2. 创建任务并关联父Epic（推荐方式）：
    bash
    bd create "Issue title" -t task -d "Description" \
  --parent <epic-id> \
  --acceptance "- [ ] Criterion 1"
    备选方案（创建时未知Epic ID的场景）：
    bash
    # bd dep add <child-id> <parent-id> = "child depends on parent"
bd dep add <issue-id> <epic-id> --type parent-child
  3. 添加阻塞依赖（仅添加真实阻塞项）：
    bash
    # bd dep add <dependent-id> <prerequisite-id> = "dependent depends on prerequisite"
bd dep add <dependent-id> <prerequisite-id>
  4. 验证：
    bash
    bd dep cycles          # Must return empty
bd ready --json        # Check expected items ready

Phase 6: Generate Report

第六阶段：生成报告

A. Creation Summary
Created: X epics, Y issues
  Epic 1: [Name] (N issues)
  ...
B. Dependency Graph (show blocking relationships and parallel opportunities)
C. Ready Work Queue (items with no blockers)
D. Coverage Verification
Source sections: N
Mapped to beads: N ✓
Information loss: None
A. 创建总结
已创建：X个Epic，Y个任务
  Epic 1: [Name] (N个任务)
  ...
B. 依赖关系图（展示阻塞关系与并行机会）
C. 就绪任务队列（无阻塞的任务）
D. 覆盖验证
源文档章节数：N
已映射到beads的章节数：N ✓
信息丢失：无

Loophole Closures

常见误区规避

"I'll review it myself to save time" → WRONG. Self-review is biased. Launch subagents.
"The review passes are just a formality" → WRONG. Apply fixes between each pass. Document what changed.
"User checkpoint slows things down" → WRONG. Wrong structure wastes more time. Get confirmation.
"These items obviously need to be sequential" → WRONG. Prove it. State why A must complete before B can START.
"I captured the key points" → WRONG. Capture ALL points. Lossless means lossless.
"This is simple enough for one pass" → WRONG. Even simple docs need review for dependencies.
"Phase 1 legitimately depends on Phase 3" → WRONG. Backward phase dependencies signal incorrect ordering. Ask user if source doc needs updating.
"This phase is simpler, it doesn't need much detail" → WRONG. If the source has detail, capture it. A 600-word source section becoming a 120-word beads issue = 80% information loss. Sparse issues cause implementation failures.
"I'll add more detail when implementing" → WRONG. The beads issue IS the specification. If detail isn't in the issue, it's not in the spec. Capture it now or lose it.
“我自己审核来节省时间” → 错误。自我审核存在偏见，请启动Subagent审核。
“审核环节只是走个形式” → 错误。每轮审核后都要修复问题，并记录修改内容。
“用户确认节点拖慢进度” → 错误。错误的任务结构会浪费更多时间，请务必获取用户确认。
“这些任务显然需要顺序执行” → 错误。请证明必要性，说明A必须在B启动前完成的原因。
“我已经捕捉了关键点” → 错误。要捕捉所有内容，无丢失意味着完全无遗漏。
“这个文档很简单，一轮审核就够了” → 错误。即使是简单文档也需要审核依赖关系。
“第一阶段确实依赖第三阶段” → 错误。跨阶段反向依赖意味着阶段顺序错误，请询问用户是否需要更新源文档。
“这个阶段更简单，不需要太多细节” → 错误。如果源文档包含细节，就必须完整捕捉。600词的源文档章节变成120词的beads任务意味着80%的信息丢失，内容稀疏的任务会导致实施失败。
“我会在实施时补充更多细节” → 错误。beads任务就是实施规格。如果细节不在任务中，就不属于规格内容，请现在就完整捕捉，避免信息丢失。

Common Mistakes

常见错误与修复方案

MistakeFix
Flat issue listUse epics with parent-child
Self-reviewLaunch subagents
Sequential-by-defaultProve each blocker
Backward phase dependenciesReorder phases or move task; offer to update source doc
Summarizing detailsPreserve exact wording
Sparse descriptions (<50% density)Compare word counts; flesh out before proceeding
Skipping user checkpointAlways get confirmation
Rushing for time pressureQuality over speed
错误修复方案
扁平化任务列表使用带有父子关系的Epic结构
自我审核启动Subagent进行审核
默认顺序执行验证每个阻塞项的必要性
跨阶段反向依赖调整阶段顺序或任务所属阶段；询问用户是否需要更新源文档
简化细节保留源文档的原始表述
内容稀疏的描述（密度<50%）对比字数占比，补充内容后再继续
跳过用户确认节点务必获取用户确认
因时间仓促敷衍质量优先于速度

Quick Reference

快速参考

1. READ entire source document
2. DRAFT structure with coverage matrix
3. SUBAGENT Pass 1: Completeness → Apply fixes
4. SUBAGENT Pass 2: Dependencies → Apply fixes
5. SUBAGENT Pass 3: Clarity → Apply fixes
6. (Optional) SUBAGENT Pass 4: Implementation readiness
7. USER CHECKPOINT: Present structure, get confirmation
8. EXECUTE bd commands (epics → issues → deps)
9. VERIFY no cycles, expected items ready
10. REPORT summary, graph, queue, coverage
Remember: Lossless. Epics. Subagent reviews. User checkpoint. Maximum parallelization.
1. 通读整个源文档
2. 草拟任务结构并制作覆盖矩阵
3. SUBAGENT第一轮审核：完整性 → 修复问题
4. SUBAGENT第二轮审核：依赖关系 → 修复问题
5. SUBAGENT第三轮审核：清晰度 → 修复问题
6. （可选）SUBAGENT第四轮审核：实施就绪度
7. 用户确认节点：展示结构，获取确认
8. 执行bd命令（先创建Epic → 再创建任务 → 最后添加依赖）
9. 验证无循环依赖，确认就绪任务符合预期
10. 生成报告：总结、依赖图、就绪队列、覆盖验证
谨记： 无信息丢失、Epic层级、Subagent审核、用户确认、最大并行化。