Claude Code CLAUDE.md 파일 사용법을 소개하는 공식 발표 이미지
이미지: claude.com/blog (Using CLAUDE.md files: Customizing Claude Code for your codebase)

몇 달 손을 놓고 있던 저장소를 다시 열었는데 CLAUDE.md가 없었습니다. 세션을 열자마자 "이 프로젝트는 패키지 매니저로 pnpm을 쓰고, 테스트는 변경된 워크스페이스만 돌리고, 린트는 커밋 전에 꼭 돌려야 한다"는 설명을 처음부터 다시 쳐야 했습니다. 이전에 CLAUDE.md를 만들어둔 다른 저장소들은 이런 설명이 필요 없었던 걸 생각하면 손해가 분명했습니다.

어떤 작업이었나

매번 같은 설명을 반복하지 않도록 CLAUDE.md를 하나 만드는 작업이었습니다. 문제는 이 저장소가 모노레포라 워크스페이스가 여섯 개였고, 각 워크스페이스마다 빌드 명령이 조금씩 달랐습니다. 직접 하나씩 뒤져서 정리하려면 package.json을 여섯 번 열어야 하고, 어느 워크스페이스가 공유 타입을 export하는지 같은 건 코드를 실제로 몇 군데 추적해봐야 알 수 있는 내용이었습니다.

AI를 어떻게 활용했나

직접 정리하는 대신 세션 안에서 /init을 호출했습니다.

/init

이 커맨드는 별다른 인자 없이 저장소 전체를 스캔합니다. 실행하자 각 워크스페이스의 package.json을 순서대로 열어서 스크립트(build, test, lint)를 뽑아내고, tsconfig.json의 path alias로 워크스페이스 간 의존 관계를 추정했습니다. 생성된 초안은 대략 이런 구조였습니다.

## Commands
- Build all: `pnpm -r build`
- Build one workspace: `pnpm --filter <name> build`
- Test changed workspace only: `pnpm --filter <name> test`

## Architecture
- `packages/core`: shared types and utils, imported by every other workspace
- `packages/api`: Express server, depends on `packages/core`
- `apps/web`: Next.js app, depends on `packages/core` and `packages/api` client

## Conventions
- Use workspace protocol (`workspace:*`) for internal deps, never pin versions manually

여기까지는 package.json만 읽어도 알 수 있는 내용이라 정확했습니다. 그런데 "Conventions" 섹션 뒷부분에 린트 규칙 설명이 덧붙어 있었는데, 실제로 쓰는 ESLint 설정이 아니라 각 파일의 import 순서만 보고 일반적인 관례를 추측해서 적어놓은 내용이었습니다. 제 환경에서는 .eslintrc에 커스텀 규칙이 몇 개 더 있었는데, 그건 설정 파일을 읽지 않으면 알 수 없는 부분이라 빠져 있었습니다.

처음에 걸렸던 부분

생성된 파일을 바로 커밋하려다가 "Testing" 섹션에 pnpm test로 전체 테스트를 돌리라는 문장이 들어있는 걸 늦게 발견했습니다. 워크스페이스가 여섯 개라 전체 테스트는 로컬에서 8분 넘게 걸리는데, 실제로 평소에 쓰는 건 변경된 워크스페이스만 돌리는 pnpm --filter였습니다. /init이 package.json의 루트 스크립트를 그대로 가져다 쓴 것뿐이라, 실제 작업 습관까지는 반영하지 못한 셈입니다. 이 문장을 지우고 "변경된 워크스페이스만 --filter로 테스트, 전체 테스트는 PR 올리기 직전에만"으로 바꿔 적었습니다.

결과와 얻은 팁

  • /init이 만든 초안은 코드에서 기계적으로 뽑아낼 수 있는 부분(스크립트, 디렉터리 구조, 워크스페이스 의존 관계)은 정확했지만, 실제 작업 습관이나 설정 파일 안쪽 디테일은 추측에 기대고 있었습니다. 생성된 그대로 커밋하지 않고 한 줄씩 읽어보는 게 꼭 필요했습니다.
  • 틀린 부분보다 더 손이 많이 간 건 "맞지만 필요 없는" 설명이었습니다. 각 워크스페이스 설명에 기본적인 Express/Next.js 사용법 수준의 문장이 끼어 있었는데, 이런 보편적인 내용은 지워도 모델이 이미 아는 내용이라 손실이 없었습니다.
  • 기존 프로젝트에 CLAUDE.md가 이미 있는 상태에서 다시 /init을 돌리면 새로 쓰는 대신 기존 파일에 빠진 부분을 보완하는 식으로 동작했습니다. 워크스페이스를 하나 새로 추가한 뒤 다시 돌려보니, 기존 섹션은 그대로 두고 새 워크스페이스 설명만 추가됐습니다.