deep-read

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Read — Codebase Reading Engine

Deep Read — 代码库阅读引擎

Systematic source-code-first analysis protocol. Reads implementations, not just interfaces. Every finding cites

file:line

Core principle: Source code is the source of truth. Documentation lies, comments rot, function names mislead. Read the actual code.

以源代码为优先的系统化分析协议。读取实现代码而非仅接口。每一项发现都标注

file:line

引用。

核心原则： 源代码是唯一可信来源。文档可能不实，注释会过时，函数名可能有误导性。请读取实际代码。

Protocol

执行协议

Process every

/deep-read

invocation through these 6 phases in strict order. Never skip a phase. Gate each phase: do not advance until the gate condition is met.

每次调用

/deep-read

都严格按照以下6个阶段执行。禁止跳过任何阶段。每个阶段都设有准入门槛：满足门槛条件后方可进入下一阶段。

Phase 1: SCOPE — Define the Reading Target

阶段1：范围界定（SCOPE）—— 定义阅读目标

Narrow the target to a tractable area before reading anything.

Parse
```
$ARGUMENTS
```
as the reading target (module, flow, question, or path)
Read CLAUDE.md and MEMORY.md for project context — but treat these as hints, not truth
Run initial discovery to estimate scope:
- ```
Glob
```
  for relevant file patterns (
```
**/*.ts
```
  ,
```
**/*.py
```
  , etc.)
- ```
Grep
```
  for key terms from the target description
- Count matching files
If scope exceeds 50 source files:
- Use
```
AskUserQuestion
```
  to narrow: which subsystem, which flow, which layer?
- Suggest specific narrowing options based on directory structure
If the target is a question (e.g., "how are commissions calculated?"):
- Translate to concrete search terms
- Grep for domain terms to locate relevant modules
If the target is a path (e.g.,
```
src/services/billing/
```
):
- List all files in the path
- Identify entry points (exported functions, route handlers, main files)

Output: A scope definition listing:

Target description (1-2 sentences)
File list (< 50 source files)
Identified entry points
Out-of-scope areas (explicitly noted)

Gate: Scope is defined and contains < 50 source files. Entry points identified. Proceed.

在开始阅读前先将目标缩小到可处理的范围。

将
```
$ARGUMENTS
```
解析为阅读目标（模块、流程、问题或路径）
读取CLAUDE.md和MEMORY.md获取项目上下文，但仅将这些内容作为参考提示，而非事实依据
执行初步探查评估范围：
- 用
```
Glob
```
  匹配相关文件模式（
```
**/*.ts
```
  、
```
**/*.py
```
  等）
- 用
```
Grep
```
  检索目标描述中的关键词
- 统计匹配的文件数量
如果范围超过50个源代码文件：
- 使用
```
AskUserQuestion
```
  缩小范围：询问要查看哪个子系统、哪个流程、哪个层级？
- 基于目录结构给出具体的范围缩小选项
如果目标是一个问题（例如："佣金是怎么计算的？"）：
- 转换为具体的搜索关键词
- 检索领域术语定位相关模块
如果目标是一个路径（例如：
```
src/services/billing/
```
）：
- 列出路径下的所有文件
- 识别入口点（导出函数、路由处理程序、主文件）

输出： 范围定义清单：

目标描述（1-2句话）
文件列表（少于50个源代码文件）
识别出的入口点
明确标注的排除范围

准入门槛： 范围已定义且包含少于50个源代码文件，入口点已识别。可进入下一阶段。

Phase 2: MAP — Build Structural Overview

阶段2：结构映射（MAP）—— 构建整体结构概览

Understand the shape of the code before reading it deeply.

Directory structure — map the relevant directories:
- Use
```
Glob
```
  to list files by type and directory
- Note the organizational pattern (by feature, by layer, by domain)
Tech stack — identify from configs (not from docs):
- Read
```
package.json
```
  ,
```
Cargo.toml
```
  ,
