implement

implement

根据 tasks.md 中的任务分解与 design.md 中的技术计划，按阶段、依赖与 TDD 要求执行实施，并产出任务执行报告。

指令

执行步骤总览（TodoList）

须按下面顺序执行：上一项未完成（或未达到其「可跳过」条件），不得进入下一项。**【关键规则】所有任务必须全部完成才能结束，包括：功能代码任务、测试任务（TDD/单元测试/集成测试）、文档任务。任何未完成任务都是不完整的交付。**每完成一项，在会话中勾选或明确回复「步骤 N 已完成」。涉及 clear 与 .cache/context_cost.log 的规则见「上下文成本日志」及 §1、§7。

• 步骤 1 — 阶段开始：上下文快照、clear（或 fork 豁免 + no_clear 行）、仅依赖落盘文件（见 §1）
• 步骤 2 — 设置：运行 check-prerequisites、解析 FEATURE_DIR / AVAILABLE_DOCS（见 §2）
• 步骤 3 — 检查清单状态：扫描 FEATURE_DIR/checklists/；无该目录则本步记为跳过（见 §3）
• 步骤 4 — 加载与分析实施上下文：读取 tasks.md、design.md 及 §4 所列可选文档（见 §4）
• 步骤 5 — 项目设置验证：创建/校验各忽略文件（见 §5）
• 步骤 6 — 解析 tasks.md：阶段、依赖、[P]、执行顺序（见 §6）
• 步骤 7 — 按任务计划执行实施：分阶段 / TDD / 同文件协调；每批结束后 clear + 日志；下一批前重读 tasks.md 等（见 §7；实施中同时遵守 §8 规则与 §9 进度/错误处理）
• 步骤 8 — 完成验证与任务状态分析：复验 tasks.md、未完成项归类（见 §10）
• 步骤 9 — 生成最终报告、技能结束快照与 skill_end 日志行（见 §11）

说明：§8（实施执行规则）、§9（进度与错误处理）不单独占序号，在 步骤 7 执行过程中持续遵守；若 §3 清单未通过且用户选择不继续，在 步骤 3 终止。

上下文成本日志（.cache/context_cost.log）

<REPO_ROOT> = git rev-parse --show-toplevel（与步骤 2 一致）。在 <REPO_ROOT>/.cache/ 下只追加该文件，勿覆盖。每次 clear（或等价清理）须先写 before_clear、后写 after_clear（§1 入场、§7 每批等）；读不到占用时 after_clear 填 unavailable。豁免 clear 时写一行：...|no_clear|reason=<说明>。

行格式（| 分隔，UTF-8）：
<ISO8601>|implement|<事件>|before_clear|<Token 或 unavailable>
<ISO8601>|implement|<事件>|after_clear|<Token 或 unavailable>
事件示例：phase_start、batch:设置、batch:子批-1。技能结束见 §11，追加一行：<ISO8601>|implement|skill_end|context|<…>。

0. skill执行开始时间打点记录

开始执行步骤之前，需要进行一些打点记录工作，记录本skill的执行时间到 start_time字段：

• 判断当前操作系统，windows还是linux系统;
• 针对不同操作系统运行脚本获取配置 windows: Get-Date -Format "yyyy-MM-dd HH:mm:ss" linux: date +"%Y-%m-%d %H:%M:%S"
• 将获取的时间记录到 start_time

1. 阶段开始：上下文快照、清理与执行边界

本技能一开始（进入步骤 2 之前）须完成下列事项，以降低上下文超限风险；不得跳过后续对文件的读取。

1. 记录上下文规模

   • 若宿主（如 Claude Code / Cursor）提供当前会话的 Token 用量、上下文占用比例或等价指标，在回复中输出一行快照，例如：[implement 阶段开始] 上下文/Token：<数值或说明>。
   • 若环境无法读取，输出：[implement 阶段开始] 上下文规模：不可用，然后继续。
   • 写入日志：在随后执行第 2 步 clear（或等价清理）之前，按「上下文成本日志」追加 before_clear；清理完成后追加 after_clear（事件标识 phase_start）。

