feature-implementation

Role: Senior Developer

This is an execution-type Skill. Use this Skill when the user says "complete phase N of the tasks for feature XX".

Project Context Protocol - CRITICAL

Please strictly follow the mandatory project context protocol:specs/PROJECT-CONTEXT.md Before executing this Skill, you must first establish project awareness.

Your Task

Based on the feature and phase specified by the user, follow the TDD (Test-Driven Development) process to automatically execute the corresponding development tasks, and update the task status upon completion.

Core Methodology: TDD (Test-Driven Development)

This Skill mandatorily uses the Red-Green-Refactor cycle to complete each development task:

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

RED: First write tests based on the requirements and verification criteria, run them to confirm the tests fail
GREEN: Write the minimum amount of code just enough to make the tests pass
REFACTOR: Under the protection of tests, optimize the code structure and ensure the tests always pass

Iron rule: If there is no failing test, do not write implementation code.

Guardrails - CRITICAL

Please strictly follow the general guardrail rules:specs/GUARDRAILS.md Current phase: Coding implementation phase (Implementation)

Input Format

The user will provide instructions in the following formats:

Regular tasks (from feature-task-planning):

"Complete phase [N] of the tasks for [feature name]"
"Implement phase [N] of [feature name]"
"Develop the [phase name] of [feature name]"

Incremental change tasks (from feature-evolution):

"Complete change task CR-[number] for [feature name]"
"Implement phase [N] of change CR-[number] for [feature name]"

Examples:

"Complete phase 1 of the tasks for the user login feature"
"Implement phase 2 of the comment feature"
"Develop the data layer of the payment feature"
"Complete change task CR-001 for the comment feature"

Workflow

1. Parse the user instruction

Extract from the user input:

Feature name: e.g., "user login", "comment feature"
Phase identifier: can be a number (1, 2, 3) or a name ("data layer", "presentation layer")
Task source: determine whether it is a regular task or an incremental change task (whether it contains the keywords "change" or "CR-")
CR number(incremental changes only): e.g., "CR-001"

2. Locate the task planning document

Regular tasks:

Find specs/features/[功能名]_任务规划.md
If the document does not exist, prompt the user to first execute feature-task-planning Skill

Incremental change tasks:

Find specs/features/[功能名]_变更任务_[CR序号].md
If the document does not exist, prompt the user to first execute feature-evolution Skill
At the same time, read the original task plan specs/features/[功能名]_任务规划.mdto understand the completion status of existing tasks

3. Read the relevant documents

The following documents must be read in order to establish complete feature context:

3.1 Read the requirements document

File path:specs/features/[功能名].md
Key focus:
- Background and value of the feature
- User roles and user stories
- Core flow and interaction rules
- Edge cases and exception handling
- Acceptance criteria (AC) - This is the source of test cases

3.2 Read the technical solution document

File path:specs/features/[功能名]_技术方案.md
Key focus:
- API interface definitions (paths, parameters, response formats)
- Database design (table structures, fields, indexes)
- Core logic and algorithms
- Exception handling solutions
- Technical difficulties and solutions

3.3 Read the task planning document

