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-planningSkill
增量变更任务：
- 查找
specs/features/[功能名]_变更任务_[CR序号].md - 如果文档不存在，提示用户先执行
feature-evolutionSkill - 同时读取原始任务规划
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 - 编写失败的测试
在编写任何实现代码之前，先编写测试。
- 分析测试需求
- 根据任务的验证标准和对应的验收标准（AC），确定需要哪些测试用例 - 测试必须覆盖： - 正常情况（Happy Path） - 边界情况（Edge Cases） - 异常情况（Error Cases）
- 编写测试文件
- 测试类型根据任务性质选择： - 数据层任务 -> 单元测试（测试 CRUD 操作） - API 任务 -> 集成测试（测试接口响应） - 组件任务 -> 组件测试（测试渲染和交互） - 工具函数 -> 单元测试（测试输入输出） - 测试文件命名规范： - tests/unit/[模块名].test.js - tests/integration/[功能名].test.js - tests/components/[组件名].test.js - 测试描述要清晰（describe/it 语句要说明测试内容） - 每个测试只验证一个行为点
- 运行测试，确认失败（RED）
- 运行刚编写的测试 - 测试必须失败（因为还没有实现代码） - 确认失败原因是"功能未实现"，而不是测试本身有 bug - 向用户展示测试失败的结果
如果测试在没有实现代码的情况下就通过了，说明：
- 测试写得有问题（没有真正验证功能），需要修正测试
- 或者功能已经被其他代码实现了，需要重新评估任务
5.3 GREEN - 编写最少的实现代码
目标：用最少的代码让测试通过，不多不少。
- 编写实现代码
- 严格遵守需求文档：确保实现符合用户故事和验收标准 - 严格遵守技术方案：按照设计的 API、数据库结构、核心逻辑实现 - 严格遵守项目规范：遵守技术栈和开发规范 - 优先复用代码：复用项目中已有的代码、组件、工具函数 - 参考文档章节：任务中标注的"参考"章节是实现的依据 - 克制过度实现：只写让当前测试通过所需的代码，不要提前实现后续任务的功能
- 运行测试，确认通过（GREEN）
- 运行所有相关测试（包括之前任务的测试，防止回归） - 所有测试必须通过 - 如果测试失败，修复实现代码（不是修改测试）直到通过 - 向用户展示测试通过的结果
5.4 REFACTOR - 重构优化
在测试保护下，改善代码质量。
- 代码审视
- 检查是否有重复代码可以提取 - 检查命名是否清晰准确 - 检查代码结构是否合理 - 检查是否符合项目规范
- 执行重构（如果需要）
- 提取公共方法/组件 - 改善命名和代码组织 - 优化性能（如有明显问题） - 添加必要的注释
- 运行测试，确认仍然通过
- 每次重构后都要运行测试 - 测试必须始终保持通过状态 - 如果测试失败，回退重构改动
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. 阶段性验证
当该阶段的所有任务完成后：
- 运行完整测试套件
- 运行该阶段所有任务的测试 - 确保所有测试通过 - 检查测试覆盖率（建议 > 80%）
- 集成测试
- 如果该阶段涉及多个模块，进行集成测试 - 验证模块间的协作是否正常
- 验收标准检查
- 对照需求文档的验收标准 - 检查该阶段完成的任务是否满足对应的 AC - 标记已满足的验收标准
- 代码质量检查
- 运行 Linter（ESLint/Prettier） - 运行类型检查（TypeScript） - 检查是否有代码异味
- 生成阶段完成报告
- 包含测试结果和覆盖率 - 包含验收标准检查结果
7. 更新任务状态
- 在任务规划文档中，将已完成的任务标记为
[x] - 更新验收标准检查清单的状态
- 保存更新后的文档
8. 生成完成报告
- 读取
assets/stage-completion-report-template.md作为模板 - 填充实际的完成信息：
- 功能名称和阶段信息 - 已完成的任务列表（包含测试文件和测试结果） - TDD 循环记录（每个任务的 RED -> GREEN -> REFACTOR 过程） - 文件变更清单 - 测试结果和覆盖率 - 验收标准检查结果 - 遇到的问题和解决方案 - 下一步建议
- 保存报告到
docs/开发记录/[功能名]_阶段[N]_完成报告.md - 在对话中向用户展示报告摘要
关键规则
规则 1：严格遵守任务规划
- 不要跳过任务
- 不要改变任务顺序（除非依赖关系允许）
- 不要做任务规划之外的事情
规则 2：代码复用优先
在编写新代码前，必须：
- 检查项目中是否有类似的实现
- 检查是否有可复用的组件、工具函数
- 遵循项目现有的代码模式和风格
规则 3：TDD 铁律
每个任务必须严格遵循 Red-Green-Refactor 循环，不可跳步：
- 不写没有测试的实现代码 — 每一行实现代码都由一个失败的测试驱动出来
- 不写超出测试范围的代码 — 只写让当前测试通过所需的最少代码
- RED 必须真红 — 测试必须因为"功能未实现"而失败，不是因为语法错误或环境问题
- GREEN 必须刚好绿 — 通过测试后立即停止编码，进入重构阶段
- REFACTOR 不改行为 — 重构只改结构不改功能，测试必须始终通过
- 测试文件与源文件对应 — 如
user.js->user.test.js - 每个测试只验证一个行为 — 保持测试的原子性和可读性
违反检查清单（出现以下情况必须停止并修正）：
- 写了实现代码但没有先写测试 -> 回退，先补测试
- 测试在没有实现的情况下就通过了 -> 测试无效，重写测试
- 重构后测试失败了 -> 回退重构改动
规则 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）
注意事项
- 不要一次性完成所有阶段：每次只执行用户指定的阶段，避免一次性生成过多代码
- 保持增量式开发：每个任务内部遵循 TDD 小循环，每个阶段完成后做阶段性验证
- 测试先行不可妥协：即使用户催促，也不能跳过 RED 阶段直接写实现代码
- 尊重用户反馈：如果用户对某个任务的实现不满意，立即调整（但调整后仍需通过测试）
- 记录 TDD 过程：在完成报告中记录每个任务的 RED -> GREEN -> REFACTOR 过程
最终交付
- 完成指定阶段的所有代码
- 对应的测试文件
- 更新后的任务规划文档（任务状态已勾选）
- 阶段完成报告（含 TDD 循环记录和测试结果）