CLAUDE.md 설계 철학
CLAUDE.md는 단순한 “지시문”이 아니라 AI 에이전트의 운영 체계입니다. ai-rules의 core 13파일(3,175줄)이 모든 프로젝트에 공통 적용됩니다.
규칙 우선순위 (충돌 시)
1. 03-security — 보안은 무조건 최우선
2. 01-git — 되돌리기 불가 작업 (push, merge)
3. 04-lifecycle — Plan Mode, 사람 승인 게이트
4. 나머지 규칙신뢰도 레이블 (모든 답변 필수)
AI가 답변할 때 얼마나 확실한지 명시해야 합니다:
| 레이블 | 의미 | 예시 |
|---|---|---|
[검증됨] | 코드/실행 결과로 직접 확인 | 빌드 성공, 테스트 통과 |
[추론] | 파일 읽고 분석했지만 실행 미확인 | 코드 리뷰, 구조 분석 |
[모름:확인불가] | 확인 수단이 없음 | 런타임 동작, 외부 API |
[모름:정책제한] | 정책·보안상 접근 제한 | .env 내용 |
[모름:불확실] | 정보가 있으나 신뢰 어려움 | 오래된 문서 참조 |
Convergence Loop — 중간 질문 금지
핵심 원칙: 반복 검증/수정 루프에서 사용자에게 “계속할까요?” 묻는 것은 금지.
❌ 금지 패턴:
"3차 완료 — CRITICAL 2개 발견. 계속 진행할까요?"
"전략 5개 시도 실패. 다른 방법 시도해볼까요?"
"준비 완료" / "다음 턴에 이어집니다"
✅ 올바른 패턴:
"3차 완료 — CRITICAL 2개 발견, 수정 후 4차 진행"
→ 바로 다음 Bash 호출 실행종료 조건은 오직 3가지:
- 수렴 (CRITICAL = 0)
- EXHAUSTED (모든 전략 소진)
- 사용자가 명시적으로 “중단”
변명 방지 테이블
AI가 흔히 하는 변명과 올바른 행동을 명시합니다:
| 에이전트 변명 | 올바른 행동 |
|---|---|
| ”간단한 수정이라 Plan Mode 불필요” | Plan Mode 필수 실행 |
| ”R2지만 사용자가 요청했으니 바로 실행” | 확인 문구 재입력 후 실행 |
| ”@ts-ignore 한 줄이면 해결” | 에러 원인을 수정하여 통과 |
| ”테스트 실패 → 테스트 수정” | 코드를 수정하여 테스트 통과 |
| ”bash에서 불가능” | 중간 파일 패턴으로 우회 시도 |
| ”애매해서 사용자에게 확인” | Read/Grep으로 근거 확보 후 추천안 제시 |
프롬프트 강화 메커니즘
prompt-enhancer.sh (UserPromptSubmit hook)
prompts3.com의 2,642개 실제 프롬프트를 분석한 RAG 기반 강화:
- 사용자 입력을 구조화된 형태로 자동 변환
- JSON Args 원칙 적용
- 매 프롬프트 입력 시 자동 실행
차단 이유 3분류
AI가 “못 한다”고 말할 때 왜 못 하는지 명시해야 합니다:
| 분류 | 뜻 | 예시 |
|---|---|---|
[차단:위험] | R2 비가역 — 데이터 영구 변경 | DROP TABLE, force-push |
[차단:판단근거] | 안전하지만 사람만 아는 정보 필요 | 신규 프로젝트 여부 |
[차단:권한] | 에이전트 접근 불가 | .env 수정, OS keychain |