codebase-overview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Overview Skill

代码库概览Skill

Operator Context

技能运行上下文

This skill operates as an operator for systematic codebase exploration, configuring Claude's behavior for rigorous, evidence-based discovery. It implements the Phased Discovery architectural pattern -- Detect project type, Explore key files, Map architecture, Summarize findings -- with Domain Intelligence embedded in language-specific exploration strategies.

本Skill作为系统化代码库探索的操作器，配置Claude的行为以实现严谨、基于证据的探索。它实现了分阶段发现架构模式——检测项目类型、探索关键文件、映射架构、总结发现——并在特定语言的探索策略中嵌入了领域智能。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before exploration
Over-Engineering Prevention: Explore only what's needed for the overview. No speculative deep-dives, no "while I'm here" tangents
Read-Only Operations: NEVER modify, create, or delete project files
Evidence Required: Every architectural claim MUST cite an examined file and path
Systematic Phases: Follow DETECT -> EXPLORE -> MAP -> SUMMARIZE in order
Project Agnostic: Work across any language, framework, or build system
Absolute Paths: All file references in output MUST use absolute paths
Forbidden-Files Guardrail: NEVER read or quote files matching sensitive patterns. Secrets leaked into exploration output are hard to retract and easy to miss. Check every file path against the forbidden list BEFORE reading. Skip silently -- do not log the file contents or path contents in output.
```
# Secrets and credentials
.env, .env.*, *.pem, *.key, credentials.json, secrets.*, *secret*, *credential*, *password*

# Authentication tokens
token.json, .npmrc, .pypirc

# Cloud provider credentials
.aws/credentials, .gcloud/, service-account*.json
```

遵循CLAUDE.md规范：探索前先读取并遵循仓库中的CLAUDE.md文件
防止过度探索：仅探索概览所需内容，不进行推测性深度挖掘，不做“顺便探索”的无关操作
只读操作：绝不修改、创建或删除项目文件
需提供证据：所有架构结论必须引用已检查的文件和路径
按阶段系统化执行：严格按照DETECT -> EXPLORE -> MAP -> SUMMARIZE的顺序执行
项目无关性：适用于任何语言、框架或构建系统
绝对路径：输出中所有文件引用必须使用绝对路径
敏感文件防护：绝不读取或引用匹配敏感模式的文件。泄露到探索输出中的敏感信息难以撤回且容易被忽略。读取前需检查每个文件路径是否在禁止列表中。直接跳过此类文件——不要在输出中记录文件内容或路径。
```
# 密钥和凭证
.env, .env.*, *.pem, *.key, credentials.json, secrets.*, *secret*, *credential*, *password*

# 认证令牌
token.json, .npmrc, .pypirc

# 云服务商凭证
.aws/credentials, .gcloud/, service-account*.json
```

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Report facts without self-congratulation; show evidence, not descriptions
Start from current working directory
Examine up to 20 key files per category
Include recent commit themes (last 10 commits)
Generate structured markdown report to stdout

Exclude noise directories:

node_modules/

venv/

vendor/

dist/

build/

__pycache__/

Remove any temporary files created during exploration at completion
Show absolute file paths in all output

只报告事实，不自我夸耀；展示证据，而非描述
从当前工作目录开始探索
每个类别最多检查20个关键文件
包含最近提交主题（最近10次提交）
生成结构化Markdown报告输出到标准输出（stdout）

排除无关目录：

node_modules/

venv/

vendor/

dist/

build/

__pycache__/

探索完成后删除所有临时文件
所有输出中显示绝对文件路径

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

Deep dive into specific subsystems (on explicit request)
Generate architecture diagrams (requires explicit request)
Include full file contents in report (vs summaries)
Export findings to separate file (vs stdout)
Analyze dependency vulnerability status

深入探索特定子系统（需明确请求）
生成架构图（需明确请求）
在报告中包含完整文件内容（而非摘要）
将发现结果导出到单独文件（而非标准输出）
分析依赖项漏洞状态

What This Skill CAN Do

本Skill可实现的功能

Systematically discover project type, tech stack, and architecture
Identify entry points, core modules, data models, and API surfaces
Map design patterns and key abstractions with file-level evidence
Produce actionable onboarding documentation for new contributors
Work across any language and framework without prior knowledge

系统化发现项目类型、技术栈和架构
识别入口点、核心模块、数据模型和API接口
结合文件级证据映射设计模式和关键抽象
为新贡献者生成可操作的入职文档
无需预先了解，即可适配任何语言和框架

What This Skill CANNOT Do

本Skill无法实现的功能

Modify, create, or delete any files in the target project
Run the application or execute its test suite
Provide deep domain expertise (use specialized agent instead)
Replace reading the codebase (this accelerates, not replaces)
Skip any of the 4 phases

