agent-change-walkthrough

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate one coherent implementation story that explains how the code works end-to-end after the change.

生成一份连贯的实现说明故事，解释变更后代码端到端的工作逻辑。

Step 1: Capture implementation intent

步骤1：明确实现意图

Restate the requested change in plain language.

Include:

User problem being solved
Scope boundaries
Explicit non-goals

If requirements are ambiguous, state assumptions before proceeding.

用平实语言重述需求变更内容。

需包含：

待解决的用户问题
范围边界
明确的非目标项

如果需求存在歧义，先说明假设再继续后续流程。

Step 2: Build evidence from conversation + git

步骤2：从对话+git中收集依据

Collect both sources before writing:

Conversation context (planning input only)
- Requested outcome
- Constraints and acceptance criteria
- Domain context needed to interpret the code correctly
Git-based evidence (source of truth for output)
- Changed file list
- Full diff per changed file
- Relevant unchanged context needed to explain behavior

Use commands such as:

bash

git status --short
git diff --name-only
git diff -- <file>
git show -- <file>

Use history only when needed to disambiguate intent:

bash

git log --oneline -- <file>

Never include conversation process, investigation history, or request negotiation as walkthrough steps. The walkthrough must describe implementation behavior only.

编写前先收集两类来源信息：

对话上下文（仅规划类输入）
- 需求预期结果
- 约束条件和验收标准
- 正确解读代码所需的领域上下文
基于Git的证据（输出的可信来源）
- 变更文件列表
- 每个变更文件的完整diff
- 解释行为所需的相关未变更上下文

可使用以下命令：

bash

git status --short
git diff --name-only
git diff -- <file>
git show -- <file>

仅当需要明确意图时才查询历史记录：

bash

git log --oneline -- <file>

请勿将对话过程、调研历史或需求协商内容作为走查步骤，走查必须仅描述实现行为。

Step 3: Build the story stack

步骤3：搭建故事框架

Order story steps by dependency-first causality:

Introduce contracts/types/schemas/interfaces before showing call sites that use them
Introduce function/class definitions before showing new call paths that invoke them
Then continue in runtime flow order from trigger to final behavior

If runtime order and dependency order conflict, prefer dependency order and add one short transition sentence that reconnects to runtime flow.

Skip non-essential detail while preserving causal clarity.

按照依赖优先的因果顺序排列故事步骤：

先介绍契约/类型/模式/接口，再展示使用它们的调用点
先介绍函数/类定义，再展示调用它们的新调用路径
之后按照从触发到最终行为的运行时流顺序继续

如果运行时顺序和依赖顺序冲突，优先采用依赖顺序，再添加一句简短的过渡语句衔接回运行时流。

省略非必要细节，同时保留因果逻辑清晰度。

Step 4: Write each step as natural developer narrative

步骤4：将每个步骤编写为自然的开发者叙事

For each story step:

Use a clear step title that describes behavior (no file path in the heading)
Mark the step as
```
UNCHANGED CONTEXT
```
or
```
CHANGED
```
Place
```
Filename: 
```
<relative/path/to/file.ext:start_line>`` immediately above each snippet
Optionally place
```
Symbol: 
```
<function/method/class>`` above each snippet when useful
Show a short code snippet
For data-shape/model/API changes, include concrete example data (input/output or before/after payload) that uses realistic values
Explain the step in natural prose as a developer-to-developer walkthrough
Explain what this step causes next in the flow
Avoid forward references: do not use a field/type/function in a step before showing where it is defined or introduced

Avoid rigid template labels such as

Why this step exists:

Impact:

. Write readable, connected prose instead. Keep headings and narrative readable; put precise location in the snippet header.

When code changed, prefer mini-diff snippets:

diff

- old behavior
+ new behavior

When the change affects data shape or behavior, add a small

Example input/output

block after the code snippet to show realistic values flowing through the updated code.

Call out semantic effect per changed hunk.

每个故事步骤需满足：

