Codebase Onboarding Guide

Мгновенно анализируйте любую кодовую базу с помощью навыка Codebase Onboarding. Создавайте карты архитектуры, обнаруживайте соглашения и генерируйте файлы CLAUDE.md для Claude Code.

Обучение и документация ★ 172,009 GitHub (172,009 ★)

Навык Codebase Onboarding автоматизирует этап ознакомления при вхождении в новый проект, систематически сканируя технологические стеки, сигнатуры фреймворков и структуры каталогов. Он преобразует сложную структуру репозитория в удобные онбординг-гайды, создаёт или обновляет файлы CLAUDE.md, чтобы ИИ-агенты следовали локальным соглашениям о коде. Определяя точки входа, потоки данных и паттерны именования, этот навык помогает как разработчикам-людям, так и ИИ-ассистентам получить структурное понимание, необходимое для немедленной навигации и внесения вклада в кодовую базу.

Ключевые возможности

01Умное слияние с существующей документацией для сохранения исторического контекста.

02Многофазная разведка для обнаружения технологических стеков, фреймворков и точек входа.

03Автоматическое картирование архитектуры и визуализация назначения каталогов.

04Генерация проектно-специфичных инструкций CLAUDE.md для ИИ-агентов.

05Обнаружение соглашений о коде, паттернов именования и Git-воркфлоу.

06172 009 звёзд на GitHub

Сценарии использования

01Новые разработчики, присоединяющиеся к существующей команде или репозиторию, которым требуется быстрая ориентация.

02Первоначальная настройка Claude Code в недокументированном или унаследованном проекте.

03Стандартизация проектных инструкций и соглашений в нескольких репозиториях.

name	codebase-onboarding
description	Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CLAUDE.md. Use when joining a new project or setting up Claude Code for the first time in a repo.
origin	ECC

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

🧭 Что это

Codebase Onboarding Guide — это навык (skill) для Claude Code, который автоматически анализирует незнакомую кодовую базу и генерирует структурированное руководство по онбордингу (onboarding guide) и/или стартовый файл CLAUDE.md с проектными конвенциями. Он предназначен для разработчиков, которые впервые открывают репозиторий с Claude Code, присоединяются к новой команде или хотят быстро погрузиться в архитектуру проекта без ручного изучения каждого файла.

⚙️ Как работает

Процесс состоит из четырёх фаз, которые выполняются последовательно или выборочно в зависимости от запроса пользователя.

🔍 Фаза 1: Разведка (Reconnaissance)

Сбор «сигналов» о проекте без чтения каждого файла. Используются Glob и Grep для параллельного обнаружения:

Манифесты пакетов: package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle, Gemfile, composer.json, mix.exs, pubspec.yaml.
Фреймворки: конфиги Next.js, Nuxt, Angular, Vite, Django, Flask, FastAPI, Rails.
Точки входа: main.*, index.*, app.*, server.*, cmd/, src/main/.
Структура директорий: верхние два уровня дерева (исключая node_modules, vendor, .git, dist, build, __pycache__, .next).
Инструменты и CI: ESLint, Prettier, TypeScript, Makefile, Docker, GitHub Actions, .env.example.
Тесты: папки tests/, test/, __tests__/, файлы *_test.go, *.spec.ts, конфиги jest.config.*, vitest.config.*, pytest.ini.

🗺️ Фаза 2: Картирование архитектуры (Architecture Mapping)

На основе данных разведки определяются:

Технологический стек — языки, фреймворки, базы данных, ORM, сборщики, CI/CD.
Архитектурный паттерн — монолит, монопепо (monorepo), микросервисы, serverless; фронтенд/бэкенд; стиль API (REST, GraphQL, gRPC, tRPC).
Ключевые директории — сопоставление путей с их назначением (например, src/components/ → React-компоненты).
Жизненный цикл запроса — трассировка от входа (роутер/обработчик) через валидацию (middleware/схемы), бизнес-логику (сервисы/use cases) до базы данных (ORM/запросы).

📐 Фаза 3: Определение конвенций (Convention Detection)

Выявление паттернов, которые уже используются в кодовой базе:

Соглашения об именовании: kebab-case, camelCase, PascalCase, snake_case для файлов и компонентов.
Паттерны кода: стиль обработки ошибок (try/catch vs Result), DI или прямые импорты, подход к управлению состоянием, асинхронные паттерны (async/await, промисы, каналы).
Git-конвенции: стиль именования веток, коммитов, workflow PR (squash, merge, rebase). Если история Git отсутствует или слишком мелкая (--depth 1), раздел пропускается с пометкой.

📄 Фаза 4: Генерация артефактов (Generate Onboarding Artifacts)

В зависимости от запроса генерируется один или оба результата:

Артефакт 1: Руководство по онбордингу (Onboarding Guide)

Насыщенный Markdown в виде таблиц и списков:

Обзор проекта и краткое описание.
Таблица технологического стека (слой, технология, версия).
Архитектурная схема (текстовое описание связей компонентов).
Ключевые точки входа (src/api/, prisma/schema.prisma, next.config.ts).
Карта директорий (назначение каждой папки).
Пример жизненного цикла запроса.
Список конвенций (именование, обработка ошибок, тестирование, Git).
Таблицы «Куда смотреть» для типовых задач (добавить API, UI, таблицу БД, тест).

Артефакт 2: Стартовый `CLAUDE.md`

Генерируется или дополняется файл CLAUDE.md в корне проекта, содержащий:

Tech Stack.
Code Style (конвенции именования, паттерны).
Команды для тестирования, сборки, линтинга.
Карту ключевых директорий.
Git-конвенции.

Если CLAUDE.md уже существует, навык читает его и дополняет новыми данными, явно помечая добавленные/изменённые секции.

🎯 Когда использовать

Этот навык полезен в следующих сценариях:

Первое открытие проекта в Claude Code — для быстрого понимания структуры и конвенций.
Присоединение к новой команде — чтобы не тратить часы на ручное изучение репозитория.
По запросу «Помоги мне разобраться в этом коде» — пользователь просит объяснить код базу.
Генерация CLAUDE.md — запросы вроде «сгенерируй CLAUDE.md» или «обнови файл конфигурации Claude».
Обновление конвенций — когда проект уже существует, но его конвенции изменились, навык может дополнить существующий файл новыми правилами.

📝 Важно знать

Не читает каждый файл подряд — использует Glob и Grep для эффективного поиска.
Если обнаруженное из конфига не совпадает с кодом — навык доверяет реальному коду, а не конфигурации.
Если конвенцию не удалось уверенно определить, навык честно сообщает об этом (например, «Не удалось определить test runner»), а не угадывает.
Готовый CLAUDE.md не должен превышать 100 строк — навык избегает перечисления всех зависимостей или описания очевидных папок (src/).
Руководство по онбордингу ориентировано на просмотр за 2 минуты — кратко и структурированно.

Примеры использования

Пример 1. Пользователь пишет: «Onboard me to this codebase». Навык выполняет все 4 фазы, выводит руководство в диалог и записывает CLAUDE.md в корень проекта.

Пример 2. Пользователь пишет: «Generate a CLAUDE.md». Навык выполняет фазы 1–3 (разведка, архитектура, конвенции) и генерирует только CLAUDE.md.

Пример 3. Пользователь пишет: «Update the CLAUDE.md». Навык читает существующий файл, повторно анализирует код и вливает новые находки, помечая изменения.

Команды для типовых задач (пример для Node.js/Next.js)

# Запустить дев-сервер
npm run dev

# Запустить тесты
npm test

# Запустить линтер
npm run lint

# Выполнить миграции БД
npx prisma migrate dev

# Собрать для продакшена
npm run build

🚫 Анти-паттерны (чего избегать)

Генерация пустого CLAUDE.md длиннее 100 строк.
Перечисление всех зависимостей — важны только те, что влияют на стиль кода.
Описание очевидных папок («src/ содержит исходный код»).
Копирование README — руководство должно добавлять структурную информацию, которой нет в README.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code codebase-onboarding

Источник: https://mcpmarket.com/tools/skills/codebase-onboarding-guide-1

Codebase Onboarding Guide

Ключевые возможности

Сценарии использования

Codebase Onboarding

When to Use

How It Works

Phase 1: Reconnaissance

Phase 2: Architecture Mapping

Phase 3: Convention Detection

Phase 4: Generate Onboarding Artifacts

Output 1: Onboarding Guide

Output 2: Starter CLAUDE.md

Best Practices

Anti-Patterns to Avoid

Examples

Example 1: First time in a new repo

Example 2: Generate CLAUDE.md for existing project

Example 3: Enhance existing CLAUDE.md

🧭 Что это

⚙️ Как работает

🔍 Фаза 1: Разведка (Reconnaissance)

🗺️ Фаза 2: Картирование архитектуры (Architecture Mapping)

📐 Фаза 3: Определение конвенций (Convention Detection)

📄 Фаза 4: Генерация артефактов (Generate Onboarding Artifacts)

Артефакт 1: Руководство по онбордингу (Onboarding Guide)

Артефакт 2: Стартовый `CLAUDE.md`

🎯 Когда использовать

📝 Важно знать

Примеры использования

Команды для типовых задач (пример для Node.js/Next.js)

🚫 Анти-паттерны (чего избегать)

Безопасно ли запускать на больших репозиториях?

Какова основная цель навыка Codebase Onboarding?

Перезаписывает ли он существующую документацию?

Какие языки программирования поддерживаются?

Как определяется архитектура проекта?

Комментарии

Ключевые возможности

Сценарии использования

Codebase Onboarding

When to Use

How It Works

Phase 1: Reconnaissance

Phase 2: Architecture Mapping

Phase 3: Convention Detection

Phase 4: Generate Onboarding Artifacts

Output 1: Onboarding Guide

Output 2: Starter CLAUDE.md

Best Practices

Anti-Patterns to Avoid

Examples

Example 1: First time in a new repo

Example 2: Generate CLAUDE.md for existing project

Example 3: Enhance existing CLAUDE.md

🧭 Что это

⚙️ Как работает

🔍 Фаза 1: Разведка (Reconnaissance)

🗺️ Фаза 2: Картирование архитектуры (Architecture Mapping)

📐 Фаза 3: Определение конвенций (Convention Detection)

📄 Фаза 4: Генерация артефактов (Generate Onboarding Artifacts)

Артефакт 1: Руководство по онбордингу (Onboarding Guide)

Артефакт 2: Стартовый CLAUDE.md

🎯 Когда использовать

📝 Важно знать

Примеры использования

Команды для типовых задач (пример для Node.js/Next.js)

🚫 Анти-паттерны (чего избегать)

Безопасно ли запускать на больших репозиториях?

Какова основная цель навыка Codebase Onboarding?

Перезаписывает ли он существующую документацию?

Какие языки программирования поддерживаются?

Как определяется архитектура проекта?

Комментарии

Артефакт 2: Стартовый `CLAUDE.md`