FIT Framework 的 /create-task 命令：如何用自然语言一键生成规范化开发任务

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务

导读：本文围绕 FIT Framework 仓库中.claude/commands/create-task.md这一 Slash Command 实现展开，讲解在 Claude Code 环境下如何用一句自然语言描述，自动完成"任务解析 → 任务文件创建 → 需求分析 → 分析文档输出"的完整流程。读完本文，你将掌握/create-task命令的完整执行规范、task.md与analysis.md的文件格式与元数据约定、任务类型与工作流的推断映射规则，以及它与/analyze-issue、/plan-task等命令如何串联成一条完整的 AI 开发流水线。

一、命令定位：把"待办事项"变成"规范任务"

在 FIT Framework 的多 AI 协作体系中（详见 .ai-agents/README.md），Claude Code 通过.claude/commands/目录下的 Markdown 文件定义了一组 Slash Commands。/create-task是其中负责任务创建与需求分析的入口命令，其定位是：

根据用户的自然语言描述，创建任务并执行需求分析，输出分析文档。适用于没有 GitHub Issue 的场景，用户可以直接用自然语言描述想做的事情。

与直觉相反，/create-task的核心纪律是：用户描述的内容是"待办事项"，不是"立即执行的指令"。该命令只负责"解析 → 建文件 → 分析 → 输出文档 → 告知下一步"，严禁编写、修改任何业务代码或配置文件，也严禁直接实现用户描述的功能。

行为边界（命令内置的 CRITICAL 约束）

命令定义文件中明确写入了三条不可逾越的行为边界：

• 唯一产出：本命令的唯一产出是task.md和analysis.md两个文件；
• 禁止事项：禁止编写/修改/创建任何业务代码或配置文件、禁止直接实现用户描述的功能、禁止跳过工作流直接进入 plan/implement 阶段；
• 状态更新：执行命令后必须立即更新任务状态（对应 .claude/project-rules.md 中的"规则 6：任务状态管理规范"）。

这种"分析阶段不写代码"的约束，与 feature-development.yaml 中"分析和设计阶段不要急于实现，充分思考"的最佳实践一脉相承，保证了 AI 在需求未澄清、方案未设计之前不会产生任何代码副作用。

二、命令文件结构：YAML Front Matter 是命令的"注册信息"

.claude/commands/create-task.md文件头部有一段 YAML Front Matter，它定义了命令在 Claude Code 中的注册元数据：

--- name: "create-task" description: "根据自然语言描述创建任务并生成需求分析文档" usage: "/create-task <description>" ---

• name：命令名称，即斜杠触发词；
• description：命令用途说明，帮助 Claude Code 在语义识别时理解该命令（对应 .claude/project-rules.md 中"规则 5：任务语义识别"）；
• usage：参数用法示例，声明该命令接受一个<description>参数。

Front Matter 之后是命令的完整行为规范正文，包括功能说明、行为边界、执行流程、检查清单、参数说明、使用示例、注意事项、相关命令与错误处理等章节。任何在.claude/commands/目录下新增的.md文件都会自动成为可用的 Slash Command（参见 .claude/README.md 的故障排查一节）。

三、六步执行流程详解

/create-task的执行流程被严格定义为六个步骤，每一步都有明确的输入、动作与输出。

第 1 步：解析用户描述

从用户的自然语言描述中提取四类结构化信息：

如果描述不够清晰，命令要求先向用户确认关键信息再继续，而不是盲目猜测。例如缺少具体模块名、预期行为不明确等情况，都属于必须先确认的场景。

第 2 步：创建任务目录和文件

• 创建任务目录：.ai-workspace/active/TASK-{yyyyMMdd-HHmmss}/
• 使用 .ai-agents/templates/task.md 模板创建任务文件：task.md

目录命名规则（强制）：TASK-{yyyyMMdd-HHmmss}，必须包含TASK-前缀，示例：TASK-20260213-143022。任务 ID（{task-id}）即为目录名，后续所有命令（如/plan-task TASK-xxx）都通过该 ID 定位任务。

task.md的 YAML Front Matter 元数据模板如下：

id: TASK-{yyyyMMdd-HHmmss} type: feature|bugfix|refactor|docs|chore workflow: feature-development|bug-fix|refactoring status: active created_at: {yyyy-MM-dd HH:mm:ss} updated_at: {yyyy-MM-dd HH:mm:ss} created_by: human current_step: requirement-analysis assigned_to: claude

