Claude가 코드를 엉뚱하게 쓰게 두지 마세요: 설정 파일 하나로 AI 정확도를 10% 높이는 법

Claude Code로 기존 프로젝트를 수정하는데, AI가 기술 스택을 완전히 다른 것으로 착각한 적이 있나요? React 프로젝트에 Vue 방식이 튀어나오고, 문서에는 TypeScript라고 적혀 있는데 결과물은 JavaScript로 가득한 상황 말입니다. CLAUDE.md는 바로 이런 컨텍스트 불일치를 해결하기 위해 프로젝트 루트 디렉터리에 두는 설정 파일입니다.

저도 Node 백엔드 프로젝트에서 크게 당한 적이 있습니다. Claude가 Koa 기반 미들웨어를 Express 방식으로 다시 작성했고, 그 결과 전체 요청 흐름이 깨졌습니다. Anthropic의 테스트에 따르면 제대로 구성된 CLAUDE.md는 보통 코딩 정확도를 5%-10% 끌어올릴 수 있습니다. 아래 7가지 작성법은 제가 시행착오 끝에 정리한 것이며, 각 항목에는 바로 가져다 쓸 수 있는 예시를 함께 넣었습니다.

CLAUDE.md는 정확히 무엇인가

쉽게 말해 CLAUDE.md는 프로젝트 루트 디렉터리에 두는 Markdown 파일이며, Claude Code가 프로젝트를 이해하도록 안내하는 전용 설정 파일입니다. .editorconfig나 README.md와 비슷하지만 역할은 더 구체적입니다. AI가 어떤 방식으로 코드를 도와줘야 하는지 알려주는 파일입니다.
동작 방식은 단순합니다. 프로젝트에서 Claude Code를 사용할 때 이 파일을 자동으로 읽습니다. 공식 문서에서는 자동 로드된다고 설명하지만, 커뮤니티 경험상 /init 명령으로 한 번 명시적으로 불러오는 편이 좋습니다. 그래야 AI가 설정을 읽었다는 점을 더 확실히 할 수 있습니다. 파일 내용은 AI의 컨텍스트 메모리에 로드되어 이후 모든 코드 생성과 제안에 영향을 줍니다.
여기서 중요한 특징이 하나 있습니다. Claude Code는 계층형 설정을 지원합니다.

project-root/
├── CLAUDE.md              # 전역 설정(프로젝트 전체 공통)
├── frontend/
│   └── .claude/
│       └── CLAUDE.md     # 프론트엔드 전용 설정
└── backend/
    └── .claude/
        └── CLAUDE.md     # 백엔드 전용 설정

즉 루트 디렉터리에는 공통 규칙을 두고, 하위 모듈에서는 특정 규칙을 덮어쓸 수 있습니다. 예를 들어 프론트엔드는 React, 백엔드는 Node.js를 사용한다면 각자 별도의 설정을 관리할 수 있습니다.

네 가지 핵심 원칙

CLAUDE.md를 작성하기 전에 먼저 이 네 가지 원칙을 기억하세요. 저는 처음에 이 점을 놓치고 300줄이 넘는 거대한 설정 파일을 만들었는데, 오히려 Claude의 성능이 나빠졌습니다.

1. 간결성: 100줄 이내 원칙

솔직히 말하면, 이건 비용을 치르고 배운 교훈입니다. CLAUDE.md는 README가 아니며 장황하게 쓸 필요가 없습니다.
왜 간결해야 할까요? 기술적으로 보면 Claude의 컨텍스트 창은 크지만, CLAUDE.md도 token 예산을 차지합니다. 파일이 길수록 실제 코드 분석에 남는 token은 줄어듭니다. Arize AI의 연구에 따르면 100줄 이내의 설정 파일이 가장 효과적입니다.
❌ 잘못된 예시(장황하고 반복적):

