piv-implement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Execute: Implement from Plan

执行：从计划到实施

Plan to Execute

待执行计划

Read plan file:

$ARGUMENTS

读取计划文件：

$ARGUMENTS

Before you start — work on a feature branch

开始前——在功能分支上工作

A ticket gets built on its own branch, so it can become one PR. Ideally you're already on that branch — cut it before planning — so the plan commit you made is on it and rides into the PR; a plan committed on the base branch won't be in this branch's PR. If you're still on base, this step creates the branch now. Detect the base branch (don't hardcode

main

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

(fallback

main

On the base branch, clean → create one:
```
git checkout -b feature/<plan-slug>
```
.
Already on a feature branch or in a worktree → use it.
On the base branch with uncommitted changes → STOP: commit or stash first.

(One branch per ticket is also what makes parallel worktrees clean later.)

每个工单都在独立分支上开发，最终可合并为一个PR。理想情况下你已经处于该分支——在规划前就创建好分支——这样你提交的计划会包含在分支中并进入PR；如果计划提交在基础分支上，那么它不会出现在此分支的PR中。如果你仍在基础分支上，此步骤会立即创建分支。自动检测基础分支（不要硬编码

main

）：

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

（默认 fallback 为

main

）。

当前在基础分支且工作区干净 → 创建分支：
```
git checkout -b feature/<plan-slug>
```
。
已在功能分支或工作树中 → 直接使用当前分支。
当前在基础分支且有未提交的更改 → 停止：先提交或暂存更改。

（每个工单对应一个分支也能让后续并行工作树保持整洁。）

Execution Instructions

执行说明

1. Read and Understand

1. 阅读与理解

Read the ENTIRE plan carefully
Understand all tasks and their dependencies
Note the validation commands to run
Review the testing strategy

仔细阅读完整计划
理解所有任务及其依赖关系
记录需要运行的验证命令
审核测试策略

2. Execute Tasks in Order

2. 按顺序执行任务

For EACH task in "Step by Step Tasks":

针对“分步任务”中的每一项任务：

a. Navigate to the task

a. 定位任务

Identify the file and action required
Read existing related files if modifying

明确需要操作的文件及动作
如果是修改操作，先阅读相关现有文件

b. Implement the task

b. 实现任务

Follow the detailed specifications exactly
Maintain consistency with existing code patterns
Include proper type hints and documentation
Add structured logging where appropriate

严格遵循详细规格要求
与现有代码模式保持一致
添加适当的类型提示和文档
在合适的位置添加结构化日志

c. Verify as you go

c. 逐步验证

After each file change, check syntax
Ensure imports are correct
Verify types are properly defined
Run the task's own
VALIDATE
command before starting the next task. Every task in the plan carries one. A task is not done until its check passes — if it fails, fix it now rather than carrying the failure forward. The full suite still runs at step 4; this is the per-task gate that keeps step 4 from becoming a pile-up.

每次文件修改后，检查语法正确性
确保导入语句正确
验证类型定义无误
在开始下一项任务前，运行当前任务对应的
VALIDATE
命令。计划中的每个任务都配有验证命令。只有验证通过，任务才算完成——如果验证失败，立即修复，不要带着问题继续推进。步骤4仍会运行完整验证套件，但这一步的单任务验证能避免步骤4出现大量问题堆积。

3. Implement Testing Strategy

3. 落实测试策略

After completing implementation tasks:

Create all test files specified in the plan
Implement all test cases mentioned
Follow the testing approach outlined
Ensure tests cover edge cases

完成所有实施任务后：

创建计划中指定的所有测试文件
实现计划中提及的所有测试用例
遵循计划中概述的测试方法
确保测试覆盖边缘场景

4. Run Validation Commands

4. 运行验证命令

Execute ALL validation commands from the plan in order:

bash

undefined

按顺序执行计划中的所有验证命令：

bash

undefined

Run each command exactly as specified in plan

严格按照计划中的指定命令执行


If any command fails:
- Fix the issue
- Re-run the command
- Continue only when it passes


如果任何命令失败：
- 修复问题
- 重新运行命令
- 只有验证通过后才能继续

5. Final Verification

5. 最终验证

Before completing:

✅ All tasks from plan completed
✅ All tests created and passing
✅ All validation commands pass
✅ Code follows project conventions
✅ Documentation added/updated as needed

完成前确认：

✅ 计划中的所有任务已完成
✅ 所有测试已创建并通过
✅ 所有验证命令执行通过
✅ 代码符合项目规范
✅ 已按需添加/更新文档

Output — write an implementation report

输出——撰写实施报告

Write a short report to

.claude/reports/<plan-slug>-report.md

(and print the summary). This is what the PR body and the

piv-review-pr

gate read — especially the deviations (a documented deviation is an intentional decision the reviewer should not flag):

markdown

undefined

将简短报告写入

.claude/reports/<plan-slug>-report.md

（并打印摘要）。这份报告是PR正文和

piv-review-pr

环节的依据——尤其要注意偏差说明（有文档记录的偏差是评审者无需标记的 intentional 决策）：

markdown

undefined

Implementation Report — <feature>

实施报告 —— <功能名称>

Plan: <path> Branch: <feature/...> Status: COMPLETE | PARTIAL

计划：<路径> 分支：<feature/...> 状态：已完成 | 部分完成

Summary

摘要

{What was built, 2-4 sentences.}

{已完成的内容，2-4句话。}

Tasks completed

已完成任务

[task] →
```
path/to/file
```
(CREATE/UPDATE)

[任务内容] →
```
path/to/file
```
（创建/更新）

Tests added

添加的测试

{Test files + cases + results.}

{测试文件 + 用例 + 结果。}

Validation results

验证结果

{Type-check / lint / tests / build — pass/fail with counts.}

{类型检查 / 代码检查 / 测试 / 构建 —— 结果（通过/失败）及数量。}

Deviations from the plan

与计划的偏差

{What changed vs the plan and WHY — or "none". This is the reviewer's signal of intent.}

{与计划不同的修改及原因 —— 或“无偏差”。这是给评审者的意图信号。}

Issues encountered

遇到的问题

{Anything notable, or "none".}

undefined

{任何值得注意的问题 —— 或“无”。}

undefined

Ready for the next step

准备进入下一步

Confirm all changes are complete and validations pass.
Next:
```
piv-commit
```
the work, then
```
piv-create-pr
```
to open the PR (the report fills the PR body), then
```
piv-review-pr
```
.

确认所有修改已完成且验证通过。
下一步：
```
piv-commit
```
提交工作，然后
```
piv-create-pr
```
创建PR（报告将填充PR正文），接着执行
```
piv-review-pr
```
。

Notes

注意事项

If you encounter issues not addressed in the plan, document them
If you need to deviate from the plan, explain why
If tests fail, fix implementation until they pass
Don't skip validation steps

如果遇到计划中未提及的问题，请记录下来
如果需要偏离计划，请说明原因
如果测试失败，修复实现直到测试通过
不要跳过验证步骤