```
go.mod
```
  ,
```
requirements.txt
```
  , or equivalent
- Note frameworks, key dependencies, build tools
Entry points — verify by reading actual files (not just file names):
- Read route definitions, main files, exported modules
- Read the first 50 lines of each candidate entry point
- Confirm which files are actual entry points vs. helpers
Dependency graph — map internal imports within the scope:
- Grep for import/require statements within scoped files
- Build a mental model: what calls what, what depends on what
- Identify the core files (most imported by others)
Configuration and constants — read files that define behavior:
- Config files, environment schemas, constants, enums, types
- These shape behavior as much as code does

Launch parallel Explore agents for steps 2-4 if the scope has 20+ files.

Output: Structural map including:

Directory layout with annotations
Tech stack (from configs, not docs)
Entry points (verified by reading)
Dependency flow diagram (text-based)
Core files ranked by centrality

Gate: Entry points verified by reading actual files. Dependency flow mapped. Proceed.

在深度阅读前先理解代码的整体结构。

目录结构 —— 映射相关目录：
- 使用
```
Glob
```
  按类型和目录列出文件
- 记录组织模式（按功能、按层级、按领域）
技术栈 —— 从配置文件识别（而非从文档）：
- 读取
```
package.json
```
  、
```
Cargo.toml
```
  、
```
go.mod
```
  、
```
requirements.txt
```
  或等效配置文件
- 记录框架、核心依赖、构建工具
入口点 —— 通过读取实际文件验证（而非仅看文件名）：
- 读取路由定义、主文件、导出模块
- 读取每个候选入口点的前50行
- 确认哪些是实际入口点，哪些是辅助文件
依赖图 —— 映射范围内的内部导入关系：
- 检索范围内文件的import/require语句
- 构建心智模型：调用关系、依赖关系
- 识别核心文件（被其他文件引用最多的文件）
配置和常量 —— 读取定义行为的文件：
- 配置文件、环境变量 schema、常量、枚举、类型定义
- 这些内容和代码本身一样决定了系统行为

如果范围包含20个以上文件，可为步骤2-4启动并行的Explore Agent。

输出： 结构映射包括：

带注释的目录布局
技术栈（从配置文件获取，而非文档）
已验证的入口点
依赖流向图（文本形式）
按重要性排序的核心文件

准入门槛： 入口点已通过读取实际文件验证，依赖流向已映射。可进入下一阶段。

Phase 3: TRACE — Follow Execution Paths

阶段3：执行追踪（TRACE）—— 跟随执行路径

Start from entry points and trace through the code. Read every file in the path.

Select the primary execution path based on the reading target:
- For a flow (e.g., "payment processing"): start at the user-facing entry point
- For a module: start at its public API / exports
- For a question: start at the code most likely to contain the answer
Trace forward from the entry point:
- Read the entry point file in full with the Read tool
- For every function call, class instantiation, or module import encountered:
  - Grep to locate the implementation (not just the type signature)
  - Read the implementation file in full
- Continue until reaching terminal operations (DB queries, API calls, file I/O, return values)

Document the path as a chain with

file:line

citations:

Request enters at routes/payments.ts:42 (POST /api/payments)
  -> calls PaymentService.processPayment() at services/payment.ts:87
    -> validates input via PaymentSchema at schemas/payment.ts:15
    -> calls StripeClient.charge() at clients/stripe.ts:34
      -> constructs request at clients/stripe.ts:45-62
    -> stores result via PaymentRepository.save() at repos/payment.ts:28
  -> returns PaymentResponse at routes/payments.ts:58

Trace secondary paths if the reading target involves multiple flows:
- Error paths, edge cases, fallback logic
- Event handlers, webhooks, background jobs triggered by the primary path
Note every branch point — conditions, switches, feature flags:
- What determines which path is taken?
- Read the condition logic, don't just note "there's a conditional here"

Output: Complete execution trace(s) with

