codebase-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Onboarding

代码库入职引导

Systematically analyze an unfamiliar codebase and produce a structured onboarding guide. Designed for developers joining a new project or setting up Claude Code in an existing repo for the first time.

系统性地分析不熟悉的代码库，生成结构化的入职指南。专为加入新项目的开发者或首次在现有代码库中设置Claude Code的用户设计。

When to Use

使用时机

First time opening a project with Claude Code
Joining a new team or repository
User asks "help me understand this codebase"
User asks to generate a CLAUDE.md for a project
User says "onboard me" or "walk me through this repo"

首次使用Claude Code打开项目
加入新团队或新代码库
用户要求“帮我理解这个代码库”
用户要求为项目生成CLAUDE.md
用户说“带我入门”或“带我浏览这个仓库”

How It Works

工作原理

Phase 1: Reconnaissance

阶段1：侦察

Gather raw signals about the project without reading every file. Run these checks in parallel:

1. Package manifest detection
   → package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
     Gemfile, composer.json, mix.exs, pubspec.yaml

2. Framework fingerprinting
   → next.config.*, nuxt.config.*, angular.json, vite.config.*,
     django settings, flask app factory, fastapi main, rails config

3. Entry point identification
   → main.*, index.*, app.*, server.*, cmd/, src/main/

4. Directory structure snapshot
   → Top 2 levels of the directory tree, ignoring node_modules, vendor,
     .git, dist, build, __pycache__, .next

5. Config and tooling detection
   → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
     docker-compose*, .github/workflows/, .env.example, CI configs

6. Test structure detection
   → tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
     pytest.ini, jest.config.*, vitest.config.*

在不阅读每个文件的情况下收集项目原始信号。并行执行以下检查：

1. 包清单检测
   → package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
     Gemfile, composer.json, mix.exs, pubspec.yaml

2. 框架指纹识别
   → next.config.*, nuxt.config.*, angular.json, vite.config.*,
     django settings, flask app factory, fastapi main, rails config

3. 入口点识别
   → main.*, index.*, app.*, server.*, cmd/, src/main/

4. 目录结构快照
   → 目录树前2层，忽略 node_modules, vendor,
     .git, dist, build, __pycache__, .next

5. 配置与工具链检测
   → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
     docker-compose*, .github/workflows/, .env.example, CI configs

6. 测试结构检测
   → tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
     pytest.ini, jest.config.*, vitest.config.*

Phase 2: Architecture Mapping

阶段2：架构映射

From the reconnaissance data, identify:

Tech Stack

Language(s) and version constraints
Framework(s) and major libraries
Database(s) and ORMs
Build tools and bundlers
CI/CD platform

Architecture Pattern

Monolith, monorepo, microservices, or serverless
Frontend/backend split or full-stack
API style: REST, GraphQL, gRPC, tRPC

Key Directories Map the top-level directories to their purpose:

src/components/  → React UI components
src/api/         → API route handlers
src/lib/         → Shared utilities
src/db/          → Database models and migrations
tests/           → Test suites
scripts/         → Build and deployment scripts

Data Flow Trace one request from entry to response:

Where does a request enter? (router, handler, controller)
How is it validated? (middleware, schemas, guards)
Where is business logic? (services, models, use cases)
How does it reach the database? (ORM, raw queries, repositories)

根据侦察数据，识别：

技术栈

语言及版本约束
框架和主要库
数据库和ORM
构建工具和打包器
CI/CD平台

架构模式

单体、monorepo、微服务或Serverless
前后端分离或全栈
API风格：REST、GraphQL、gRPC、tRPC

关键目录

将顶级目录映射到其用途：

src/components/  → React UI组件
src/api/         → API路由处理器
src/lib/         → 共享工具函数
src/db/          → 数据库模型和迁移
tests/           → 测试套件
scripts/         → 构建和部署脚本

数据流

追踪一个请求从入口到响应：

请求从哪里进入？（路由器、处理器、控制器）
如何验证？（中间件、模式、守卫）
业务逻辑在哪里？（服务、模型、用例）
如何到达数据库？（ORM、原生查询、仓储）

Phase 3: Convention Detection

阶段3：约定检测

Identify patterns the codebase already follows:

Naming Conventions

File naming: kebab-case, camelCase, PascalCase, snake_case
Component/class naming patterns
Test file naming:
```
*.test.ts
```
,
```
*.spec.ts
```
,
```
*_test.go
```

Code Patterns

