plan-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan issue — turn an issue into an implementation plan

将Issue转化为实施计划

Produce an implementation plan grounded in the current code. Output is a single markdown document the user reviews before implementation begins.

基于当前代码生成一份实施计划。输出为单一Markdown文档，供用户在开始实施前审阅。

Before You Start

开始前准备

```
gh
```
CLI authenticated (
```
gh auth status
```
).
Root
```
CLAUDE.md
```
— for architecture context and coding conventions.
Any scope-level
```
CLAUDE.md
```
for directories likely touched.
Recent ADRs (
```
docs/adr/
```
or equivalent) — past decisions constrain the plan.

```
gh
```
CLI已完成认证（执行
```
gh auth status
```
验证）。
根目录下的
```
CLAUDE.md
```
——用于获取架构背景与编码规范。
相关范围目录下的
```
CLAUDE.md
```
——针对可能涉及的目录。
近期的ADRs文档（位于
```
docs/adr/
```
或对应目录）——过往决策会对计划形成约束。

Step 1: read the issue

步骤1：阅读Issue

bash

ISSUE=<number>
gh issue view "$ISSUE" --comments

Extract:

Goal — what does "done" look like in user-visible terms?
Scope / non-scope — what's in, what's out?
Acceptance criteria — testable outcomes.
Hints — file paths, screenshots, error messages, linked PRs, mentioned subsystems.

If the issue is vague on any of these, ask the user before planning.

bash

ISSUE=<number>
gh issue view "$ISSUE" --comments

提取以下信息：

目标：从用户可见的角度，“完成”的标准是什么？
范围/非范围：哪些内容在任务范围内，哪些不在？
验收标准：可测试的成果。
提示信息：文件路径、截图、错误信息、关联的PR、提及的子系统。

如果Issue在上述任何方面描述模糊，请在制定计划前询问用户。

Step 2: map the codebase

步骤2：梳理代码库

Find where the work will land:

bash

undefined

确定工作涉及的代码位置：

bash

undefined

For each mentioned term, find candidate files

针对每个提及的术语，查找候选文件

for term in "{term1}" "{term2}"; do echo "=== $term ===" grep -rn "$term" src/ --include='.py' --include='.ts' --include='.js' --include='.go' --include='*.rs' | head -10 done

Identify neighbors — files that will likely change together

识别关联文件——可能需要一同修改的文件

git log --pretty=format: --name-only -200 | sort | uniq -c | sort -rn | head -30


For each candidate file, read enough to understand its responsibility.

git log --pretty=format: --name-only -200 | sort | uniq -c | sort -rn | head -30


针对每个候选文件，阅读足够内容以理解其职责。

Step 3: propose an approach

步骤3：提出实施方案

Consider 2–3 approaches before locking in. For each:

What it does — one paragraph.
Files added / modified — rough list.
Trade-offs — what you give up vs what you gain.
Risk — what could go wrong or block landing.

Pick one. Explain why in one sentence.

If all approaches have significant risk or the right choice isn't clear, present both approaches to the user and let them choose.

锁定方案前先考虑2-3种思路。针对每种思路：

方案内容：一段文字说明。
新增/修改文件：大致列表。
权衡点：放弃的内容与获得的收益对比。
风险：可能出现的问题或阻碍落地的因素。

选择一种方案，用一句话说明原因。

如果所有方案都存在重大风险，或无法明确正确选择，请向用户展示两种方案并让其选择。

Step 4: write the plan

步骤4：撰写计划

markdown

undefined

markdown

undefined

Implementation plan for #<issue-number>: <title>

#<issue-number>: <标题> 实施计划

Goal

目标

{one paragraph — what done looks like}

{一段文字——说明完成状态的标准}

Approach

实施方案

{one paragraph — the chosen approach and why, over alternatives}

{一段文字——说明选定的方案及优于其他方案的原因}

Files to change

待修改文件

File	Change	Why
`src/...`	New — ...	...
`src/...`	Modify function `X` to ...	...
`src/...`	Delete — superseded by new ...	...

文件	变更内容	原因
`src/...`	新增——...	...
`src/...`	修改函数 `X` 以实现...	...
`src/...`	删除——被新增的...替代	...

New tests

新增测试用例

Test	What it asserts
`tests/integration/...`	The happy path returns 200 with expected shape
`tests/integration/...`	Permission denied returns 403
`tests/unit/...`	Edge case: empty input returns validation error

测试用例	验证内容
`tests/integration/...`	正常路径返回200及预期格式
`tests/integration/...`	权限拒绝时返回403
`tests/unit/...`	边界情况：空输入返回验证错误

Steps (implementation order)

实施步骤（顺序）

Add the data layer change (
```
src/repositories/...
```
). Small, testable.
Add the service method using it. Unit tests for the service.
Add the controller / route exposing the service. Integration tests.
Update docs in
```
docs/...
```
referencing the new behavior.
Run
```
<lint command>
```
and
```
<test command>
```
before declaring done.

