Back to Details

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.
  1. Parse 
    $ARGUMENTS
    as the reading target (module, flow, question, or path)
  2. Read CLAUDE.md and MEMORY.md for project context — but treat these as hints, not truth
  3. 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
  4. If scope exceeds 50 source files:
    • Use 
      AskUserQuestion
      to narrow: which subsystem, which flow, which layer?
    • Suggest specific narrowing options based on directory structure
  5. 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
  6. 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.
在开始阅读前先将目标缩小到可处理的范围。
  1. 将
    $ARGUMENTS
    解析为阅读目标（模块、流程、问题或路径）
  2. 读取CLAUDE.md和MEMORY.md获取项目上下文，但仅将这些内容作为参考提示，而非事实依据
  3. 执行初步探查评估范围：
    • 用
      Glob
      匹配相关文件模式（
      **/*.ts
      、
      **/*.py
      等）
    • 用
      Grep
      检索目标描述中的关键词
    • 统计匹配的文件数量
  4. 如果范围超过50个源代码文件：
    • 使用
      AskUserQuestion
      缩小范围：询问要查看哪个子系统、哪个流程、哪个层级？
    • 基于目录结构给出具体的范围缩小选项
  5. 如果目标是一个问题（例如："佣金是怎么计算的？"）：
    • 转换为具体的搜索关键词
    • 检索领域术语定位相关模块
  6. 如果目标是一个路径（例如：
    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.
  1. 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)
  2. 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
  3. 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
  4. 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)
  5. 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.
在深度阅读前先理解代码的整体结构。
  1. 目录结构 —— 映射相关目录：
    • 使用
      Glob
      按类型和目录列出文件
    • 记录组织模式（按功能、按层级、按领域）
  2. 技术栈 —— 从配置文件识别（而非从文档）：
    • 读取
      package.json
      、
      Cargo.toml
      、
      go.mod
      、
      requirements.txt
      或等效配置文件
    • 记录框架、核心依赖、构建工具
  3. 入口点 —— 通过读取实际文件验证（而非仅看文件名）：
    • 读取路由定义、主文件、导出模块
    • 读取每个候选入口点的前50行
    • 确认哪些是实际入口点，哪些是辅助文件
  4. 依赖图 —— 映射范围内的内部导入关系：
    • 检索范围内文件的import/require语句
    • 构建心智模型：调用关系、依赖关系
    • 识别核心文件（被其他文件引用最多的文件）
  5. 配置和常量 —— 读取定义行为的文件：
    • 配置文件、环境变量 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.
  1. 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
  2. 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)
  3. 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
  4. 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
  5. 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.
从入口点开始追踪代码执行流程。读取路径中的每一个文件。
  1. 基于阅读目标选择主执行路径：
    • 对于流程（例如："支付处理"）：从面向用户的入口点开始
    • 对于模块：从其公共API/导出项开始
    • 对于问题：从最可能包含答案的代码开始
  2. 从入口点向前追踪：
    • 用Read工具完整读取入口点文件
    • 对遇到的每一个函数调用、类实例化、模块导入：
      • 检索定位其实现（而非仅类型签名）
      • 完整读取实现文件
    • 持续追踪直到到达终端操作（DB查询、API调用、文件I/O、返回值）
  3. 将路径记录为带
    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
  4. 如果阅读目标涉及多个流程，追踪次要路径：
    • 错误路径、边界场景、降级逻辑
    • 主路径触发的事件处理器、webhook、后台任务
  5. 记录每一个分支点 —— 条件判断、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.
  1. 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)
  2. 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
  3. 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
  4. 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.
