code-task-generator

代码任务生成器

概述

根据粗略描述或 PDD 实施计划生成结构化代码任务文件。自动检测输入类型，并创建格式正确的 .code-task.md 文件。对于 PDD 计划，每次处理一个步骤，以便在步骤之间进行学习。

重要说明

以下规则适用于所有步骤：

• 需要用户批准： 呈现任务拆分计划，并在生成任何文件之前获得用户明确批准。
• 测试已整合： 在每项任务的验收标准中包含单元测试要求。绝不创建单独的“添加测试”任务。
• PDD 模式引用： 始终将设计文档路径列为必读内容。只有与特定任务直接相关时，才包含研究文档。

参数

• input（必填）：任务描述、文件路径或 PDD 计划路径
• step_number（可选，仅限 PDD）：要处理的特定步骤。若省略，则自动确定下一个未完成的步骤。
• output_dir（可选，默认值：specs/{task_name}/tasks/）：代码任务文件的输出目录
• task_name（可选，仅限描述模式）：覆盖自动生成的任务名称

约束：

• 必须在单个提示中一次性询问所有必填参数
• 必须支持以下输入：直接文本、文件路径、目录路径（查找 plan.md）或 URL

步骤

1. 检测输入模式

检查输入是否为符合 PDD 计划结构的文件（检查清单 + 编号步骤）。将模式设置为“pdd”或“description”，并告知用户。

2. 分析输入

• PDD 模式： 解析计划，提取步骤和检查清单状态，并确定目标步骤（根据 step_number 或第一个未完成的步骤）
• 描述模式： 确定核心功能、技术要求、复杂程度（低/中/高）和技术领域

3. 梳理需求

• PDD 模式： 提取目标步骤的标题、描述、演示要求、约束，以及与前序步骤的集成说明。找出相关研究文档。
• 描述模式： 确定功能需求，并推断技术约束和依赖项。

两种模式均需：使用 Given-When-Then 格式制定可衡量的验收标准，并准备任务拆分计划。

4. 规划任务

向用户呈现拟议的任务拆分：

• 每项任务用一行概述
• 拟议的执行顺序和依赖关系
• 未获得用户明确批准前，绝不能生成文件

5. 生成任务

按照下方的代码任务格式创建文件。

PDD 模式具体要求：

• 创建 step{NN}/ 文件夹（编号补零：step01、step02、step10）
• 按顺序为文件命名：task-01-{title}.code-task.md、task-02-{title}.code-task.md
• 按功能组件拆分，而非按测试阶段拆分

所有任务：

• 必须严格采用下方的代码任务格式结构
• 必须包含 YAML frontmatter，字段为 status: pending、created: YYYY-MM-DD、started: null、completed: null
• 必须使用 kebab-case 名称，并以 .code-task.md 为扩展名
• 必须编写涵盖主要功能和单元测试的验收标准

6. 报告结果

列出生成的文件及其路径。对于 PDD 模式，包含该步骤的演示要求。建议按顺序对任务运行 code-assist，或使用 Ralph 进行自主实施。

7. 提供 Ralph 集成选项

询问：“你希望我设置 Ralph 来自主实施这些任务吗？”

如果用户同意，则创建一份简洁的 PROMPT.md，其中包含目标、规格目录引用、执行顺序和验收标准。建议使用合适的命令：

• 完整流程：ralph run --config presets/pdd-to-code-assist.yml
• 简化流程：ralph run -c ralph.yml -H builtin:code-assist

代码任务格式规范

每个代码任务文件都必须遵循以下结构：

---
status: pending
created: YYYY-MM-DD
started: null
completed: null
---
# Task: [Task Name]

## Description
[What needs to be implemented and why]

## Background
[Context needed to understand the task]

## 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.

## Technical Requirements
1. [First requirement]
2. [Second requirement]

## Dependencies
- [Dependency with details]

## Implementation Approach
1. [Implementation step or approach]

## Acceptance Criteria

1. **[Criterion Name]**
   - Given [precondition]
   - When [action]
   - Then [expected result]

## Metadata
- **Complexity**: [Low/Medium/High]
- **Labels**: [Comma-separated labels]
- **Required Skills**: [Skills needed]

示例

描述模式输入： "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 的引用、验收标准和演示要求。

故障排除

描述含糊： 提出澄清问题，建议常见模式，创建一个基础任务并提供进一步完善。

描述复杂： 建议拆分为较小的任务，先聚焦核心功能，并提供创建相关任务。

缺少技术细节： 做出合理假设，提供多种方案，并指出需要用户决定的部分。

未找到计划文件： 检查路径是否为目录（在其中查找 plan.md），并建议常见的 PDD 计划位置。

计划格式无效： 找出缺少的部分，建议运行 PDD 以生成合适的计划，并提取现有内容。

所有步骤均已完成： 告知用户，询问是否仍需执行特定步骤，并建议检查是否有新步骤。