AI Sparkup

최신 AI 쉽게 깊게 따라잡기⚡

Claude Code 팁 – 엔지니어처럼 사고하게 만드는 프로젝트 구조

Published:

목차

claude-code는 단순한 자동완성 도구가 아니라 코드베이스를 읽고 수정하는 에이전트이기 때문에, 저장소 구조가 결과 품질에 직접 영향을 준다. 이 문서는 Claude Code가 매 세션마다 프로젝트의 목적, 규칙, 워크플로우를 빠르게 파악하도록 CLAUDE.md, .claude/skills, .claude/rules, 프로젝트 문서를 어떻게 나눠야 하는지 정리한다.

왜 구조가 중요한가

프롬프트를 길게 쓰는 것만으로는 일관성이 생기지 않는다. Claude Code가 엔지니어처럼 움직이려면 최소한 네 가지가 필요하다.

  • Why: 이 저장소가 무엇을 하는지
  • Map: 코드와 문서가 어디에 있는지
  • Rules: 무엇이 허용되고 금지되는지
  • Workflow: 작업을 어떤 순서로 끝내는지

이 네 가지를 저장소 구조에 분산해서 넣어두면, 세션이 바뀌어도 같은 기준을 반복해서 적용할 수 있다.

권장 구조

repo/
├── CLAUDE.md
├── docs/
├── .claude/
│   ├── skills/
│   └── rules/
└── src/

1. CLAUDE.md는 루트 메모리다

CLAUDE.md에는 매 세션마다 항상 필요한 정보만 넣는다.

  • 프로젝트 목적과 핵심 제약
  • 자주 쓰는 빌드·테스트 명령
  • 중요한 디렉터리 맵
  • “항상 지켜야 하는” 규칙

핵심은 짧고 구체적으로 쓰는 것이다. 공식 문서도 CLAUDE.md를 200줄 이하, 충돌 없는 명시적 지침으로 유지하라고 권장한다. 장문의 절차서나 설명을 다 넣으면 오히려 준수율이 떨어진다.

2. .claude/skills는 재사용 가능한 전문가 모드다

한 번 정의해두고 여러 번 재사용할 워크플로우는 스킬(skill)로 빼는 편이 낫다.

  • 코드 리뷰 체크리스트
  • 릴리스 노트 생성
  • 특정 프레임워크 전용 수정 절차
  • 외부 API 연동이나 배포 자동화

즉, “매번 설명하기 귀찮은 절차”를 캡슐화하는 장소다.

3. .claude/rules는 잊으면 안 되는 가드레일이다

파일 유형이나 하위 디렉터리별로 적용되는 제약은 rules가 더 적합하다.

  • api/ 아래에서는 인증 미들웨어 강제
  • infra/ 아래에서는 파괴적 명령 금지
  • frontend/ 아래에서는 디자인 시스템 준수

루트 CLAUDE.md에 모든 예외 규칙을 몰아넣기보다, 필요한 위치에서만 로드되게 분리하는 편이 정확하다.

4. docs/는 점진적 컨텍스트 저장소다

아키텍처 문서, ADR, 도메인 설명, 운영 런북은 CLAUDE.md가 아니라 문서 폴더에 두는 편이 낫다. Claude Code는 필요할 때 문서를 읽어오면 되므로, 상시 컨텍스트를 소모하지 않으면서도 깊은 배경지식을 제공할 수 있다.

위험 구간에는 로컬 CLAUDE를 둔다

데이터베이스 마이그레이션, 결제, 배포 스크립트처럼 실수 비용이 큰 경로에는 하위 디렉터리용 CLAUDE.md를 따로 두는 방식이 유효하다. 예를 들어 infra/CLAUDE.md에 “프로덕션 삭제 명령 금지”, “Terraform plan 먼저 실행” 같은 지침을 둘 수 있다.

실전 운영 원칙

  • 루트 CLAUDE.md는 짧게 유지한다.
  • 절차는 스킬로, 범위 제한 규칙은 rules로 보낸다.
  • 문서는 docs/에 두고 필요할 때만 읽게 한다.
  • 같은 규칙이 여러 파일에 중복되지 않게 정리한다.

흔한 실패 패턴

  • CLAUDE.md를 팀 철학 문서처럼 길게 쓰는 경우
  • 스킬로 분리해야 할 절차를 전부 루트 파일에 넣는 경우
  • 규칙 충돌을 방치해 세션마다 결과가 달라지는 경우
  • 위험 구간에 경로별 지침이 없어 파괴적 작업을 일반 코드 수정처럼 다루는 경우

관련 문서

참고 자료

AI Sparkup 구독하기

최신 게시물 요약과 더 심층적인 정보를 이메일로 받아 보세요! (무료)