这里有一个值得注意的约定：created_by设为human，因为任务来源于用户的自然语言描述（而非 GitHub Issue 或安全告警），这是它与/analyze-issue、/analyze-security等命令的重要区别之一。

完整的task.md模板还包含任务描述、当前状态、上下文文件清单、相关资源、工作流进度、当前任务（需要做什么 / 能力要求 / 推荐 AI / 任务清单 / 输入输出文件）、交接信息、注意事项与状态更新检查清单等章节，模板正文见 .ai-agents/templates/task.md。

第 3 步：执行需求分析

按照 feature-development.yaml 中的requirement-analysis步骤执行。该步骤的能力要求为code comprehension、system analysis、architecture understanding，推荐 AI 为 claude（擅长系统性分析和架构理解）与 gemini（超大上下文窗口）。

必须完成的任务清单（仅分析，不编写任何业务代码）：

• 理解用户描述的需求
• 搜索相关代码文件（使用 Glob/Grep 工具，只读不改）
• 分析代码结构和影响范围
• 识别潜在的技术风险和依赖
• 评估工作量和复杂度

第 4 步：输出分析文档

创建.ai-workspace/active/{task-id}/analysis.md，必须包含以下章节：

# 需求分析报告 ## 需求来源 **来源类型**: 用户自然语言描述 **原始描述**: > {用户的原始描述} ## 需求理解 {用自己的话重新描述需求，确保理解正确} ## 相关文件列表 - `{file-path}:{line-number}` - {说明} ## 影响范围评估 **直接影响**： - {影响的模块和文件} **间接影响**： - {可能影响的其他部分} ## 技术风险 - {风险描述和应对思路} ## 依赖关系 - {需要的依赖和其他模块的配合} ## 工作量和复杂度评估 - 复杂度：{高/中/低} - 风险等级：{高/中/低}

这份文档正是后续technical-design（技术方案设计）步骤的输入，feature-development.yaml 要求plan.md以analysis.md为前提展开方案决策、约束条件分析与备选方案对比。

第 5 步：更新任务状态

更新.ai-workspace/active/{task-id}/task.md：

• current_step：requirement-analysis
• assigned_to：claude
• updated_at：当前时间
• 标记analysis.md为已完成
• 在"工作流进度"中标记requirement-analysis为完成 ✅

这与 .claude/project-rules.md 的"规则 6"完全对应：/create-task（及其同类命令）执行后必须更新current_step、updated_at、assigned_to字段，否则会导致任务状态追踪失败。任务模板中也内置了状态更新检查清单，违反该清单被视为不可接受的行为。

第 6 步：告知用户

以固定格式向用户汇报任务创建与分析结果：

✅ 任务创建并分析完成 **任务信息**： - 任务ID: {task-id} - 任务标题: {title} - 任务类型: {type} - 工作流: {workflow} **输出文件**： - 任务文件: .ai-workspace/active/{task-id}/task.md - 分析文档: .ai-workspace/active/{task-id}/analysis.md **下一步**： 审查需求分析后，使用以下命令设计技术方案： /plan-task {task-id}

四、完成检查清单与 STOP 规则

命令末尾定义了执行完成后的自检清单，逐项确认：

• 已创建任务文件.ai-workspace/active/{task-id}/task.md
• 已创建分析文档.ai-workspace/active/{task-id}/analysis.md
• 已更新task.md中的current_step为requirement-analysis
• 已更新task.md中的updated_at为当前时间
• 已更新task.md中的assigned_to为你的名字
• 已在"工作流进度"中标记requirement-analysis为完成 ✅
• 已告知用户下一步操作（/plan-task）
• 未修改任何业务代码或配置文件（除task.md和analysis.md外）

关键约束（STOP 规则）：完成上述检查清单后，命令立即停止，不继续执行 plan、implement 或任何后续步骤，等待用户审查分析文档后主动调用/plan-task推进工作流。这确保了每一步都经过人工检查点，符合协作指南中"人类始终拥有最终决策权"的原则（见 .ai-agents/QUICKSTART.md 与 .ai-agents/README.md）。

五、任务类型推断与工作流映射规则

命令内置了从自然语言关键词到任务类型的推断规则：

任务类型进一步映射到工作流：

六、参数说明与使用示例

参数：<description>—— 自然语言的任务描述（必需）。

使用示例（来自命令定义文件，示例中的模块均存在于本仓库）：