修改、创建或删除目标项目中的任何文件
运行应用程序或执行其测试套件
提供深度领域专业知识（请使用专门的Agent）
替代直接阅读代码库（本Skill仅加速理解，无法替代）
跳过四个阶段中的任何一个

Instructions

执行步骤

Execute all phases autonomously. Verify each gate before advancing. Consult

references/exploration-strategies.md

for language-specific discovery commands.

自主执行所有阶段，推进前需验证每个阶段的准入条件。请参考

references/exploration-strategies.md

获取特定语言的探索命令。

Phase 1: DETECT

阶段1：DETECT（检测）

Goal: Determine project type, language, framework, and tech stack.

Step 1: Examine root directory

bash

ls -la

Identify configuration files that indicate project type:

```
package.json
```
-> Node.js/JavaScript/TypeScript
```
go.mod
```
-> Go
```
pyproject.toml
```
,
```
requirements.txt
```
,
```
setup.py
```
-> Python
```
pom.xml
```
,
```
build.gradle
```
-> Java
```
Cargo.toml
```
-> Rust
See
```
references/exploration-strategies.md
```
for complete indicator table

Step 2: Read primary configuration

Based on detected type, read the main config file. Preference order:

Python:
```
pyproject.toml
```
>
```
setup.py
```
>
```
requirements.txt
```
Node.js:
```
package.json
```
Go:
```
go.mod
```

Extract: project name, dependencies, language version, build system, scripts/commands.

Step 3: Identify frameworks and tooling

Search for framework-specific files:

bash

undefined

目标：确定项目类型、语言、框架和技术栈。

步骤1：检查根目录

bash

ls -la

识别指示项目类型的配置文件：

```
package.json
```
-> Node.js/JavaScript/TypeScript
```
go.mod
```
-> Go
```
pyproject.toml
```
,
```
requirements.txt
```
,
```
setup.py
```
-> Python
```
pom.xml
```
,
```
build.gradle
```
-> Java
```
Cargo.toml
```
-> Rust
完整的指示符表请参考
```
references/exploration-strategies.md
```

步骤2：读取主配置文件

根据检测到的项目类型，读取主配置文件。优先级顺序：

Python:
```
pyproject.toml
```
>
```
setup.py
```
>
```
requirements.txt
```
Node.js:
```
package.json
```
Go:
```
go.mod
```

提取信息：项目名称、依赖项、语言版本、构建系统、脚本/命令。

步骤3：识别框架和工具

搜索框架特定文件：

bash

undefined

Frameworks

框架

ls -la manage.py next.config.js nuxt.config.js angular.json 2>/dev/null

Build and infrastructure

构建和基础设施

ls -la Makefile Dockerfile docker-compose.yml 2>/dev/null ls -la .github/workflows/ 2>/dev/null


**Step 4: Check for CLAUDE.md**

Read any `.claude/CLAUDE.md` or `CLAUDE.md` in the repository root. Follow its instructions throughout remaining phases.

**Step 5: Document findings**

```markdown

ls -la Makefile Dockerfile docker-compose.yml 2>/dev/null ls -la .github/workflows/ 2>/dev/null


**步骤4：检查CLAUDE.md**

读取仓库根目录下的`.claude/CLAUDE.md`或`CLAUDE.md`文件。在剩余阶段中遵循其指示。

**步骤5：记录检测结果**

```markdown

DETECT Results

DETECT阶段结果

Language: [detected language + version]
Framework: [detected framework + version]
Build system: [build tool]
Key dependencies: [top 5-10]
Run command: [from scripts/Makefile]
Test command: [from scripts/Makefile]


**Gate**: Project type identified (language + framework). Tech stack documented. Build/run commands known. Proceed ONLY when gate passes.

语言：[检测到的语言 + 版本]
框架：[检测到的框架 + 版本]
构建系统：[构建工具]
关键依赖项：[前5-10个]
运行命令：[来自脚本/Makefile]
测试命令：[来自脚本/Makefile]


**准入条件**：已识别项目类型（语言 + 框架），已记录技术栈，已知晓构建/运行命令。仅当满足条件时方可进入下一阶段。

Phase 2: EXPLORE

阶段2：EXPLORE（探索）

Goal: Discover entry points, core modules, data models, API surfaces, configuration, and tests.

Step 1: Find entry points

Use language-specific patterns from

references/exploration-strategies.md

. Read each entry point file to understand application bootstrapping.

For any language, look for:

```
main
```
functions or
```
__main__
```
modules
Server/app initialization files
CLI entry points declared in config

Step 2: Map directory structure

bash

find . -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules/*' \
  -not -path '*/venv/*' \
  -not -path '*/vendor/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -50

Categorize directories by layer:

Pattern	Layer
`models/` , `db/` , `schema/` , `entities/`	Data
`api/` , `routes/` , `handlers/` , `controllers/`	API
`services/` , `lib/` , `core/` , `domain/`	Business logic
`utils/` , `helpers/` , `common/`	Utilities
`tests/` , `test/` , `__tests__/`	Tests
`config/` , `settings/`	Configuration
`cmd/` , `cli/`	CLI

Step 3: Examine data layer

Search for model, schema, and entity files. Read 3-5 representative files.

markdown

undefined

目标：发现入口点、核心模块、数据模型、API接口、配置和测试。

步骤1：寻找入口点

使用

references/exploration-strategies.md

中的特定语言模式。读取每个入口点文件以理解应用程序的启动流程。

对于任何语言，寻找：

```
main
```
函数或
```
__main__
```
模块
服务器/应用初始化文件
配置中声明的CLI入口点

步骤2：映射目录结构

bash

find . -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules/*' \
  -not -path '*/venv/*' \
  -not -path '*/vendor/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -50

按层级对目录进行分类：

模式	层级
`models/` , `db/` , `schema/` , `entities/`	数据层
`api/` , `routes/` , `handlers/` , `controllers/`	API层
`services/` , `lib/` , `core/` , `domain/`	业务逻辑层
`utils/` , `helpers/` , `common/`	工具层
`tests/` , `test/` , `__tests__/`	测试层
`config/` , `settings/`	配置层
`cmd/` , `cli/`	CLI层

步骤3：检查数据层

搜索模型、模式和实体文件。读取3-5个代表性文件。

markdown

undefined

Data Layer Findings

数据层发现结果

Database: [technology]
ORM: [library, if any]
Key models:
- [ModelName] ([file path]): [primary fields, relationships]
- [ModelName] ([file path]): [primary fields, relationships]
Migrations: [tool and location]


Document: entity relationships (which models reference which), primary data structures and their fields, database technology, migration strategy.

**Step 4: Discover API surface**

Search for route, handler, and controller files. Read 3-5 key API files.

```markdown

数据库：[技术选型]
ORM：[库（如果有）]
关键模型：
- [模型名称]（[文件路径]）：[主要字段、关系]
- [模型名称]（[文件路径]）：[主要字段、关系]
迁移：[工具和位置]


记录内容：实体关系（哪些模型相互引用）、主要数据结构及其字段、数据库技术、迁移策略。

**步骤4：发现API接口**

搜索路由、处理器和控制器文件。读取3-5个关键API文件。

```markdown

API Surface Findings

API接口发现结果

Type: [REST/GraphQL/gRPC]
Auth: [JWT/OAuth/API keys/none]
Key endpoints:
- [METHOD] /path - [purpose] ([handler file])
- [METHOD] /path - [purpose] ([handler file])
Versioning: [strategy, if any]


Document: endpoint structure and URL patterns, HTTP methods and request/response formats, authentication and authorization patterns, API versioning strategy.

**Step 5: Identify configuration**

Find `.env.example`, config files, and settings modules.

```bash

类型：[REST/GraphQL/gRPC]
认证：[JWT/OAuth/API密钥/无]
关键端点：
- [请求方法] /路径 - [用途]（[处理器文件]）
- [请求方法] /路径 - [用途]（[处理器文件]）
版本控制：[策略（如果有）]


记录内容：端点结构和URL模式、HTTP方法和请求/响应格式、认证和授权模式、API版本控制策略。

**步骤5：识别配置**

查找`.env.example`、配置文件和设置模块。

```bash

Environment configs

环境配置

ls -la .env .env.example config.yaml config.json settings.py 2>/dev/null

Environment-specific configs

特定环境配置

