“AI에게 코드를 맡기기 전에, 프로젝트부터 정리하자”
Claude Code는 단순한 코드 자동완성 도구가 아닙니다.
프로젝트 전체 구조, README, 규칙 문서, 무시 파일을 하나의 컨텍스트로 이해한 뒤 그 안에서 판단합니다.
즉,
- 아무 설정 없이 탐색 → 엉뚱한 파일 수정, 스타일 붕괴
- 기준을 잡고 탐색 → 팀원급 코드 제안
이 차이는 처음 30분 세팅에서 결정됩니다.
가장 먼저 준비해야 할 것: README.md
Claude Code에게 프로젝트의 “세계관”을 설명하는 문서입니다.
없다면 반드시 만드시는 걸 권장드립니다.
안 좋은 README 예시
# my-project
프로젝트 설명이 상태에서는 Claude가 아무 기준도 모릅니다.
Claude 친화적인 README 예시
# Dashboard Web
이 프로젝트는 지표(DACU, MAU, 매출 등)를 시각화하는
대시보드 웹 애플리케이션입니다.
## Tech Stack
- Backend: Java 8, Spring Framework 4, MyBatis
- Frontend: JSP, jQuery, Chart.js
- DB: PostgreSQL
- Infra: Tomcat, Jenkins
## Project Rules
- 신규 비즈니스 로직은 Service 레이어에 작성
- JSP에서는 데이터 가공 금지
- JavaScript는 ES5 기준으로 작성
- 외부 라이브러리 추가 시 반드시 사유 명시
## Folder Structure
- /controller : 요청 처리
- /service : 비즈니스 로직
- /mapper : SQL 정의
- /jsp : 화면포인트
- 기술 스택을 정확히
- “하지 말아야 할 것”을 명시
- 폴더 역할을 설명
이 README 하나로 Claude Code의 답변 품질이 체감될 정도로 달라집니다.
Claude 전용 규칙 문서 만들기
이 파일은 Claude Code만을 위한 프로젝트 운영 규칙입니다.
팀 컨벤션 + AI에게 시키고 싶은 행동을 명확히 적습니다.
파일명은 보통 CLAUDE.md (대문자 권장)
CLAUDE.md 예시
# Claude Code Instructions
## Coding Style
- Java는 기존 코드 스타일을 절대 변경하지 말 것
- 메서드 분리는 20줄 이내 기준
- 기존 public API 시그니처 변경 금지
## Frontend Rules
- JSP에서는 로직 작성 금지
- JS는 jQuery 기반으로 유지
- React / ES6 문법 제안 금지
## When Modifying Code
- 반드시 변경 이유를 주석으로 남길 것
- 기존 동작을 유지하는 방향으로 리팩토링
- 불필요한 추상화 제안 금지
## What NOT to do
- 라이브러리 교체 제안
- 아키텍처 전면 개편 제안
- 최신 트렌드 강요이 문서의 효과
- “그럴듯하지만 쓸 수 없는 코드” 방지
- 과한 리팩토링 제안 차단
- 실무 친화적 답변 유지
절대 탐색시키지 말아야 할 파일 설정
Claude Code는 보이는 모든 파일을 학습 대상으로 인식합니다.
따라서 아래 파일들은 반드시 제외해야 합니다.
탐색 제외 대상
node_modules/
dist/, build/
target/
logs/
.env, .key, .pem
대용량 JSON / CSV
자동 생성 코드
.gitignore 예시
node_modules/
target/
build/
dist/
logs/
.env.claudeignore (있다면 적극 활용)
node_modules
target
build
logs
*.log
*.csv왜 중요한가
- 불필요한 컨텍스트 제거
- 응답 속도 개선
- 엉뚱한 파일 수정 방지
“이 프로젝트에서 AI가 뭘 해줬으면 하는지” 명확히 하기
초보자 분들이 가장 많이 놓치는 부분입니다.
Claude Code에게 이런 역할을 기대하시는지 먼저 정리해 보셔야 합니다.
예시 ① 유지보수 보조용
- 기존 코드 설명
- 버그 원인 분석
- 최소 수정 제안예시 ② 리팩토링 보조용
- 가독성 개선
- 중복 로직 제거
- 성능 영향 없는 개선이 기준을 CLAUDE.md에 적어두면 가장 좋습니다.
최초 탐색 전에 꼭 해보면 좋은 테스트 질문
탐색 후 바로 작은 질문으로 방향성을 확인하세요.
추천 질문 예시
- “이 프로젝트 구조를 요약해줘”
- “비즈니스 로직은 어디에 작성하는 게 맞아?”
- “이 프로젝트에서 수정 시 주의할 점 알려줘”
바로 이런 질문은 비추천
- “전체 구조를 최신 아키텍처로 바꿔줘”
- “React로 전환해줘”
흔한 실수 TOP 5
- README 없이 탐색
- 규칙 문서 없음
- 빌드 산출물 포함
- 기술 스택 모호
- AI에게 모든 결정 위임
Claude Code는 시키는 대로만 잘합니다.
Claude Code는 잘 정리된 프로젝트에서는 숙련된 팀원처럼 정리되지 않은 프로젝트에서는 초보 인턴처럼 행동합니다.
설치는 시작일 뿐이고, 세팅이 곧 실력 차이를 만듭니다.