使用描述行为的清晰步骤标题（标题中不要出现文件路径）
将步骤标记为
```
UNCHANGED CONTEXT
```
（未变更上下文）或
```
CHANGED
```
（已变更）
在每个代码片段上方紧邻位置标注
```
Filename: 
```
<relative/path/to/file.ext:start_line>``
有用的情况下可选择性在代码片段上方标注
```
Symbol: 
```
<function/method/class>``
展示简短的代码片段
针对数据结构/模型/API变更，包含使用真实值的具体示例数据（输入/输出或变更前后的负载）
用自然的书面语以开发者对开发者的走查形式解释步骤
说明该步骤在流程中触发的后续操作
避免前向引用：不要在步骤中使用尚未展示定义或引入位置的字段/类型/函数

避免使用生硬的模板标签，例如

为什么存在这个步骤:

或

影响:

，改为编写可读性强、衔接自然的文本。保持标题和叙述可读性强，将精确位置信息放在代码片段头部。

代码发生变更时，优先使用迷你diff片段：

diff

- old behavior
+ new behavior

如果变更影响数据结构或行为，在代码片段后添加小型的

输入/输出示例

块，展示流经更新后代码的真实值。

说明每个变更块的语义影响。

Step 5: Integrate analysis inline

步骤5：内嵌分析内容

Embed analysis at the relevant story step:

Trade-offs chosen at that step
Viable alternatives and why not chosen
Performance implications
Failure modes and compatibility risk

Use natural language callouts in prose; keep them concise and specific.

在对应的故事步骤中嵌入分析内容：

该步骤选择的方案权衡
可行的替代方案以及未选用的原因
性能影响
失败模式和兼容性风险

在正文中使用自然语言标注，保持内容简洁具体。

Step 6: End with concise close-out

步骤6：添加简洁的收尾内容

After the final story step, add a short close-out with:

What changed overall
Why behavior is now different
What to monitor or validate next

在最后一个故事步骤后，添加简短的收尾，包含：

整体变更内容
行为发生变化的原因
后续需要监控或验证的内容

Output contract

输出契约

Return this structure:

```
# Implementation Walkthrough
```
One brief setup paragraph (intent + scope)
Numbered story steps (
```
## Step 1
```
,
```
## Step 2
```
, ...)
```
## Final Outcome
```

返回以下结构：

```
# 实现走查
```
一段简短的开篇段落（意图+范围）
编号的故事步骤（
```
## 步骤1
```
、
```
## 步骤2
```
...）
```
## 最终结果
```

Output example

输出示例

Use this structure:

markdown

undefined

使用以下结构：

markdown

undefined

Implementation Walkthrough

实现走查

This change adds source-aware feature behavior for a new UI path while preserving the existing invocation flow.

本次变更为新的UI路径添加了源感知的功能行为，同时保留了现有调用流。

Step 1 — User click enters the feature entrypoint [UNCHANGED CONTEXT]

步骤1 — 用户点击进入功能入口 [UNCHANGED CONTEXT]

The runtime trigger is still the button click. That handler forwards the input into the existing feature path, so the change does not alter how execution begins.

Filename:

src/ui/button.ts:42

Symbol:

onClick

button.onClick = () => startFeature(input)

From here, control moves into

startFeature()

运行时触发仍然是按钮点击，处理程序会将输入转发到现有功能路径，因此本次变更不会改变执行的起始逻辑。

Filename:

src/ui/button.ts:42

Symbol:

onClick

button.onClick = () => startFeature(input)

从这里开始，控制权流转到

startFeature()

。

Step 2 — Entrypoint forwards to service [UNCHANGED CONTEXT]

步骤2 — 入口转发到服务 [UNCHANGED CONTEXT]

The orchestration layer remains unchanged and continues to delegate work to

run()

. This is important context because it means the new behavior is introduced deeper in the service layer, not at the boundary.

Filename:

src/feature/entry.ts:10

Symbol:

startFeature

export function startFeature(input: Input) {
  return run(input)
}

That keeps the original control flow intact and localizes the behavior change.

编排层保持不变，仍然会将任务委托给

run()

，这个上下文很重要，说明新行为是在服务层更深处引入的，而非在边界层。

Filename:

src/feature/entry.ts:10

Symbol:

startFeature

export function startFeature(input: Input) {
  return run(input)
}

这保留了原始控制流的完整性，将行为变更的影响范围限制在局部。

Step 3 — Service return payload updated [CHANGED]

步骤3 — 服务返回负载已更新 [CHANGED]