Error handling style: try/catch, Result types, error codes
Dependency injection or direct imports
State management approach
Async patterns: callbacks, promises, async/await, channels

Git Conventions

Branch naming from recent branches
Commit message style from recent commits
PR workflow (squash, merge, rebase)
If the repo has no commits yet or only a shallow history (e.g.
```
git clone --depth 1
```
), skip this section and note "Git history unavailable or too shallow to detect conventions"

识别代码库已遵循的模式：

命名约定

文件命名：kebab-case、camelCase、PascalCase、snake_case
组件/类命名模式
测试文件命名：
```
*.test.ts
```
、
```
*.spec.ts
```
、
```
*_test.go
```

代码模式

错误处理方式：try/catch、Result类型、错误码
依赖注入或直接导入
状态管理方法
异步模式：回调、Promise、async/await、channel

Git约定

从近期分支推断分支命名
从近期提交推断提交信息风格
PR工作流（squash、merge、rebase）
如果仓库尚无提交或历史过浅（例如
```
git clone --depth 1
```
），则跳过此部分，并注明“Git历史不可用或太浅，无法检测约定”

Phase 4: Generate Onboarding Artifacts

阶段4：生成入职产物

Produce two outputs:

生成两样输出：

Output 1: Onboarding Guide

输出1：入职指南

markdown

undefined

markdown

undefined

Onboarding Guide: [Project Name]

入职指南：[项目名称]

Overview

概述

[2-3 sentences: what this project does and who it serves]

[2-3句话：这个项目做什么，服务谁]

Tech Stack

技术栈

Layer	Technology	Version
Language	TypeScript	5.x
Framework	Next.js	14.x
Database	PostgreSQL	16
ORM	Prisma	5.x
Testing	Jest + Playwright	-

层次	技术	版本
语言	TypeScript	5.x
框架	Next.js	14.x
数据库	PostgreSQL	16
ORM	Prisma	5.x
测试	Jest + Playwright	-

Architecture

架构

[Diagram or description of how components connect]

[组件连接方式图或描述]

Key Entry Points

关键入口点

API routes:
```
src/app/api/
```
— Next.js route handlers
UI pages:
```
src/app/(dashboard)/
```
— authenticated pages
Database:
```
prisma/schema.prisma
```
— data model source of truth
Config:
```
next.config.ts
```
— build and runtime config

API路由：
```
src/app/api/
```
— Next.js路由处理器
UI页面：
```
src/app/(dashboard)/
```
— 已认证页面
数据库：
```
prisma/schema.prisma
```
— 数据模型的事实来源
配置：
```
next.config.ts
```
— 构建和运行时配置

Directory Map

目录映射

[Top-level directory → purpose mapping]

[顶级目录 → 用途映射]

Request Lifecycle

请求生命周期

[Trace one API request from entry to response]

[追踪一个API请求从入口到响应]

Conventions

约定

[File naming pattern]
[Error handling approach]
[Testing patterns]
[Git workflow]

[文件命名模式]
[错误处理方法]
[测试模式]
[Git工作流]

Common Tasks

常见任务

Run dev server:
```
npm run dev
```
Run tests:
```
npm test
```
Run linter:
```
npm run lint
```
Database migrations:
```
npx prisma migrate dev
```
Build for production:
```
npm run build
```

启动开发服务器：
```
npm run dev
```
运行测试：
```
npm test
```
运行linter：
```
npm run lint
```
数据库迁移：
```
npx prisma migrate dev
```
生产构建：
```
npm run build
```

Where to Look

在哪里查找

I want to...	Look at...
Add an API endpoint	`src/app/api/`
Add a UI page	`src/app/(dashboard)/`
Add a database table	`prisma/schema.prisma`
Add a test	`tests/` matching the source path
Change build config	`next.config.ts`

undefined

我想...	查看...
添加API端点	`src/app/api/`
添加UI页面	`src/app/(dashboard)/`
添加数据库表	`prisma/schema.prisma`
添加测试	`tests/` 匹配源路径
更改构建配置	`next.config.ts`

undefined

Output 2: Starter CLAUDE.md

输出2：初始CLAUDE.md

Generate or update a project-specific CLAUDE.md based on detected conventions. If

CLAUDE.md

already exists, read it first and enhance it — preserve existing project-specific instructions and clearly call out what was added or changed.

markdown

undefined

根据检测到的约定生成或更新项目特定的CLAUDE.md。如果

CLAUDE.md

已存在，先读取并增强——保留现有项目特定指令，并明确标出新增或更改的内容。

