코드베이스 온보딩

코드베이스 온보딩은(는) 무엇을 하나요?

처음 접하는 코드베이스를 체계적으로 분석하여 구조화된 온보딩 가이드를 생성합니다. 새 프로젝트에 참여하거나 기존 저장소에서 Claude Code를 처음 설정하는 개발자를 위해 설계되었습니다.

사용 시점

• Claude Code로 처음 프로젝트를 열 때
• 새 팀이나 저장소에 참여할 때
• 사용자가 "이 코드베이스를 이해할 수 있게 도와줘"라고 요청할 때
• 사용자가 프로젝트용 CLAUDE.md 생성을 요청할 때
• 사용자가 "온보딩 해줘" 또는 "이 저장소를 설명해줘"라고 말할 때

작동 방식

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 컴포넌트
src/api/         → API 라우트 핸들러
src/lib/         → 공유 유틸리티
src/db/          → 데이터베이스 모델 및 마이그레이션
tests/           → 테스트 스위트
scripts/         → 빌드 및 배포 스크립트

데이터 흐름 하나의 요청을 진입점부터 응답까지 추적합니다:

• 요청은 어디로 들어오나요? (라우터, 핸들러, 컨트롤러)
• 어떻게 검증되나요? (미들웨어, 스키마, 가드)
• 비즈니스 로직은 어디에 있나요? (서비스, 모델, 유스케이스)
• 데이터베이스에 어떻게 도달하나요? (ORM, 원시 쿼리, 리포지토리)

3단계: 컨벤션 탐지

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

네이밍 컨벤션

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

코드 패턴

• 에러 처리 스타일: try/catch, Result 타입, 에러 코드
• 의존성 주입 또는 직접 임포트
• 상태 관리 방식
• 비동기 패턴: 콜백, 프로미스, async/await, 채널

Git 컨벤션

• 최근 브랜치의 브랜치 네이밍
• 최근 커밋의 커밋 메시지 스타일
• PR 워크플로 (squash, merge, rebase)
• 저장소에 커밋이 없거나 얕은 히스토리만 있는 경우 (예: git clone --depth 1), 이 섹션을 건너뛰고 "Git 히스토리를 사용할 수 없거나 컨벤션을 감지하기에 너무 얕습니다"라고 기록합니다.

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

두 가지 출력을 생성합니다:

출력 1: 온보딩 가이드

# 온보딩 가이드: [프로젝트 이름]

## 개요
[2~3문장: 이 프로젝트가 하는 일과 대상 사용자]

## 기술 스택
<!-- Next.js 프로젝트 예시 — 감지된 스택으로 대체 -->
| 계층 | 기술 | 버전 |
|-------|-----------|---------|
| 언어 | TypeScript | 5.x |
| 프레임워크 | Next.js | 14.x |
| 데이터베이스 | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| 테스팅 | Jest + Playwright | - |

## 아키텍처
[컴포넌트 연결 다이어그램 또는 설명]

## 주요 진입점
<!-- Next.js 프로젝트 예시 — 감지된 경로로 대체 -->
- **API 라우트**: `src/app/api/` — Next.js 라우트 핸들러
- **UI 페이지**: `src/app/(dashboard)/` — 인증된 페이지
- **데이터베이스**: `prisma/schema.prisma` — 데이터 모델의 진실 공급원
- **설정**: `next.config.ts` — 빌드 및 런타임 설정

## 디렉터리 맵
[최상위 디렉터리 → 목적 매핑]

## 요청 수명 주기
[하나의 API 요청을 진입점부터 응답까지 추적]

## 컨벤션
- [파일 네이밍 패턴]
- [에러 처리 방식]
- [테스트 패턴]
- [Git 워크플로]

## 일반적인 태스크
<!-- Node.js 프로젝트 예시 — 감지된 명령어로 대체 -->
- **개발 서버 실행**: `npm run dev`
- **테스트 실행**: `npm test`
- **린터 실행**: `npm run lint`
- **데이터베이스 마이그레이션**: `npx prisma migrate dev`
- **프로덕션 빌드**: `npm run build`

