프로젝트 설정 마크다운 가이드: CLAUDE.md와 AGENTS.md

프로젝트 설정 MD란?

바이브 코딩 도구는 세션이 시작될 때 프로젝트 루트에 있는 특정 마크다운 파일을 자동으로 읽는다. 이 파일이 해당 프로젝트에서 AI가 따라야 할 '규칙서' 역할을 한다.

도구별 설정 파일:• Claude Code: CLAUDE.md (프로젝트 루트)
• Codex: AGENTS.md (프로젝트 루트)

파일명은 다르지만 역할과 작성 방식은 동일하다. AI 에이전트에게 "이 프로젝트에서는 이렇게 작업해라"라고 알려주는 지속적인 메모리(persistent memory)인 셈이다.

왜 필요한가?

설정 MD 없이도 바이브 코딩은 가능하다. 하지만 매번 같은 지시를 반복해야 하는 불편함이 생긴다.

설정 MD 없이 작업할 때:• "한국어로 대답해줘"
• "커밋은 내가 시킬 때만 해"
• "이 폴더는 건드리지 마"
• "코드 수정 전에 먼저 물어봐"

이런 지시를 새 세션을 시작할 때마다 반복해야 한다. 컴팩트가 일어나면 잊어버리기도 한다.

설정 MD를 작성해두면:• 세션 시작 시 자동으로 규칙을 인식
• 일관된 작업 방식 유지
• 실수 방지 (금지된 작업 차단)
• 팀원 간 동일한 AI 동작 보장

빠른 시작: /init 명령어

처음부터 직접 작성하기 어렵다면 자동 생성 기능을 활용하자. 두 도구 모두 /init 명령어를 지원한다.

Claude Code:

claude
> /init

Codex:

codex
> /init

프로젝트 구조와 기술 스택을 분석해서 기본 설정 파일(CLAUDE.md 또는 AGENTS.md)을 생성해준다. 이걸 기반으로 필요한 규칙을 추가하면 된다.

폴더 구조와 우선순위

설정 MD는 프로젝트 루트뿐 아니라 하위 폴더에도 둘 수 있다. 하위 폴더의 설정이 상위를 오버라이드한다.

my-project/
├── CLAUDE.md (또는 AGENTS.md)  # 프로젝트 전체 규칙
├── frontend/
│   └── CLAUDE.md               # 프론트엔드 전용 규칙
└── backend/
    └── CLAUDE.md               # 백엔드 전용 규칙

탐색 순서:1. 현재 작업 파일이 있는 폴더에서 시작
2. 상위 폴더로 올라가며 설정 파일 탐색
3. 프로젝트 루트(보통 .git이 있는 곳)까지 확인
4. 발견된 모든 설정을 병합 (하위가 우선)

모노레포나 멀티 프로젝트 구조에서 각 영역별로 다른 규칙을 적용할 때 유용하다.

전역 설정 vs 프로젝트 설정

홈 디렉토리에 두는 전역 설정과 프로젝트 루트에 두는 프로젝트 설정이 있다.

Claude Code:• 전역: ~/.claude/CLAUDE.md → 모든 프로젝트에 적용
• 프로젝트: 프로젝트 루트의 CLAUDE.md → 해당 프로젝트만 적용

Codex:• 전역: ~/.codex/AGENTS.md → 모든 프로젝트에 적용
• 프로젝트: 프로젝트 루트의 AGENTS.md → 해당 프로젝트만 적용

전역 설정에는 언어, 어투 같은 개인 선호를 두고, 프로젝트 설정에는 해당 프로젝트만의 규칙을 두는 것이 일반적이다.

핵심 구성 요소

설정 MD에 포함할 수 있는 주요 항목들이다. 모두 필수는 아니고, 프로젝트에 필요한 것만 선택해서 작성하면 된다.

1. 성격 설정 (Language & Tone)

AI의 응답 언어와 어투를 정의한다.

## Language
- 모든 설명은 한국어로 진행
- 친근하고 자연스러운 어투 (~했어요, ~할게요)
- 존댓말 사용
- 이모지는 사용자 요청 시에만

글로벌 팀이라면 영어로, 일본어 프로젝트라면 일본어로 설정할 수 있다.

2. 작업 범위 (Work Scope)

AI가 수정할 수 있는 경로와 금지된 경로를 명시한다.

## Work Scope

### 허용된 경로
- `src/` - 소스 코드
- `tests/` - 테스트
- `docs/` - 문서

### 수정 금지
- `config/production.json` - 프로덕션 설정
- `.env` - 환경 변수
- `dist/` - 빌드 산출물

민감한 파일이나 빌드 결과물을 보호할 수 있다.

3. 코드 컨벤션 (Code Style)

프로젝트의 코딩 스타일을 정의한다.

## Code Conventions

### 스타일
- 들여쓰기: 2칸 스페이스
- 따옴표: 작은따옴표
- 세미콜론: 생략

