Back to Details

codebase-exploration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Exploration

代码库探索

Purpose

用途

Specializes in systematic codebase exploration and discovery. Uses advanced search techniques, pattern recognition, and code analysis to quickly understand unfamiliar code, locate specific implementations, map architectural patterns, and answer location-based questions about code.
专注于系统化的代码库探索与发现。使用高级搜索技术、模式识别和代码分析来快速理解不熟悉的代码，定位特定实现，梳理架构模式，并解答与代码位置相关的问题。

When to Use

使用场景

  • Exploring an unfamiliar codebase for the first time
  • Need to find where specific functionality is implemented
  • Looking for examples of a pattern across the codebase
  • Understanding how components interact
  • Locating all usages of a particular API or pattern
  • Mapping architectural organization
  • Finding similar code across the project
  • Questions like "Where is X?", "Which file has Y?", "Find code that does Z"
  • 首次探索不熟悉的代码库
  • 需要查找特定功能的实现位置
  • 在代码库中查找某类模式的示例
  • 理解组件之间的交互方式
  • 定位某个API或模式的所有用法
  • 梳理架构组织结构
  • 在项目中查找相似代码
  • 诸如“X在哪里？”、“哪个文件包含Y？”、“查找实现Z功能的代码”这类问题

Quick Start

快速开始

Invoke this skill when:
  • Exploring an unfamiliar codebase for the first time
  • Need to find where specific functionality is implemented
  • Looking for examples of a pattern across the codebase
  • Understanding how components interact
  • Questions like "Where is X?", "Which file has Y?", "Find code that does Z"
Do NOT invoke when:
  • Debugging a known bug (use debugger-skill)
  • Refactoring code (use refactoring-specialist-skill)
  • Reviewing code quality (use code-reviewer-skill)
  • Writing new code from scratch (use appropriate developer skill)
在以下场景调用此技能：
  • 首次探索不熟悉的代码库
  • 需要查找特定功能的实现位置
  • 在代码库中查找某类模式的示例
  • 理解组件之间的交互方式
  • 诸如“X在哪里？”、“哪个文件包含Y？”、“查找实现Z功能的代码”这类问题
请勿在以下场景调用：
  • 调试已知bug（使用debugger-skill）
  • 重构代码（使用refactoring-specialist-skill）
  • 审查代码质量（使用code-reviewer-skill）
  • 从零开始编写新代码（使用对应的开发者技能）

Thoroughness Levels

细致程度等级

Quick (Fast, broad strokes)
  • File structure overview
  • High-level pattern matching
  • Directory organization
  • Main entry points
  • ~30 seconds
Medium (Balanced depth)
  • Detailed file examination
  • Cross-file pattern discovery
  • Architectural mapping
  • Common patterns analysis
  • ~2-3 minutes
Very Thorough (Deep dive)
  • Exhaustive code analysis
  • Complex pattern matching
  • Dependency tracing
  • Edge case discovery
  • ~5-10 minutes
快速（速度快，概览性）
  • 文件结构概览
  • 高层级模式匹配
  • 目录组织结构
  • 主要入口点
  • 约30秒
中等（平衡深度）
  • 详细文件检查
  • 跨文件模式发现
  • 架构梳理
  • 常见模式分析
  • 约2-3分钟
非常细致（深度探索）
  • 全面代码分析
  • 复杂模式匹配
  • 依赖追踪
  • 边界情况发现
  • 约5-10分钟

Decision Framework

决策框架

Search Strategy Selection

搜索策略选择

Question TypeSearch Strategy
"Where is user authentication?"Search for auth keywords + login patterns
"How does data flow work?"Find models, services, controllers pattern
"Which file handles X API?"Search endpoints + route definitions
"Find all database queries"Search ORM patterns, SQL keywords
"Locate error handling"Find try-catch, error classes
问题类型搜索策略
"用户认证在哪里实现？"搜索auth相关关键词 + 登录模式
"数据流是如何工作的？"查找models、services、controllers模式
"哪个文件处理X API？"搜索端点 + 路由定义
"查找所有数据库查询"搜索ORM模式、SQL关键词
"定位错误处理逻辑"查找try-catch、错误类

Tool Selection

工具选择

ToolBest ForExample
grep/rg
Text pattern matching
rg "function handleAuth"
find/fd
File name/path matching
fd -e ts auth
ast-grep
Code structure matching
ast-grep --pattern "class $NAME"
LSP toolsSymbol and reference finding
lsp_find_references
git log
Historical context
git log --name-only
工具最佳适用场景示例
grep/rg
文本模式匹配
rg "function handleAuth"
find/fd
文件名/路径匹配
fd -e ts auth
ast-grep
代码结构匹配
ast-grep --pattern "class $NAME"
LSP工具符号与引用查找
lsp_find_references
git log
历史上下文查询
git log --name-only

Approach by Question Type

按问题类型选择方法

"Where is X implemented?"
  1. Search for X by name: 
    rg "X|x"
  2. Search for related terms: 
    rg "related|terms"
  3. Check obvious locations: 
    ls src/X/
  4. Look in tests: 
    rg "X" tests/
"How does Y work?"
  1. Find Y's definition
  2. Find Y's usage
  3. Trace the flow
  4. Understand dependencies
"Which files use Z?"
  1. Search for imports of Z
  2. Use LSP find-references
  3. Search for Z's methods being called
"X在哪里实现？"
  1. 按名称搜索X：
    rg "X|x"
  2. 搜索相关术语：
    rg "related|terms"
  3. 检查明显的位置：
    ls src/X/
  4. 查看测试文件：
    rg "X" tests/
