CLAUDE.md 완전 정복 - 프로젝트 규모별 템플릿

개인 프로젝트부터 모노레포까지 복붙으로 바로 쓰는 설정 가이드

CLAUDE.md의 내용은 프로젝트 규모에 따라 크게 달라집니다. 혼자 만드는 작은 스크립트와 팀이 함께 개발하는 대규모 서비스는 AI에게 전달해야 할 정보의 종류와 양이 다릅니다.

이 장에서는 Small·Medium·Large 세 가지 규모별로 바로 복붙해서 쓸 수 있는 템플릿을 소개합니다.

Small: 개인 프로젝트 / 사이드 프로젝트 / 스크립트

혼자 개발하는 소규모 프로젝트에 적합합니다. 10~20행으로 충분합니다. 규약을 세세하게 작성할 필요는 없고, 기술 스택과 실행 커맨드를 명시하는 것만으로 Claude Code는 적절하게 동작합니다.

Python 스크립트 · 자동화 툴

# 프로젝트명

한 줄로 프로젝트 설명.

## 스택

- 언어: Python 3.12
- 주요 라이브러리: requests, click
- 테스트: pytest

## 규칙

- 타입 힌트를 반드시 붙인다
- 함수에는 docstring을 작성한다
- 테스트는 `tests/`에 배치한다

## 커맨드

- 실행: `python main.py`
- 테스트: `pytest`
- 린트: `ruff check .`

CLI 툴 예시 (Node.js)

# mycli — 파일 변환 CLI 툴

CSV/JSON/YAML 상호 변환을 수행하는 CLI 툴.

## 스택

- Node.js 22 + TypeScript
- CLI: Commander.js
- 테스트: Vitest

## 규칙

- ESM 형식으로 작성한다 (`import`/`export`)
- 에러는 `process.exit(1)`로 종료한다. 예외를 throw하지 않는다
- CLI 옵션 설명 및 사용자용 메시지는 한국어로 작성한다

## 커맨드

- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 로컬 실행: `pnpm start -- --input file.csv --output file.json`

국내 환경 팁: 개인 사이드 프로젝트라도 나중에 오픈소스로 공개할 계획이 있다면, 커밋 메시지·주석·에러 메시지를 영어로 할지 한국어로 할지 방침을 Small 단계부터 CLAUDE.md에 명시해 두는 것을 권장합니다. AI가 일관되지 않게 두 언어를 섞어 쓰는 상황을 방지할 수 있습니다.

Medium: 팀 개발 웹 서비스