feature-implementation

Role: 高级开发工程师 (Senior Developer)

这是一个执行型 Skill。当用户说"完成 XX 功能的任务 第几阶段"时，使用此 Skill。

项目上下文协议 (Project Context Protocol) - CRITICAL

请严格遵守项目上下文强制协议：specs/PROJECT-CONTEXT.md 在执行本 Skill 之前，必须先建立项目认知。

你的任务

根据用户指定的功能和阶段，按照 TDD（测试驱动开发） 流程自动执行对应的开发任务，并在完成后更新任务状态。

核心方法论：TDD（测试驱动开发）

本 Skill 强制使用 Red-Green-Refactor 循环来完成每一个开发任务：

RED（红灯）→ GREEN（绿灯）→ REFACTOR（重构）
  ↑                                    │
  └────────────────────────────────────┘
         下一个任务 / 下一组测试

• RED：先根据需求和验证标准编写测试，运行确认测试失败
• GREEN：编写刚好让测试通过的最少代码
• REFACTOR：在测试保护下优化代码结构，确保测试始终通过

铁律：没有失败的测试，就不写实现代码。

边界守卫 (Guardrails) - CRITICAL

请严格遵守通用边界守卫规则：specs/GUARDRAILS.md 当前阶段: 编码实现阶段 (Implementation)

输入格式

用户会以以下格式提供指令：

常规任务（来自 feature-task-planning）：

• "完成 [功能名] 的任务 第 [N] 阶段"
• "实现 [功能名] 阶段 [N]"
• "开发 [功能名] 的 [阶段名称]"

增量变更任务（来自 feature-evolution）：

• "完成 [功能名] 的变更任务 CR-[序号]"
• "实现 [功能名] 变更 CR-[序号] 阶段 [N]"

示例：

• "完成用户登录功能的任务 第1阶段"
• "实现评论功能 阶段2"
• "开发支付功能的数据层"
• "完成评论功能的变更任务 CR-001"

工作流程

1. 解析用户指令

从用户输入中提取：

• 功能名称：例如"用户登录"、"评论功能"
• 阶段标识：可以是数字（1、2、3）或名称（"数据层"、"表现层"）
• 任务来源：判断是常规任务还是增量变更任务（是否包含"变更"或"CR-"关键词）
• CR 编号（仅增量变更）：例如"CR-001"

2. 定位任务规划文档

常规任务：

• 查找 specs/features/[功能名]_任务规划.md
• 如果文档不存在，提示用户先执行 feature-task-planning Skill

增量变更任务：

• 查找 specs/features/[功能名]_变更任务_[CR序号].md
• 如果文档不存在，提示用户先执行 feature-evolution Skill
• 同时读取原始任务规划 specs/features/[功能名]_任务规划.md，了解已有任务的完成状态

3. 读取相关文档

必须按顺序读取以下文档，建立完整的功能上下文：

3.1 读取需求文档

• 文件路径：specs/features/[功能名].md
• 重点关注：
  • 功能的背景和价值
  • 用户角色和用户故事
  • 核心流程和交互规则
  • 边界情况和异常处理
  • 验收标准（AC） - 这是测试用例的来源

3.2 读取技术方案文档

• 文件路径：specs/features/[功能名]_技术方案.md
• 重点关注：
  • API 接口定义（路径、参数、响应格式）
  • 数据库设计（表结构、字段、索引）
  • 核心逻辑和算法
  • 异常处理方案
  • 技术难点和解决方案

3.3 读取任务规划文档

• 文件路径：specs/features/[功能名]_任务规划.md
• 重点关注：
  • 识别指定阶段的所有任务
  • 提取每个任务的：
    • 任务编号（如 Task-01）
    • 任务标题和说明
    • 涉及文件
    • 测试文件（RED 阶段创建测试文件时必须使用此路径）
    • 参考文档章节
    • 对应的验收标准
    • 依赖关系
    • 验证标准（这是编写测试的直接依据）

如果任何文档缺失，必须停止并提示用户先完成前置步骤。

4. 前置检查

在开始编码前，必须检查：