This is the functional change: the service now includes source metadata in its return payload so downstream consumers can render source-specific UI behavior.

Filename:

src/feature/service.ts:88

Symbol:

run

diff

- return { state: "pending" }
+ return { state: "ready", source: "agent" }

Example input/output:

json

{
  "input": { "taskId": "t_123", "state": "pending" },
  "output_before": { "state": "pending" },
  "output_after": { "state": "ready", "source": "agent" }
}

The team chose to enrich the existing payload instead of creating a second metadata endpoint, which avoids an extra network hop and synchronization complexity. Performance impact here is negligible because no additional I/O is introduced, but there is a compatibility risk for legacy consumers that assume the old payload shape.

这是功能性变更：服务现在会在返回负载中包含源元数据，因此下游消费者可以渲染源特定的UI行为。

Filename:

src/feature/service.ts:88

Symbol:

run

diff

- return { state: "pending" }
+ return { state: "ready", source: "agent" }

输入/输出示例：

json

{
  "input": { "taskId": "t_123", "state": "pending" },
  "output_before": { "state": "pending" },
  "output_after": { "state": "ready", "source": "agent" }
}

团队选择丰富现有负载而非创建第二个元数据接口，这避免了额外的网络跳转和同步复杂度。此处性能影响可以忽略，因为没有引入额外的I/O，但对于假设旧负载结构的旧版消费者存在兼容性风险。

Step 4 — UI consumes enriched payload [CHANGED]

步骤4 — UI消费丰富后的负载 [CHANGED]

Rendering now branches on the new

source

field, which is what makes the feature visible to users. This step is where the service-layer change becomes observable behavior.

Filename:

src/ui/render.ts:120

Symbol:

renderState

if (data.source === "agent") {
  showAgentState()
}

At this point the flow reaches the updated UI outcome.

渲染逻辑现在会基于新增的

source

字段分支，这就是用户可以感知到新功能的原因，服务层的变更在这一步成为可观测的行为。

Filename:

src/ui/render.ts:120

Symbol:

renderState

if (data.source === "agent") {
  showAgentState()
}

至此流程到达更新后的UI输出结果。

Final Outcome

最终结果

The feature still starts at the same runtime trigger and follows the same orchestration path, but the changed service payload now drives source-aware rendering. Next validation should confirm that legacy consumers handle the added

source

field safely.

undefined

功能仍然从相同的运行时触发启动，遵循相同的编排路径，但修改后的服务负载现在会驱动源感知渲染。后续验证需要确认旧版消费者可以安全处理新增的

source

字段。

undefined

Validation and exit criteria

验证和退出标准

Complete only when all checks pass:

Story begins at runtime trigger and ends at final observable behavior.
Every changed file appears in at least one
```
CHANGED
```
story step.

Every snippet header uses

Filename: relative/path/to/file.ext:start_line

format.

No forward references: definitions/contracts appear before usages that depend on them.
Unchanged-but-critical context appears in
```
UNCHANGED CONTEXT
```
steps.
Each changed hunk includes reason + behavioral effect.
Data-shape/model/API changes include concrete example input/output with realistic values.
Trade-offs, alternatives, performance notes, and risk notes appear at relevant steps.
Facts are distinguished from inference.
Unknowns are explicitly labeled.
Conversation process/history does not appear as a walkthrough step.
No claim of validation is made unless validation was actually performed.

If any criterion fails, state what is missing and continue refining before finalizing.

所有检查通过后方可完成：

故事从运行时触发开始，到最终可观测行为结束。
每个变更文件至少出现在一个
```
CHANGED
```
故事步骤中。

每个代码片段头部都使用

Filename: relative/path/to/file.ext:start_line

格式。

无前置引用：定义/契约出现在依赖它们的用法之前。
关键的未变更上下文出现在
```
UNCHANGED CONTEXT
```
步骤中。
每个变更块都包含原因和行为影响说明。
数据结构/模型/API变更包含带真实值的具体输入/输出示例。
方案权衡、替代选项、性能说明和风险说明出现在对应步骤中。
事实和推断已区分。
未知项已明确标注。
对话过程/历史没有作为走查步骤出现。
除非实际执行了验证，否则不主张已完成验证。

如果任何标准未满足，说明缺失的内容，继续优化后再最终输出。