## 참고 위치
<!-- Next.js 프로젝트 예시 — 감지된 경로로 대체 -->
| 하고 싶은 작업 | 참고할 위치 |
|--------------|-----------|
| API 엔드포인트 추가 | `src/app/api/` |
| UI 페이지 추가 | `src/app/(dashboard)/` |
| 데이터베이스 테이블 추가 | `prisma/schema.prisma` |
| 테스트 추가 | 소스 경로와 일치하는 `tests/` |
| 빌드 설정 변경 | `next.config.ts` |

출력 2: 시작용 CLAUDE.md

감지된 컨벤션을 기반으로 프로젝트 특화 CLAUDE.md를 생성하거나 업데이트합니다. CLAUDE.md가 이미 존재하는 경우 먼저 읽고 보강합니다. 기존 프로젝트별 지침을 유지하고 추가되거나 변경된 내용을 명확히 표시합니다.

# 프로젝트 지침

## 기술 스택
[감지된 스택 요약]

## 코드 스타일
- [감지된 네이밍 컨벤션]
- [따라야 할 감지된 패턴]

## 테스팅
- 테스트 실행: `[감지된 테스트 명령어]`
- 테스트 패턴: [감지된 테스트 파일 컨벤션]
- 커버리지: [설정된 경우 커버리지 명령어]

## 빌드 및 실행
- 개발: `[감지된 개발 명령어]`
- 빌드: `[감지된 빌드 명령어]`
- 린트: `[감지된 린트 명령어]`

## 프로젝트 구조
[주요 디렉터리 → 목적 맵]

## 컨벤션
- [감지 가능한 경우 커밋 스타일]
- [감지 가능한 경우 PR 워크플로]
- [에러 처리 패턴]

모범 사례

1. 모든 것을 읽지 마세요 — 정찰은 Glob과 Grep을 사용해야 하며, 모든 파일을 Read하지 않아야 합니다. 모호한 신호에 대해서만 선택적으로 읽습니다.
2. 추측하지 말고 확인하세요 — 설정에서 프레임워크가 감지되었지만 실제 코드가 다른 것을 사용한다면 코드를 신뢰하세요.
3. 기존 CLAUDE.md를 존중하세요 — 이미 존재하는 경우 교체하지 말고 보강하세요. 새로운 내용과 기존 내용을 구분해서 표시하세요.
4. 간결하게 유지하세요 — 온보딩 가이드는 2분 안에 훑어볼 수 있어야 합니다. 세부 사항은 가이드가 아닌 코드에 담겨야 합니다.
5. 알 수 없는 것은 표시하세요 — 컨벤션을 확실하게 감지할 수 없으면 추측하지 말고 그렇게 말하세요. 틀린 답변보다 "테스트 러너를 결정할 수 없음"이 더 낫습니다.

피해야 할 안티패턴

• 100줄이 넘는 CLAUDE.md 생성 — 집중력을 유지하세요
• 모든 의존성을 나열 — 코드 작성 방식을 결정짓는 것만 강조하세요
• 명백한 디렉터리 이름 설명 — src/는 설명이 필요 없습니다
• README 복사 — 온보딩 가이드는 README에 없는 구조적 통찰력을 제공합니다

예시

예시 1: 새 저장소 처음 사용

사용자: "이 코드베이스에 나를 온보딩 해줘" 동작: 전체 4단계 워크플로 실행 → 온보딩 가이드 + 시작용 CLAUDE.md 생성 출력: 온보딩 가이드는 대화에 직접 출력되고, CLAUDE.md는 프로젝트 루트에 작성됩니다

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

사용자: "이 프로젝트용 CLAUDE.md를 생성해줘" 동작: 1~3단계 실행, 온보딩 가이드 건너뛰고 CLAUDE.md만 생성 출력: 감지된 컨벤션이 포함된 프로젝트 특화 CLAUDE.md

예시 3: 기존 CLAUDE.md 보강

사용자: "현재 프로젝트 컨벤션으로 CLAUDE.md를 업데이트 해줘" 동작: 기존 CLAUDE.md 읽기, 1~3단계 실행, 새 발견 사항 병합 출력: 추가 사항이 명확히 표시된 업데이트된 CLAUDE.md