Ai 마법서

01_claude_md

7 min read

모듈 1: CLAUDE.md - AI의 헌법

학습 목표

  • CLAUDE.md가 무엇이고 왜 필요한지 이해한다
  • 프로젝트에 맞는 CLAUDE.md를 작성할 수 있다
  • AI가 CLAUDE.md를 어떻게 활용하는지 이해한다

CLAUDE.md란?

프로젝트 루트에 위치하는 특별한 마크다운 파일입니다. Claude Code가 세션을 시작할 때 자동으로 읽어 프로젝트 맥락으로 활용합니다.

쉽게 말하면: 새로 입사한 AI 개발자에게 주는 온보딩 문서입니다.

신입 개발자에게 말하듯이:
"우리 팀은 WPF + MVVM 패턴을 씁니다."
"HmEG 객체는 반드시 Dispose 해야 합니다."
"빌드 경고 0개가 목표입니다."

현재 프로젝트의 CLAUDE.md 분석

# CLAUDE.md
 
HmEG 3D 엔진 기반 WPF C# 데스크톱 애플리케이션.
상세 아키텍처/API 문서는 docs/ 참고. 도메인 지식은 .claude/skills/ 참고.

첫 줄의 역할: AI에게 “이것은 어떤 프로젝트인가”를 단번에 알려줍니다.

  • 기술 스택: HmEG 3D 엔진 + WPF + C#
  • 추가 정보 위치: docs/, .claude/skills/

섹션별 분석

1. 개발 명령어

## 개발 명령어
dotnet restore && dotnet build    # 빌드
dotnet test                       # 테스트
dotnet format                     # 포맷

효과: AI가 “빌드하겠습니다”라고 할 때 올바른 명령어를 사용합니다. npm run build 같은 엉뚱한 명령어를 시도하지 않습니다.

2. 커스텀 명령어 등록

## 커스텀 명령어 (.claude/commands/)
- /generate-prp INITIAL.md - 기능 요청 -> PRP 생성
- /execute-prp PRPs/feature.md - PRP 실행 -> 구현
- /hmeg-api - HmEG API 문서 RAG 검색 (할루시네이션 방지용, 반드시 사용)

효과: 사용 가능한 커스텀 명령어를 AI가 인지하고, 적절한 상황에 제안합니다.

3. 필수 규칙 (가장 중요한 섹션)

## 필수 규칙
 
- 리소스 관리: 모든 HmEG 객체는 using 블록 또는 명시적 Dispose() 필수
- 예외 처리: 호스트 앱 크래시 방지 - 반드시 try/catch로 사용자 친화적 에러 출력
- 빌드 경고: Warning 0개 목표
- 이모지 금지: 코드 주석 및 문서에 이모지 사용 금지 (인코딩 문제)
- MCP: 직접 MCP 서버 설정 금지 - .claude/skills/의 Skill로 래핑하여 on-demand 호출

각 규칙의 이유:

규칙이유
using/Dispose 필수HmEG 엔진 메모리 누수 방지
try/catch호스트 앱(토목 설계 SW) 크래시 방지
Warning 0잠재적 버그 조기 발견
이모지 금지Windows 인코딩(CP949) 파일 손상 방지
MCP 직접 설정 금지팀 환경 일관성 유지

4. 프로젝트 구조

## 프로젝트 구조
src/core/       # 플랫폼 독립 비즈니스 로직 (단위 테스트 대상)
src/services/   # 서비스 계층
src/ui/         # WPF Views + ViewModels (MVVM)
.claude/skills/ # HmEG API 문서 검색 등 Skill 모음
PRPs/           # 제품 요구사항 프롬프트

효과: AI가 새 파일을 만들 때 올바른 위치에 생성합니다. “UI 컴포넌트니까 src/ui/에 넣어야겠다”고 판단합니다.

CLAUDE.md 작성 실습

빈 프로젝트에 CLAUDE.md 작성하기

다음 항목을 채워보세요:

# CLAUDE.md
 
[프로젝트 한 줄 설명 - 기술 스택 포함]
 
## 개발 명령어
[빌드/테스트/포맷 명령어]
 
## 필수 규칙
- [팀에서 반드시 지켜야 할 규칙 1]
- [팀에서 반드시 지켜야 할 규칙 2]
- [팀에서 반드시 지켜야 할 규칙 3]
 
## 프로젝트 구조
[주요 폴더와 역할 설명]

CLAUDE.md가 적용되는 시점

사용자가 claude 명령어 실행
        |
        v
Claude Code 시작
        |
        v
CLAUDE.md 자동 로드 (컨텍스트에 포함)
        |
        v
사용자 메시지 처리 (CLAUDE.md 규칙 적용 상태)

효과 비교

CLAUDE.md 없을 때

사용자: "EGViewport에 박스 추가하는 코드 작성해줘"

AI:
void AddBox(EGViewport viewport)
{
    // Warning C4996 무시...
    var box = new Box3D();   // 잘못된 클래스
    viewport.Add(box);       // 잘못된 메서드
    // Dispose 없음 - 메모리 누수
}

CLAUDE.md 있을 때

사용자: "EGViewport에 박스 추가하는 코드 작성해줘"

AI (hmeg-api Skill도 호출 후):
private void AddBox(EGViewport viewport)
{
    try
    {
        // CLAUDE.md 규칙: 모든 HmEG 객체는 using 또는 Dispose 필수
        var shape = viewport.RootSpace.AddBox(1.0, 1.0, 1.0);
        viewport.ZoomExtents();
    }
    catch (Exception ex)
    {
        // CLAUDE.md 규칙: try/catch로 사용자 친화적 에러 출력
        MessageBox.Show($"박스 추가 실패: {ex.Message}");
    }
}

핵심 정리

  • CLAUDE.md는 세션마다 자동 로드되는 프로젝트 헌법
  • 필수 규칙 섹션이 코드 품질에 가장 큰 영향을 미침
  • 짧고 명확하게 작성할수록 AI가 더 잘 따름 (긴 CLAUDE.md는 효과 감소)
  • 팀 전체가 공유하는 git 추적 파일이므로 팀 규약이 자동으로 AI에 적용됨

Graph View