| 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，按全阶段推进并确认 | 需求模糊、跨模块、架构/接口/数据/权限等高风险改动 |
执行要求：
- 先用一句话告诉用户采用的等级和理由；默认由 AI 自主决策并推进，不把可由 AI 判断的流程等级、技术方案或验证命令交给用户选择。
- 选择能覆盖风险的最轻流程。不要因为技能被触发就机械创建 artifacts 或跑完整阶段。
- 若调查中发现风险升高，立即升级流程并说明原因。
- 用户明确要求“快速处理”“直接改”时，可在不违反风险条件的前提下降级；用户明确要求“走完整流程”时按用户要求执行。
- 只有需求目标不明确、验收标准无法自洽、涉及权限/安全/数据/部署等高风险边界、需要破坏性操作或外部授权时，才暂停向用户确认。
输入来源
用户可通过以下方式提供 raw-input：
- 直接输入文字描述
- 引用文件路径（如
artifacts/xxx/raw-input/task.md）
- 引用外部链接（issue、文档等）
查找已有任务
仅在用户提到"之前做过"、"上次"、"继续之前的"、"之前有个"等引用历史任务的意图时，才执行查找。否则直接创建新的任务产出目录。
- 在
artifacts/ 中查找 — 用 Glob 匹配目录名中包含任务关键词的活跃产出目录（只看目录名，不读文件内容）
- 未找到则查
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 时，不要为了“流程完整”创建任务目录。直接：
- 定位文件
- 做最小修改
- 运行或说明最小验证
- 最终总结改动和验证结果
示例：修正文案错别字、改 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
通用规则
- L2/L3 每个阶段在
artifacts/{YYYYMMDD}__{feature-name}/ 对应子目录下产出文件（日期为创建当天的 YYYYMMDD 格式，如 20260402__user-login）
- L2/L3 每阶段结束：展示产出物、AI 决策、取舍理由和风险 → 更新产出目录 AGENTS.md 索引 → 若无暂停条件则继续下一阶段；不要询问用户“选择哪个方案”或“是否进入下一阶段”
- 用户可随时暂停、回退、修改之前的产出
- 不要主动启动服务，默认必要服务已经启动
阶段一：raw-input（原始输入）
目标：保存用户的原始描述，不做加工。
行为：
- 创建任务产出目录
artifacts/{YYYYMMDD}__{feature-name}/
- 将原始输入保存到
artifacts/{YYYYMMDD}__{feature-name}/raw-input/
- 如果是文字描述，保存为
task.md；若分解为多个任务，则使用 task-001.md、task-002.md...（或按用户指定名称）
- 如果引用了文件，读取并保存副本
产出物：
artifacts/{YYYYMMDD}__{feature-name}/raw-input/
└── task.md # 原始输入内容（多任务时 task-001.md, task-002.md...）
阶段二：requirements（需求提炼）
目标：从 raw-input 提炼出结构化需求。
前置：阅读以下 background 文档获取上下文：
background/product/overview.md — 主题定位background/domains.md — 领域模型（如存在）background/features.md — 交付状态（如存在）
行为：
- 分析 raw-input，提炼出需求要点
- 产出结构化需求文档
产出物：artifacts/{YYYYMMDD}__{feature-name}/requirements/requirements.md
# {任务名称} 需求文档
## 背景与目标
{为什么做这个任务，解决什么问题}
## 验收标准 (AC)
- [ ] AC1: {具体可验证的标准}
- [ ] AC2: ...
## 范围
### 包含
- ...
### 不包含
- ...
## 依赖
- {依赖的其他功能、系统、资源}
## 涉及模块
- {从业务角度描述涉及的模块或服务，不涉及具体文件路径}
## 开放问题
- {待确认的设计决策或技术问题}
检查点：向用户展示需求文档、AI 提炼的 AC 和范围；若存在无法由代码事实或用户原始输入解决的开放问题，则暂停确认，否则继续下一阶段。
阶段三：design（技术选型）
目标：AI 自主比较技术方案并做出决策。不产出施工细节。
行为：
- 基于 requirements，调研可行方案
- 如需了解现有代码，读取
projects/ 下相关文件
- 产出技术选型讨论文档
产出物：artifacts/{YYYYMMDD}__{feature-name}/design/design.md
# {任务名称} 技术选型
## 方案概述
{一句话描述技术方案}
## 技术选型决策
| 决策点 | 选项 | 最终选择 | 理由 |
|--------|------|---------|------|
| 方案选择 | {可行方案摘要} | {AI 最终选择} | {选择理由} |
| ... | ... | ... | ... |
## 风险与权衡
- {已知风险和应对策略}
检查点：向用户展示技术选型、最终选择、未选方案和取舍理由；不要要求用户在方案间选择。仅当决策依赖业务偏好、外部授权或高风险边界时暂停确认，否则继续下一阶段。
阶段四：tech-spec（技术规范）
目标：将技术选型细化为可执行的变更清单。
行为：
- 基于 design 的决策，产出精确的技术规范
- 包含数据模型、接口定义、变更清单
产出物：artifacts/{YYYYMMDD}__{feature-name}/tech-spec/tech-spec.md
# {任务名称} 技术规范
## 数据模型
{接口/类型定义，用代码块}
## 核心逻辑
{关键算法、流程的伪代码或代码片段}
## 变更清单
| 序号 | 变更项 | 文件路径 | 变更类型 | 说明 |
|------|--------|---------|---------|------|
| 1 | 新增 {能力名称} | {文件路径} | 新增 | {变更说明} |
## 配置变更
{需要新增或修改的配置文件}
## 测试计划
- {需要编写的测试用例}
检查点：向用户展示技术规范、变更清单和测试计划；若无开放问题或高风险操作，直接进入实现。
阶段五：implementation（代码实现）
目标：按 tech-spec 执行代码变更。
行为：
- 按 tech-spec 中的变更清单逐项实现
- 使用 Context7 MCP 查询第三方库 API，不要杜撰
- 如遇 tech-spec 未覆盖的问题，记录决策到 implementation 记录中
产出物：
projects/ 下的实际代码变更artifacts/{YYYYMMDD}__{feature-name}/implementation/decisions.md（如有额外决策）
检查点：向用户展示代码变更摘要；若无阻塞，继续测试验证。
阶段六：testing（测试验证）
目标：验证实现的正确性。
行为：
- 按 tech-spec 中的测试计划编写测试
- 优先读取
.agents/recipes.json 选择验证命令；不存在时运行 /an-recipes 探测
- 记录测试结果
产出物：artifacts/{YYYYMMDD}__{feature-name}/testing/testing-report.md
# {任务名称} 测试报告
## 测试用例
| 序号 | 用例 | 结果 | 备注 |
|------|------|------|------|
| 1 | ... | ✅/❌ | ... |
## 缺陷记录
| 序号 | 描述 | 严重程度 | 状态 |
|------|------|---------|------|
| ... | ... | ... | ... |
检查点：向用户展示测试结果；若存在失败、缺陷或未关闭风险，AI 先自行修复和复测，只有无法继续时才请求用户决策。
阶段七：quality-eval（质量评价）
目标：判断任务是否真的完成，而不是只看代码是否修改。
行为：
-
L2/L3 在 testing 后运行：
node .agents/skills/an-eval/scripts/evaluate-task.mjs artifacts/{YYYYMMDD}__{feature-name}
-
将输出保存为 artifacts/{YYYYMMDD}__{feature-name}/testing/eval-report.md
-
如果结论为 BLOCKED，不要归档任务；先补验收标准、测试证据或风险处理
阶段八：deployment（部署归档）
目标：完成收尾工作。
行为：
- 更新
background/features.md 中的交付状态（如存在）
- 更新项目根
AGENTS.md 的活跃 Artifacts 表
- 产出部署说明（如有必要）
产出物：artifacts/{YYYYMMDD}__{feature-name}/deployment/release-notes.md
# {任务名称} 发布说明
## 变更摘要
{本次任务的核心变更}
## 版本信息
- 版本号: ...
- 分支: ...
## 上线清单
- [ ] 代码已合并
- [ ] 测试通过
- [ ] 文档已更新
## 回滚方案
{如有风险，描述回滚步骤}
完成：输出任务完成总结。
Artifact 索引
每创建一个新产出目录，同步更新项目根 AGENTS.md 的活跃 Artifacts 表：
| Artifact | 描述 | 状态 |
|----------|------|------|
| artifacts/{feature-name} | {简述} | 🚧 进行中 |
完成后更新为 ✅。
错误处理
| 情况 | 处理 |
|---|
| 用户中途想修改之前阶段产出 | 回到对应阶段，修改后重新确认，评估对后续阶段的影响 |
| 用户想跳过某个阶段 | 允许跳过，但告知可能的风险 |
| 用户想暂停 | 保存当前进度到产出目录 AGENTS.md，下次可恢复 |
| 代码实现遇到 tech-spec 未覆盖的问题 | 记录决策，必要时回退更新 tech-spec |
