Back to Details

code-task-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Task Generator

代码任务生成器

Overview

概述

Generate structured code task files from rough descriptions or PDD implementation plans. Auto-detects input type and creates properly formatted 
.code-task.md
files. For PDD plans, processes one step at a time to allow learning between steps.
根据粗略的任务描述或PDD实施计划生成结构化的代码任务文件。自动检测输入类型并创建格式规范的.code-task.md文件。在PDD计划模式下，会分步处理每个环节，以便在步骤之间逐步学习和推进。

Important Notes

重要说明

These rules apply across ALL steps:
  • User approval required: Present the task breakdown plan and get explicit approval before generating any files.
  • Tests are integrated: Include unit test requirements in each task's acceptance criteria. Never create separate "add tests" tasks.
  • PDD mode references: Always include the design document path as required reading. Only include research docs if directly relevant to the specific task.
以下规则适用于所有步骤：
  • 需用户批准： 在生成任何文件之前，必须先提交任务分解计划并获得用户的明确批准。
  • 测试集成： 在每个任务的验收标准中包含单元测试要求。切勿创建单独的“添加测试”任务。
  • PDD模式参考： 必须包含设计文档路径作为必读内容。仅当研究文档与具体任务直接相关时才予以包含。

Parameters

参数

  • input (required): Task description, file path, or PDD plan path
  • step_number (optional, PDD only): Specific step to process. Auto-determines next uncompleted step if omitted.
  • output_dir (optional, default: 
    specs/{task_name}/tasks/
    ): Output directory for code task files
  • task_name (optional, description mode only): Override auto-generated task name
Constraints:
  • You MUST ask for all required parameters upfront in a single prompt
  • You MUST support input as: direct text, file path, directory path (looks for plan.md), or URL
  • input（必填）：任务描述、文件路径或PDD计划路径
  • step_number（可选，仅PDD模式）：要处理的特定步骤。如果省略，会自动确定下一个未完成的步骤。
  • output_dir（可选，默认值：
    specs/{task_name}/tasks/
    ）：代码任务文件的输出目录
  • task_name（可选，仅描述模式）：覆盖自动生成的任务名称
约束条件：
  • 必须在单次提示中主动询问所有必填参数
  • 必须支持以下类型的输入：直接文本、文件路径、目录路径（会在其中查找plan.md）或URL

Steps

步骤

1. Detect Input Mode

1. 检测输入模式

Check if input is a file with PDD plan structure (checklist + numbered steps). Set mode to "pdd" or "description" and inform the user.
检查输入是否为带有PDD计划结构（清单+编号步骤）的文件。将模式设置为“pdd”或“description”并告知用户。

2. Analyze Input

2. 分析输入

  • PDD mode: Parse the plan, extract steps and checklist status, determine target step (from step_number or first uncompleted)
  • Description mode: Identify core functionality, technical requirements, complexity level (Low/Medium/High), and technology domain
  • PDD模式： 解析计划，提取步骤和清单状态，确定目标步骤（来自step_number参数或第一个未完成的步骤）
  • 描述模式： 识别核心功能、技术要求、复杂度等级（低/中/高）以及技术领域

3. Structure Requirements

3. 梳理需求

  • PDD mode: Extract the target step's title, description, demo requirements, constraints, and integration notes with previous steps. Identify relevant research documents.
  • Description mode: Identify functional requirements, infer technical constraints and dependencies.
For both modes: create measurable acceptance criteria in Given-When-Then format and prepare a task breakdown plan.
  • PDD模式： 提取目标步骤的标题、描述、演示要求、约束条件以及与之前步骤的集成说明。识别相关的研究文档。
  • 描述模式： 识别功能需求，推断技术约束和依赖关系。
对于两种模式：以Given-When-Then格式创建可衡量的验收标准，并准备任务分解计划。

4. Plan Tasks

4. 规划任务

Present the proposed breakdown to the user:
  • One-line summary per task
  • Proposed sequence and dependencies
  • You MUST NOT generate files until the user explicitly approves
向用户提交拟议的任务分解方案：
  • 每个任务的单行摘要
  • 拟议的执行顺序和依赖关系
  • 在用户明确批准之前，不得生成任何文件

5. Generate Tasks

5. 生成任务

Create files following the Code Task Format below.
PDD mode specifics:
  • Create 
    step{NN}/
    folder (zero-padded: step01, step02, step10)
  • Name files sequentially: 
    task-01-{title}.code-task.md
    , 
    task-02-{title}.code-task.md
  • Break down by functional components, not testing phases
All tasks:
  • You MUST use the exact Code Task Format structure below
  • You MUST include YAML frontmatter with 
    status: pending
    , 
    created: YYYY-MM-DD
    , 
    started: null
    , 
    completed: null
  • You MUST use kebab-case names with 
    .code-task.md
    extension
  • You MUST include acceptance criteria covering main functionality and unit tests
按照以下代码任务格式创建文件。
PDD模式特定要求：
  • 创建
    step{NN}/
    文件夹（补零格式：step01、step02、step10）
  • 按顺序命名文件：
    task-01-{title}.code-task.md
    、
    task-02-{title}.code-task.md
  • 按功能组件分解任务，而非测试阶段
所有任务通用要求：
  • 必须严格遵循下文的代码任务格式结构
  • 必须包含YAML前置元数据，内容为
    status: pending
    、
    created: YYYY-MM-DD
    、
    started: null
    、
    completed: null
  • 必须使用短横线命名法（kebab-case），文件扩展名为
    .code-task.md
  • 必须包含覆盖主要功能和单元测试的验收标准