2. 清理上下文

   • Claude Agent / Claude Code：在记录完第 1 步快照后、进入步骤 2「设置」之前，使用宿主提供的 clear 指令（或等价「清空上下文」操作）清理当前对话上下文，再仅依据文件继续；清理后在回复中注明 [implement] 已执行 clear。
   • 其他宿主（如 Cursor）：在宿主支持的前提下，通过新开会话、清空对话历史、使用摘要/压缩等方式，主动释放本技能调用之前累积的长对话占用。
   • 若本技能已通过 context: fork（或等价机制）在隔离子会话中执行，在快照中注明 已 fork/隔离，可不再要求执行 clear/手动清历史，但仍须遵守第 3 条文件边界；豁免时按「上下文成本日志」写 no_clear 说明行。
   • 清理或隔离之后，不得依赖对「进入本技能之前」长对话内容的逐条记忆推进实施。

3. 仅以前序产物为准

   • 实施所需信息必须来自仓库与 FEATURE_DIR 下已由前序步骤（specify / design / tasks 等）写入磁盘的文件；缺信息时打开文件读取，禁止仅凭对话记忆补全可能已过期的细节。
   • 步骤 4「加载与分析实施上下文」所列文档为本阶段的权威来源。

2. 设置

• 判断当前操作系统（Windows 或 Linux）
• 从仓库根目录运行对应脚本：
  • Windows: scripts/powershell/check-prerequisites.ps1 --json --require-tasks --include-tasks
  • Linux: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
• 解析脚本 JSON 输出，获取 FEATURE_DIR 和 AVAILABLE_DOCS 列表；所有路径使用绝对路径。参数中含单引号时（如 "I'm Groot"）使用转义 'I'\''m Groot' 或双引号 "I'm Groot"。

3. 检查清单状态

（若存在 FEATURE_DIR/checklists/）

• 扫描 checklists/ 目录中的所有清单文件

• 对于每个清单, 统计:

  • 总项目数: 所有匹配 - [ ] 或 - [X] 或 - [x] 的行
  • 已完成项目数: 匹配 - [X] 或 - [x] 的行
  • 未完成项目数: 匹配 - [ ] 的行

• 创建状态表:

  | Checklist | Total | Completed | Incomplete | Status |
  |-----------|-------|-----------|------------|--------|
  | ux.md     | 12    | 12        | 0          | ✓ PASS |
  | test.md   | 8     | 5         | 3          | ✗ FAIL |
  | security.md | 6   | 6         | 0          | ✓ PASS |
  

• 计算总体状态:

  • PASS: 所有清单都有 0 个未完成项目
  • FAIL: 一个或多个清单有未完成项目

• 若有清单未完成

  • 显示含未完成项数量的表格
  • 停止并询问："Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
  • 等待用户响应后再继续
  • 用户回复 "no" / "wait" / "stop" → 停止；"yes" / "proceed" / "continue" → 进入步骤 4

• 若所有清单均已完成

  • 显示所有清单通过的表格
  • 自动进入步骤 4

4. 加载与分析实施上下文

• 必需: 读取 tasks.md 获取完整任务列表和执行计划
• 必需: 读取 design.md 获取技术栈、架构和文件结构
• 如果存在: 读取 data-model.md 获取实体和关系
• 如果存在: 读取 contracts/ 获取 API 规范和测试要求
• 如果存在: 读取 research.md 获取技术决策和约束
• 如果存在: 读取 quickstart.md 获取集成场景

5. 项目设置验证

• 必需：基于实际项目设置创建或验证忽略文件。

检测与创建逻辑

• 检查以下命令是否成功以判断是否为 Git 仓库（若是，则创建/验证 .gitignore）：

  git rev-parse --git-dir 2>/dev/null
  

• 存在 Dockerfile* 或 design.md 提及 Docker → 创建/验证 .dockerignore

• 存在 .eslintrc* 或 eslint.config.* → 创建/验证 .eslintignore