file:line

citations for every step.

Gate: At least 1 complete path traced from entry to terminal. Every file in the path has been Read in full. Proceed.

从入口点开始追踪代码执行流程。读取路径中的每一个文件。

基于阅读目标选择主执行路径：
- 对于流程（例如："支付处理"）：从面向用户的入口点开始
- 对于模块：从其公共API/导出项开始
- 对于问题：从最可能包含答案的代码开始
从入口点向前追踪：
- 用Read工具完整读取入口点文件
- 对遇到的每一个函数调用、类实例化、模块导入：
  - 检索定位其实现（而非仅类型签名）
  - 完整读取实现文件
- 持续追踪直到到达终端操作（DB查询、API调用、文件I/O、返回值）

将路径记录为带
file:line
引用的链式结构：

Request enters at routes/payments.ts:42 (POST /api/payments)
  -> calls PaymentService.processPayment() at services/payment.ts:87
    -> validates input via PaymentSchema at schemas/payment.ts:15
    -> calls StripeClient.charge() at clients/stripe.ts:34
      -> constructs request at clients/stripe.ts:45-62
    -> stores result via PaymentRepository.save() at repos/payment.ts:28
  -> returns PaymentResponse at routes/payments.ts:58

如果阅读目标涉及多个流程，追踪次要路径：
- 错误路径、边界场景、降级逻辑
- 主路径触发的事件处理器、webhook、后台任务
记录每一个分支点 —— 条件判断、switch语句、功能开关：
- 路径选择的判断依据是什么？
- 读取条件逻辑，而不是仅记录"此处有条件判断"

输出： 完整的执行追踪路径，每一步都带有

file:line

引用。

准入门槛： 至少完成1条从入口到终端的完整路径追踪，路径中的所有文件都已完整读取。可进入下一阶段。

Phase 4: DEEP READ — Line-by-Line Analysis of Critical Files

阶段4：深度阅读（DEEP READ）—— 关键文件逐行分析

This is the core phase. Read critical files thoroughly, understanding every line of business logic.

Identify critical files from Phase 3 — files that contain:
- Business logic (calculations, rules, transformations)
- State management (mutations, transactions, side effects)
- Security logic (auth, validation, access control)
- Data transformations (mapping, filtering, aggregation)
- Error handling (catch blocks, error boundaries, recovery logic)
Read each critical file in full with the Read tool:
- Do NOT skim — read the entire file
- For files > 500 lines: read in sections, but read ALL sections
- Launch parallel Read calls for independent files
For each critical file, document:
- Purpose: What this file actually does (based on code, not comments)
- Key functions: Each function's logic, with citations:
```
calculateCommission(sale: Sale): number  [billing/commission.ts:45-78]
  - Base rate: 5% of sale.amount (line 52)
  - Bonus tier: if sale.amount > 10000, rate += 2% (line 56)
  - Cap: commission capped at 5000 (line 62)
  - Proration: multiplied by daysInPeriod/30 (line 67)
  - Returns: rounded to 2 decimal places (line 74)
```
- Formulas and conditions: Write out the actual math and logic, not summaries
- State changes: What gets mutated, what side effects occur
- Edge cases handled: Null checks, bounds, error recovery
- Edge cases NOT handled: Missing validation, unchecked assumptions
Cross-reference between files:
- When file A calls file B, verify that A's expectations match B's implementation
- Note any mismatches between interface contracts and implementations
- Check that error handling in callers matches errors thrown by callees

Output: Detailed analysis of each critical file with:

Function-level logic documentation with
```
file:line
```
citations
Formulas written out explicitly
Conditions and branch logic documented
State changes and side effects listed

Gate: Every critical file (identified in step 1) has been Read in full. Logic documented with formulas, conditions, and citations. Proceed.

这是核心阶段。彻底读取关键文件，理解每一行业务逻辑。

