프로젝트 초기 세팅과 컨텍스트 관리 (CLAUDE.md)
AI 에이전트를 활용할 때 가장 주의해야 할 점은 **컨텍스트 오버플로우와 환각(Hallucination)**입니다. 이를 방지하는 핵심 도구가 바로 claude.md 파일입니다.
⚠️ 핵심: 반드시 프로젝트 루트(Root) 디렉토리에서 실행하세요
Claude Code는 현재 디렉토리를 기준으로 파일을 탐색합니다. 하위 폴더(예: /apps/api)에서 실행해버리면 프로젝트 전체 구조를 읽지 못해 엉뚱한 코드를 짜거나 파일을 찾지 못하는 문제가 발생합니다. 항상 최상단 루트 디렉토리에서 실행하는 습관을 들이세요.
/init 명령어와 CLAUDE.md 계층 구조
터미널에서 /init을 실행하면 프로젝트 설명서 역할을 하는 claude.md가 생성됩니다.
- 글로벌 적용:
~/.claude/claude.md(모든 프로젝트 공통 규칙. 예: "항상 한국어로 답변할 것") - 프로젝트 적용:
프로젝트루트/claude.md(해당 프로젝트 전용 아키텍처 및 컨벤션)
💡 claude.md 토큰 최적화 및 분할 전략 (중요)
매번 AI가 claude.md를 읽어오기 때문에, 파일이 너무 길어지면 토큰이 크게 낭비됩니다.
- 300자 이내 유지: 루트에 있는
claude.md는 핵심만 요약하여 300자 이내로 가볍게 유지하세요. (권장사항) - 폴더별 분할: DB 관련 규칙은
/supabase/claude.md에, API 관련 규칙은/api/claude.md에 따로 생성하세요. 클로드가 해당 폴더를 작업할 때만 세부 규칙을 읽어오게 되어 훨씬 효율적입니다.
트리거 키워드 (Trigger Keyword) 설정
반복되는 파이프라인(예: 테스트 통과 시 커밋 후 푸시)을 claude.md에 트리거 키워드로 등록해둘 수 있습니다.
"배포(Ship)라는 단어를 입력하면 1. 테스트 실행 2. 실패 시 중단 3. 통과 시 git add & commit 4. push 순서로 진행해줘" 이제 클로드 코드에 '배포'라고만 쳐도 위 일련의 과정이 자동으로 수행됩니다.
🤝 컴파운드 엔지니어링 (팀 단위 컨텍스트 동기화)
claude.md를 깃(Git) 레포지토리에 커밋하여 팀 전체가 공유하세요. 한 팀원이 아키텍처 규칙을 업데이트하면, 다른 팀원들도 동일한 규칙과 맥락 위에서 AI를 사용할 수 있게 됩니다.
💡 꿀팁: 직접 수정하지 말고 AI에게 시키기 대화 중 새로운 코딩 컨벤션이나 규칙을 정했다면, claude.md 파일을 직접 열어서 타이핑할 필요가 없습니다.
"방금 우리가 정한 패턴을 claude.md에 추가해줘" 라고 지시하면 클로드가 알아서 파일을 업데이트해 줍니다.