an-task

name	an-task
description	根据输入的任务描述，先智能判断任务复杂度与风险，再选择 L0 直接处理、L1 快速修复、L2 标准开发或 L3 完整流程。适用于开发任务、bug 修复、代码重构、配置修改、文档更新、需求实现等。当用户想要：1) 开始一个开发任务 2) 提供了任务/票据/想法的原始描述 3) 执行 /an-task 命令 4) 提到"开发"、"实现"、"修复"、"添加"等关键词时触发此技能。触发后不要默认套完整流程；小改动可不创建 artifacts，直接实现、验证并总结。

AI Native 任务开发

将任务描述（票据、想法、问题描述）按最轻但足够安全的 AI Native 流程推进到代码实现。

核心原则：先分流，再执行

触发本技能后，第一步不是创建 artifact，也不是进入完整流程，而是根据 conventions/flow-policy.md 自主判断任务等级：

等级	使用方式	何时使用
L0 直接处理	不进入流程，不创建 artifacts；直接改、验证、总结	改字、改注释、明显一行修复、无行为风险的小配置
L1 快速修复	可不创建 artifacts；必要时只保留轻量记录	单模块、小范围、目标明确、有最小验证
L2 标准开发	创建 artifacts，从 raw-input + tech-spec 开始	明确的小功能、方案清楚、影响少量模块
L3 完整流程	创建 artifacts，按全阶段推进并确认	需求模糊、跨模块、架构/接口/数据/权限等高风险改动

执行要求：

1. 先用一句话告诉用户采用的等级和理由；默认由 AI 自主决策并推进，不把可由 AI 判断的流程等级、技术方案或验证命令交给用户选择。
2. 选择能覆盖风险的最轻流程。不要因为技能被触发就机械创建 artifacts 或跑完整阶段。
3. 若调查中发现风险升高，立即升级流程并说明原因。
4. 用户明确要求“快速处理”“直接改”时，可在不违反风险条件的前提下降级；用户明确要求“走完整流程”时按用户要求执行。
5. 只有需求目标不明确、验收标准无法自洽、涉及权限/安全/数据/部署等高风险边界、需要破坏性操作或外部授权时，才暂停向用户确认。

输入来源

用户可通过以下方式提供 raw-input：

• 直接输入文字描述
• 引用文件路径（如 artifacts/xxx/raw-input/task.md）
• 引用外部链接（issue、文档等）

查找已有任务

仅在用户提到"之前做过"、"上次"、"继续之前的"、"之前有个"等引用历史任务的意图时，才执行查找。否则直接创建新的任务产出目录。

1. 在 artifacts/ 中查找 — 用 Glob 匹配目录名中包含任务关键词的活跃产出目录（只看目录名，不读文件内容）
2. 未找到则查 artifacts/archive/ — 同样只匹配目录名

匹配到后向用户说明，询问：继续推进该任务，还是以此为参考创建新任务。用户确认后才读取该 artifact 的文件内容。未找到则正常创建新的任务产出目录。

注意：只做目录名匹配，不搜索文件内容，避免大量 artifacts 时消耗过多上下文。

判断流程范围

根据输入和初步代码调查判断工作流范围。优先套用 conventions/flow-policy.md，本节只保留快速判断口径：

信号	范围	行为
拼写、注释、明显一行 bug、无行为风险的小配置	L0 直接修复	不创建 artifacts，不进入阶段流程；直接改并验证
单模块、小范围、行为明确、有现成验证	L1 快速修复	可不创建 artifacts；直接实现，必要时补轻量记录
用户已有明确方案或接口约定	L2 标准开发	保存原始输入，从技术规范开始，再实现、验证、质量评价
需求模糊、新功能、跨模块、架构决策	L3 完整流程	raw-input → requirements → design → tech-spec → implementation → testing → deployment → 质量评价

判断后先告诉用户将采用哪个等级。L0/L1 可直接完成后总结；L2/L3 默认由 AI 展示阶段产出、决策依据和风险后继续推进；仅在触发暂停条件时等待用户确认。

L0 直接处理规则

满足 L0 时，不要为了“流程完整”创建任务目录。直接：

1. 定位文件
2. 做最小修改
3. 运行或说明最小验证
4. 最终总结改动和验证结果

示例：修正文案错别字、改 Markdown 链接、补一行注释、修明显 typo。

L1 快速修复规则

满足 L1 时，优先直接实现和验证。只有在需要留下上下文、用户要求可追踪、或修改虽小但后续可能继续扩展时，才创建轻量 artifact。

