Back to Details

planning-implementation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Planning Implementation

规划实施

Overview

概述

Extract every implementation task from architecture document(s) into a structured JSON task graph. The output is a DAG of tasks sized for autonomous agent workers — each task self-contained, dependency-ordered, and verifiable without access to the full architecture.
从架构文档中提取所有实施任务，转换为结构化的JSON任务图。输出结果是一个适合自主Agent Worker执行的任务DAG（有向无环图）——每个任务独立完整、按依赖排序，无需访问完整架构文档即可验证。

Before Planning Begins

规划开始前的准备

  1. Get existing state: Run 
    dark-factory list --job $JOB --status pending --include-content
    to see outstanding tasks already in the graph
  2. Explore the codebase: Dispatch background explore agents to review files relevant to each section of the document — understand existing patterns, types, and integration points before writing tasks
  3. Research dependencies: Use web search to research any libraries, frameworks, or tools referenced in the architecture that you're unfamiliar with
  1. 获取现有状态：运行
    dark-factory list --job $JOB --status pending --include-content
    查看任务图中已有的待处理任务
  2. 探索代码库：派遣后台探索Agent审查与文档各部分相关的文件——在编写任务前，先了解现有模式、类型和集成点
  3. 研究依赖项：使用网络搜索研究架构文档中提到的、你不熟悉的任何库、框架或工具

Output Schema

输出 Schema

Write valid JSON to the specified output path:
json
{
  "project": "<project name>",
  "tasks": [
    {
      "id": "T001",
      "title": "Short task title",
      "description": "Detailed description of what to implement",
      "dependencies": ["T000"],
      "files": ["src/path/to/file.ts"],
      "acceptance_criteria": "Specific, verifiable criteria",
      "verification_steps": ["cargo build", "bun test"],
      "context_files": ["specs/ARCHITECTURE.md"],
      "estimated_complexity": "low|medium|high",
      "implementation_details": "Markdown with ### headers"
    }
  ]
}
  • Sequential IDs: T001, T002, ...
  • Dependencies must reference valid task IDs within the list
  • Extract EVERY task mentioned in the document — do not skip or merge
将有效的JSON写入指定输出路径：
json
{
  "project": "<project name>",
  "tasks": [
    {
      "id": "T001",
      "title": "Short task title",
      "description": "Detailed description of what to implement",
      "dependencies": ["T000"],
      "files": ["src/path/to/file.ts"],
      "acceptance_criteria": "Specific, verifiable criteria",
      "verification_steps": ["cargo build", "bun test"],
      "context_files": ["specs/ARCHITECTURE.md"],
      "estimated_complexity": "low|medium|high",
      "implementation_details": "Markdown with ### headers"
    }
  ]
}
  • 顺序ID：T001、T002……
  • 依赖项必须引用列表中的有效任务ID
  • 提取文档中提到的所有任务——请勿跳过或合并

Task Sizing

任务大小

Each task should represent 1-3 hours of human developer work and stay under 500 LOC unless the changes are boilerplate or generated code. If a task exceeds this, split it.
每个任务应对应1-3小时的人类开发者工作量，代码量不超过500行（除非是样板代码或生成代码）。如果任务超出此范围，请拆分任务。

Field Guide

字段指南

dependencies

dependencies

  • Organize for maximum parallelism — only add a dependency when a task literally cannot be worked on, or its acceptance criteria cannot be verified, until the dependency completes
  • Avoid unnecessary serial chains
  • 以最大并行度为目标组织任务——仅当某任务确实无法开展，或其验收标准必须在依赖任务完成后才能验证时，才添加依赖
  • 避免不必要的串行链

files

files

Files this task will directly add, modify, or delete.
此任务将直接添加、修改或删除的文件。

context_files

context_files

Other codebase files the agent should read before starting. Prefer inlining relevant architecture content in 
implementation_details
rather than listing the architecture doc as a context file — workers see only their task.
Agent开始工作前应阅读的其他代码库文件。优先将相关架构内容内联到
implementation_details
中，而非将架构文档列为上下文文件——Worker只能看到自己的任务。

acceptance_criteria

acceptance_criteria

The most important field for verification:
  • Enumerate all cases that need automated tests, including edge cases not mentioned in the architecture docs
  • If automated tests aren't possible, describe steps an agent can perform to verify the work
  • Be specific about what behaviour must be proven
  • Include specific test fixtures and validation cases
这是验证环节最重要的字段：
  • 列举所有需要自动化测试的场景，包括架构文档中未提及的边缘情况
  • 如果无法进行自动化测试，请描述Agent可执行的验证步骤
  • 明确说明必须验证的行为
  • 包含具体的测试夹具和验证用例

verification_steps

verification_steps

Concrete commands to run: 
bun test
, 
cargo build
, 
bun run typecheck
, etc.
可执行的具体命令：
bun test
、
cargo build
、
bun run typecheck
等。

implementation_details

implementation_details

This is the most valuable field. Write as if briefing a senior developer who has never seen the codebase:
  • Inline specific sections, patterns, and code examples from the architecture doc(s)
  • Include: function signatures, struct/type definitions, trait impls, API shapes
  • Include: integration points — existing modules/functions this code must connect to
  • Include: edge cases, error handling requirements, known gotchas
  • Include: example code snippets showing expected patterns when the docs provide them
  • Format with markdown headers: 
    ### Pattern
    , 
    ### Integration Points
    , 
    ### Edge Cases
  • Self-contained — workers see ONLY their task, not the full architecture
Scale detail to complexity:
ComplexityWord count
Low~50-100
Medium~100-200
High~200-400
这是最有价值的字段。撰写时假设面向从未接触过该代码库的资深开发者：
  • 将架构文档中的特定章节、模式和代码示例内联进来
  • 包含：函数签名、结构体/类型定义、trait实现、API形态
  • 包含：集成点——此代码必须连接的现有模块/函数
  • 包含：边缘情况、错误处理要求、已知陷阱
  • 包含：文档提供的预期模式示例代码片段
  • 使用Markdown标题格式化：
    ### Pattern
    、
    ### Integration Points
    、
    ### Edge Cases
  • 独立完整——Worker只能看到自己的任务，无法访问完整架构文档
根据复杂度调整细节程度：
复杂度字数
Low~50-100
Medium~100-200
High~200-400

Validation

验证

CRITICAL: After writing the output file, read it back and validate it parses as valid JSON matching the schema. If it doesn't parse, fix and re-write. Do not finish until the file contains valid JSON.
关键注意事项：写入输出文件后，需重新读取并验证其是否为符合Schema的有效JSON。如果无法解析，请修复后重新写入。在文件包含有效JSON前，请勿结束操作。