• 文档完整性：需求文档、技术方案、任务规划都已存在
• 依赖任务：检查任务规划中的依赖任务是否已勾选完成
• 项目环境：项目能否正常启动，依赖库是否安装
• 测试环境：测试框架已配置，能正常运行测试
• 上下文理解：确认已理解需求和技术方案的关键内容

如果前置条件不满足，必须停止并告知用户。

5. 执行开发任务（TDD 循环）

按照任务顺序，逐个完成。每个任务严格遵循 Red-Green-Refactor 循环：

5.1 任务确认

• 向用户确认："即将开始执行 [任务编号]: [任务标题]，是否继续？"
• 说明任务的目标和涉及的文件
• 展示该任务的验证标准（即将据此编写测试）

5.2 RED - 编写失败的测试

在编写任何实现代码之前，先编写测试。

1. 分析测试需求

   • 根据任务的验证标准和对应的验收标准（AC），确定需要哪些测试用例
   • 测试必须覆盖：
     • 正常情况（Happy Path）
     • 边界情况（Edge Cases）
     • 异常情况（Error Cases）

2. 编写测试文件

   • 测试类型根据任务性质选择：
     • 数据层任务 -> 单元测试（测试 CRUD 操作）
     • API 任务 -> 集成测试（测试接口响应）
     • 组件任务 -> 组件测试（测试渲染和交互）
     • 工具函数 -> 单元测试（测试输入输出）
   • 测试文件命名规范：
     • tests/unit/[模块名].test.js
     • tests/integration/[功能名].test.js
     • tests/components/[组件名].test.js
   • 测试描述要清晰（describe/it 语句要说明测试内容）
   • 每个测试只验证一个行为点

3. 运行测试，确认失败（RED）

   • 运行刚编写的测试
   • 测试必须失败（因为还没有实现代码）
   • 确认失败原因是"功能未实现"，而不是测试本身有 bug
   • 向用户展示测试失败的结果

如果测试在没有实现代码的情况下就通过了，说明：

• 测试写得有问题（没有真正验证功能），需要修正测试
• 或者功能已经被其他代码实现了，需要重新评估任务

5.3 GREEN - 编写最少的实现代码

目标：用最少的代码让测试通过，不多不少。

1. 编写实现代码

   • 严格遵守需求文档：确保实现符合用户故事和验收标准
   • 严格遵守技术方案：按照设计的 API、数据库结构、核心逻辑实现
   • 严格遵守项目规范：遵守技术栈和开发规范
   • 优先复用代码：复用项目中已有的代码、组件、工具函数
   • 参考文档章节：任务中标注的"参考"章节是实现的依据
   • 克制过度实现：只写让当前测试通过所需的代码，不要提前实现后续任务的功能

2. 运行测试，确认通过（GREEN）

   • 运行所有相关测试（包括之前任务的测试，防止回归）
   • 所有测试必须通过
   • 如果测试失败，修复实现代码（不是修改测试）直到通过
   • 向用户展示测试通过的结果

5.4 REFACTOR - 重构优化

在测试保护下，改善代码质量。

1. 代码审视

   • 检查是否有重复代码可以提取
   • 检查命名是否清晰准确
   • 检查代码结构是否合理
   • 检查是否符合项目规范

2. 执行重构（如果需要）

   • 提取公共方法/组件
   • 改善命名和代码组织
   • 优化性能（如有明显问题）
   • 添加必要的注释

3. 运行测试，确认仍然通过

   • 每次重构后都要运行测试
   • 测试必须始终保持通过状态
   • 如果测试失败，回退重构改动

5.5 展示结果

• 向用户展示完成的代码和测试代码
• 展示完整的测试结果（包括 RED -> GREEN 的过程记录）
• 询问用户是否满意，是否需要调整

5.6 自动化验收测试

TDD 循环完成后，必须通过验收测试验证任务成果在真实环境中的正确性。

测试依据：

• 当前任务的验证标准（见任务规划文档中当前任务的验证标准）
• 当前任务对应的验收标准（AC）（来源：specs/features/[功能名].md 中的验收标准章节）
• 需求文档的完整上下文（specs/features/[功能名].md）

浏览器端测试（优先）

适用场景：当前任务有 UI 变化或页面可感知的行为变更。

使用 Playwright MCP 对 http://localhost:3300 进行端到端验证。

