claude.md 처럼 분석에 필요한 기본 .md 파일 목록

claude.md 처럼 분석에 필요한 기본 .md 파일 목록

 

 

Claude Code CLI 환경에서 프로젝트를 분석하거나 개발을 진행할 때, claude.md(또는 CLAUDE.md) 외에도 함께 구성해 두면 Claude가 자동으로 조회하여 분석 품질을 극대화할 수 있는 핵심 기본 .md 파일 세트가 있습니다.

제공해주신 파일 관리 및 가이드 가이드라인에 기반하여, 프로젝트 루트 디렉토리에 구축해 두면 가장 좋은 추천 가이드라인 파일 목록과 그 안에 들어갈 핵심 내용을 정리해 드립니다.

📂 Claude CLI 분석 효율을 극대화하는 4대 기본 .md 파일 목록

1. claude.md (또는 CLAUDE.md) - 프로젝트 개발 마스터 지침서

Claude Code CLI가 실행될 때 가장 먼저 찾아서 컨텍스트에 주입하는 가장 중요한 마스터 파일입니다.

• 핵심 포함 내용:
  • 프로젝트 실행, 빌드, 테스트, 배포를 위한 실제 터미널 명령어 명시 (npm run dev, mvn spring-boot:run 등)
  • 이 프로젝트에서 엄격하게 준수해야 하는 코딩 스타일 및 네이밍 규칙 (예: "자바스크립트는 CamelCase 준수, 변수명은 명사형으로 작성")
  • 필수 예외 처리 방식 및 프레임워크 제약 조건

2. domain.md - 비즈니스 및 도메인 용어 사전

프로젝트의 기획적 배경, 비즈니스 규칙, 그리고 데이터베이스 설계 시 사용되는 고유 도메인 용어들을 정리해 두는 파일입니다. Claude가 코드를 분석하거나 데이터베이스 사전을 만들 때 엉뚱한 기술 용어 대신 현업에서 쓰는 정확한 용어를 사용하도록 교정해 줍니다.

• 핵심 포함 내용:
  • 용어 매핑 정의: 예) 현업 용어인 "학원"은 소스 코드와 DB에서 Academy 대신 Institute 또는 School로 통일한다.
  • 도메인 특화 규칙: 예) "회원 구분값은 1: 정회원, 2: 준회원, 3: 탈퇴회원으로 고정한다."
  • 서비스의 주요 비즈니스 도메인 범위 및 타겟층 요약

3. architecture.md (또는 system.md) - 아키텍처 및 시스템 구조 정의서

프로젝트의 전반적인 기술 스택, 폴더 구조, 데이터 흐름을 정의해 두는 파일입니다. Claude가 소스 코드를 읽기 전에 전체 지도를 먼저 파악하게 하므로, 방대한 양의 소스 코드를 분석할 때 기술적 오판을 방지해 줍니다.

• 핵심 포함 내용:
  • 기술 스택 일람: 언어 버전(Node 18+, JDK 17 등), 프레임워크(Spring Boot 3.x, Next.js 14 등), 데이터베이스(MySQL, Redis 등)
  • 디렉토리 가이드: 주요 기능이나 모듈이 어떤 폴더 구조(app/playville, src/main/java 등) 패턴으로 설계되어 있는지 설명
  • 백엔드와 프론트엔드 간의 데이터 교환 패턴 및 외부 연동 API 시스템 목록

4. roadmap.md (또는 tasks.md) - 마일스톤 및 기술 부채 현황판

현재 프로젝트의 개발 진행 상황, 추후 개선해야 할 리팩토링 항목, 혹은 마이그레이션 타스크를 기록해 두는 파일입니다. Claude에게 다음 작업을 지시할 때 "roadmap.md에 적힌 다음 우선순위 작업을 진행해줘"라고 바로 연계할 수 있습니다.

• 핵심 포함 내용:
  • 현재 파악된 기술 부채 및 리팩토링 대상 코드 목록
  • 기획서나 DDL 분석을 통해 도출된 추후 구현 예정 기능 일람
  • 마일스톤별 진행 상황 (Todo / In Progress / Done) 표시

💡 파일 기반 운용을 위한 Claude Code CLI 실무 팁

1. 컨텍스트 자동 동기화: Claude Code CLI는 현재 폴더 내부의 모든 파일 상태를 실시간으로 추적합니다. VS Code 등에서 위의 .md 파일들을 수정한 뒤, 대화창에 /reset 명령어를 입력하면 이전 대화 기록을 깔끔하게 비우면서 방금 수정한 가이드 파일들의 최신 내용을 컨텍스트에 완벽하게 새로고침(Reload) 합니다.
2. Qwen/LLM 프롬프트 파일화 활용: 만약 특정 모델(예: Qwen 등)의 스타일이나 복잡한 프롬프트 가이드를 고정적으로 쓰고 싶다면, 프로젝트 루트에 qwen_guide.md나 prompt_guide.md라는 이름으로 파일을 따로 빼두고, Claude에게 "코드 생성 시 현재 폴더의 prompt_guide.md 규칙을 준수해줘"라고 명령 파일로 사용할 수도 있습니다.