• 存在 .prettierrc* → 创建/验证 .prettierignore

• 存在 .npmrc 或 package.json 且需发布 → 创建/验证 .npmignore

• 存在 Terraform 文件 *.tf → 创建/验证 .terraformignore

• 存在 Helm charts → 创建/验证 .helmignore

若忽略文件已存在：校验是否包含基本模式，仅追加缺失的关键模式。 若忽略文件不存在：为检测到的技术创建完整模式集。

按技术栈的通用模式（参考 design.md）：

• Node.js/JavaScript: node_modules/, dist/, build/, *.log, .env*
• Python: __pycache__/, *.pyc, .venv/, venv/, dist/, *.egg-info/
• Java: target/, *.class, *.jar, .gradle/, build/
• C#/.NET: bin/, obj/, *.user, *.suo, packages/
• Go: *.exe, *.test, vendor/, *.out
• Ruby: .bundle/, log/, tmp/, *.gem, vendor/bundle/
• PHP: vendor/, *.log, *.cache, *.env
• Rust: target/, debug/, release/, *.rs.bk, *.rlib, *.prof*, .idea/, *.log, .env*
• Kotlin: build/, out/, .gradle/, .idea/, *.class, *.jar, *.iml, *.log, .env*
• C++: build/, bin/, obj/, out/, *.o, *.so, *.a, *.exe, *.dll, .idea/, *.log, .env*
• C: build/, bin/, obj/, out/, *.o, *.a, *.so, *.exe, Makefile, config.log, .idea/, *.log, .env*
• Swift: .build/, DerivedData/, *.swiftpm/, Packages/
• R: .Rproj.user/, .Rhistory, .RData, .Ruserdata, *.Rproj, packrat/, renv/
• 通用: .DS_Store, Thumbs.db, *.tmp, *.swp, .vscode/, .idea/

工具特定模式

• Docker: node_modules/, .git/, Dockerfile*, .dockerignore, *.log*, .env*, coverage/
• ESLint: node_modules/, dist/, build/, coverage/, *.min.js
• Prettier: node_modules/, dist/, build/, coverage/, package-lock.json, yarn.lock, pnpm-lock.yaml
• Terraform: .terraform/, *.tfstate*, *.tfvars, .terraform.lock.hcl
• Kubernetes/k8s：*.secret.yaml, secrets/, .kube/, kubeconfig*, *.key, *.crt

6. 解析 tasks.md 结构并提取

• 任务阶段：设置、测试、核心、集成、完善
• 任务依赖：顺序与并行规则
• 任务详情：ID、描述、文件路径、并行标记 [P]
• 执行流程：顺序与依赖要求

7. 按任务计划执行实施

• 分阶段：完成当前阶段后再进入下一阶段

• 依赖：顺序任务按序执行，带 [P] 的并行任务可一并执行

• TDD：在对应实施任务前执行测试任务

• 同文件协调：影响同一文件的任务须顺序执行

• 检查点：每阶段完成后验证再继续

• 【强制要求】所有任务必须完成：

  • 功能代码任务：所有标记为代码实现的任务必须完成并通过编译/语法检查
  • 测试任务：所有测试任务（包括单元测试、集成测试任务）必须实现，测试代码必须生成到文件
  • 文档任务：所有文档更新任务必须完成
  • 禁止提前结束：即使功能代码已完成，仍须完成所有测试任务才能进入步骤 8

• 【关键】测试任务的定义是"生成测试代码"，不是"验证测试编译"：

  • 测试代码生成：编写测试文件，这是必须完成的，与编译环境无关
  • 测试编译验证：运行测试命令（如 go test、pytest、npm test 等）验证编译，这依赖环境
  • 正确行为：当编译环境不可用时，仍然要生成测试代码，只是跳过验证步骤
  • 禁止行为：因为无法验证编译就跳过测试代码生成
  • 示例：
    • ❌ 错误：编译器不可用 → 跳过测试任务
    • ✅ 正确：编译器不可用 → 生成测试代码到文件 → 报告"测试代码已生成，但编译验证待环境修复后执行"

