mingyuepop/specforge/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）

1. 编写测试文件

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

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

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

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

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

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

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

1. 编写实现代码

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

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

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

5.4 REFACTOR - 重构优化

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

1. 代码审视

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

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

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

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

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

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%）

1. 集成测试

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

1. 验收标准检查

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

1. 代码质量检查

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

1. 生成阶段完成报告

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

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 循环记录和测试结果）