# 프로젝트 소개
이 프로젝트는 React 기반 프론트엔드 프로젝트입니다. 우리는 React로 사용자 인터페이스를 구축합니다.
React는 Facebook이 개발한 JavaScript 라이브러리입니다... (여기서 React 소개 200자 생략)
# 기술 스택
우리의 기술 스택은 다음과 같습니다.
- React - 우리의 UI 프레임워크이며 버전은 18.2입니다...
- TypeScript - 타입 검사를 위해 사용합니다...

✅ 올바른 예시(간결하고 직접적):

# 기술 스택
- React 18.2 (Hooks 우선, Class 컴포넌트 지양)
- TypeScript (strict mode)
- TailwindCSS (utilities 우선)
# 코드 규칙
- 함수 컴포넌트 + 커스텀 Hooks
- Props는 구조 분해 할당
- const 우선 사용, let 지양

차이가 보이시나요? 두 번째 버전은 훨씬 짧지만 같거나 더 많은 유효 정보를 전달합니다.

2. 구체성: 사람이 알아들을 말로, 모호하게 쓰지 않기

이 원칙은 쉬워 보이지만 실제로는 자주 어깁니다.
❌ 잘못된 예시(모호함):

# 코드 스타일
- 코드를 간결하게 유지한다
- Best practice를 사용한다
- 성능 최적화에 주의한다

이렇게 쓰면 안 쓴 것과 다르지 않습니다. 무엇이 간결한 코드인가요? 어떤 best practice를 말하나요? AI는 실행할 수 없습니다.
✅ 올바른 예시(구체적이고 실행 가능):

# 코드 스타일
- 단일 함수는 50줄을 넘지 않는다. 넘으면 분리한다
- API 호출에는 반드시 오류 처리와 loading 상태를 포함한다
- 리스트 렌더링에는 반드시 key 속성을 추가하고, index가 아닌 ID를 사용한다
- 중첩 삼항 연산자는 피하고 if/else 또는 early return을 사용한다

이제 AI는 무엇을 해야 하는지 압니다. 각 규칙이 명확하고 검증 가능합니다.

3. 반복 개선: 수정하는 것을 두려워하지 말고 계속 업데이트하기

프로젝트 초기에 CLAUDE.md를 작성해두고 반년 동안 한 번도 건드리지 않는 개발자를 본 적이 있습니다. 프로젝트는 Vue 2에서 Vue 3로 마이그레이션됐는데, 설정 파일에는 여전히 Options API를 사용하라고 적혀 있었습니다.
# 키로 빠르게 업데이트하기. 제가 가장 좋아하는 팁 중 하나입니다. Claude Code에서 # 키를 누르면 CLAUDE.md를 빠르게 참조하고 편집할 수 있습니다. AI의 동작이 기대와 다르면 바로 설정을 고치세요. 미루지 않는 것이 좋습니다.
실제 사례입니다. 지난주 한 프로젝트에서 Claude가 계속 axios 기반 코드를 생성했습니다. 하지만 우리 팀은 이미 fetch + 커스텀 래퍼로 통일한 상태였습니다. 저는 바로 # 키를 눌러 CLAUDE.md에 한 줄을 추가했습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

# HTTP 요청
- `src/utils/request.ts`에 래핑된 fetch를 통일해서 사용한다
- axios 또는 원시 fetch를 직접 사용하는 것을 금지한다

저장한 뒤 Claude는 이 실수를 다시 하지 않았습니다.

4. 팀 공유: 버전 관리에 포함하기

이 항목은 많은 사람이 놓칩니다. CLAUDE.md는 .gitignore처럼 중요하므로 반드시 Git 저장소에 커밋해야 합니다.
왜 그럴까요? 이 설정은 팀의 코딩 합의를 나타내기 때문입니다. 각자 로컬에 서로 다른 CLAUDE.md를 갖고 있으면, AI가 한 사람에게 생성한 코드 스타일과 다른 사람에게 생성한 코드 스타일이 완전히 달라져 혼란이 생깁니다.