### 네이밍
- 변수/함수: camelCase
- 클래스: PascalCase
- 상수: UPPER_SNAKE_CASE

### 주석
- 코드가 스스로 설명하도록 작성
- 주석은 'why'만 설명
- 수정하지 않은 코드에 주석 추가 금지

ESLint, Prettier 설정이 있다면 해당 설정을 따르라고 명시해도 좋다.

4. 작업 프로세스와 금지 사항

가장 중요한 부분이다. AI가 어떤 절차를 따라야 하고, 절대 하면 안 되는 것이 무엇인지 정의한다.

## ⛔ ABSOLUTE PROHIBITIONS

**승인 없는 코드 수정 금지**
- ❌ 분석 후 바로 수정
- ✅ 분석 → 계획 제안 → 승인 → 실행

**승인 없는 Git 작업 금지**
- ❌ 자동 커밋, 자동 푸시
- ✅ 변경 보고 후 "커밋해" 요청 시만 실행

**빌드/배포 무단 실행 금지**
- ❌ "확인 차 빌드 실행"
- ✅ 사용자가 명시적으로 요청할 때만

5. 환경 정보

OS별 경로 차이, 실행 방식, 외부 도구 연동 정보를 정의한다.

## Environment

### 경로
- macOS: `/Users/dev/project`
- Windows/WSL: `/mnt/c/project`

### 명령 실행
- macOS: bash 직접 실행
- WSL: PowerShell 경유 필요

### 외부 도구
- MCP 연동: Unity Editor
- GitHub CLI: `gh workflow run`

6. Git 워크플로우

Git 관련 작업의 규칙을 정의한다. 자동 커밋, 푸시 등을 방지하고 승인 절차를 명시한다.

## Git Workflow

### 읽기 전용 (승인 불필요)
- `git status`, `git log`, `git diff`, `git branch`

### 승인 필요
- `git add`, `git commit`, `git push`, `git pull`
- 사용자가 "커밋해", "푸시해" 요청 시에만 실행

### 절대 금지
- `git reset --hard`, `git push --force`
- `git clean -fd` 등 파괴적 명령

### 커밋 메시지
- 형식: `YYYY-MM-DD HH:MM 변경 내용`
- 자동 서명 추가 금지

7. 에이전트 활용

서브에이전트 호출 기준과 병렬 처리 정책을 정의한다. Claude Code는 이미 에이전트 시스템이 안정화되어 있고, Codex도 에이전트 시스템을 도입하고 있지만 아직 완성도가 높지 않다.

## Agent Usage

### 서브에이전트
- Explore: 파일 검색, 코드베이스 탐색
- Plan: 복잡한 작업 계획 수립

### 호출 기준
- 검색 작업: Explore 에이전트 우선
- 복잡한 작업(3단계 이상): Plan 먼저 수립

### 병렬 처리
- Explore: 여러 영역 탐색 시 병렬 가능
- Git 작업: 충돌 방지를 위해 순차 실행

서브에이전트를 잘 활용하면 메인 컨텍스트를 절약하면서 복잡한 작업을 처리할 수 있다.

8. 특이사항

프로젝트만의 특수한 규칙을 정리한다.

## Project Notes

### 빌드 시스템
- `dist/`는 빌드 산출물 → 직접 수정 금지
- 빌드: `npm run build`

### 데이터 파일
- JSON은 2칸 들여쓰기
- CSV는 UTF-8 인코딩 유지

### 관련 문서
- API 작업 시: `API.md` 참조
- 배포 작업 시: `DEPLOY.md` 참조

작성 팁

1. 200줄 이내로 유지
설정 MD는 AI 컨텍스트에 포함된다. 너무 길면 실제 작업에 쓸 컨텍스트가 줄어든다. Codex는 기본 32KB 제한이 있다.

2. 점진적으로 추가
처음부터 완벽하게 쓰려 하지 말자. AI가 실수할 때마다 해당 규칙을 추가하면 된다.

3. 예시 명령어는 코드 블록으로
코드 블록 안의 명령어는 AI가 그대로 따라 쓴다.

4. 다른 문서 참조 활용
내용이 길어지면 별도 파일로 분리하고 참조하도록 한다.

API 작업 시 → `API.md` 참조

5. Git에 커밋
설정 MD는 프로젝트의 일부다. Git에 커밋해서 팀원과 공유하자. 단, 개인 설정(settings.local.json 등)은 .gitignore에 추가한다.

마치며

CLAUDE.md나 AGENTS.md는 AI 에이전트와의 '계약서'다. 잘 작성해두면 매번 같은 지시를 반복할 필요 없이, 일관된 품질의 작업을 기대할 수 있다.

처음에는 간단하게 시작하자. AI가 실수할 때마다 "이 규칙을 추가해야겠다"고 생각하면, 점점 더 똑똑한 에이전트로 길들일 수 있다.