ls -la config/.yaml config/.json config/*.toml 2>/dev/null


Document: required environment variables and their purpose, external service dependencies (databases, APIs, caches, queues), feature flags or runtime options.

**Step 6: Examine test structure**

Find test files and test configuration. Read 2-3 representative tests.

```bash

ls -la config/.yaml config/.json config/*.toml 2>/dev/null


记录内容：所需环境变量及其用途、外部服务依赖（数据库、API、缓存、队列）、功能标志或运行时选项。

**步骤6：检查测试结构**

查找测试文件和测试配置。读取2-3个代表性测试文件。

```bash

Find test files (language-agnostic)

查找测试文件（通用语言）

find . -name "_test." -o -name ".test." -o -name "Test." -o -path "/tests/"
2>/dev/null | head -20


Document: testing framework, test organization (co-located vs separate directory), common patterns (fixtures, factories, mocks), coverage tooling.

**Gate**: Entry points identified. Core modules mapped. Data layer understood. API surface discovered. Configuration examined. Test structure documented. Proceed ONLY when gate passes.

find . -name "_test." -o -name ".test." -o -name "Test." -o -path "/tests/"
2>/dev/null | head -20


记录内容：测试框架、测试组织方式（与代码同目录/单独目录）、常见模式（夹具、工厂、模拟）、覆盖率工具。

**准入条件**：已识别入口点，已映射核心模块，已理解数据层，已发现API接口，已检查配置，已记录测试结构。仅当满足条件时方可进入下一阶段。

Phase 3: MAP

阶段3：MAP（映射）

Goal: Synthesize findings into architectural understanding.

Step 1: Identify design patterns

Based on examined files, identify and document with evidence:

markdown

undefined

目标：将发现结果整合为架构理解。

步骤1：识别设计模式

基于已检查的文件，识别并结合证据记录：

markdown

undefined

Design Patterns

设计模式

Architecture: [MVC/layered/microservices/etc.] (evidence: [file paths])
Organization: [by-feature/by-layer] (evidence: [directory structure])
Error handling: [exceptions/error returns/result types] (evidence: [file paths])
Async patterns: [promises/async-await/goroutines/callbacks] (evidence: [file paths])
DI approach: [manual/framework/none] (evidence: [file paths])


**Step 2: Map key abstractions**

Identify the 5-10 most important types, classes, or modules:

```markdown

架构：[MVC/分层/微服务等]（证据：[文件路径]）
组织方式：[按功能/按层级]（证据：[目录结构]）
错误处理：[异常/错误返回/结果类型]（证据：[文件路径]）
异步模式：[Promise/async-await/Goroutine/回调]（证据：[文件路径]）
依赖注入方式：[手动/框架/无]（证据：[文件路径]）


**步骤2：映射关键抽象**

识别5-10个最重要的类型、类或模块：

```markdown

Key Abstractions

关键抽象

[TypeName] ([file path]): [responsibility, what depends on it]
[TypeName] ([file path]): [responsibility, what depends on it] ...


Document: core domain concepts, primary interfaces/abstractions, component communication (direct calls, events, queues).

**Step 3: Document data flow**

Trace a typical request from entry point through the full stack:

```markdown

[类型名称]（[文件路径]）：[职责、依赖它的组件]
[类型名称]（[文件路径]）：[职责、依赖它的组件] ...


记录内容：核心领域概念、主要接口/抽象、组件通信方式（直接调用、事件、队列）。

**步骤3：记录数据流**

跟踪典型请求从入口点到整个栈的完整流程：

```markdown

Request Flow (typical)

典型请求流程

[/abs/path/main.py] - Starts server, registers routes
[/abs/path/routes/api.py] - Maps URL to handler
[/abs/path/handlers/user.py] - Validates input, calls service
[/abs/path/services/user.py] - Applies business logic
[/abs/path/models/user.py] - Persists to database
Response flows back through handler


**Step 4: Analyze recent activity**

```bash
git log --oneline --no-decorate -10

Categorize commits into themes:

Feature development (new capabilities)
Bug fixes (corrections)
Refactoring (structural changes)
Infrastructure (CI/CD, deployment, dependencies)

If not a git repository, note this limitation and skip this step.

Gate: Design patterns identified with file evidence. Key abstractions mapped (5-10 concepts). Data flow documented with absolute paths. Recent activity analyzed. Proceed ONLY when gate passes.

[/绝对路径/main.py] - 启动服务器，注册路由
[/绝对路径/routes/api.py] - 将URL映射到处理器
[/绝对路径/handlers/user.py] - 验证输入，调用服务
[/绝对路径/services/user.py] - 应用业务逻辑
[/绝对路径/models/user.py] - 持久化到数据库
响应通过处理器返回


**步骤4：分析近期活动**

```bash
git log --oneline --no-decorate -10

将提交分类为以下主题：

功能开发（新功能）
Bug修复（问题修正）
重构（结构变更）
基础设施（CI/CD、部署、依赖项）

如果不是Git仓库，记录此限制并跳过此步骤。

准入条件：已结合文件证据识别设计模式，已映射关键抽象（5-10个概念），已结合绝对路径记录数据流，已分析近期活动。仅当满足条件时方可进入下一阶段。

Phase 4: SUMMARIZE

阶段4：SUMMARIZE（总结）

Goal: Generate structured overview report.

Step 1: Generate report

Use the template in

references/report-template.md

. Fill every section with evidence from examined files. Requirements:

All file paths MUST be absolute
All architectural claims MUST cite source files
All commands MUST come from actual config files (package.json, Makefile, etc.)
Empty sections MUST note why information is unavailable

Step 2: Quality check

Before outputting, verify:

All 13 template sections addressed
No placeholder text remains
Every claim backed by file evidence
Paths are absolute, not relative
Commands are real, not guessed

Step 3: Generate "Where to Add New Code" section

Append a prescriptive section to the report. Developers exploring a codebase need to know not just what exists but where to put new things. For each major code category discovered during exploration, provide the directory, a concrete example file to use as a template, and any naming conventions.

markdown

undefined

目标：生成结构化概览报告。

步骤1：生成报告

使用

references/report-template.md

中的模板。用已检查文件的证据填充每个部分。要求：

所有文件路径必须为绝对路径
所有架构结论必须引用源文件
所有命令必须来自实际配置文件（package.json、Makefile等）
空部分必须注明信息不可用的原因

步骤2：质量检查

输出前，验证：

已覆盖所有13个模板章节
无占位文本残留
所有结论均有文件证据支持
路径为绝对路径，而非相对路径
命令为实际存在的，而非推测的

步骤3：生成“新增代码位置”章节

在报告末尾添加一个指导性章节。探索代码库的开发者不仅需要了解现有内容，还需要知道新增代码的位置。针对探索过程中发现的每个主要代码类别，提供目录、可作为模板的具体示例文件以及命名规范。

markdown

undefined

Where to Add New Code

新增代码位置指南

I want to add...	Put it in...	Follow the pattern in...
[category from exploration]	[directory path]	[concrete example file path]


Populate this table from evidence gathered in Phases 2-3. Every entry MUST reference a real file that already exists in the codebase. If a category has no clear home, note that explicitly rather than guessing.

**Step 4: Post-exploration secret scan**

Before presenting results, scan all output for accidentally captured secrets. Even with the forbidden-files guardrail, secrets can appear in non-obvious places (config comments, inline connection strings, hardcoded tokens in source).

```bash

我要添加...	应放在...	参考示例文件...
[探索中发现的类别]	[目录路径]	[具体示例文件路径]


使用阶段2-3中收集的证据填充此表格。每个条目必须引用代码库中已存在的真实文件。如果某个类别没有明确的存放位置，请明确注明，不要猜测。

**步骤4：探索后敏感信息扫描**

呈现结果前，扫描所有输出以检查是否意外捕获敏感信息。即使有敏感文件防护，敏感信息仍可能出现在非明显位置（配置注释、内联连接字符串、源代码中的硬编码令牌）。

```bash

Scan exploration output for common secret patterns

扫描探索输出中的常见敏感信息模式

grep -iE '(password|secret|token|api[-]?key|auth|credential)\s*[:=]' <output_file> || true grep -E '(AIza|sk-|ghp|gho_|AKIA|-----BEGIN)' <output_file> || true


If any matches are found:
1. Do NOT present the raw output to the user
2. Redact the matched lines (replace values with `[REDACTED]`)
3. Flag the finding: "Secret pattern detected in exploration output -- redacted before display. Review [file path] manually."

**Step 5: Output report**

Display complete markdown report to stdout. If export behavior is enabled, also write to file.

**Gate**: Report has all sections filled. All paths are absolute. All claims cite evidence. "Where to Add New Code" section populated with real file references. Secret scan passed (no unredacted secrets in output). Report is actionable for onboarding. Quality check passes. Total files examined count is accurate.

---

grep -iE '(password|secret|token|api[-]?key|auth|credential)\s*[:=]' <输出文件> || true grep -E '(AIza|sk-|ghp|gho_|AKIA|-----BEGIN)' <输出文件> || true


如果发现匹配项：
1. 不要向用户呈现原始输出
2. 编辑匹配行（将值替换为`[REDACTED]`）
3. 标记发现：“在探索输出中检测到敏感信息模式——显示前已编辑。请手动检查[文件路径]。”

**步骤5：输出报告**

将完整的Markdown报告显示到标准输出。如果启用了导出行为，同时写入到文件。

**准入条件**：报告所有章节已填充，所有路径为绝对路径，所有结论均有证据支持，“新增代码位置指南”章节已使用真实文件引用填充，敏感信息扫描通过（输出中无未编辑的敏感信息），报告对入职有实际指导意义，质量检查通过，已检查文件总数准确。

---

Parallel Domain-Specific Mapping (Deep Dive Mode)

并行领域特定映射（深度探索模式）

When the user requests a full architectural analysis (e.g., "give me the full picture", "I'm new to this codebase", "we're considering a major refactor"), use parallel domain-specific agents instead of single-threaded sequential exploration. This is faster (parallel execution) and produces higher-quality results (each agent focuses on its domain rather than context-switching across concerns).

当用户请求完整的架构分析时（例如：“给我完整的架构图”“我是这个代码库的新人”“我们正在考虑重大重构”），使用并行领域特定Agent而非单线程顺序探索。这种方式更快（并行执行）且结果质量更高（每个Agent专注于其领域，无需在不同关注点间切换上下文）。

When to Use

适用场景

Use parallel mapping when the exploration goal is broad and open-ended -- full onboarding, major refactor preparation, or comprehensive architectural review. Do NOT use for targeted questions about a single subsystem; the standard 4-phase flow is more efficient for focused exploration.

当探索目标广泛且开放时使用并行映射——例如完整入职准备、重大重构准备或全面架构审查。不要用于关于单个子系统的针对性问题；标准四阶段流程更适合聚焦式探索。

Agent Domains

Agent领域

Launch 4 parallel agents using Task, each focused on a specific domain. Each agent follows the forbidden-files guardrail and writes a structured document.

Agent	Focus	Output File
Technology Stack	Languages, frameworks, dependencies, build tools, CI/CD pipelines, runtime requirements	`exploration/tech-stack.md`
Architecture	Module structure, data flow, API boundaries, state management, component relationships, entry points	`exploration/architecture.md`
Code Quality	Test coverage patterns, linting config, type safety, documentation density, code style conventions	`exploration/code-quality.md`
Risks & Concerns	Technical debt indicators, security patterns, dependency health, TODO/FIXME/HACK density, deprecated APIs	`exploration/risks.md`

使用Task启动4个并行Agent，每个Agent专注于特定领域。每个Agent遵循敏感文件防护规则并编写结构化文档。

Agent	聚焦领域	输出文件
技术栈	语言、框架、依赖项、构建工具、CI/CD流水线、运行时要求	`exploration/tech-stack.md`
架构	模块结构、数据流、API边界、状态管理、组件关系、入口点	`exploration/architecture.md`
代码质量	测试覆盖模式、代码检查配置、类型安全、文档密度、代码风格规范	`exploration/code-quality.md`
风险与关注点	技术债务指标、安全模式、依赖项健康状况、TODO/FIXME/HACK密度、已弃用API	`exploration/risks.md`

Orchestration Rules

编排规则

Phase 1 (DETECT) runs first, sequentially -- All agents need the project type context from DETECT before they can explore effectively
Agents launch after DETECT gate passes -- Spawn all 4 agents in parallel using Task
Each agent writes its own output file -- Agents do not share context or coordinate
Timeout: 5 minutes per agent -- If an agent times out, proceed with completed results. Minimum 3 of 4 agents MUST complete.
Orchestrator does NOT merge results -- The parallel documents ARE the output. The orchestrator collects confirmations and line counts, then runs the post-exploration secret scan across all output files
Slight redundancy is acceptable -- Both Architecture and Risks agents may note the same coupling issue. This is preferable to gaps from trying to deduplicate.

阶段1（DETECT）先顺序执行——所有Agent需要DETECT阶段的项目类型上下文才能有效探索
DETECT阶段通过后启动Agent——使用Task并行生成所有4个Agent
每个Agent写入自己的输出文件——Agent之间不共享上下文或协调
超时：每个Agent5分钟——如果某个Agent超时，使用已完成的结果继续。至少3个Agent必须完成。
编排器不合并结果——并行文档即为输出结果。编排器收集确认信息和行数统计，然后对所有输出文件执行探索后敏感信息扫描
允许轻微冗余——架构Agent和风险Agent可能会注意到相同的耦合问题。这比尝试去重导致的信息缺失更可取。

Agent Instructions Template

Agent指令模板

Each parallel agent receives these instructions:

You are exploring a [language/framework] codebase focused on [DOMAIN].
Project root: [absolute path]
Project type: [from DETECT phase]

RULES:
- Read-only. NEVER modify files.
- NEVER read files matching forbidden patterns: .env, .env.*, *.pem, *.key, credentials.json, secrets.*, *secret*, *credential*, *password*, token.json, .npmrc, .pypirc, .aws/credentials, .gcloud/, service-account*.json
- All file paths in output MUST be absolute.
- Every claim MUST cite an examined file.

Write your findings to: exploration/[domain].md

每个并行Agent将收到以下指令：

你正在探索一个[语言/框架]代码库，聚焦于[领域]。
项目根目录：[绝对路径]
项目类型：[来自DETECT阶段]

规则：
- 只读操作。**绝不**修改文件。
- **绝不**读取匹配以下模式的文件：.env, .env.*, *.pem, *.key, credentials.json, secrets.*, *secret*, *credential*, *password*, token.json, .npmrc, .pypirc, .aws/credentials, .gcloud/, service-account*.json
- 输出中所有文件路径必须为绝对路径。
- 所有结论必须引用已检查的文件。

请将你的发现写入：exploration/[领域].md

Post-Parallel Gate

并行阶段准入条件

Gate: At least 3 of 4 domain agents completed. All output files exist. Secret scan passed across all output files. Each file contains file-backed evidence (not generic descriptions).

准入条件：至少4个领域Agent中的3个已完成，所有输出文件已存在，所有输出文件通过敏感信息扫描，每个文件包含基于文件的证据（而非通用描述）。

Examples

示例

Example 1: New Project Onboarding

示例1：新项目入职

User says: "Help me understand this codebase" Actions:

Check root for config files, identify Python/FastAPI project (DETECT)
Read
```
main.py
```
, map
```
src/
```
structure, examine
```
models/
```
,
```
routes/
```
(EXPLORE)
Identify layered architecture, map User/Order/Payment models, trace request flow (MAP)
Generate report with all sections, absolute paths, evidence citations (SUMMARIZE) Result: Structured overview enabling immediate productive contribution

用户请求：“帮我理解这个代码库” 操作：

检查根目录配置文件，识别为Python/FastAPI项目（DETECT）
读取
```
main.py
```
，映射
```
src/
```
结构，检查
```
models/
```
、
```
routes/
```
（EXPLORE）
识别分层架构，映射User/Order/Payment模型，跟踪请求流程（MAP）
生成包含所有章节、绝对路径和证据引用的报告（SUMMARIZE）结果：结构化概览，可立即用于高效贡献

Example 2: Pre-Review Context Building

示例2：代码审查前构建上下文

User says: "I need to review a PR in this repo but don't know the codebase" Actions:

Detect Go project with
```
go.mod
```
, identify Gin framework (DETECT)
Find
```
cmd/server/main.go
```
entry point, map
```
internal/
```
packages (EXPLORE)
Map handler -> service -> repository pattern, document gRPC + REST dual API (MAP)
Generate report focused on architecture and conventions (SUMMARIZE) Result: Reviewer has architectural context for informed code review

用户请求：“我需要审查这个仓库的PR，但我不了解这个代码库” 操作：

通过
```
go.mod
```
检测为Go项目，识别Gin框架（DETECT）
找到
```
cmd/server/main.go
```
入口点，映射
```
internal/
```
包（EXPLORE）
映射处理器->服务->仓库模式，记录gRPC + REST双API（MAP）
生成聚焦于架构和规范的报告（SUMMARIZE）结果：审查者具备架构上下文，可进行有依据的代码审查

Example 3: Pre-Debug Context

示例3：调试前构建上下文

User says: "I need to fix a bug but don't know this codebase yet" Actions:

Detect Node.js/Express project from
```
package.json
```
(DETECT)
Find
```
src/index.ts
```
entry, map middleware chain, locate error handlers (EXPLORE)
Map request lifecycle through middleware -> router -> controller -> service (MAP)
Generate report emphasizing error handling patterns and test structure (SUMMARIZE) Result: Debugger has structural context to apply systematic-debugging skill effectively

用户请求：“我需要修复一个Bug，但我还不了解这个代码库” 操作：

通过
```
package.json
```
检测为Node.js/Express项目（DETECT）
找到
```
src/index.ts
```
入口，映射中间件链，定位错误处理器（EXPLORE）
映射请求生命周期：中间件 -> 路由 -> 控制器 -> 服务（MAP）
生成强调错误处理模式和测试结构的报告（SUMMARIZE）结果：调试者具备结构上下文，可有效应用系统化调试技能

Error Handling

错误处理

Error: "Cannot Determine Project Type"

错误：“无法确定项目类型”

Cause: No recognized configuration files in root directory Solution:

Check if in a subdirectory (
```
pwd
```
)
Look for README that might indicate project type
Examine file extensions to infer dominant language
Document as "Unknown project type" and proceed with generic exploration

原因：根目录中无识别的配置文件解决方案：

检查是否在子目录中（
```
pwd
```
）
查找可能指示项目类型的README
检查文件扩展名以推断主导语言
记录为“未知项目类型”，并继续通用探索

Error: "Not a Git Repository"

错误：“不是Git仓库”

Cause: Directory lacks

.git/

or git is not initialized Solution: Skip git-related steps (recent commits, development activity). Note in report that version control info is unavailable. Continue with all other phases.

原因：目录缺少

.git/

或未初始化Git 解决方案：跳过Git相关步骤（最近提交、开发活动）。在报告中记录版本控制信息不可用。继续执行所有其他阶段。

Error: "Too Many Files to Examine"

错误：“文件过多，无法全部检查”

Cause: Large monorepo, generated files, or broad project scope Solution:

Limit to 20 files per category (default behavior)
Exclude noise directories
Focus on representative samples, not exhaustive coverage
Note in report: "Examined N of M files as representative samples"

原因：大型单体仓库、生成文件或项目范围过广解决方案：

每个类别限制为20个文件（默认行为）
排除无关目录
聚焦于代表性样本，而非全面覆盖
在报告中记录：“已检查N个文件作为代表性样本，共M个文件”

Error: "Permission Denied Reading File"

错误：“读取文件权限被拒绝”

Cause: File permissions prevent reading Solution: Skip the inaccessible file. Note in the "Files Examined" section which files were inaccessible. Continue with remaining files in that category.

原因：文件权限阻止读取解决方案：跳过无法访问的文件。在“已检查文件”部分记录哪些文件无法访问。继续检查该类别中的剩余文件。

Anti-Patterns

反模式

Anti-Pattern 1: Exploring Without Detecting Project Type

反模式1：未检测项目类型就开始探索

What it looks like: Reading random source files before checking config files Why wrong: Wastes time, misinterprets code without framework context, produces inaccurate conclusions Do instead: Complete Phase 1 (DETECT) first. Always read config before code.

表现：在检查配置文件前读取随机源文件危害：浪费时间，缺乏框架上下文导致代码解读错误，结论不准确 正确做法：先完成阶段1（DETECT）。始终先读取配置文件再读取代码。

Anti-Pattern 2: Claims Without File Evidence

反模式2：无文件证据的结论

What it looks like: "This appears to use microservices" without citing any examined file Why wrong: Violates evidence-required hardcoded behavior. Misleads readers. Cannot be verified. Do instead: Every claim cites a file. Example: "Uses PostgreSQL (confirmed in

/abs/path/config/database.py

postgresql://...

表现：“这似乎使用了微服务架构”但未引用任何已检查文件危害：违反需提供证据的硬编码行为。误导读者。无法验证。 正确做法：所有结论必须引用文件。示例：“使用PostgreSQL（在

/绝对路径/config/database.py

中确认：

postgresql://...

）”

Anti-Pattern 3: Exhaustive File Reading

反模式3：过度读取文件

What it looks like: Reading all 50+ files in

models/

directory instead of 3-5 representatives Why wrong: Token bloat without proportional value. Violates over-engineering prevention. Do instead: Limit to 20 files per category. Read representative samples. Note coverage in report.

表现：读取

models/

目录中的所有50+文件，而非3-5个代表性文件危害：无意义的令牌消耗，性价比低。违反防止过度探索规则。 正确做法：每个类别限制为20个文件。读取代表性样本。在报告中记录覆盖范围。

Anti-Pattern 4: Skipping Phase Gates

反模式4：跳过阶段准入条件

What it looks like: Jumping to MAP before finishing EXPLORE, or generating report with missing sections Why wrong: Incomplete overview with critical gaps. Wrong architectural assumptions. Do instead: Verify every gate condition before proceeding. Return to previous phase if information is missing.

表现：未完成EXPLORE就跳转到MAP，或生成内容不全的报告危害：概览不完整，存在关键漏洞。架构假设错误。 正确做法：推进前验证每个阶段的准入条件。如果信息缺失，返回上一阶段。

Anti-Pattern 5: Generic Report Output

反模式5：通用报告输出

What it looks like: Report with "This module handles business logic" and no file paths or specifics Why wrong: Not actionable for onboarding. No better than reading a README. Do instead: Include specific paths, line references, and exact commands from config files.

表现：报告中仅包含“此模块处理业务逻辑”，无文件路径或具体信息危害：对入职无实际指导意义。效果不如直接阅读README。 正确做法：包含具体路径、行引用和配置文件中的准确命令。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本Skill使用以下共享模式：

反合理化 - 防止捷径式合理化
验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

特定领域反合理化

Rationalization	Why It's Wrong	Required Action
"I can infer the architecture from the README"	README may be outdated or incomplete	Examine actual source files
"Config files are enough to understand the project"	Config shows dependencies, not architecture	Read entry points and core modules
"20 files is enough for any project"	Some areas need deeper sampling	Adjust per category, note limitations
"Report looks complete"	Looking complete != being complete	Verify every section has file-backed evidence

合理化借口	错误原因	正确做法
“我可以从README推断架构”	README可能过时或不完整	检查实际源代码文件
“配置文件足以理解项目”	配置仅显示依赖项，不显示架构	读取入口点和核心模块
“20个文件足够覆盖任何项目”	某些领域需要更深入的抽样	根据类别调整，记录限制
“报告看起来完整了”	看起来完整不等于实际完整	验证每个章节均有文件证据支持

Reference Files

参考文件

```
${CLAUDE_SKILL_DIR}/references/report-template.md
```
: Standard markdown report template with all sections

${CLAUDE_SKILL_DIR}/references/exploration-strategies.md

: Language-specific discovery commands and patterns

```
${CLAUDE_SKILL_DIR}/references/report-template.md
```
：包含所有章节的标准Markdown报告模板

${CLAUDE_SKILL_DIR}/references/exploration-strategies.md

：特定语言的探索命令和模式