# .gitignore에서 CLAUDE.md를 무시하지 마세요
# ❌ 잘못된 방식
*.md
# ✅ 올바른 방식
*.md
!CLAUDE.md
!README.md

그리고 Code Review 때 CLAUDE.md 변경도 확인해야 합니다. 누군가 설정을 바꿨다면 팀 전체가 알아야 합니다.

"설정 파일은 간결하고 구체적이어야 하며, 100줄 이내일 때 효과가 가장 좋습니다. 각 규칙은 실행 가능하고 검증 가능해야 합니다."

반드시 포함해야 할 5가지 콘텐츠 모듈

제가 정리한 최소 실행 가능 설정입니다. 이 모듈이 빠지면 CLAUDE.md는 사실상 별 도움이 되지 않습니다.

1. 기술 스택 선언

사용 중인 프레임워크, 라이브러리, 버전을 명확히 나열해야 합니다. 가장 기본입니다.

# 기술 스택
**프론트엔드**
- Next.js 14 (App Router)
- React 18 (Server Components 우선)
- TypeScript 5.2
- Tailwind CSS 3.4
**백엔드**
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15

버전 번호를 적었다는 점에 주목하세요. 버전을 적지 않으면 Claude가 오래된 API로 코드를 생성할 수 있습니다. 예를 들어 Next.js 13과 14의 라우팅 방식은 완전히 다르기 때문에 버전을 지정하지 않으면 위험합니다.

2. 프로젝트 구조 설명

AI에게 파일이 어떻게 구성되어 있는지 알려주세요. 그래야 코드를 올바른 위치에 둘 수 있습니다.

# 프로젝트 구조
src/
├── app/              # Next.js 페이지 라우트
├── components/       # 재사용 가능한 UI 컴포넌트
│   ├── ui/          # 기본 컴포넌트(Button, Input)
│   └── features/    # 비즈니스 컴포넌트(UserCard, OrderList)
├── lib/             # 유틸 함수와 hooks
├── services/        # API 호출 계층
└── types/           # TypeScript 타입 정의
# 파일 네이밍
- 컴포넌트: PascalCase (UserProfile.tsx)
- 유틸 함수: camelCase (formatDate.ts)
- 상수: UPPER_SNAKE_CASE (API_BASE_URL)

이제 Claude는 새 사용자 카드 컴포넌트를 components/features/UserCard.tsx에 만들어야 한다는 것을 압니다. 아무 데나 파일을 만들 가능성이 줄어듭니다.

3. 자주 쓰는 명령어

이 부분은 자주 빠지지만 매우 유용합니다.

# 개발 명령어
npm run dev          # 개발 서버 시작(localhost:3000)
npm run build        # 프로덕션 빌드
npm run test         # Jest 테스트 실행
npm run lint         # ESLint 검사
npm run type-check   # TypeScript 타입 검사
# 데이터베이스
npx prisma studio    # 데이터베이스 GUI 열기
npx prisma migrate dev  # 데이터베이스 마이그레이션 실행

왜 이걸 적어야 할까요? Claude가 코드를 검증하거나 테스트를 실행해야 할 때가 있기 때문입니다. 올바른 명령어를 알려주면 많은 문제를 피할 수 있습니다.

4. 코드 스타일 규칙

여기가 핵심입니다. 충분히 구체적으로 작성해야 합니다.

# 코드 규칙
## React 컴포넌트
- 함수 컴포넌트 + Hooks 사용, Class 컴포넌트 금지
- Props 타입은 컴포넌트 위에 정의하고 type이 아닌 interface 사용
- 컴포넌트 내부 순서: Props 정의 → 컴포넌트 함수 → export
## 상태 관리
- 로컬 상태: useState/useReducer
- 서버 상태: TanStack Query
- 전역 상태: Zustand (Context 사용 지양)
## 오류 처리
- API 호출은 반드시 try-catch 사용
- 사용자에게 보이는 오류는 toast로 안내
- 개발 환경에서는 console.error, 프로덕션 환경에서는 Sentry로 보고