# 添加新功能 /create-task 给 fit-runtime 添加优雅停机功能，在收到 SIGTERM 信号时等待当前请求处理完成后再关闭 # 修复 Bug /create-task fit-broker 在高并发场景下偶尔出现连接池耗尽的问题，需要排查并修复 # 重构代码 /create-task 将 fit-conf 模块的配置加载逻辑从同步改为异步，提升启动性能 # 改进文档 /create-task 补充 fit-aop 模块的 Javadoc，特别是公共 API 的参数和返回值说明

示例中的fit-runtime（fit-runtime）、fit-broker（fit-broker）、fit-conf（fit-conf）、fit-aop（fit-aop）均为 FIT Framework 仓库中真实存在的 Java 模块。

七、与 analyze-issue 的区别：两条任务创建入口

任务创建存在两条并行入口，命令定义文件明确区分了二者的差异：

• /analyze-issue <number>：从 GitHub Issue 获取信息，关联 Issue 编号，适用于已有 Issue 的场景（其实现见 analyze-issue.md，通过gh issue view <issue-number> --json number,title,body,labels拉取 Issue 信息）；
• /create-task <description>：从用户自然语言描述创建，相关 Issue 标记为"无"，适用于没有 GitHub Issue 的场景。

两条入口殊途同归：都产出.ai-workspace/active/{task-id}/task.md与analysis.md，都遵循 feature-development.yaml 的requirement-analysis步骤，都要求执行后立即更新任务状态。区别仅在于需求来源与 Issue 关联。

八、错误处理与注意事项

错误处理

注意事项（命令内置的五条约定）

1. 描述清晰度：描述模糊或缺少关键信息（如缺少具体模块名、预期行为不明确）时，先向用户确认；
2. 任务类型推断：按关键词规则推断类型（见第五节）；
3. 工作流映射：按类型映射工作流（见第五节）；
4. 与 analyze-issue 的区别：见第七节；
5. 人工检查点：分析完成后建议人工审查，确认需求理解正确后再进入下一步。

九、命令上下游衔接：完整的任务生命周期

/create-task不是孤立命令，它处于 FIT Framework AI 协作任务生命周期的最前端（完整的命令与工作流速查见 .claude/QUICK-REFERENCE.md）：

/create-task <description> # 本文主角：创建任务 + 需求分析 ↓ /plan-task <task-id> # 设计技术方案（output: plan.md，必须人工审查） ↓ /implement-task <task-id> # 实施任务（output: implementation.md） ↓ /review-task <task-id> # 审查代码（output: review.md） ↓ /complete-task <task-id> # 完成任务（归档到 completed）

辅助命令包括/check-task <task-id>（查看任务状态，见 check-task.md，支持在 active/completed/blocked 多目录中查找任务）与/sync-issue <task-id>（同步进度到 GitHub Issue）。

在 feature-development.yaml 定义的标准功能开发流程中，requirement-analysis是六个步骤（需求分析 → 技术方案设计 → 代码实现 → 代码审查 → 问题修复 → 最终确认与提交）的第一步；/create-task产出的analysis.md是整个流程的上下文基石——任何 AI 都可以通过读取.ai-workspace/active/{task-id}/下的文档接手任务，这正是"文档即上下文、上下文即协作"的多 AI 协作机制（详见 .ai-agents/README.md）。

十、小结：从一句话到一份可交接的任务档案

/create-task的价值在于把"用户的一句自然语言"规范化为两份可追踪、可交接、可审查的文档资产：

• task.md：任务的身份档案（ID、类型、工作流、状态、进度、上下文清单），是整个任务生命周期状态追踪的唯一事实来源；
• analysis.md：需求分析报告（来源、理解、相关文件、影响范围、技术风险、依赖、工作量评估），是后续方案设计与代码实现的输入前提。

配合.ai-workspace/（临时工作区，已被 git ignore，见 .ai-workspace/README.md）的目录约定，以及.claude/project-rules.md的任务状态管理规则，该命令与其余 Slash Commands 一起，在 FIT Framework 仓库中构成了一个"分析有产出、步骤有检查、状态有追踪、交接有文档"的 AI 辅助开发闭环。若要在你自己的项目中复刻这套机制，只需在.claude/commands/下按本文所述的 Front Matter 与章节结构创建命令文件，并配套.ai-agents/templates/task.md与工作流 YAML 定义即可。

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务