6. Report Results

6. 结果报告

List generated files with paths. For PDD mode, include the step's demo requirements. Suggest running code-assist on tasks in sequence, or using Ralph for autonomous implementation.
列出生成的文件及其路径。在PDD模式下，需包含步骤的演示要求。建议按顺序对任务运行code-assist，或使用Ralph进行自主实现。

7. Offer Ralph Integration

7. 提供Ralph集成选项

Ask: "Would you like me to set up Ralph to implement these tasks autonomously?"
If yes, create a concise PROMPT.md with objective, spec directory reference, execution order, and acceptance criteria. Suggest the appropriate command:
  • Full pipeline: 
    ralph run --config presets/pdd-to-code-assist.yml
  • Simpler flow: 
    ralph run --config presets/spec-driven.yml
询问用户：“是否需要我设置Ralph来自主实现这些任务？”
如果用户同意，创建简洁的PROMPT.md文件，包含目标、规范目录参考、执行顺序和验收标准。建议使用相应的命令：
  • 完整流程：
    ralph run --config presets/pdd-to-code-assist.yml
  • 简化流程：
    ralph run --config presets/spec-driven.yml

Code Task Format Specification

代码任务格式规范

Each code task file MUST follow this structure:
markdown
---
status: pending
created: YYYY-MM-DD
started: null
completed: null
---
每个代码任务文件必须遵循以下结构：
markdown
---
status: pending
created: YYYY-MM-DD
started: null
completed: null
---

Task: [Task Name]

Task: [任务名称]

Description

Description

[What needs to be implemented and why]
[需要实现的内容及原因]

Background

Background

[Context needed to understand the task]
[理解任务所需的上下文信息]

Reference Documentation

Reference Documentation

Required:
  • Design: specs/{task_name}/design.md
Additional References (if relevant to this task):
  • [Specific research document or section]
Note: Read the design document before beginning implementation.
Required:
  • Design: specs/{task_name}/design.md
Additional References (if relevant to this task):
  • [特定研究文档或章节]
Note: Read the design document before beginning implementation.

Technical Requirements

Technical Requirements

  1. [First requirement]
  2. [Second requirement]
  1. [第一项要求]
  2. [第二项要求]

Dependencies

Dependencies

  • [Dependency with details]
  • [带有详细信息的依赖项]

Implementation Approach

Implementation Approach

  1. [Implementation step or approach]
  1. [实现步骤或方法]

Acceptance Criteria

Acceptance Criteria

  1. [Criterion Name]
    • Given [precondition]
    • When [action]
    • Then [expected result]
  1. [标准名称]
    • Given [前置条件]
    • When [操作行为]
    • Then [预期结果]

Metadata

Metadata

  • Complexity: [Low/Medium/High]
  • Labels: [Comma-separated labels]
  • Required Skills: [Skills needed]
undefined
  • Complexity: [Low/Medium/High]
  • Labels: [逗号分隔的标签]
  • Required Skills: [所需技能]
undefined

Examples

示例

Description mode input: 
"I need a function that validates email addresses and returns detailed error messages"
Description mode output: 
specs/email-validator/tasks/email-validator.code-task.md
— task with acceptance criteria for valid/invalid email handling, error messages, and unit tests.
PDD mode input: 
"specs/data-pipeline/plan.md"
PDD mode output: 
specs/data-pipeline/tasks/step02/
containing 
task-01-create-data-models.code-task.md
, 
task-02-implement-validation.code-task.md
, 
task-03-add-serialization.code-task.md
— each with design.md reference, acceptance criteria, and demo requirements.
描述模式输入： 
"I need a function that validates email addresses and returns detailed error messages"
描述模式输出： 
specs/email-validator/tasks/email-validator.code-task.md
—— 包含处理有效/无效邮箱、错误消息以及单元测试的验收标准的任务文件。
PDD模式输入： 
"specs/data-pipeline/plan.md"
PDD模式输出： 
specs/data-pipeline/tasks/step02/
目录下包含
task-01-create-data-models.code-task.md
、
task-02-implement-validation.code-task.md
、
task-03-add-serialization.code-task.md
—— 每个文件都包含design.md参考、验收标准和演示要求。

Troubleshooting

故障排除

Vague description: Ask clarifying questions, suggest common patterns, create a basic task and offer to refine.
Complex description: Suggest breaking into smaller tasks, focus on core functionality first, offer to create related tasks.
Missing technical details: Make reasonable assumptions, include multiple approaches, note areas needing user decisions.
Plan file not found: Check if path is a directory (look for plan.md within), suggest common PDD plan locations.
Invalid plan format: Identify missing sections, suggest running PDD to generate a proper plan, extract what's available.
All steps complete: Inform user, ask if they want a specific step anyway, suggest reviewing for new steps.
模糊描述： 提出澄清问题，建议常见模式，创建基础任务并提供优化选项。
复杂描述： 建议拆分为更小的任务，先聚焦核心功能，提供创建相关任务的选项。
缺失技术细节： 做出合理假设，提供多种实现方法，标注需要用户决策的部分。
未找到计划文件： 检查路径是否为目录（在其中查找plan.md），建议常见的PDD计划存放位置。
无效计划格式： 识别缺失的章节，建议运行PDD生成规范的计划，提取现有可用内容。
所有步骤已完成： 告知用户，询问是否仍需要处理特定步骤，建议复查以添加新步骤。",