5. 워크플로와 제한

AI에게 무엇을 할 수 있고, 무엇을 하면 안 되는지 알려주세요.

# 워크플로
- 새 기능 개발: 타입 정의 먼저 작성 → 컴포넌트 작성 → 테스트 작성
- 버그 수정: 재현 테스트 먼저 작성 → 코드 수정 → 테스트 통과 확인
# 제한 사항
- ❌ `/prisma/schema.prisma` 수정 금지(팀 리뷰 필요)
- ❌ 새 의존성 패키지 설치 금지(package.json review 때 논의 필요)
- ❌ `/lib/auth/*` 수정 금지(인증 로직은 민감함)
- ✅ `/components`와 `/app` 아래의 비즈니스 코드는 자유롭게 수정 가능

이렇게 하면 AI가 선의로 중요한 코드를 잘못 건드리는 일을 막을 수 있습니다.

효과를 두 배로 만드는 실전 팁 7가지

팁 1: SHOULD/MUST로 우선순위 강조하기

모든 규칙이 같은 중요도를 갖는 것은 아닙니다. 키워드로 우선순위를 구분하세요.

# 규칙 우선순위
**MUST (반드시 준수)**
- MUST TypeScript strict mode를 사용한다
- MUST 모든 API에 오류 처리를 추가한다
**SHOULD (권장)**
- SHOULD 컴포넌트는 200줄을 넘기지 않는다
- SHOULD 반복 로직은 커스텀 Hook으로 추출한다
**COULD (선택)**
- COULD JSDoc 주석을 추가한다

이 팁은 RFC 규격 문서의 표현 방식에서 가져왔습니다. 사용해보니 Claude가 MUST 규칙을 훨씬 더 엄격하게 따랐습니다.

팁 2: /init 명령 적극 활용하기

공식적으로는 CLAUDE.md가 자동 로드된다고 하지만, 저는 프로젝트를 열 때마다 먼저 /init 명령을 실행하는 것을 강력히 권장합니다.

사용자: /init
Claude: 프로젝트 설정을 로드했습니다. 현재 기술 스택: React 18 + TypeScript...

이건 AI의 기억을 새로 고치는 것과 같습니다. 특히 CLAUDE.md를 막 수정했다면 /init을 통해 변경 사항을 즉시 반영할 수 있습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

팁 3: 예시 코드는 천 마디 설명보다 낫다

규칙을 설명하기보다 바로 예시를 보여주는 편이 좋습니다.
❌ 텍스트 설명만 있는 경우:

- API 함수에는 타입 정의, 오류 처리, loading 상태를 포함해야 한다

✅ 예시 코드가 있는 경우:

# API 호출 규칙
참고 예시:
\`\`\`typescript
// src/services/user.ts
export async function getUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('getUser error:', error);
    throw error;
  }
}
\`\`\`
모든 API 함수는 이 패턴을 따른다: 타입 반환값 + try-catch + 오류 로그

Claude는 예시를 보면 훨씬 기대에 가까운 코드를 생성합니다.

팁 4: 계층형 설정 관리하기(Monorepo 필수)

프로젝트가 Monorepo 구조라면 반드시 계층형 설정을 사용하세요.

monorepo-root/
├── CLAUDE.md                    # 전역: 공통 규칙, Git 워크플로
├── apps/
│   ├── web/
│   │   └── .claude/CLAUDE.md   # Web 앱: React + Next.js
│   └── mobile/
│       └── .claude/CLAUDE.md   # 모바일: React Native
└── packages/
    └── shared/
        └── .claude/CLAUDE.md   # 공유 패키지: 순수 TS 유틸 라이브러리

루트 CLAUDE.md(전역 규칙):

# Monorepo 공통 규칙
- 패키지 매니저로 pnpm을 사용한다
- TypeScript 설정은 루트 tsconfig.json을 상속한다
- Commit 메시지는 Conventional Commits를 따른다
# 워크플로
- 코드 수정 전 `pnpm install`을 먼저 실행한다
- 제출 전 `pnpm run lint`로 모든 패키지를 검사한다

apps/web/.claude/CLAUDE.md(프론트엔드 전용):

# Web 앱 전용 설정
루트 디렉터리 규칙을 상속하며, 아래는 추가 설정입니다.
- 기술 스택: Next.js 14 + React 18
- 스타일: Tailwind CSS
- 상태 관리: Zustand

Claude는 먼저 루트 디렉터리 설정을 읽고, 이후 현재 작업 디렉터리에 따라 하위 설정을 읽습니다. 이렇게 하면 모든 하위 프로젝트에 공통 규칙을 반복해서 쓸 필요가 없습니다.

팁 5: ❌와 ✅로 비교하기

사람도 AI도 비교 학습을 좋아합니다.

# 상태 업데이트 규칙
❌ 잘못된 방식: state를 직접 수정
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
user.age = 31; // 오류! 객체를 직접 수정함
\`\`\`
✅ 올바른 방식: 불변 업데이트 사용
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
setUser(prev => ({...prev, age: 31}));
\`\`\`

이런 비교는 규칙을 한눈에 보여주고, Claude의 학습 효율도 높입니다.

팁 6: 흔한 오류 패턴 기록하기

팀이 자주 저지르는 실수를 적어두면 AI가 함께 점검해줍니다.

# ⚠️ 흔한 오류와 피하는 법
## 1. 부수 효과 정리를 잊음
❌ 문제 코드:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  // 정리를 잊음!
}, []);
\`\`\`
✅ 올바른 방식:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  return () => clearInterval(timer); // 타이머 정리
}, []);
\`\`\`
## 2. 의존성 누락
ESLint가 의존성 누락을 경고하면 경고를 끄지 말고, 의존성을 추가하거나 useCallback/useMemo로 최적화한다

이렇게 해두면 Claude가 코드를 생성할 때 이런 함정을 적극적으로 피합니다.

팁 7: 상세 문서로 링크하기

CLAUDE.md는 간결해야 하지만, 상세 문서로 연결할 수는 있습니다.

# 상세 규칙 문서
- [API 설계 규칙](./docs/api-guidelines.md) - RESTful API 설계 표준
- [컴포넌트 개발 가이드](./docs/component-guide.md) - 컴포넌트 분리와 재사용 원칙
- [테스트 규칙](./docs/testing.md) - 단위 테스트와 통합 테스트 요구사항

이렇게 하면 CLAUDE.md의 간결함을 유지하면서도 필요할 때 더 자세한 정보를 제공할 수 있습니다. Claude는 이 링크를 통해 더 많은 컨텍스트를 얻을 수 있습니다.

가장 쉽게 빠지는 함정 5가지

함정 1: 파일이 너무 길고 모든 내용을 밀어 넣음

초보자가 가장 자주 하는 실수입니다. README, API 문서, 비즈니스 로직 설명을 전부 CLAUDE.md에 넣는 방식입니다.
문제: token을 너무 많이 차지해 오히려 중요한 정보가 희석됩니다.
해결: 100줄 이내로 엄격히 제한하고, AI가 코딩할 때 정말 필요한 정보만 작성합니다.

함정 2: 설정을 전혀 업데이트하지 않음

프로젝트는 변하는데 CLAUDE.md는 그대로인 경우입니다.
문제: 오래된 설정 때문에 AI가 잘못된 코드를 생성합니다.
해결: 습관을 들이세요. 큰 리팩터링 후에는 CLAUDE.md를 업데이트하고, PR에서 설정 변경도 review합니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

함정 3: 버전 관리를 잊음

CLAUDE.md를 .gitignore에 넣거나 저장소에 커밋하지 않는 경우입니다.
문제: 팀원이 각자 다른 기준으로 작업하면서 코드 스타일이 혼란스러워집니다.
해결: 반드시 Git에 포함하고 코드와 함께 review합니다.

함정 4: 지나치게 추상적인 규칙

코드를 간결하게 유지한다, best practice를 따른다 같은 빈말을 쓰는 경우입니다.
문제: AI가 실행할 수 없으므로 쓰지 않은 것과 같습니다.
해결: 모든 규칙은 구체적이고, 검증 가능하며, 실행 가능해야 합니다.

함정 5: 민감 정보 유출

API 키나 데이터베이스 비밀번호를 CLAUDE.md에 쓰는 경우입니다.
문제: 설정 파일은 저장소에 커밋되므로 민감 정보가 유출됩니다.
해결: 설정 방식만 설명하고 실제 값은 쓰지 않습니다.

❌ 잘못된 예
\`\`\`markdown
# 데이터베이스 설정
DATABASE_URL=postgresql://admin:password123@localhost:5432/mydb
\`\`\`
✅ 올바른 예
\`\`\`markdown
# 환경 변수
- DATABASE_URL: .env.local에서 읽는다. 형식은 .env.example 참고
- API_KEY: 환경 변수에서 가져온다. 로컬 개발용 테스트 key는 @장삼에게 문의
\`\`\`

실제 프로젝트 사례 3가지

사례 1: React 프론트엔드 프로젝트

아래는 제가 현재 유지보수 중인 이커머스 프론트엔드 프로젝트의 설정입니다(간소화 버전).

# 이커머스 프론트엔드 프로젝트
## 기술 스택
- Next.js 14.0 (App Router)
- React 18.2
- TypeScript 5.2
- Tailwind CSS 3.4
- Zustand (상태 관리)
- TanStack Query (서버 상태)
## 프로젝트 구조
src/
├── app/          # 페이지 라우트
├── components/   # 컴포넌트
│   ├── ui/      # 기본 컴포넌트
│   └── features/ # 비즈니스 컴포넌트
├── lib/         # 유틸 함수
└── services/    # API 호출
## 코드 규칙
- 컴포넌트: 함수 컴포넌트 + Hooks
- 상태: 로컬은 useState, 전역은 Zustand, 서버는 TanStack Query
- 스타일: Tailwind utilities, 복잡한 레이아웃은 컴포넌트로 추출
- 오류 처리: API 호출은 반드시 try-catch
## 명령어
npm run dev      # 개발 서버
npm run build    # 프로덕션 빌드
npm run lint     # 코드 검사
## 제한
- /lib/auth/* 수정 금지(인증 로직)
- 새 패키지 설치 금지(팀 논의 필요)

효과: 이 설정을 사용한 뒤 Claude가 생성하는 컴포넌트 구조가 제가 직접 작성하는 코드와 거의 같아졌고, 수정 시간을 크게 줄일 수 있었습니다.

사례 2: Node.js 백엔드 프로젝트

아래는 Express API 프로젝트의 설정입니다.

# 주문 관리 시스템 API
## 기술 스택
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15
- Zod (데이터 검증)
## 프로젝트 구조
src/
├── routes/       # 라우트 정의
├── controllers/  # 비즈니스 로직
├── services/     # 데이터베이스 작업
├── middleware/   # 미들웨어
└── utils/        # 유틸 함수
## 코딩 규칙
- 모든 API는 요청 검증(Zod) + 오류 처리 + 로그 기록을 포함해야 한다
- 데이터베이스 작업은 services 계층에 통일해서 둔다
- 컨트롤러는 요청과 응답만 처리하고 비즈니스 로직은 쓰지 않는다
- async/await를 사용하고 callback은 피한다
## API 예시
\`\`\`typescript
// controllers/order.controller.ts
export async function createOrder(req: Request, res: Response) {
  try {
    const data = orderSchema.parse(req.body); // Zod 검증
    const order = await orderService.create(data);
    logger.info('Order created', { orderId: order.id });
    res.json({ success: true, data: order });
  } catch (error) {
    logger.error('Create order failed', error);
    res.status(500).json({ success: false, error: 'Internal error' });
  }
}
\`\`\`
## 명령어
npm run dev       # 개발 모드(nodemon)
npm run build     # TypeScript 컴파일
npm test          # Jest 테스트
npx prisma studio # 데이터베이스 GUI

효과: 이제 Claude가 생성하는 API 엔드포인트에는 Zod 검증과 오류 처리가 기본으로 포함되어 품질이 눈에 띄게 좋아졌습니다.

사례 3: Monorepo 아키텍처

아래는 프론트엔드와 백엔드를 함께 포함하는 Monorepo 프로젝트입니다.
루트 CLAUDE.md:

# 풀스택 애플리케이션 Monorepo
## 아키텍처
- pnpm workspaces 사용
- apps/: 애플리케이션
- packages/: 공유 패키지
## 공통 규칙
- TypeScript strict mode
- ESLint + Prettier로 포맷 통일
- Commit은 Conventional Commits를 따른다
## 명령어
pnpm install           # 모든 의존성 설치
pnpm run dev           # 프론트엔드와 백엔드 동시 시작
pnpm run lint          # 모든 패키지 검사
pnpm --filter web dev  # web 앱만 시작

apps/web/.claude/CLAUDE.md:

# Web 앱 설정
루트 디렉터리 규칙 상속
- Next.js 14 + React
- 포트: 3000
- 자세한 규칙은 루트 CLAUDE.md 참고

apps/api/.claude/CLAUDE.md:

# API 서비스 설정
루트 디렉터리 규칙 상속
- Express + Prisma
- 포트: 4000
- 자세한 규칙은 루트 CLAUDE.md 참고

효과: Claude는 현재 작업 디렉터리에 따라 컨텍스트를 자동으로 전환할 수 있습니다. 프론트엔드 디렉터리에서는 React 코드를, 백엔드 디렉터리에서는 Express 코드를 생성합니다.

결론: 오늘부터 CLAUDE.md를 개선하세요

이 7가지 팁을 읽었다면 CLAUDE.md를 잘 작성하는 방법이 꽤 분명해졌을 것입니다. 가장 중요한 세 가지를 기억하세요.

1. 간결하게 유지하기 - 100줄 이내로, 필요한 정보만 작성
2. 충분히 구체적으로 쓰기 - 모든 규칙은 실행 가능하고 검증 가능해야 함
3. 계속 업데이트하기 - 프로젝트가 바뀌면 설정도 함께 바뀌어야 함
   제 실제 경험으로 보면 좋은 CLAUDE.md는 AI의 작업 효율을 최소 30% 높여줍니다. 처음부터 모든 내용을 완성할 필요는 없습니다. 가장 기본적인 기술 스택 선언부터 시작하고, AI가 실수할 때마다 CLAUDE.md에 규칙을 하나씩 추가하면 됩니다.
   지금 바로 프로젝트를 열어 CLAUDE.md를 만들거나 개선해보세요. 아직 Claude Code를 쓰지 않았다면 이 설정 파일이 좋은 첫걸음이 될 것입니다. 이미 쓰고 있지만 AI 결과가 만족스럽지 않다면 오늘 공유한 팁을 적용해보세요.
   마지막으로 한 가지 더 강조하겠습니다. CLAUDE.md는 한 번 만들고 끝나는 작업이 아닙니다. 프로젝트와 함께 성장해야 합니다. 큰 리팩터링, 기술 스택 업그레이드, 규칙 변경이 있을 때마다 이 파일도 잊지 말고 업데이트하세요. AI가 프로젝트를 제대로 이해하도록 만드는 일은 좋은 CLAUDE.md에서 시작됩니다.