从阶段3的结果中识别关键文件，包含以下内容的文件：
- 业务逻辑（计算、规则、转换）
- 状态管理（变更、事务、副作用）
- 安全逻辑（认证、校验、权限控制）
- 数据转换（映射、过滤、聚合）
- 错误处理（catch块、错误边界、恢复逻辑）
用Read工具完整读取每一个关键文件：
- 不要略读 —— 读取整个文件
- 超过500行的文件：分节读取，但要读完所有节
- 对独立文件可发起并行Read调用
为每个关键文件记录：
- 用途： 该文件实际的功能（基于代码而非注释）
- 核心函数： 每个函数的逻辑，带引用：
```
calculateCommission(sale: Sale): number  [billing/commission.ts:45-78]
  - Base rate: 5% of sale.amount (line 52)
  - Bonus tier: if sale.amount > 10000, rate += 2% (line 56)
  - Cap: commission capped at 5000 (line 62)
  - Proration: multiplied by daysInPeriod/30 (line 67)
  - Returns: rounded to 2 decimal places (line 74)
```
- 公式和条件： 写出实际的数学运算和逻辑，而非摘要
- 状态变更： 哪些内容被修改，产生了哪些副作用
- 已处理的边界场景： 空值检查、边界限制、错误恢复
- 未处理的边界场景： 缺失的校验、未检查的假设
跨文件交叉校验：
- 当文件A调用文件B时，验证A的预期是否符合B的实现
- 记录接口契约和实现之间的不匹配
- 检查调用方的错误处理是否符合被调用方抛出的错误

输出： 每个关键文件的详细分析，包含：

函数级别的逻辑文档，带
```
file:line
```
引用
明确写出的公式
记录的条件和分支逻辑
列出的状态变更和副作用

准入门槛： 步骤1中识别的所有关键文件都已完整读取，逻辑已通过公式、条件和引用完整记录。可进入下一阶段。

Phase 5: CONNECT — Synthesize Understanding

阶段5：模式合成（CONNECT）—— 整合理解

Step back and reason about the system as a whole. Use sequential-thinking MCP for structured analysis.

Start a sequential-thinking chain with all evidence from Phases 1-4:

javascript

mcp__sequential-thinking__sequentialthinking({
  thought: "Synthesizing understanding of <target>. Evidence from phases: ...",
  thoughtNumber: 1,
  totalThoughts: 8,
  nextThoughtNeeded: true
})

Identify patterns across the codebase (minimum 3):
- Architectural patterns (layering, dependency injection, event-driven, etc.)
- Coding conventions (error handling style, naming patterns, data flow patterns)
- Implicit rules (invariants maintained by convention, not enforced by code)
- Anti-patterns or technical debt
Map data flows end to end:
- How does data enter the system?
- What transformations does it undergo? (with
```
file:line
```
  citations)
- Where does it end up? (DB, API response, file, event)
Identify risks and assumptions:
- What assumptions does the code make that aren't validated?
- What would break if those assumptions were violated?
- Are there race conditions, consistency gaps, or security concerns?
Answer the original question if the reading target was a question:
- Provide the answer with full evidence chain
- Cite every source

Use branching in sequential-thinking to explore alternative interpretations of ambiguous code.

Output: Synthesis including:

3+ patterns identified with evidence (
```
file:line
```
)
End-to-end data flow map
Risk assessment
Answer to the original question (if applicable)

Gate: At least 5 reasoning steps completed. At least 3 patterns identified with

file:line

evidence. Proceed.

退一步从整体层面思考系统。使用sequential-thinking MCP进行结构化分析。

结合阶段1-4的所有证据启动链式连续思考：

javascript

mcp__sequential-thinking__sequentialthinking({
  thought: "Synthesizing understanding of <target>. Evidence from phases: ...",
  thoughtNumber: 1,
  totalThoughts: 8,
  nextThoughtNeeded: true
})