"Y是如何工作的？"
  1. 查找Y的定义
  2. 查找Y的用法
  3. 追踪执行流程
  4. 理解依赖关系
"哪些文件使用了Z？"
  1. 搜索Z的导入语句
  2. 使用LSP查找引用
  3. 搜索Z的方法调用

Core Capabilities

核心能力

Search Strategies

搜索策略

Pattern-Based Search
  • Find by naming conventions
  • Locate by code patterns
  • Discover by architectural markers
  • Identify by file organization
Context-Aware Search
  • Understand code relationships
  • Map dependencies
  • Trace execution flows
  • Find related components
Multi-Angle Discovery
  • Search by functionality
  • Search by structure
  • Search by naming
  • Search by patterns
基于模式的搜索
  • 按命名约定查找
  • 按代码模式定位
  • 按架构标识发现
  • 按文件组织结构识别
上下文感知搜索
  • 理解代码间的关系
  • 梳理依赖关系
  • 追踪执行流程
  • 查找相关组件
多角度发现
  • 按功能搜索
  • 按结构搜索
  • 按名称搜索
  • 按模式搜索

Exploration Workflow

探索流程

Step 1: Orient

步骤1：明确目标

  • What are we looking for?
  • Why do we need it?
  • What level of detail is needed?
  • Which thoroughness level is appropriate?
  • 我们要找什么？
  • 我们为什么需要它？
  • 需要什么细致程度？
  • 哪种细致程度最合适？

Step 2: Map Structure

步骤2：梳理结构

  • Identify top-level organization
  • Find key markers (entry points, config files)
  • Note directory naming patterns
  • 识别顶层组织结构
  • 查找关键标识（入口点、配置文件）
  • 记录目录命名模式

Step 3: Execute Search

步骤3：执行搜索

  • Choose appropriate tools
  • Use multiple search angles
  • Document findings
  • 选择合适的工具
  • 使用多种搜索角度
  • 记录发现内容

Step 4: Analyze & Synthesize

步骤4：分析与整合

  • Connect the dots
  • Identify patterns
  • Prioritize findings
  • 关联各个发现
  • 识别模式
  • 对发现内容排序

Best Practices

最佳实践

Start Broad, Then Narrow

先广后深

  1. First: Get the lay of the land (
    tree -L 2
    , 
    ls -la src/
    )
  2. Second: Identify patterns (
    fd -e ts
    , 
    rg -c "class|function"
    )
  3. Third: Target specific areas
  1. 首先：了解整体情况（
    tree -L 2
    、
    ls -la src/
    ）
  2. 其次：识别模式（
    fd -e ts
    、
    rg -c "class|function"
    ）
  3. 最后：定位特定区域

Use Multiple Search Angles

使用多种搜索角度

  • Search by name: 
    fd auth
  • Search by content: 
    rg "authentication"
  • Search by structure: 
    ast-grep --pattern "class $NAME"
  • Search by symbols: 
    lsp_workspace_symbols
  • 按名称搜索：
    fd auth
  • 按内容搜索：
    rg "authentication"
  • 按结构搜索：
    ast-grep --pattern "class $NAME"
  • 按符号搜索：
    lsp_workspace_symbols

Follow the Breadcrumbs

顺藤摸瓜

  1. Check imports to find dependencies
  2. Use LSP to find references
  3. Look at file location for architectural clues
  4. Check git history for context
  1. 检查导入语句以查找依赖
  2. 使用LSP查找引用
  3. 通过文件位置获取架构线索
  4. 查看git历史获取上下文

Document as You Go

边探索边记录

markdown
undefined
markdown
undefined

Authentication Flow

Authentication Flow

  1. Entry: src/middleware/auth.ts
  2. Token validation: src/services/jwt.service.ts
  3. User lookup: src/repositories/user.repository.ts
  4. Guards: src/guards/auth.guard.ts
undefined
  1. Entry: src/middleware/auth.ts
  2. Token validation: src/services/jwt.service.ts
  3. User lookup: src/repositories/user.repository.ts
  4. Guards: src/guards/auth.guard.ts
undefined

Anti-Patterns

反模式

  • Don't Search Without Context: Understand what you're looking for first
  • Don't Ignore File Structure: Always check directory organization
  • Don't Rely on Single Search Method: Use multiple approaches
  • Don't Forget About Tests: Search test files for real usage
  • Don't Skip Configuration Files: Check config early
  • 不要无上下文搜索：先明确要找什么
  • 不要忽略文件结构：务必检查目录组织结构
  • 不要依赖单一搜索方法：使用多种方式
  • 不要忘记测试文件：在测试文件中查找实际用法
  • 不要跳过配置文件：尽早检查配置

Related Skills

相关技能

  • Use [[debugger-skill]] when exploration reveals bugs
  • Use [[architect-reviewer-skill]] to evaluate discovered patterns
  • Use [[refactoring-specialist-skill]] to improve found code
  • Use [[technical-advisory-skill]] for complex architectural questions
  • 当探索发现bug时，使用[[debugger-skill]]
  • 使用[[architect-reviewer-skill]]评估发现的模式
  • 使用[[refactoring-specialist-skill]]优化找到的代码
  • 对于复杂架构问题，使用[[technical-advisory-skill]]

Additional Resources

额外资源

  • Detailed Technical Reference: See REFERENCE.md
  • Code Examples & Patterns: See EXAMPLES.md
  • 详细技术参考：查看REFERENCE.md
  • 代码示例与模式：查看EXAMPLES.md