코드베이스 온보딩

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

익숙하지 않은 코드베이스를 체계적으로 분석하고 구조화된 온보딩 가이드를 생성합니다. 새 프로젝트에 참여하거나 기존 저장소에서 처음으로 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 설정

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 워크플로우 (스쿼시, 머지, 리베이스)
• 저장소에 커밋이 없거나 기록이 얕은 경우(예: 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` — 데이터 모델 소스 of truth
- **설정**: `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을 사용해야 하며, 모든 파일을 읽어서는 안 됩니다. 모호한 신호에 대해서만 선택적으로 읽으세요.
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