markdown

undefined

Project Instructions

项目指令

Tech Stack

技术栈

[Detected stack summary]

[检测到的技术栈摘要]

Code Style

代码风格

[Detected naming conventions]
[Detected patterns to follow]

[检测到的命名约定]
[检测到的要遵循的模式]

Testing

测试

Run tests:
```
[detected test command]
```
Test pattern: [detected test file convention]
Coverage: [if configured, the coverage command]

运行测试：
```
[检测到的测试命令]
```
测试模式：[检测到的测试文件约定]
覆盖率：[如已配置，则覆盖率命令]

Build & Run

构建与运行

Dev:
```
[detected dev command]
```
Build:
```
[detected build command]
```
Lint:
```
[detected lint command]
```

开发：
```
[检测到的开发命令]
```
构建：
```
[检测到的构建命令]
```
静态检查：
```
[检测到的lint命令]
```

Project Structure

项目结构

[Key directory → purpose map]

[关键目录 → 用途映射]

Conventions

约定

[Commit style if detectable]
[PR workflow if detectable]
[Error handling patterns]

undefined

[可检测到时的提交风格]
[可检测到时的PR工作流]
[错误处理模式]

undefined

Best Practices

最佳实践

Don't read everything — reconnaissance should use Glob and Grep, not Read on every file. Read selectively only for ambiguous signals.
Verify, don't guess — if a framework is detected from config but the actual code uses something different, trust the code.
Respect existing CLAUDE.md — if one already exists, enhance it rather than replacing it. Call out what's new vs existing.
Stay concise — the onboarding guide should be scannable in 2 minutes. Details belong in the code, not the guide.
Flag unknowns — if a convention can't be confidently detected, say so rather than guessing. "Could not determine test runner" is better than a wrong answer.

不要通读所有文件 — 侦察应使用Glob和Grep，而不是读取每个文件。仅对模糊信号进行选择性读取。
验证而非猜测 — 如果从配置检测到框架，但实际代码使用了不同的东西，相信代码。
尊重现有CLAUDE.md — 如果已存在，则增强而不是替换。标出新内容与已有内容的区别。
保持简洁 — 入职指南应在2分钟内扫读完毕。细节属于代码，而非指南。
标记未知项 — 如果无法自信地检测到某个约定，直接说明，而不是猜测。“无法确定测试运行器”胜过错误答案。

Anti-Patterns to Avoid

应避免的反模式

Generating a CLAUDE.md that's longer than 100 lines — keep it focused
Listing every dependency — highlight only the ones that shape how you write code
Describing obvious directory names —
```
src/
```
doesn't need an explanation
Copying the README — the onboarding guide adds structural insight the README lacks

生成超过100行的CLAUDE.md——保持聚焦
列出每个依赖项——只突出影响代码编写方式的那部分
描述显而易见的目录名——
```
src/
```
不需要解释
复制README——入职指南提供了README缺少的结构性见解

Examples

示例

Example 1: First time in a new repo

示例1：首次进入新代码库

User: "Onboard me to this codebase" Action: Run full 4-phase workflow → produce Onboarding Guide + Starter CLAUDE.md Output: Onboarding Guide printed directly to the conversation, plus a

CLAUDE.md

written to the project root

用户：“带我进入这个代码库” 操作：运行完整的4阶段工作流 → 生成入职指南 + 初始CLAUDE.md 输出：入职指南直接打印到对话中，同时将

CLAUDE.md

写入项目根目录

Example 2: Generate CLAUDE.md for existing project

示例2：为现有项目生成CLAUDE.md

User: "Generate a CLAUDE.md for this project" Action: Run Phases 1-3, skip Onboarding Guide, produce only CLAUDE.md Output: Project-specific

CLAUDE.md

with detected conventions

用户：“为这个项目生成CLAUDE.md” 操作：运行阶段1-3，跳过入职指南，仅生成CLAUDE.md 输出：包含检测到的约定的项目特定

CLAUDE.md

Example 3: Enhance existing CLAUDE.md

示例3：增强现有CLAUDE.md

User: "Update the CLAUDE.md with current project conventions" Action: Read existing CLAUDE.md, run Phases 1-3, merge new findings Output: Updated

CLAUDE.md

with additions clearly marked

用户：“用当前项目约定更新CLAUDE.md” 操作：读取现有CLAUDE.md，运行阶段1-3，合并新发现输出：已更新

CLAUDE.md

，并明确标记新增内容