按照 AC 描述的用户操作路径执行交互，验证页面状态、显示内容、交互反馈是否符合预期，并在关键验证点截图留档。

强制停止规则：如果存在浏览器端测试场景，但由于任何原因（开发服务器无法启动、环境变量缺失、浏览器启动失败、页面加载错误等）无法执行浏览器端测试，必须立即停止当前任务，在报告中详细说明无法执行的原因，不得跳过浏览器端测试继续完成任务。

单元测试（兜底）

适用场景：纯后端逻辑、工具函数、数据处理等无法通过浏览器验证的任务。

此类任务在 TDD 阶段已编写单元测试，确认 TDD 测试全部通过即视为验收通过。

数据验证

适用场景：涉及数据库变更的任务（如创建、修改、删除数据）。

使用 Supabase MCP（execute_sql）查询数据库，验证数据是否符合预期：

• 数据是否正确写入/更新/删除
• 字段值、数据类型、约束是否符合设计
• 关联数据的一致性

注意：数据验证可与浏览器端测试或单元测试组合使用，不互斥。

5.7 修复与重测循环

若验收测试未通过，进入修复循环：

验收测试失败 → 分析失败原因 → 修复代码 → 重跑 TDD 测试（防回归）→ 重跑验收测试 → 仍失败则继续循环

规则：

• 最大重试次数：3 次。超出仍未通过，标记任务为失败，向用户报告失败原因和已尝试的修复措施
• 每次修复后，必须同时重跑 TDD 阶段的测试，确保修复未引入回归
• 每次修复需记录：问题描述、修复措施、重测结果

5.8 文档同步

修复过程中，如果实现逻辑与现有功能文档产生偏差，必须同步更新相关文档：

• 检查 specs/features/ 下的需求文档和任务规划文档
• 如果代码行为与文档描述不一致，更新文档使其与实际实现对齐
• 在完成报告中列出所有文档变更

如果未经历修复且代码与文档一致，跳过此步骤。

重要：如果跳过了 RED 阶段（没有先写测试），任务不算完成。

6. 阶段性验证

当该阶段的所有任务完成后：

1. 运行完整测试套件

   • 运行该阶段所有任务的测试
   • 确保所有测试通过
   • 检查测试覆盖率（建议 > 80%）

2. 集成测试

   • 如果该阶段涉及多个模块，进行集成测试
   • 验证模块间的协作是否正常

3. 验收标准检查

   • 对照需求文档的验收标准
   • 检查该阶段完成的任务是否满足对应的 AC
   • 标记已满足的验收标准

4. 代码质量检查

   • 运行 Linter（ESLint/Prettier）
   • 运行类型检查（TypeScript）
   • 检查是否有代码异味

5. 生成阶段完成报告

   • 包含测试结果和覆盖率
   • 包含验收标准检查结果

7. 更新任务状态

• 在任务规划文档中，将已完成的任务标记为 [x]
• 更新验收标准检查清单的状态
• 保存更新后的文档

8. 生成完成报告

• 读取 assets/stage-completion-report-template.md 作为模板
• 填充实际的完成信息：
  • 功能名称和阶段信息
  • 已完成的任务列表（包含测试文件和测试结果）
  • TDD 循环记录（每个任务的 RED -> GREEN -> REFACTOR 过程）
  • 文件变更清单
  • 测试结果和覆盖率
  • 验收标准检查结果
  • 遇到的问题和解决方案
  • 下一步建议
• 保存报告到 docs/开发记录/[功能名]_阶段[N]_完成报告.md
• 在对话中向用户展示报告摘要

关键规则

规则 1：严格遵守任务规划

• 不要跳过任务
• 不要改变任务顺序（除非依赖关系允许）
• 不要做任务规划之外的事情

规则 2：代码复用优先

在编写新代码前，必须：

1. 检查项目中是否有类似的实现
2. 检查是否有可复用的组件、工具函数
3. 遵循项目现有的代码模式和风格

规则 3：TDD 铁律

每个任务必须严格遵循 Red-Green-Refactor 循环，不可跳步：

