codebase-onboarding

코드베이스 온보딩

익숙하지 않은 코드베이스를 체계적으로 분석하고 구조화된 온보딩 가이드를 만듭니다. 새 프로젝트에 합류한 개발자나 기존 저장소에 Claude Code를 처음 설정하는 상황을 위한 스킬입니다.

사용 시점

• Claude Code로 프로젝트를 처음 열 때
• 새 팀이나 저장소에 합류할 때
• 사용자가 "help me understand this codebase"라고 할 때
• 프로젝트용 CLAUDE.md 생성을 요청할 때
• 사용자가 "onboard me", "walk me through this repo"라고 할 때

동작 방식

1단계: 정찰

모든 파일을 읽지 않고 프로젝트에 대한 원시 신호를 수집합니다. 다음 점검을 병렬로 실행합니다.

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. 디렉터리 구조 스냅샷
   → node_modules, vendor, .git, dist, build, __pycache__, .next를 제외한
     상위 2단계 디렉터리 트리

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

2단계: 아키텍처 매핑

정찰 데이터로부터 다음을 식별합니다.

기술 스택

• 언어와 버전 제약
• 프레임워크와 주요 라이브러리
• 데이터베이스와 ORM
• 빌드 도구와 번들러
• CI/CD 플랫폼

아키텍처 패턴

• 모놀리식, 모노레포, 마이크로서비스, 서버리스 중 무엇인지
• 프론트/백엔드 분리형인지, 풀스택인지
• API 스타일: REST, GraphQL, gRPC, tRPC

주요 디렉터리 상위 디렉터리를 목적과 연결합니다.

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

데이터 흐름 요청 하나를 엔트리부터 응답까지 추적합니다.

• 요청은 어디로 들어오는가? (router, handler, controller)
• 어디서 검증되는가? (middleware, schema, guard)
• 비즈니스 로직은 어디에 있는가? (service, model, use case)
• DB까지는 어떻게 도달하는가? (ORM, raw query, repository)

3단계: 규칙 탐지

코드베이스가 이미 따르는 패턴을 식별합니다.

네이밍 규칙

• 파일명 패턴: kebab-case, camelCase, PascalCase, snake_case
• 컴포넌트/클래스 이름 규칙
• 테스트 파일명 규칙: *.test.ts, *.spec.ts, *_test.go

코드 패턴

• 오류 처리 스타일: try/catch, Result 타입, error code
• 의존성 주입인지 직접 import인지
• 상태 관리 접근 방식
• 비동기 패턴: callback, promise, async/await, channel

Git 규칙

• 최근 브랜치에서 드러나는 브랜치 네이밍
• 최근 커밋 메시지 스타일
• PR 워크플로(squash, merge, rebase)
• 커밋이 없거나 shallow history만 있으면 이 섹션은 건너뛰고 "Git history unavailable or too shallow to detect conventions"라고 적습니다.

4단계: 온보딩 산출물 생성

두 가지 출력을 만듭니다.

출력 1: 온보딩 가이드

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

출력 2: 시작용 CLAUDE.md

탐지된 규칙을 바탕으로 프로젝트 전용 CLAUDE.md를 생성하거나 갱신합니다. 이미 CLAUDE.md가 있으면 먼저 읽고 강화합니다. 기존 프로젝트 전용 지침은 보존하고, 무엇을 추가/변경했는지 분명히 드러냅니다.

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

모범 사례

1. 전부 읽지 않기 — 정찰 단계는 Glob과 Grep를 사용하고, 모든 파일에 Read를 걸지 않습니다. 애매한 신호만 선택적으로 읽습니다.
2. 추측하지 말고 검증하기 — 설정상 프레임워크가 감지돼도 실제 코드가 다르면 코드를 신뢰합니다.
3. 기존 CLAUDE.md 존중 — 이미 있다면 교체하지 말고 강화합니다. 무엇이 새로 들어갔는지 구분합니다.
4. 간결하게 유지 — 온보딩 가이드는 2분 안에 훑을 수 있어야 합니다. 세부 내용은 가이드보다 코드에 있어야 합니다.
5. 모르는 건 모른다고 표시 — 확신할 수 없는 규칙은 억지로 추정하지 않습니다. "Could not determine test runner"가 틀린 답보다 낫습니다.

피해야 할 안티패턴

• CLAUDE.md를 100줄 넘게 생성하는 것
• 모든 의존성을 나열하는 것
• 너무 자명한 디렉터리 이름까지 설명하는 것. 예: src/
• README를 그대로 복사하는 것. 온보딩 가이드는 구조적 통찰을 더해야 합니다.

예시

예시 1: 새 저장소에 처음 들어온 경우

User: "Onboard me to this codebase"
Action: 전체 4단계 워크플로 실행 -> 온보딩 가이드 + 시작용 CLAUDE.md 생성
Output: 대화에 온보딩 가이드 출력 + 프로젝트 루트에 CLAUDE.md 작성

예시 2: 기존 프로젝트용 CLAUDE.md 생성

User: "Generate a CLAUDE.md for this project"
Action: 1~3단계 실행, 온보딩 가이드는 생략하고 CLAUDE.md만 생성
Output: 탐지된 규칙이 반영된 프로젝트 전용 CLAUDE.md

예시 3: 기존 CLAUDE.md 강화

User: "Update the CLAUDE.md with current project conventions"
Action: 기존 CLAUDE.md를 읽고 1~3단계를 실행한 뒤 새 발견사항을 병합
Output: 추가/변경점이 반영된 CLAUDE.md