完成数据层变更（
```
src/repositories/...
```
）。规模小，可测试。
添加使用该数据层的服务方法，并为服务编写单元测试。
添加暴露该服务的控制器/路由，并编写集成测试。
更新
```
docs/...
```
中涉及新行为的文档。
完成前执行
```
<lint命令>
```
和
```
<测试命令>
```
。

Risks and mitigations

风险与缓解措施

Risk	Mitigation
A ripple-effect change to `<file>` breaks an unrelated feature	Search for callers of the changed function first (Phase 1 of impact-analyzer agent).
Migration on live data	Wrap in a guard; add a feature flag; roll out behind it.

风险	缓解措施
对 `<文件>` 的连锁变更破坏了无关功能	先搜索变更函数的调用者（impact-analyzer agent的第一阶段）。
线上数据迁移	加入防护机制；添加功能开关；在开关后逐步推出。

Out of scope

非范围内容

{Thing the issue hints at but we're not doing in this change} — {follow-up issue idea}
{Refactor that would be nice but compounds risk} — {separate PR}

{Issue中暗示但本次变更不涉及的内容} — {后续Issue建议}
{虽有益但会增加风险的重构工作} — {单独提交PR}

Open questions for the user

需用户确认的问题

{Ambiguity in the issue that needs a decision}
{Technical choice that depends on constraints not visible in the repo}

undefined

{Issue中存在的模糊点，需要决策}
{依赖仓库中未明确约束的技术选择}

undefined

Step 5: present the plan

步骤5：提交计划

Share the plan. The user either approves (and implementation starts), asks for changes, or pushes back on the approach. Do NOT write any code until the plan is approved.

分享计划。用户会选择批准（然后开始实施）、要求修改或反对方案。计划未获批准前请勿编写任何代码。

Verify

验证

bash

undefined

bash

undefined

Every file path mentioned in the plan exists (if it's a modify) or has a parent dir (if new)

确认计划中提及的所有文件路径（若为修改操作则文件需存在，若为新增操作则父目录需存在）

Copy the list of

src/...

paths from the plan into a check:

将计划中的

src/...

路径列表复制到以下检查中：

for p in src/foo/x.ts src/bar/y.ts; do if [[ "$p" == new ]]; then [ -d "$(dirname "$p")" ] || echo "PARENT MISSING: $p" else [ -f "$p" ] || echo "STALE: $p" fi done

undefined

for p in src/foo/x.ts src/bar/y.ts; do if [[ "$p" == new ]]; then [ -d "$(dirname "$p")" ] || echo "PARENT MISSING: $p" else [ -f "$p" ] || echo "STALE: $p" fi done

undefined

Common Mistakes

常见错误

Mistake	Correction
Planning without reading the code	The plan says "modify `src/users.ts` " but `users.ts` doesn't exist. Read files before naming them.
Choosing the first approach without considering alternatives	Briefly name 2–3 approaches so trade-offs are visible. Picking the only one you thought of hides the tradeoff.
Acceptance criteria copied verbatim from the issue without expanding	Issues often say "works correctly." Translate into testable, specific outcomes.
Starting to code before the user approves	Plans are cheap; wasted code is expensive. Get explicit approval on the plan.

错误	修正方法
未阅读代码就制定计划	计划中提到“修改 `src/users.ts` ”但 `users.ts` 不存在。命名文件前先阅读文件。
未考虑替代方案就选择第一个思路	简要列出2-3种方案，以便清晰看到权衡点。只选择想到的第一个方案会隐藏权衡信息。
直接复制Issue中的验收标准而未细化	Issue常只说“正常工作”。需将其转化为可测试的具体成果。
用户批准前就开始编写代码	计划成本低；浪费的代码代价高。需获得用户对计划的明确批准。

plan-issue

Original

Translation

Plan issue — turn an issue into an implementation plan

将Issue转化为实施计划

Before You Start

开始前准备

Step 1: read the issue

步骤1：阅读Issue

Step 2: map the codebase

步骤2：梳理代码库

For each mentioned term, find candidate files

针对每个提及的术语，查找候选文件

Identify neighbors — files that will likely change together

识别关联文件——可能需要一同修改的文件

Step 3: propose an approach

步骤3：提出实施方案

Step 4: write the plan

步骤4：撰写计划

Implementation plan for #<issue-number>: <title>

#<issue-number>: <标题> 实施计划

Goal

目标

Approach

实施方案

Files to change

待修改文件

New tests

新增测试用例

Steps (implementation order)

实施步骤（顺序）

Risks and mitigations

风险与缓解措施

Out of scope

非范围内容

Open questions for the user

需用户确认的问题

Step 5: present the plan

步骤5：提交计划

Verify

验证

Every file path mentioned in the plan exists (if it's a modify) or has a parent dir (if new)

确认计划中提及的所有文件路径（若为修改操作则文件需存在，若为新增操作则父目录需存在）

Copy the list of src/... paths from the plan into a check:

将计划中的src/...路径列表复制到以下检查中：

Common Mistakes

常见错误

Copy the list of
`src/...`
paths from the plan into a check:

将计划中的
`src/...`
路径列表复制到以下检查中：