• 【关键】环境限制的处理原则：

  • 环境限制（如编译器/解释器不可用）不能作为跳过任务的理由
  • 任务可分两类：
    1. 可无环境执行：生成代码、生成测试文件，写配置 → 必须完成
    2. 必须依赖环境：编译验证、运行测试 → 报告问题但继续其他任务
  • 测试代码生成属于"可无环境执行"类别
  • 只有"必须依赖环境"的任务才能因环境问题而跳过

每批任务完成后的上下文清理（避免超限）

• 一批的默认含义：tasks.md 中一个任务阶段（设置 / 测试 / 核心 / 集成 / 完善）内，本轮应执行的任务已全部完成，且本阶段检查点已通过、tasks.md 中对应项已更新为 - [X]。若单阶段任务过多、上下文增长过快，可将「一批」细分为更小的子批（例如每完成若干顺序任务、或每轮 [P] 并行任务全部结束）并在每个子批结束后同样执行下列清理。
• 每批结束前须落盘：本批涉及的代码与配置已保存；tasks.md 中本批任务已勾选，避免 clear 后丢失进度。
• 每批结束后清理上下文：在 Claude Agent / Claude Code 下执行 clear（与 §1 第 2 条一致），并在回复中注明 [implement] 批次完成，已 clear：<阶段名或子批说明>。每次执行 clear 前、后，按「上下文成本日志」向 <REPO_ROOT>/.cache/context_cost.log 追加 before_clear / after_clear（事件标识使用 batch:<阶段名> 或 batch:子批-<说明>）。其他宿主用 §1 所述等价方式。若本技能始终在 context: fork 子会话中执行且宿主对子会话自动轮换，可按 §1 说明在快照中说明豁免条件，豁免时同样写入 no_clear 说明行；但仍须保证下一批从文件恢复状态。
• 下一批仅依赖文件：清理后推进下一批任务时，须重新读取 tasks.md（及 design.md 等 §4 所列文档）确认当前进度与约束，禁止仅凭对本批对话的长记忆继续实施。

8. 实施执行规则

• 设置：初始化项目结构、依赖、配置

• 测试先行：按需为合约、实体、集成场景编写测试；当存在 FEATURE_DIR/e2e-impl-design.md 时，按照e2e 用例实施方法进行编写

• 核心开发：模型、服务、CLI、端点

• 集成：数据库、中间件、日志、外部服务

• 收尾：单元测试、性能与文档

• e2e 用例实施（仅当存在 FEATURE_DIR/e2e-impl-design.md 时）:

  • 强制前置检查: 在实施 e2e 用例前，必须：
    • 读取并完整理解 FEATURE_DIR/e2e-impl-design.md
    • 读取 tasks.md 中与 e2e 相关的任务定义
    • 确认理解所有约定：测试数据格式、Fake定义、验证逻辑、入口函数签名等
  • 严格实施约束:
    • 必须严格按照 tasks.md 中定义的步骤顺序实施，不得调换或跳过
    • 必须严格遵循 e2e-impl-design.md 中的约定：
      • 测试数据必须完全按照约定格式构造
      • Mock 对象必须使用约定的 Fake 实现和配置
      • 验证逻辑必须实现约定的检查点，不得遗漏或简化
      • 入口函数签名必须与约定完全一致
    • 禁止自行发挥：不得"优化"、"简化"或"改进"约定，任何偏差必须立即报告
  • 实施后校验并输出报告:

  ## 📋 e2e 用例实施校验报告
  - 对比实施步骤与 tasks.md 定义的一致性: ✅
  - 对比测试数据格式与 e2e-impl-design.md 约定: ✅
  - 对比 Fake 对象使用与约定: ✅
  - 对比验证逻辑实现与约定: ✅
  - 对比入口函数签名与约定: ✅
  - 偏离检查: 无偏离
  - 校验结果: ✅ e2e 用例实现严格遵循约定，无任何偏移
  

9. 进度与错误处理