识别代码库中的模式（至少3个）：
- 架构模式（分层、依赖注入、事件驱动等）
- 编码规范（错误处理风格、命名模式、数据流模式）
- 隐式规则（通过约定维护而非代码强制的不变量）
- 反模式或技术债务
端到端映射数据流：
- 数据如何进入系统？
- 经历了哪些转换？（带
```
file:line
```
  引用）
- 最终流向哪里？（DB、API响应、文件、事件）
识别风险和假设：
- 代码有哪些未经验证的假设？
- 如果这些假设不成立会导致什么问题？
- 是否存在竞态条件、一致性漏洞或安全隐患？
如果阅读目标是问题，回答原始问题：
- 提供带完整证据链的答案
- 标注所有来源引用

对含义模糊的代码可在连续思考中使用分支逻辑探索不同的解释。

输出： 合成结果包括：

3个以上带证据（
```
file:line
```
）的模式识别
端到端数据流图
风险评估
原始问题的答案（如果适用）

准入门槛： 至少完成5个推理步骤，至少识别3个带

file:line

证据的模式。可进入下一阶段。

Phase 6: REPORT — Structured Deliverable

阶段6：结构化报告（REPORT）—— 输出交付物

Produce the final report. Every claim must cite

file:line

markdown

undefined

生成最终报告。每一项结论都必须标注

file:line

引用。

markdown

undefined

Deep Read Report: <target>

Deep Read 报告：<目标>

Scope

范围

Target: <what was analyzed>
Files analyzed: <count> files, <count> read in full
Entry points: <list with file:line>

目标： <分析的内容>
分析的文件： <数量>个文件，<数量>个文件已完整读取
入口点： <带file:line的列表>

Architecture Overview

架构概览

<阶段2得到的结构摘要 —— 目录布局、技术栈、依赖流向>

Execution Flow

执行流程

<阶段3得到的追踪路径 —— 从入口到终端带file:line引用>

Critical Logic

核心逻辑

For each critical area:

What it does: <plain language description>
How it works: <formulas, conditions, logic with file:line>
State changes: <what gets mutated>
Edge cases: <handled and unhandled>

<阶段4得到的详细函数级分析>

每个核心领域：

功能： <通俗语言描述>
实现逻辑： <公式、条件、逻辑带file:line引用>
状态变更： <被修改的内容>
边界场景： <已处理和未处理的内容>

Patterns & Conventions

模式与规范

<pattern> — evidence: file:line
<pattern> — evidence: file:line
<pattern> — evidence: file:line

<阶段5得到的合成模式>

<模式> —— 证据：file:line
<模式> —— 证据：file:line
<模式> —— 证据：file:line

Data Flow

数据流

<end-to-end data flow map from Phase 5>

<阶段5得到的端到端数据流图>

Risks & Assumptions

风险与假设

<阶段5得到的风险评估>

Key Findings

核心发现

<最重要发现的精简列表>

<发现> —— file:line

Answer

答案


**Gate:** All sections populated. Every finding cites `file:line`. Report complete.

---

<如果阅读目标是问题，在此给出带完整证据的答案>


**准入门槛：** 所有章节已填充，每一项发现都标注`file:line`引用，报告完成。

---

Tool Usage by Phase

各阶段工具使用

Phase	Primary Tools	When to Use Agents
1. SCOPE	Read, Glob, Grep, AskUserQuestion	--
2. MAP	Glob, Grep, Read (configs, entry points)	Explore agents (parallel) for 20+ file codebases
3. TRACE	Read (full files), Grep (cross-refs)	Explore agent for locating implementations
4. DEEP READ	Read (full files, parallel)	--
5. CONNECT	sequential-thinking MCP	deep-analysis skill for complex reasoning
6. REPORT	Structured output	--

