---
id: daily-codebase-onboarding
name: "codebase-onboarding"
url: https://skills.yangsir.net/skill/daily-codebase-onboarding
author: affaan-m
domain: ai-dev-tools-workflow
tags: ["codebase", "onboarding", "ai", "llm", "agents"]
install_count: 4000
rating: 4.40 (20 reviews)
github: https://github.com/affaan-m/everything-claude-code
---

# codebase-onboarding

> 系统化分析陌生代码库，生成结构化的入门指南，帮助开发者快速理解项目架构和核心功能

**Stats**: 4,000 installs · 4.4/5 (20 reviews)

## Before / After 对比

### 快速理解陌生代码库

**Before**:

当开发者加入新项目或首次接触陌生代码库时，通常需要手动进行大量探索。这包括逐个查看 `package.json`、`go.mod` 等配置文件以识别技术栈，手动浏览目录结构、查找入口文件、猜测框架类型，并尝试追踪请求的数据流。这个过程耗时且容易遗漏关键信息，需要反复查阅文档或请教同事，导致初期上手效率低下，理解不全面。

**After**:

使用 `codebase-onboarding` 后，AI 会系统化地分析代码库。它会自动执行侦察阶段，检测包清单、框架指纹、入口点、目录结构、配置工具和测试结构。随后，它会映射出技术栈、架构模式、关键目录及其用途，并追踪一个请求的完整数据流。最终生成一份结构化的入门指南，帮助开发者快速、准确地掌握项目全貌，显著缩短学习曲线。

| Metric | Before | After | Change |
|---|---|---|---|
| 理解代码库所需时间 | 8小时 | 0.5小时 | -93.75% |
| 首次贡献代码所需时间 | 3天 | 1天 | -66.67% |
| 关键架构信息发现完整度 | 60% | 90% | +50% |

## Readme

# codebase-onboarding

# 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.

## 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"

## How It Works

### Phase 1: Reconnaissance

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.*

```

### Phase 2: Architecture Mapping

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)

### Phase 3: Convention Detection

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"

### Phase 4: Generate Onboarding Artifacts

Produce two outputs:

#### Output 1: Onboarding Guide

```
# Onboarding Guide: [Project Name]

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

## Tech Stack
<!-- Example for a Next.js project — replace with detected stack -->
| Layer | Technology | Version |
|-------|-----------|---------|
| Language | TypeScript | 5.x |
| Framework | Next.js | 14.x |
| Database | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| Testing | Jest + Playwright | - |

## Architecture
[Diagram or description of how components connect]

## Key Entry Points
<!-- Example for a Next.js project — replace with detected paths -->
- **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

## Directory Map
[Top-level directory → purpose mapping]

## Request Lifecycle
[Trace one API request from entry to response]

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

## Common Tasks
<!-- Example for a Node.js project — replace with detected commands -->
- **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`

## Where to Look
<!-- Example for a Next.js project — replace with detected paths -->
| 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` |

```

#### Output 2: Starter 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.

```
# 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]`

## Project Structure
[Key directory → purpose map]

## Conventions
- [Commit style if detectable]
- [PR workflow if detectable]
- [Error handling patterns]

```

## 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.

## 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

## Examples

### Example 1: First time in a new repo

**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

### Example 2: Generate CLAUDE.md for existing project

**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

### Example 3: Enhance existing 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
Weekly Installs290Repository[affaan-m/everyt…ude-code](https://github.com/affaan-m/everything-claude-code)GitHub Stars105.0KFirst Seen5 days agoSecurity Audits[Gen Agent Trust HubPass](/affaan-m/everything-claude-code/codebase-onboarding/security/agent-trust-hub)[SocketPass](/affaan-m/everything-claude-code/codebase-onboarding/security/socket)[SnykPass](/affaan-m/everything-claude-code/codebase-onboarding/security/snyk)Installed oncodex279cursor253opencode251github-copilot251gemini-cli251amp251

---
*Source: https://skills.yangsir.net/skill/daily-codebase-onboarding*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-codebase-onboarding/markdown*