1. 不写没有测试的实现代码 — 每一行实现代码都由一个失败的测试驱动出来
2. 不写超出测试范围的代码 — 只写让当前测试通过所需的最少代码
3. RED 必须真红 — 测试必须因为"功能未实现"而失败，不是因为语法错误或环境问题
4. GREEN 必须刚好绿 — 通过测试后立即停止编码，进入重构阶段
5. REFACTOR 不改行为 — 重构只改结构不改功能，测试必须始终通过
6. 测试文件与源文件对应 — 如 user.js -> user.test.js
7. 每个测试只验证一个行为 — 保持测试的原子性和可读性

违反检查清单（出现以下情况必须停止并修正）：

• 写了实现代码但没有先写测试 -> 回退，先补测试
• 测试在没有实现的情况下就通过了 -> 测试无效，重写测试
• 重构后测试失败了 -> 回退重构改动

规则 4：文档同步

如果代码修改影响了文档，必须：

• 更新相关的 API 文档
• 更新 README（如果需要）
• 在完成报告中说明文档变更

规则 5：透明沟通

• 在开始每个任务前，告知用户
• 在 RED 阶段展示测试代码和失败结果
• 在 GREEN 阶段展示实现代码和通过结果
• 在 REFACTOR 阶段说明重构内容和测试结果
• 遇到问题时，及时向用户说明
• 完成后，展示结果并征求反馈

异常处理

情况 1：文档缺失

错误：缺少必要的文档

检查结果：
- 需求文档 (specs/features/[功能名].md): [存在 / 缺失]
- 技术方案 (specs/features/[功能名]_技术方案.md): [存在 / 缺失]
- 任务规划 (specs/features/[功能名]_任务规划.md): [存在 / 缺失]

请先执行以下步骤：
1. 使用 feature-requirements-clarification 生成需求文档
2. 使用 feature-tech-design 生成技术方案
3. 使用 feature-task-planning 生成任务规划

然后再使用本 Skill 进行编码实现。

情况 2：依赖任务未完成

警告：依赖任务未完成

当前任务 Task-05 依赖于：
- Task-02 (未完成)
- Task-04 (未完成)

建议：
1. 先完成依赖任务
2. 或者调整任务顺序（需要用户确认）

情况 3：技术方案不明确

警告：技术方案细节不足

任务 Task-03 要求实现 XXX，但技术方案中缺少以下信息：
- API 接口定义
- 数据结构设计

建议：
1. 补充技术方案文档
2. 或者根据现有信息做合理推断（需要用户确认）

情况 4：测试环境异常

警告：测试无法正常运行

错误信息：[具体错误]

可能原因：
1. 测试框架未安装或未配置
2. 依赖库缺失

建议修复方案：
1. 检查并安装测试依赖
2. 检查测试配置文件

测试环境就绪后才能开始 TDD 循环。

情况 5：代码冲突或错误

错误：代码执行失败

错误信息：[具体错误]

可能原因：
1. [原因分析]
2. [原因分析]

建议修复方案：
1. [方案1]
2. [方案2]

是否继续尝试修复？

交互示例

示例 1：TDD 正常执行流程

用户: 完成用户登录功能的任务 第1阶段

AI:
正在读取相关文档...

需求文档：specs/features/用户登录.md
   - 核心需求：支持手机号+密码登录
   - 验收标准：AC-001 到 AC-005

技术方案：specs/features/用户登录_技术方案.md
   - API: POST /api/auth/login
   - 数据库：users 表设计
   - 核心逻辑：密码加密、JWT 生成

任务规划：specs/features/用户登录_任务规划.md
   - 第1阶段包含 2 个任务

第1阶段：数据层 (Data Layer)
包含以下任务：
- Task-01: 创建 users 表
- Task-02: 实现用户数据访问层

前置检查：
[x] 文档完整性检查通过
[x] 项目环境就绪
[x] 测试环境就绪（Jest 已配置）
[x] 无依赖任务
[x] 已理解需求和技术方案

即将开始执行 Task-02: 实现用户数据访问层
验证标准：
  - 能根据手机号查询用户
  - 能创建新用户记录
  - 密码字段使用 bcrypt 加密存储
是否继续？

用户: 继续

AI:
=== RED 阶段：编写测试 ===

创建测试文件：tests/unit/user-repository.test.js

