linear-walkthrough

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linear Code Walkthrough

线性代码走查

Generate a linear, step-by-step markdown walkthrough that explains how code works. Output is GitHub-flavored markdown that can be rendered as a self-contained HTML page.

生成线性的、分步的Markdown代码走查内容，解释代码的工作原理。输出为GitHub风格的Markdown，可渲染为独立的HTML页面。

Detail Level

细节级别

If in an interactive session (not piped/scripted), use AskUserQuestion to ask the detail level before writing:

Brief — The user already knows the domain. Keep explanations short, focus on structure and key decisions. Minimal prose, mostly code snippets with short annotations.
In-depth — The user wants thorough understanding. Explain design decisions, trade-offs, how pieces connect, and why things are done a certain way.
Beginner-friendly — The user is new to this topic. Explain concepts as you go, define jargon, add context a newcomer would need. Enough depth to actually teach the topic, not just show the code.

If the user specifies a level in their request (e.g. "give me a quick walkthrough"), skip the question and use that level.

如果是交互式会话（非管道/脚本执行），在撰写前使用AskUserQuestion询问用户所需的细节级别：

简要 — 用户已熟悉相关领域。保持解释简洁，重点关注结构和关键决策。尽量减少文字描述，主要使用代码片段加简短注释。
深入 — 用户希望全面理解内容。解释设计决策、权衡方案、各部分的关联以及选择特定实现方式的原因。
新手友好 — 用户是该领域的初学者。随文解释概念，定义专业术语，补充新手所需的背景知识。内容深度需达到能够真正教授相关主题的程度，而非仅展示代码。

如果用户在请求中指定了级别（例如“给我一个快速的走查”），则跳过询问直接使用该级别。

Modes

模式

1. Codebase Walkthrough

1. 代码库走查

When asked to explain a codebase, module, or feature:

Read the relevant source files
Ask detail level (if interactive)
Plan a linear narrative: entry point -> core logic -> supporting pieces
Write the walkthrough markdown file
Suggest visualization

当需要解释代码库、模块或功能时：

阅读相关源文件
询问细节级别（如果是交互式会话）
规划线性叙事结构：入口点 -> 核心逻辑 -> 支持组件
撰写走查Markdown文件
建议可视化方案

2. Pull Request Walkthrough

2. 拉取请求（PR）走查

When given a PR (URL or number):

Fetch the PR diff and source using
```
gh
```
Read the changed files and understand the full context
Ask detail level (if interactive)
Write the walkthrough markdown file
Reply with the content (do NOT commit)

当提供PR（URL或编号）时：

使用
```
gh
```
获取PR差异和源文件
阅读变更文件并理解完整上下文
询问细节级别（如果是交互式会话）
撰写走查Markdown文件
返回内容（请勿提交）

Writing the Walkthrough

撰写走查内容

Format: GitHub-flavored markdown (GFM)

Structure: Follow a linear narrative. Start from the entry point and walk through the code in the order it executes or in logical dependency order.

Rules:

Include actual code snippets using fenced code blocks with language tags
Use
```
grep
```
,
```
sed
```
,
```
cat
```
, or read tools to extract real snippets -- never fabricate code
Use Mermaid.js diagrams (
```
```mermaid
```
) for architecture, data flow, or request lifecycle visualizations
Name the file something relevant (e.g.,
```
auth-flow-walkthrough.md
```
,
```
api-design-walkthrough.md
```
) unless the user specifies a name
Do NOT commit the walkthrough file unless explicitly asked

Code block source links:

Every code snippet MUST have a source link immediately above or below the fenced block so readers can jump to the original.

Remote PR walkthrough: Link to the file on GitHub at the PR's head commit with line range. Format:

[path/to/file.py#L10-L25](https://github.com/OWNER/REPO/blob/HEAD_SHA/path/to/file.py#L10-L25)

Get the head SHA via

gh pr view NUMBER --json headRefOid -q .headRefOid

Local codebase walkthrough: Link using the
```
vscode://
```
protocol so clicking opens the file in VS Code at the right line. Format:
```
[path/to/file.py:10-25](vscode://file/absolute/path/to/file.py:10:1)
```
The
```
vscode://file/PATH:LINE:COLUMN
```
URI opens the file in VS Code. Use line range in the link text for readability.

Template structure:

markdown

undefined

格式： GitHub风格Markdown（GFM）

结构： 遵循线性叙事。从入口点开始，按照代码执行顺序或逻辑依赖顺序逐步讲解。

规则：

使用带语言标签的围栏代码块包含实际代码片段
使用
```
grep
```
、
```
sed
```
、
```
cat
```
或读取工具提取真实片段——切勿编造代码
使用Mermaid.js图表（
```
```mermaid
```
）展示架构、数据流或请求生命周期
为文件命名相关的名称（例如
```
auth-flow-walkthrough.md
```
、
```
api-design-walkthrough.md
```
），除非用户指定名称
除非明确要求，否则请勿提交走查文件

代码块源链接：

每个代码片段必须在围栏块的上方或下方添加源链接，以便读者跳转到原始位置。

远程PR走查： 链接到GitHub上PR头部提交对应的文件及行范围。格式：

[path/to/file.py#L10-L25](https://github.com/OWNER/REPO/blob/HEAD_SHA/path/to/file.py#L10-L25)

通过

gh pr view NUMBER --json headRefOid -q .headRefOid

获取头部提交SHA

本地代码库走查： 使用
```
vscode://
```
协议，点击链接可在VS Code中打开对应行的文件。格式：
```
[path/to/file.py:10-25](vscode://file/absolute/path/to/file.py:10:1)
```
```
vscode://file/PATH:LINE:COLUMN
```
URI可在VS Code中打开文件。链接文本中使用行范围以提升可读性。

模板结构：

markdown

undefined

[Topic]: Walkthrough

[主题]: 走查

[1-2 sentence summary of what this walkthrough covers]

[1-2句话总结本走查涵盖的内容]

Entry Point: [filename/function]

入口点: [文件名/函数]

[Explanation of where everything starts]

src/main.py:10-18

python

[actual code snippet from the codebase]
`` `

[解释一切的起始位置]

src/main.py:10-18

python

[来自代码库的实际代码片段]

[Next Logical Step]

[下一个逻辑步骤]

[Explanation continuing the narrative]

src/handler.py:5-12

python

[code snippet]
`` `

[继续叙事的解释]

src/handler.py:5-12

python

[代码片段]

[Continue as needed...]

[根据需要继续...]

[Use mermaid diagrams where they help:]

mermaid

graph LR
    A[Request] --> B[Router]
    B --> C[Handler]
    C --> D[Database]
`` `

[在有帮助的地方使用Mermaid图表:]

mermaid

graph LR
    A[Request] --> B[Router]
    B --> C[Handler]
    C --> D[Database]

Summary

总结

Component	File	Purpose
...	...	...

undefined

组件	文件	用途
...	...	...

undefined

For Pull Requests

针对拉取请求（PR）

Use

gh

to fetch PR details:

bash

gh pr view NUMBER --json title,body,files,additions,deletions
gh pr diff NUMBER

Get the merge base commit SHA for GitHub permalinks:

bash

gh pr view NUMBER --json baseRefOid,headRefOid

Then follow the same walkthrough structure, focusing on what the PR changes and why.

PR-specific additions:

Start with a full GitHub PR URL link:
```
[PR #123: Title](https://github.com/OWNER/REPO/pull/123)
```
— this format (
```
https://github.com/OWNER/REPO/pull/NUMBER
```
) is required so the interactive server can auto-detect and fetch the PR diff for follow-up context.
Follow with a summary of the PR's purpose
Walk through changes in logical order (not file order)
Highlight the key design decisions
Note any potential concerns or trade-offs

使用

gh

获取PR详情:

bash

gh pr view NUMBER --json title,body,files,additions,deletions
gh pr diff NUMBER

获取GitHub永久链接的合并基准提交SHA:

bash

gh pr view NUMBER --json baseRefOid,headRefOid

然后遵循相同的走查结构，重点关注PR的变更内容及原因。

PR专属补充内容:

以完整的GitHub PR URL链接开头:
```
[PR #123: Title](https://github.com/OWNER/REPO/pull/123)
```
— 必须使用此格式 (
```
https://github.com/OWNER/REPO/pull/NUMBER
```
)，以便交互式服务器自动检测并获取PR差异用于后续上下文。
跟随PR的用途总结
按照逻辑顺序（而非文件顺序）讲解变更
突出关键设计决策
记录任何潜在问题或权衡方案

After Generating

生成后操作

After writing the walkthrough file, tell the user:

Walkthrough saved to
[filename]
. To visualize it as a styled HTML page:
bash
uvx linear-walkthrough [filename] --serve
Or generate a static HTML file:
bash
uvx linear-walkthrough [filename] -o walkthrough.html

For PR walkthroughs, suggest

--serve

with

--pr

so the interactive server seeds Claude with the full PR diff and metadata for better follow-up answers:

bash
uvx linear-walkthrough [filename] --serve --pr owner/repo#123
The
--pr
flag fetches PR info and diff via
gh
CLI and includes it in the Claude seed context. If omitted, the server auto-detects GitHub PR URLs from the markdown content.

Do NOT run

uvx linear-walkthrough --serve

automatically -- let the user choose.

撰写完走查文件后，告知用户:

走查已保存至
[filename]
。如需将其可视化为带样式的HTML页面:
bash
uvx linear-walkthrough [filename] --serve
或生成静态HTML文件:
bash
uvx linear-walkthrough [filename] -o walkthrough.html

对于PR走查，建议使用

--serve

搭配

--pr

参数，以便交互式服务器通过Claude的种子上下文获取完整的PR差异和元数据，提升后续回答质量:

bash
uvx linear-walkthrough [filename] --serve --pr owner/repo#123
--pr
参数通过
gh
CLI获取PR信息和差异，并将其包含在Claude的种子上下文中。如果省略该参数，服务器会自动从Markdown内容中检测GitHub PR URL。

请勿自动运行

uvx linear-walkthrough --serve

— 让用户自行选择。