这是核心阶段。彻底读取关键文件，理解每一行业务逻辑。
  1. 从阶段3的结果中识别关键文件，包含以下内容的文件：
    • 业务逻辑（计算、规则、转换）
    • 状态管理（变更、事务、副作用）
    • 安全逻辑（认证、校验、权限控制）
    • 数据转换（映射、过滤、聚合）
    • 错误处理（catch块、错误边界、恢复逻辑）
  2. 用Read工具完整读取每一个关键文件：
    • 不要略读 —— 读取整个文件
    • 超过500行的文件：分节读取，但要读完所有节
    • 对独立文件可发起并行Read调用
  3. 为每个关键文件记录：
    • 用途： 该文件实际的功能（基于代码而非注释）
    • 核心函数： 每个函数的逻辑，带引用： 
      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)
    • 公式和条件： 写出实际的数学运算和逻辑，而非摘要
    • 状态变更： 哪些内容被修改，产生了哪些副作用
    • 已处理的边界场景： 空值检查、边界限制、错误恢复
    • 未处理的边界场景： 缺失的校验、未检查的假设
  4. 跨文件交叉校验：
    • 当文件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.
  1. 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
})
  2. 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
  3. 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)
  4. 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?
  5. 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. 结合阶段1-4的所有证据启动链式连续思考：
    javascript
    mcp__sequential-thinking__sequentialthinking({
  thought: "Synthesizing understanding of <target>. Evidence from phases: ...",
  thoughtNumber: 1,
  totalThoughts: 8,
  nextThoughtNeeded: true
})
  2. 识别代码库中的模式（至少3个）：
    • 架构模式（分层、依赖注入、事件驱动等）
    • 编码规范（错误处理风格、命名模式、数据流模式）
    • 隐式规则（通过约定维护而非代码强制的不变量）
    • 反模式或技术债务
  3. 端到端映射数据流：
    • 数据如何进入系统？
    • 经历了哪些转换？（带
      file:line
      引用）
    • 最终流向哪里？（DB、API响应、文件、事件）
  4. 识别风险和假设：
    • 代码有哪些未经验证的假设？
    • 如果这些假设不成立会导致什么问题？
    • 是否存在竞态条件、一致性漏洞或安全隐患？
  5. 如果阅读目标是问题，回答原始问题：
    • 提供带完整证据链的答案
    • 标注所有来源引用
对含义模糊的代码可在连续思考中使用分支逻辑探索不同的解释。
输出： 合成结果包括：
  • 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

架构概览

<structural summary from Phase 2 — directory layout, tech stack, dependency flow>
<阶段2得到的结构摘要 —— 目录布局、技术栈、依赖流向>

Execution Flow

执行流程

<traced paths from Phase 3 — entry to terminal with file:line citations>
<阶段3得到的追踪路径 —— 从入口到终端带file:line引用>

Critical Logic

核心逻辑

<detailed function-level analysis from Phase 4>
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

模式与规范

<synthesized patterns from Phase 5>
  1. <pattern> — evidence: file:line
  2. <pattern> — evidence: file:line
  3. <pattern> — evidence: file:line
<阶段5得到的合成模式>
  1. <模式> —— 证据：file:line
  2. <模式> —— 证据：file:line
  3. <模式> —— 证据：file:line

Data Flow

数据流

<end-to-end data flow map from Phase 5>
<阶段5得到的端到端数据流图>

Risks & Assumptions

风险与假设

<risk assessment from Phase 5>
<阶段5得到的风险评估>

Key Findings

核心发现

<concise bullet list of the most important discoveries> - <finding> — <file:line>
<最重要发现的精简列表>
  • <发现> —— file:line

Answer

答案

<if the reading target was a question, answer it here with full evidence>

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

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

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

---

Tool Usage by Phase

各阶段工具使用

PhasePrimary ToolsWhen to Use Agents
1. SCOPERead, Glob, Grep, AskUserQuestion--
2. MAPGlob, Grep, Read (configs, entry points)Explore agents (parallel) for 20+ file codebases
3. TRACERead (full files), Grep (cross-refs)Explore agent for locating implementations
4. DEEP READRead (full files, parallel)--
5. CONNECTsequential-thinking MCPdeep-analysis skill for complex reasoning
6. REPORTStructured 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 HabitWhat 
/deep-read
Does Instead
Read README/CLAUDE.md and call it donePhase 1 treats docs as hints; Phases 3-4 read source
Skim file headers and imports onlyPhase 4 requires line-by-line reading with citations
Summarize without evidenceEvery claim must cite 
file:line
Stop at the first abstraction layerPhase 3 traces full call chains to leaf functions
Rely on function names to infer behaviorPhase 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 implementationsPhase 3 Greps for implementations, not just signatures
Skip error paths and edge casesPhase 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 其他工具

SituationUse
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 获取不同类型代码库的专属阅读策略和上下文管理方法。