测试用例：
  describe('UserRepository')
    it('应能根据手机号查询已有用户')
    it('查询不存在的手机号应返回 null')
    it('应能创建新用户并返回用户对象')
    it('创建用户时密码应使用 bcrypt 加密')
    it('创建重复手机号用户应抛出错误')

运行测试...

FAIL tests/unit/user-repository.test.js
  UserRepository
    x 应能根据手机号查询已有用户 (ReferenceError: UserRepository is not defined)
    x 查询不存在的手机号应返回 null
    x 应能创建新用户并返回用户对象
    x 创建用户时密码应使用 bcrypt 加密
    x 创建重复手机号用户应抛出错误

Tests: 5 failed, 0 passed
RED 确认：5 个测试全部失败，原因是功能未实现。进入 GREEN 阶段。

=== GREEN 阶段：编写实现代码 ===

创建文件：src/repositories/user-repository.js

[展示实现代码...]

运行测试...

PASS tests/unit/user-repository.test.js
  UserRepository
    v 应能根据手机号查询已有用户 (23ms)
    v 查询不存在的手机号应返回 null (8ms)
    v 应能创建新用户并返回用户对象 (45ms)
    v 创建用户时密码应使用 bcrypt 加密 (120ms)
    v 创建重复手机号用户应抛出错误 (15ms)

Tests: 5 passed, 0 failed
GREEN 确认：全部测试通过。进入 REFACTOR 阶段。

=== REFACTOR 阶段：优化代码 ===

重构内容：
- 提取数据库连接逻辑为公共方法
- 优化错误信息的可读性

运行测试确认重构安全...

PASS tests/unit/user-repository.test.js (5/5)
REFACTOR 确认：重构完成，所有测试仍然通过。

=== Task-02 完成 ===

TDD 循环记录：
- RED:   5 个测试失败（功能未实现）
- GREEN: 5 个测试通过（实现完成）
- REFACTOR: 5 个测试通过（重构安全）

测试覆盖率: 96%

是否满意？继续下一个任务还是需要调整？

示例 2：RED 阶段发现测试异常

AI:
=== RED 阶段：编写测试 ===

创建测试文件：tests/unit/auth-service.test.js
运行测试...

PASS tests/unit/auth-service.test.js
  AuthService
    v 应验证正确的密码 (5ms)

警告：测试在没有实现代码的情况下通过了！

分析原因：项目中已存在 src/services/auth-service.js，
其中包含了 validatePassword 方法。

处理方案：
1. 该功能已被之前的任务实现，跳过此测试点
2. 补充更具体的测试用例来验证未覆盖的场景

建议选择方案 2，补充以下测试：
  - 测试密码为空时的处理
  - 测试超长密码的处理

是否同意？

示例 3：依赖未满足

用户: 完成支付功能的任务 第3阶段

AI:
已定位任务规划文档：specs/features/支付功能_任务规划.md

警告：依赖任务未完成

第3阶段的任务依赖于：
- Task-01 (数据层) - 未完成
- Task-03 (表现层) - 未完成

建议：
1. 先完成第1阶段和第2阶段
2. 或者告诉我"强制执行"（不推荐）

请选择：

输出

• 完成指定阶段的所有代码
• 对应的测试文件（在实现代码之前编写）
• 更新后的任务规划文档（任务状态已勾选）
• 阶段完成报告（保存到 docs/开发记录/[功能名]_阶段[N]_完成报告.md）

注意事项

1. 不要一次性完成所有阶段：每次只执行用户指定的阶段，避免一次性生成过多代码
2. 保持增量式开发：每个任务内部遵循 TDD 小循环，每个阶段完成后做阶段性验证
3. 测试先行不可妥协：即使用户催促，也不能跳过 RED 阶段直接写实现代码
4. 尊重用户反馈：如果用户对某个任务的实现不满意，立即调整（但调整后仍需通过测试）
5. 记录 TDD 过程：在完成报告中记录每个任务的 RED -> GREEN -> REFACTOR 过程

最终交付

• 完成指定阶段的所有代码
• 对应的测试文件
• 更新后的任务规划文档（任务状态已勾选）
• 阶段完成报告（含 TDD 循环记录和测试结果）