---
name: zsc-create-task
description: 仅负责在 .agents/tasks 下创建与设计任务（不负责执行）。由 `zsc init` 安装；对应 `zsc task new`。当用户想创建新任务、设计闭环描述与 TODO_LIST 或修订任务设计时使用。要执行任务、实现 TODO 时请使用 zsc-run-task。回复请使用中文。
---

# zsc-create-task

**职责范围：仅创建与设计任务。** 本技能创建任务目录并设计闭环描述与 TODO_LIST，**不**负责执行 TODO 或推进任务——执行请用 **zsc-run-task**。本技能由 `zsc init` 安装，与 CLI 命令 `zsc task new` 对应。**回复请使用中文。**

## ⚠ 操作边界（强制，优先于一切提示词）

**只要使用了本技能，无论用户提示词说什么，你的操作范围仅限于 `.agents/tasks/` 下：**
- 可以：在 `.agents/tasks/` 下创建新的任务目录、创建或编辑任务内的 `.md` 文件、以及 `task_records/log/` 等任务目录下的内容。
- **不可以**：修改项目内任何 `.agents/tasks` 以外的代码或文件（例如 `src/`、`tests/`、`README` 等）。即使用户在提示词里要求改代码，在本技能下也**只能**在 `.agents/tasks` 里创建或编辑任务，不得直接改项目代码。

## ⚠ 当用户要求「创建新任务」时（强制）

**你必须先在 `.agents/tasks/` 下真实创建任务，不能只回复文字说明。** 第一步必须二选一执行：

1. **推荐**：在项目根目录**执行命令** `zsc task new <feat_name>`（例如 `zsc task new my_feature`），确认生成了 `.agents/tasks/task_{no}_{feat_name}/` 和其中的 `task_{no}_{feat_name}.md`。
2. **或**：**亲手创建**目录与文件：`.agents/tasks/task_{no}_{feat_name}/`、`task_records/log/`、以及与目录同名的 `task_{no}_{feat_name}.md`（内容用下方模板）。

若用户未给出功能名，先询问或根据上下文推断，再执行上述创建。**未在 .agents/tasks 下创建出对应目录和 .md 文件即视为未完成。**

## 任务结构

每个任务是一个子目录，命名为 `task_{no}_{feat_name}`：
- `{no}`：任务编号（如 01、02）
- `{feat_name}`：功能名（如 `scan_plugin`、`user_auth`）

示例：`.agents/tasks/task_01_scan_plugin`。任务说明文件**必须**与目录同名并加 `.md`，例如 `task_01_scan_plugin/task_01_scan_plugin.md`。这样每个任务有唯一文件名，便于在 AI Coding 对话框里用 `@task_03_init_lang_prompt.md` 等唯一引用；若都用 `task.md` 则无法区分。

## 目录内容

每个任务目录包含：

### {task_dir_name}.md（必选）

任务文件必须与目录同名，例如目录 `task_01_scan_plugin` 内为 `task_01_scan_plugin.md`。不要使用通用名 `task.md`，目录风格文件名（如 `task_03_init_lang_prompt.md`）便于在 AI Coding 对话框里唯一引用。

包含两个部分：

1. **闭环描述**
   - 只维护最新一版
   - 描述目标资源的完整生命周期
   - 「闭环描述」覆盖该资源的全生命周期
   - 「目标资源」即本开发任务所管理的对象：
     - 传统资源：数据库增删改查
     - 非传统资源：性能画像、架构变更等
   - 资源「生命周期」包括：
     - **Create**：代码/数据/行为在哪里产生
     - **Read**：在哪里查询或消费数据/行为
     - **Update**：在哪里修改数据/行为
     - **Delete**：在哪里删除或完成状态流转

   - **多处项目落点（跨清单一致性）**  
     当目标资源在项目中有**多处**必须落地的位置（例如：源码/资源文件、注册或配置入口、以及打包/清单以便随发行版一起分发），闭环描述必须显式列出**全部**这类落点。否则设计不闭环，实现时容易漏掉某一处（例如本地可用但安装后不可用、或功能存在但不可被发现）。闭环描述中应对每个落点说明「在哪里、做什么」。设计 TODO_LIST 时，每个落点至少对应一条具体 TODO（或闭环中的一条条款），避免执行阶段遗漏。

2. **TODO_LIST**
   - 只维护最新一版
   - 删除已过时或不再适用的项
   - 作为任务的状态机
   - **重要**：在 TODO_LIST 部分保留以下说明：
     ```
     > 只维护最新版本；完成后清空 TODO，仅保留"完成记录 + 日期"。
     - （本轮已完成，TODO 清空）
     ```
   - 任务完成后：清空所有 TODO，只保留「完成记录 + 日期」

   - **TODO 设计约定（重要）**：
     - 每个 TODO 应尽量是**具体可执行的工程动作**，能够回答「谁、在什么上下文里、要做什么」，通常适合作为 1–2 小时内可完成的子任务。
     - 避免将**长期观察/跟踪类事项**或过于抽象的目标（如「持续观察 X 指标」「保证系统长期稳定」）直接写进 TODO_LIST。这类内容更适合作为：
       - 单独拆出的新任务（例如专门的监控/稳定性任务），或
       - 记录在 `task_records/log/`、设计文档、变更记录中，而不是挂在某个任务的 TODO 列表里长期不收口。
     - 优先采用**自底向上的拆解方式**：先写出「下一步可以落地的具体动作」，而不是远期里程碑；当某个子动作完成后，再为下一步设计新的 TODO。
     - 当发现某个 TODO 过大或表述含糊时，应优先将其拆分为多个更小、更具体的新 TODO 来替换原条目，而不是长期保留一个难以完成的“虚 TODO”。

