planning-implementation

规划实现

概述

从架构文档中提取每一项实现任务，并整理为结构化的 JSON 任务图。输出是一个 DAG，任务的规模适合自主 Agent 工作人员处理——每项任务都独立完整、按依赖关系排序，且无需访问完整架构文档即可验证。

开始规划前

1. 获取现有状态：运行 dark-factory list --job $JOB --status pending --include-content，查看任务图中已有的待处理任务
2. 探索代码库：派遣后台探索 Agent，检查与文档各章节相关的文件——在编写任务前，先了解现有模式、类型和集成点
3. 研究依赖项：使用网络搜索，研究架构中提及但你不熟悉的库、框架或工具

输出架构

将有效的 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
• 提取文档中提及的每一项任务——不要跳过或合并

任务规模

每项任务应相当于 1-3 小时的人类开发工作，且代码量应少于 500 LOC，除非修改属于样板代码或生成代码。若任务超出此规模，请拆分。

字段指南

dependencies

• 以实现最大并行度为目标进行组织——只有当某项任务确实无法开始，或其验收标准无法验证，直到依赖项完成时，才添加依赖项
• 避免不必要的串行链

files

此任务将直接新增、修改或删除的文件。

context_files

Agent 开始前应阅读的其他代码库文件。优先将相关架构内容内联到 implementation_details，而不是将架构文档列为上下文文件——工作者只能看到自己的任务。

acceptance_criteria

最重要的验证字段：

• 列出所有需要自动化测试的情况，包括架构文档未提及的边界情况
• 如果无法进行自动化测试，请描述 Agent 可执行的验证步骤
• 明确指出必须证明哪些行为
• 包含具体的测试样例和验证用例

verification_steps

需要运行的具体命令：bun test、cargo build、bun run typecheck 等。

implementation_details

这是最有价值的字段。 请像向从未接触过代码库的资深开发者做简报一样撰写：

• 内联架构文档中的具体章节、模式和代码示例
• 包含：函数签名、结构体／类型定义、trait 实现、API 形式
• 包含：集成点——此代码必须连接到的现有模块／函数
• 包含：边界情况、错误处理要求、已知注意事项
• 包含：文档提供预期模式时，附上展示该模式的示例代码片段
• 使用 Markdown 标题进行格式编排：### Pattern、### Integration Points、### Edge Cases
• 自包含——工作者只能看到自己的任务，看不到完整架构

按复杂度调整详细程度：

复杂度	字数
低	~50-100
中	~100-200
高	~200-400

验证

至关重要： 写入输出文件后，重新读取并验证其能否解析为符合架构的有效 JSON。如果无法解析，请修复并重新写入。文件内容为有效 JSON 之前，不要结束。