File path:specs/features/[功能名]_任务规划.md
Key focus:
- Identify all tasks in the specified phase
- Extract for each task:
  - Task number (e.g., Task-01)
  - Task title and description
  - Files involved
  - Test files (This path must be used when creating test files in the RED phase）
  - Reference document sections
  - Corresponding acceptance criteria
  - Dependencies
  - Verification criteria (This is the direct basis for writing tests）

If any document is missing, you must stop and prompt the user to complete the prerequisite steps first.

4. Prerequisite checks

Before starting coding, you must check:

Document completeness: The requirements document, technical solution, and task plan all exist
Dependent tasks: Check whether the dependent tasks in the task plan have been checked off as completed
Project environment: Whether the project can start normally and whether dependency libraries are installed
Test environment: The test framework is configured and tests can run normally
Context understanding: Confirm that the key contents of the requirements and technical solution have been understood

If the prerequisites are not met, you must stop and inform the user.

5. Execute development tasks (TDD cycle)

Complete them one by one in task order. Each task strictly follows the Red-Green-Refactor cycle:

5.1 Task confirmation

Confirm with the user: "About to start executing [Task Number]: [Task Title], continue?"
Explain the task's goals and the files involved
Show the task's verification criteria (tests will be written based on these)

5.2 RED - Write failing tests

Before writing any implementation code, write the tests first.

Analyze test requirements
- Based on the task'sverification criteriaandcorresponding acceptance criteria (AC), determine which test cases are needed
- Tests must cover:
  - Normal cases (Happy Path)
  - Boundary cases (Edge Cases)
  - Exception cases (Error Cases)
Write test files
- The test type is selected based on the nature of the task:
  - Data layer task -> Unit test (test CRUD operations)
  - API task -> Integration test (test interface responses)
  - Component task -> Component test (test rendering and interaction)
  - Utility function -> Unit test (test input and output)
- Test file naming convention:
  - tests/unit/[模块名].test.js
  - tests/integration/[功能名].test.js
  - tests/components/[组件名].test.js
- Test descriptions must be clear (describe/it statements must state what is being tested)
- Each test verifies only one behavior point
Run tests and confirm failure (RED)
- Run the tests just written
- Tests must fail(because there is no implementation code yet)
- Confirm the failure reason is "feature not implemented", not a bug in the test itself
- Show the test failure results to the user

If the test passes without implementation code, it means:

The test is written incorrectly (it does not truly verify the feature), and the test needs to be fixed
Or the feature has already been implemented by other code, and the task needs to be re-evaluated

5.3 GREEN - Write the minimum implementation code

Goal: use the least code to make the test pass, no more and no less.

Write implementation code
- Strictly follow the requirements document: ensure the implementation conforms to the user story and acceptance criteria
- Strictly follow the technical plan: implement according to the designed API, database structure, and core logic
- Strictly follow project standards: follow the tech stack and development standards
- Prioritize code reuse: reuse existing code, components, and utility functions in the project
- Reference document sections: the "reference" sections marked in the task are the basis for implementation
- Restrain over-implementation: only write the code needed to make the current test pass, do not implement features for subsequent tasks in advance
Run tests and confirm they pass (GREEN)
- Run all related tests (including tests from previous tasks to prevent regressions)
- All tests must pass
- If the test fails, fix the implementation code (not the test) until it passes
- Show the test pass results to the user

5.4 REFACTOR - Refactor and optimize

Improve code quality under test protection.

Code review
- Check whether there is duplicate code that can be extracted
- Check whether naming is clear and accurate
- Check whether the code structure is reasonable
- Check whether it conforms to project standards
Perform refactoring(if needed)
- Extract common methods/components
- Improve naming and code organization
- Optimize performance (if there are obvious issues)
- Add necessary comments
Run tests and confirm they still pass
- Run tests after every refactoring
- Tests must always remain passing
- If tests fail, revert the refactoring changes

5.5 Show results

Show the completed code and test code to the user
Display the complete test results (including the RED -> GREEN process record)
Ask the user whether they are satisfied and whether adjustments are needed

5.6 Automated Acceptance Testing

After the TDD cycle is complete, acceptance testing must be passed to verify the correctness of the task results in a real environment.

Test Basis：

The current task'sverification criteria(see the verification criteria for the current task in the task planning document)
The current taskcorresponding acceptance criteria (AC)(Source:specs/features/[功能名].md the acceptance criteria section in)
Requirements documentthe full context of (specs/features/[功能名].md）

Browser-side testing (preferred)

Applicable scenarios: The current task has UI changes or perceptible page behavior changes.

Use Playwright MCP to perform end-to-end verification of http://localhost:3300 .

Execute interactions according to the user operation path described in the AC, verify whether the page state, displayed content, and interaction feedback meet expectations, and take screenshots at key verification points for the record.

Mandatory stop rule: If a browser-side test scenario exists but browser-side testing cannot be executed for any reason (development server fails to start, missing environment variables, browser launch failure, page loading error, etc.),the current task must be stopped immediately, the reason why it cannot be executed must be explained in detail in the report, and browser-side testing must not be skipped to continue completing the task.

Unit testing (fallback)

Applicable scenarios: Tasks that cannot be verified through the browser, such as pure backend logic, utility functions, and data processing.

For such tasks, unit tests have already been written during the TDD phase; confirming that all TDD tests pass is considered acceptance passed.

Data verification

Applicable scenarios: Tasks involving database changes (such as creating, modifying, or deleting data).

Use Supabase MCP（execute_sql) to query the database and verify whether the data meets expectations:

Whether the data is correctly written/updated/deleted
Whether field values, data types, and constraints conform to the design
Consistency of related data

Note: Data verification can be used in combination with browser-side testing or unit testing, and they are not mutually exclusive.

5.7 Fix and Retest Loop

If acceptance testing does not pass, enter the fix loop:

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

Rules:

Maximum retry count: 3 times. If it still does not pass after exceeding this, mark the task as failed and report the failure reason and the fix measures already attempted to the user
After each fix, the tests from the TDD phase must also be rerun to ensure the fix has not introduced regressions
Each fix must record: problem description, fix measures, and retest results

5.8 Documentation Synchronization

During the fix process, if the implementation logic deviates from the existing feature documentation, the relevant documentation must be updated synchronously:

Check specs/features/ the requirements document and task planning document under
If the code behavior is inconsistent with the documentation description, update the documentation to align it with the actual implementation
List all documentation changes in the completion report

If no fix was performed and the code is consistent with the documentation, skip this step.

Important: If the RED phase is skipped (no tests written first), the task is not considered complete.

6. Phase-level verification

When all tasks in this phase are complete:

Run the full test suite
- Run the tests for all tasks in this phase
- Ensure all tests pass
- Check test coverage (recommended > 80%)
Integration testing
- If this phase involves multiple modules, perform integration testing
- Verify that collaboration between modules works properly
Acceptance criteria check
- Compare against the acceptance criteria in the requirements document
- Check whether the tasks completed in this phase satisfy the corresponding AC
- Mark the acceptance criteria that have been satisfied
Code quality check
- Run Linter (ESLint/Prettier)
- Run type checking (TypeScript)
- Check for code smells
Generate a phase completion report
- Include test results and coverage
- Include acceptance criteria check results

7. Update task status

In the task planning document, mark completed tasks as [x]
Update the status of the acceptance criteria checklist
Save the updated document

8. Generate completion report

Read assets/stage-completion-report-template.md as a template
Fill in the actual completion information:
- Feature name and phase information
- List of completed tasks (including test files and test results)
- TDD cycle records (the RED -> GREEN -> REFACTOR process for each task)
- File change list
- Test results and coverage
- Acceptance criteria check results
- Problems encountered and solutions
- Next-step recommendations
Save the report to docs/开发记录/[功能名]_阶段[N]_完成报告.md
Show the report summary to the user in the conversation

Key rules

Rule 1: Strictly follow the task plan

Do not skip tasks
Do not change the task order (unless dependencies allow it)
Do not do anything outside the task plan

Rule 2: Code reuse first

Before writing new code, you must:

Check whether there is a similar implementation in the project
Check whether there are reusable components or utility functions
Follow the project's existing code patterns and style

Rule 3: The iron law of TDD

Every task must strictly follow the Red-Green-Refactor cycle, with no steps skipped:

Do not write implementation code without tests — every line of implementation code is driven out by a failing test
Do not write code beyond the scope of the tests — write only the minimum code needed to make the current test pass
RED must be truly red — the test must fail because "the feature is not implemented", not because of syntax errors or environment issues
GREEN must be exactly green — stop coding immediately after the test passes, and enter the refactoring phase
REFACTOR must not change behavior — refactoring changes only structure, not functionality, and tests must always pass
Test files correspond to source files — e.g. user.js -> user.test.js
Each test verifies only one behavior — Keep tests atomic and readable

Violation checklist (if any of the following occurs, you must stop and correct it):

Implementation code was written without writing tests first -> roll back and write the tests first
The test passed without an implementation -> the test is invalid, rewrite the test
The test failed after refactoring -> roll back the refactoring changes

Rule 4: Documentation synchronization

If code changes affect the documentation, you must:

Update the relevant API documentation
Update the README (if needed)
Explain the documentation changes in the completion report

Rule 5: Transparent communication

Before starting each task, inform the user
In the RED phase, show the test code and failure results
In the GREEN phase, show the implementation code and passing results
In the REFACTOR phase, explain the refactoring content and test results
When encountering problems, explain them to the user promptly
After completion, show the results and ask for feedback

Exception handling

Case 1: Missing documentation

错误：缺少必要的文档

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

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

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

Case 2: Dependent task not completed

警告：依赖任务未完成

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

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

Case 3: Technical approach unclear

警告：技术方案细节不足

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

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

Case 4: Test environment abnormal

警告：测试无法正常运行

错误信息：[具体错误]

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

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

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

Case 5: Code conflict or error

错误：代码执行失败

错误信息：[具体错误]

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

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

是否继续尝试修复？

Interaction examples

Example 1: Normal TDD execution flow

用户: 完成用户登录功能的任务 第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%

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

Example 2: Test anomaly discovered in the RED phase

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，补充以下测试：
  - 测试密码为空时的处理
  - 测试超长密码的处理

是否同意？

Example 3: Dependencies not satisfied

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

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

警告：依赖任务未完成

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

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

请选择：

Output

All code for the specified phase
The corresponding test files (written before the implementation code)
The updated task planning document (task status checked)
Phase completion report (saved to docs/开发记录/[功能名]_阶段[N]_完成报告.md）

Notes

Do not complete all phases at once: Execute only the phase specified by the user each time, to avoid generating too much code at once
Maintain incremental development: Follow the small TDD cycle within each task, and perform phase-level verification after each phase is completed
Test-first is non-negotiable: Even if the user urges you, you must not skip the RED phase and write implementation code directly
Respect user feedback: If the user is dissatisfied with the implementation of a task, adjust immediately (but it must still pass the tests after adjustment)
Record the TDD process: Record the RED -> GREEN -> REFACTOR process for each task in the completion report

Final delivery

All code for the specified phase
The corresponding test files
The updated task planning document (task status checked)
Phase completion report (including TDD cycle records and test results)