轻量 artifact 只需要包含必要文件，不补齐完整阶段：

artifacts/{YYYYMMDD}__{feature-name}/
├── raw-input/task.md
├── implementation/summary.md
└── testing/testing-report.md

升级条件

出现以下情况时，至少升级到 L2，高风险时升级到 L3：

• 公开契约、持久化结构、安全边界、权限、部署配置。
• 跨工程或跨核心模块。
• 需求存在开放问题或验收标准不明确。
• 需要新增依赖、数据迁移、外部服务或破坏性命令。
• 测试缺失且改动影响用户可见行为。

调查策略

不同范围适用不同的代码调查方式，按效率从高到低递进：

范围	首选策略	递进策略
快速修复	Grep 关键词 → Read 定位到的文件相关段落	Grep 定位不到时，再用 Explore agent
标准开发	Grep + Read 定位变更点	需要理解模块间关系时，用 Explore agent
完整流程	Read background/ 文档获取上下文	设计阶段用 Explore agent 了解现有架构

原则：先用轻量工具（Grep/Glob），定位不到再用重量级工具（Explore agent）。避免对明确 bug 启动全面探索。

---

标准工作流

仅 L2/L3 默认使用本节。L0 不使用标准工作流；L1 只在需要留痕时使用轻量子集。

raw-input → requirements → design → tech-spec → implementation → testing → deployment

通用规则

1. L2/L3 每个阶段在 artifacts/{YYYYMMDD}__{feature-name}/ 对应子目录下产出文件（日期为创建当天的 YYYYMMDD 格式，如 20260402__user-login）
2. L2/L3 每阶段结束：展示产出物、AI 决策、取舍理由和风险 → 更新产出目录 AGENTS.md 索引 → 若无暂停条件则继续下一阶段；不要询问用户“选择哪个方案”或“是否进入下一阶段”
3. 用户可随时暂停、回退、修改之前的产出
4. 不要主动启动服务，默认必要服务已经启动

---

阶段一：raw-input（原始输入）

目标：保存用户的原始描述，不做加工。

行为：

1. 创建任务产出目录 artifacts/{YYYYMMDD}__{feature-name}/
2. 将原始输入保存到 artifacts/{YYYYMMDD}__{feature-name}/raw-input/
3. 如果是文字描述，保存为 task.md；若分解为多个任务，则使用 task-001.md、task-002.md...（或按用户指定名称）
4. 如果引用了文件，读取并保存副本

产出物：

artifacts/{YYYYMMDD}__{feature-name}/raw-input/
└── task.md              # 原始输入内容（多任务时 task-001.md, task-002.md...）

---

阶段二：requirements（需求提炼）

目标：从 raw-input 提炼出结构化需求。

前置：阅读以下 background 文档获取上下文：

• background/product.md — 产品定位
• background/domains.md — 领域模型
• background/features.md — 功能状态

行为：

1. 分析 raw-input，提炼出需求要点
2. 产出结构化需求文档

产出物：artifacts/{YYYYMMDD}__{feature-name}/requirements/requirements.md

# {任务名称} 需求文档

## 背景与目标
{为什么做这个任务，解决什么问题}

## 验收标准 (AC)
- [ ] AC1: {具体可验证的标准}
- [ ] AC2: ...

## 范围
### 包含
- ...
### 不包含
- ...

## 依赖
- {依赖的其他功能、系统、资源}

## 涉及模块
- {从业务角度描述涉及的模块或服务，不涉及具体文件路径}

## 开放问题
- {待确认的设计决策或技术问题}

检查点：向用户展示需求文档、AI 提炼的 AC 和范围；若存在无法由代码事实或用户原始输入解决的开放问题，则暂停确认，否则继续下一阶段。

---

阶段三：design（技术选型）

目标：AI 自主比较技术方案并做出决策。不产出施工细节。

行为：

1. 基于 requirements，调研可行方案
2. 如需了解现有代码，读取 projects/ 下相关文件
3. 产出技术选型讨论文档

产出物：artifacts/{YYYYMMDD}__{feature-name}/design/design.md

# {任务名称} 技术选型

## 方案概述
{一句话描述技术方案}

## 技术选型决策
| 决策点 | 选项 | 最终选择 | 理由 |
|--------|------|---------|------|
| 方案选择 | {可行方案摘要} | {AI 最终选择} | {选择理由} |
| ... | ... | ... | ... |