• 每完成一项任务即报告进度
• 非并行任务失败则停止；并行任务 [P] 中失败的单独报告，其余继续
• 错误信息需包含调试上下文；无法继续时给出下一步建议
• 重要：已完成任务须在 tasks.md 中标记为 - [X]。

10. 完成验证与任务状态分析

• 重新读取 tasks.md：获取最新状态，统计已完成（- [X]）与未完成（- [ ]）任务。

• 任务完成度验证

  • 对已标记完成的任务做实际校验：
    • 验证所有必需任务已完成
    • 检查实施功能是否与原始规范匹配
    • 验证测试通过且覆盖率满足要求
    • 确认实施遵循技术计划
  • 校验不通过的任务改回未完成。

• 【关键】未完成任务必须继续执行：

  • 评估每个未完成任务是否可执行：
    • 检查依赖项(其他任务、外部服务、工具)是否满足
    • 检查所需文件或资源是否存在
    • 检查权限或配置问题
  • 所有可执行的未完成任务（包括测试任务）必须继续执行，不得跳过
  • 只有因外部依赖不可用（如等待其他团队提供的 API）而确实无法执行的任务才能标记为"等待依赖"
  • 环境限制（如缺少编译器）应报告解决方案，而不是跳过任务

• 任务执行处理

  • 可执行：立即按依赖顺序执行，不得询问用户是否继续
  • 无法执行：生成分析报告（任务 ID、原因、阻塞说明、解决建议），并继续尝试执行其他可执行任务

11. 生成最终报告

• 【关键】最终报告必须准确反映任务完成状态：

  • 若存在未完成任务，报告不是"实施完成"，而是"部分完成，待完成 X 个任务"
  • 未完成的任务必须列出并说明原因

• 任务执行报告（需包含）：

  ## 任务执行最终报告
  ### 总体统计
  - 总任务数: X
  - 已完成: Y (Z%)
  - 未完成: W (V%)
    - 可执行: A
    - 无法完成: B
  
  ### 已完成任务列表
  [列出所有已完成的任务ID和描述]
  
  ### 【重点】未完成任务列表（功能未完成，不得结束）
  [列出所有未完成的任务ID和描述]
  - 代码任务: [列表]
  - 测试任务: [列表] ← 必须完成
  - 文档任务: [列表]
  
  ### 无法完成的任务分析
  [列出无法完成的任务, 包含:
   - 任务ID和描述
   - 阻塞原因(等待依赖/缺少资源/环境限制/需求问题/其他)
   - 详细说明
   - 解决建议]
  

• 下一步建议

  • 全部完成 → 报告成功，注明"所有任务已完成，包括功能代码和测试用例"
  • 存在可执行未完成任务 → 强制继续执行，不得结束
  • 存在无法完成的任务 → 建议用户排查并解决阻塞后再执行
  • 存在无法完成的任务 → 建议用户排查并解决阻塞后再执行

• 技能结束时的上下文规模（与 §1 成对记录）

  • 在本技能全部执行完毕时（已生成上述最终报告，或因清单/错误等明确结束本技能时），须再输出一行结束快照：若宿主可提供当前会话的 Token 用量、上下文占用比例或等价指标，输出：[implement 技能结束] 上下文/Token：<数值或说明>。
  • 若环境无法读取，输出：[implement 技能结束] 上下文规模：不可用。
  • 该结束快照应出现在最终面向用户的回复中，便于与 §1「阶段开始」快照对照，评估本会话实施阶段的上下文占用。
  • 写入日志：同时将上述结束占用追加一行到 <REPO_ROOT>/.cache/context_cost.log（与「上下文成本日志」同一文件）：
    <ISO8601>|implement|skill_end|context|<上下文/Token 可读值或 unavailable>

注意：本技能假定 tasks.md 中已有完整任务分解。若任务不完整或缺失，请先通过相应命令重新生成任务列表。

12. 记录本skill的运行日志信息

执行runlog-record skill，请将前面获取到的start_time的值作为参数传入runlog-record skill