阶段	核心工具	何时使用Agent
1. 范围界定	Read、Glob、Grep、AskUserQuestion	--
2. 结构映射	Glob、Grep、Read（配置文件、入口点）	超过20个文件的代码库使用并行Explore Agent
3. 执行追踪	Read（完整文件）、Grep（交叉引用）	用Explore Agent定位实现代码
4. 深度阅读	Read（完整文件，并行）	--
5. 模式合成	sequential-thinking MCP	复杂推理使用deep-analysis skill
6. 结构化报告	结构化输出	--

Anti-Patterns — What This Skill Prevents

反模式 —— 本技能可避免的问题

Bad Habit	What `/deep-read` Does Instead
Read README/CLAUDE.md and call it done	Phase 1 treats docs as hints; Phases 3-4 read source
Skim file headers and imports only	Phase 4 requires line-by-line reading with citations
Summarize without evidence	Every claim must cite `file:line`
Stop at the first abstraction layer	Phase 3 traces full call chains to leaf functions
Rely on function names to infer behavior	Phase 4 reads implementations, documents actual logic
Produce vague "this seems to do X"	Phase 4 requires concrete formulas and conditions
Read types/interfaces instead of implementations	Phase 3 Greps for implementations, not just signatures
Skip error paths and edge cases	Phase 3 traces secondary paths; Phase 4 documents edge cases

不良习惯	`/deep-read` 的替代做法
读完README/CLAUDE.md就结束	阶段1将文档视为参考提示，阶段3-4读取源代码
仅略读文件头部和导入	阶段4要求逐行阅读并标注引用
无证据的摘要总结	每一项结论都必须标注 `file:line` 引用
停留在第一层抽象	阶段3追踪完整调用链直到叶子函数
依赖函数名推断行为	阶段4读取实现代码，记录实际逻辑
输出模糊的"看起来是做X的"	阶段4要求输出具体的公式和条件
读取类型/接口而非实现	阶段3检索实现代码而非仅签名
跳过错误路径和边界场景	阶段3追踪次要路径，阶段4记录边界场景

Scope Examples

范围示例

/deep-read payment processing flow from checkout to settlement
/deep-read src/services/billing/
/deep-read how are sales commissions calculated and distributed?
/deep-read the authentication and authorization system
/deep-read data pipeline from ingestion to reporting dashboard
/deep-read how does the caching layer work and when does it invalidate?

/deep-read payment processing flow from checkout to settlement
/deep-read src/services/billing/
/deep-read how are sales commissions calculated and distributed?
/deep-read the authentication and authorization system
/deep-read data pipeline from ingestion to reporting dashboard
/deep-read how does the caching layer work and when does it invalidate?

When to Use

/deep-read

vs Other Tools

何时使用

/deep-read

vs 其他工具

Situation	Use
Understand how existing code works	`/deep-read`
Quick "what does this function do?"	Read tool directly
Bug, crash, error, unexpected behavior	`/investigate`
Architecture decision or trade-off	`/deep-analysis`
Build a new feature	`/execute`
Understand code, then reason about it	`/deep-read` then `/deep-analysis`
Understand code, then redesign it	`/deep-read` then `/deep-analysis` then `/execute`
Onboard to an unfamiliar codebase	`/deep-read`
Code review with full context	`/deep-read` then code-quality agent

场景	使用工具
理解现有代码的运行逻辑	`/deep-read`
快速查询"这个函数是做什么的"	直接使用Read工具
Bug、崩溃、错误、异常行为	`/investigate`
架构决策或权衡分析	`/deep-analysis`
开发新功能	`/execute`
先理解代码再推理分析	先 `/deep-read` 再 `/deep-analysis`
先理解代码再重新设计	先 `/deep-read` 再 `/deep-analysis` 再 `/execute`
熟悉陌生代码库	`/deep-read`
带完整上下文的代码评审	先 `/deep-read` 再调用code-quality agent

References

参考资料

See references/reading-strategies.md for codebase-type-specific reading strategies and context management approaches.

查看 references/reading-strategies.md 获取不同类型代码库的专属阅读策略和上下文管理方法。