## 风险与权衡
- {已知风险和应对策略}

检查点：向用户展示技术选型、最终选择、未选方案和取舍理由；不要要求用户在方案间选择。仅当决策依赖业务偏好、外部授权或高风险边界时暂停确认，否则继续下一阶段。

---

阶段四：tech-spec（技术规范）

目标：将技术选型细化为可执行的变更清单。

行为：

1. 基于 design 的决策，产出精确的技术规范
2. 包含数据模型、接口定义、变更清单

产出物：artifacts/{YYYYMMDD}__{feature-name}/tech-spec/tech-spec.md

# {任务名称} 技术规范

## 数据模型
{接口/类型定义，用代码块}

## 核心逻辑
{关键算法、流程的伪代码或代码片段}

## 变更清单
| 序号 | 变更项 | 文件路径 | 变更类型 | 说明 |
|------|--------|---------|---------|------|
| 1 | 新增 {能力名称} | {文件路径} | 新增 | {变更说明} |

## 配置变更
{需要新增或修改的配置文件}

## 测试计划
- {需要编写的测试用例}

检查点：向用户展示技术规范、变更清单和测试计划；若无开放问题或高风险操作，直接进入实现。

---

阶段五：implementation（代码实现）

目标：按 tech-spec 执行代码变更。

行为：

1. 按 tech-spec 中的变更清单逐项实现
2. 使用 Context7 MCP 查询第三方库 API，不要杜撰
3. 如遇 tech-spec 未覆盖的问题，记录决策到 implementation 记录中

产出物：

• projects/ 下的实际代码变更
• artifacts/{YYYYMMDD}__{feature-name}/implementation/decisions.md（如有额外决策）

检查点：向用户展示代码变更摘要；若无阻塞，继续测试验证。

---

阶段六：testing（测试验证）

目标：验证实现的正确性。

行为：

1. 按 tech-spec 中的测试计划编写测试
2. 优先读取 .agents/recipes.json 选择验证命令；不存在时运行 /an-recipes 探测
3. 记录测试结果

产出物：artifacts/{YYYYMMDD}__{feature-name}/testing/testing-report.md

# {任务名称} 测试报告

## 测试用例
| 序号 | 用例 | 结果 | 备注 |
|------|------|------|------|
| 1 | ... | ✅/❌ | ... |

## 缺陷记录
| 序号 | 描述 | 严重程度 | 状态 |
|------|------|---------|------|
| ... | ... | ... | ... |

检查点：向用户展示测试结果；若存在失败、缺陷或未关闭风险，AI 先自行修复和复测，只有无法继续时才请求用户决策。

---

阶段七：quality-eval（质量评价）

目标：判断任务是否真的完成，而不是只看代码是否修改。

行为：

1. L2/L3 在 testing 后运行：

   node .agents/skills/an-eval/scripts/evaluate-task.mjs artifacts/{YYYYMMDD}__{feature-name}
   

2. 将输出保存为 artifacts/{YYYYMMDD}__{feature-name}/testing/eval-report.md

3. 如果结论为 BLOCKED，不要归档任务；先补验收标准、测试证据或风险处理

---

阶段八：deployment（部署归档）

目标：完成收尾工作。

行为：

1. 更新 background/features.md 中的功能状态
2. 更新项目根 AGENTS.md 的活跃 Artifacts 表
3. 产出部署说明（如有必要）

产出物：artifacts/{YYYYMMDD}__{feature-name}/deployment/release-notes.md

# {任务名称} 发布说明

## 变更摘要
{本次任务的核心变更}

## 版本信息
- 版本号: ...
- 分支: ...

## 上线清单
- [ ] 代码已合并
- [ ] 测试通过
- [ ] 文档已更新

## 回滚方案
{如有风险，描述回滚步骤}

完成：输出任务完成总结。

---

Artifact 索引

每创建一个新产出目录，同步更新项目根 AGENTS.md 的活跃 Artifacts 表：

| Artifact | 描述 | 状态 |
|----------|------|------|
| artifacts/{feature-name} | {简述} | 🚧 进行中 |

完成后更新为 ✅。

---

错误处理

情况	处理
用户中途想修改之前阶段产出	回到对应阶段，修改后重新确认，评估对后续阶段的影响
用户想跳过某个阶段	允许跳过，但告知可能的风险
用户想暂停	保存当前进度到产出目录 AGENTS.md，下次可恢复
代码实现遇到 tech-spec 未覆盖的问题	记录决策，必要时回退更新 tech-spec