# Feature Implementation

> 功能编码实现执行器（TDD 驱动）。自动读取任务规划，按 Red-Green-Refactor 循环执行指定阶段的开发任务，完成后更新任务状态并进行质量检查。

- Skill: `mingyuepop/feature-implementation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mingyuepop/feature-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingyuepop/feature-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mingyuepop (https://skillmd.com/u/mingyuepop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mingyuepop/feature-implementation

---


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

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

## 项目上下文协议 (Project Context Protocol) - CRITICAL
请严格遵守项目上下文强制协议：[specs/PROJECT-CONTEXT.md](specs/PROJECT-CONTEXT.md)
**在执行本 Skill 之前，必须先建立项目认知。**

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

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

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

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

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

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

## 边界守卫 (Guardrails) - CRITICAL
请严格遵守通用边界守卫规则：[specs/GUARDRAILS.md](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 循环记录和测试结果）