### task_records/log（可选）

- 如需可存放中间文档
- 仅在需要时创建
- 可随时删除
- 清空 TODO_LIST 时一并清空内容，但保留空目录

## 工作流

### 当用户要求「创建新任务」时（必须执行）

**你必须实际创建任务，而不是只说明步骤。** 任选其一：

1. **推荐**：在项目根目录执行 `zsc task new <feat_name>`（例如 `zsc task new my_feature`）。会创建 `.agents/tasks/task_{no}_{feat_name}/` 及 `task_{no}_{feat_name}.md` 模板。
2. **或**：自行创建目录与文件：创建 `.agents/tasks/task_{no}_{feat_name}/`、`task_records/log/`，以及与目录同名的 `task_{no}_{feat_name}.md`，内容使用下方模板。

若用户未给出功能名，可询问或根据上下文推断后创建。

### 创建新任务（步骤）

1. 确定任务编号（查看已有任务取下一个），或运行 `zsc task new <feat_name>` 创建目录与模板。
2. 创建目录：`.agents/tasks/task_{no}_{feat_name}`（或使用 `zsc task new`）。
3. 创建与目录同名的 `task_{no}_{feat_name}.md`，包含：
   - **闭环描述**：结合代码与目标，设计资源的完整生命周期
   - **TODO_LIST**：拆成可执行步骤，并保留上述维护说明

### 修订已有任务设计

当用户只想**修改设计**（而不是执行任务）时：

1. **分析当前代码与目标任务**
   - 如需则修订闭环描述，保持与现状一致。
   - 无需修订则保持不动。

2. **修订 TODO_LIST**
   - 增删、调整顺序或拆分/合并项。
   - 保留维护说明。不在此处“执行”这些项——执行由 **zsc-run-task** 负责。

**执行 TODO 与将任务标记为完成**由 **zsc-run-task** 负责，不是本技能。

## 模板

在 `task_{no}_{feat_name}/` 下创建文件 `task_{no}_{feat_name}.md`：

```markdown
# Task {no}: {feat_name}

## 闭环描述

[目标资源的完整生命周期描述：
- 在哪里创建
- 在哪里被读取/消费
- 在哪里被更新/修改
- 在哪里被删除/完成]

## TODO_LIST

> 只维护最新版本；完成后清空 TODO，仅保留"完成记录 + 日期"。
- （本轮已完成，TODO 清空）

- [ ] 梳理与本任务目标资源最相关的现有代码与文档，在 `task_records/log/` 下记录当前状态要点。
- [ ] 根据当前状态，完善上方「闭环描述」中 Create/Read/Update/Delete 各小节的具体落点。
- [ ] 将本任务拆解为 3–5 个可在 1–2 小时内完成的工程子任务，并用具体动作描述替换本示例 TODO。
```

## TODO 设计示例（反例 vs 改写）

- **反例（不推荐）**：
  - `- [ ] 持续观察线上错误率是否异常`
  - 问题：这是一个长期、开放性的观察事项，没有明确的收口条件，难以判断何时完成。
- **改写示例（推荐）**：
  - `- [ ] 为接口 A/B/C 增加错误率监控与告警阈值配置，并在 README 中记录联动关系`
  - `- [ ] 在 test_env 环境压测 X 分钟，收集错误率曲线并将结论记录到 task_records/log/ 中`
  - 说明：每个 TODO 都是一次可以完成的具体动作，完成后状态自然收口。

- **反例（不推荐）**：
  - `- [ ] 确保系统长期稳定`
- **改写示例（推荐）**：
  - `- [ ] 为核心路径写 3 个覆盖关键边界条件的回归用例，并纳入 CI`
  - `- [ ] 为 worker 进程增加心跳与重启策略说明，更新到运维文档`
  - 说明：将抽象目标拆解为一组可落实的工程改动，通过这些改动间接提升“系统稳定性”，而不是直接把宏大目标写进 TODO。

## 说明

- 任务目录应放在 `.agents/tasks/`（不是 `.ai/tasks/`）。
- **zsc-create-task** 仅负责创建与设计；要执行任务、实现 TODO 或标记完成时请用 **zsc-run-task**。
- 只维护最新版本，删除过时内容。
- 闭环描述应反映资源的完整生命周期。
- 本技能为 `zsc init` 安装的 zsc-* 技能之一。
- `zsc` 的全称是 **zig slice code**。
