3줄 요약
- Claude Code는 npm 전역 설치 후 Anthropic 계정 인증만으로 바로 쓸 수 있다 — 로컬 GPU·모델 설치 불필요.
- CLAUDE.md는 프로젝트 규칙·아키텍처·금기사항을 AI에 주입하는 핵심 파일 — 반복 지시를 없애고 일관된 결과를 만든다.
- 에이전틱 워크플로의 핵심은 작업 쪼개기, 중간 검증, 컨텍스트 관리다 — AI를 실행 주체로 두되 사람이 오케스트레이션한다.
Claude Code를 처음 열었을 때 가장 먼저 드는 질문은 대개 둘 중 하나다. “어디서 설치하지?” 그리고 “이걸 제대로 쓰려면 뭘 해야 하지?” 설치 자체는 5분이면 끝난다. 하지만 그다음 — AI가 내 프로젝트 맥락을 이해하고 규칙대로 움직이게 만드는 것은 CLAUDE.md 설계에 달려 있다. 이 글은 설치부터 CLAUDE.md 작성, 에이전틱 워크플로 습관까지 한 번에 정리한다.
Claude Code란 무엇인가 — 짧게
Claude Code는 Anthropic의 CLI 기반 AI 코딩 에이전트다. 터미널에서 실행하면 AI가 파일을 읽고·수정하고·명령을 실행하며 다단계 작업을 수행한다. 단순한 코드 자동완성이 아니라 에이전틱 코딩(agentic coding) — AI가 맥락을 파악하고, 파일을 탐색하며, 실제 작업 흐름을 주도하는 방식이다. 모델은 클라우드에서 실행되므로 로컬 GPU가 없어도 된다. 구형 CPU 서버나 노트북으로 충분하다.
Claude Code 설치 방법 — 단계별
Node.js(18 이상)와 npm이 설치된 환경이라면 전역 설치 한 줄로 끝난다.
# npm 전역 설치 (예시 — 최신 버전은 공식 문서 확인)
npm install -g @anthropic-ai/claude-code설치 후 프로젝트 디렉터리로 이동해 실행한다.
cd /your/project
claude최초 실행 시 인증 흐름이 시작된다. 대략 이런 순서다.
- CLI가 브라우저 인증 URL을 표시한다.
- Anthropic 계정으로 로그인 후 승인한다.
- 일회용 코드를 CLI에 붙여넣는다.
- 인증 완료 — 이후 재인증 없이 사용 가능하다.
Claude Code 사용은 Anthropic의 유료 플랜 또는 API 크레딧을 소모한다. 무료 체험 범위는 공식 사이트에서 확인하자. 설치와 인증이 끝나면 바로 프롬프트를 입력할 수 있다.
🖥️ 누스쿨 수강생이라면 — init 한 줄로 Claude Code까지 설치
02편에서 소개한 누스쿨 ai-os-init 스크립트(curl -fsSL https://nuschool.cc/dl/install.sh | sudo sh)를 실행하면 Docker·LVM·보안 설정 같은 서버 기본 환경뿐 아니라 Claude Code까지 한 번에 설치·구성된다. 위의 npm 설치·인증 과정을 따로 밟지 않아도 개발을 바로 시작할 수 있다. (누스쿨은 주니크가 운영하는 교육기관 — 회원가입 후 수강권 인증이 필요하며, 설치 파일만 원하면 문의로 요청할 수 있다.)
CLAUDE.md 컨텍스트 설계 — 반복 지시를 없애는 핵심
Claude Code는 실행 시 프로젝트 루트의 CLAUDE.md 파일을 자동으로 읽는다. 여기에 프로젝트 규칙·아키텍처·금기사항을 적어두면, 매번 같은 지시를 반복하지 않아도 AI가 일관된 방식으로 작업한다. 팀 컨벤션을 문서가 아닌 AI 행동 규칙으로 만드는 것이 CLAUDE.md의 역할이다.
좋은 CLAUDE.md의 구성 요소
| 항목 | 내용 예시 |
|---|---|
| 프로젝트 아키텍처 | MSA 구조, 서비스 간 의존 관계, 디렉터리 규칙 |
| 기술 스택 & 버전 | Node 20, Python 3.12, Docker Compose v2 |
| 코딩 컨벤션 | 함수명 camelCase, SQL은 heredoc 금지, 들여쓰기 2스페이스 |
| 금기사항 (절대 하지 말 것) | 프로덕션 DB 직접 수정 금지, 특정 파일 편집 금지 |
| 배포 규칙 | Gitea 푸시 전 테스트 필수, nginx reload만(컨테이너 재시작 금지) |
| 도구 & 경로 | wp-cli 실행 방법, 시크릿 파일 위치, 로그 경로 |
규칙이 많다고 좋은 게 아니다. AI가 잘못된 판단을 내릴 가능성이 높은 지점에 집중하자. 특히 “하지 말아야 할 것”을 명시적으로 적는 것이 효과가 크다.
CLAUDE.md 예시 스니펫
# 프로젝트: 내 서비스명
## 아키텍처
- MSA 구조: api-gateway / user-service / order-service
- 서비스 간 통신: REST (gRPC 사용 금지)
- DB: MariaDB — 각 서비스가 독립 DB 소유
## 배포 규칙
- nginx는 reload만 (컨테이너 재시작 금지)
- 프로덕션 DB 직접 수정 금지 — 반드시 마이그레이션 스크립트 경유
## 코딩 컨벤션
- Python: 함수명 snake_case, 타입 힌트 필수
- 환경변수는 .env 파일로 — 코드에 하드코딩 금지
## 금기 파일 (편집 금지)
- /app/secrets/ 하위 파일
- docker-compose.yml (변경 필요 시 먼저 보고)CLAUDE.md는 프로젝트 루트 외에도 서브디렉터리에 추가로 둘 수 있다. 각 디렉터리 진입 시 해당 CLAUDE.md가 추가로 로드되므로 서비스별·모듈별 규칙을 분리 관리할 수 있다.
권한과 안전 — 파일 수정 범위를 이해하자
Claude Code는 실행 환경의 파일 시스템에 직접 접근한다. AI가 파일을 생성하거나 수정할 때는 확인 프롬프트가 표시되는 것이 기본 동작이다. 주의할 점은 다음과 같다.
- 작업 디렉터리 범위: 실행한 디렉터리와 하위를 대상으로 작업한다. 루트 디렉터리에서 실행하면 프로젝트 전체에 접근 가능하다.
- 명령 실행 확인: bash 명령 실행 전 확인을 요청한다. 자주 쓰는 명령은 허용 목록(allowlist)에 추가해 반복 확인을 줄일 수 있다.
- 민감 파일 보호: CLAUDE.md에 편집 금지 파일·디렉터리를 명시해두면 AI가 해당 경로를 건드리지 않도록 유도할 수 있다.
CI 환경이나 자동화 파이프라인에서 대화형 확인 없이 실행하는 옵션도 있으나, 처음엔 대화형 모드에서 AI의 행동 패턴을 먼저 파악하는 것을 권장한다.
에이전틱 워크플로 습관 — 위임이 아닌 오케스트레이션
Claude Code를 처음 쓰면 “프롬프트 하나로 모든 것을 해결하려는” 실수를 한다. 에이전틱 코딩의 진짜 힘은 작업을 잘게 쪼개고, 단계마다 검증하며, 사람이 흐름을 오케스트레이션(orchestration)하는 것에 있다.
실전 습관 3가지
- 작업 단위 분리: “로그인 기능 전체 만들어줘” 대신 “users 테이블 스키마 먼저 설계해줘 → 확인 → API 엔드포인트 작성해줘 → 확인 → 테스트 작성해줘”처럼 단계를 나눈다.
- 중간 검증 요청: “변경 전에 어떤 파일을 수정할 예정인지 먼저 알려줘”라고 묻는 습관. AI가 잘못된 방향으로 달리기 전에 방향을 잡는다.
- 컨텍스트 관리: 대화가 길어질수록 AI의 응답 품질이 떨어진다. 새 작업은 새 세션에서 시작하고, CLAUDE.md로 컨텍스트를 대화가 아닌 파일로 공급한다.
흔한 함정 — 이것만 피해도 절반은 성공
| 함정 | 증상 | 대처 |
|---|---|---|
| 맥락 과다 주입 | CLAUDE.md가 너무 길어 AI가 핵심 규칙을 놓침 | 항목당 1~2줄, 필수 규칙만. 세부는 별도 파일로 분리 |
| 검증 없이 위임 | AI가 의도와 다른 파일을 수정하거나 삭제 | 큰 작업 전 “수정할 파일 목록 먼저 알려줘” 습관 |
| 한 세션에 너무 많이 | 대화가 길어질수록 앞 규칙을 잊고 엉뚱한 응답 | 작업 단위로 새 세션, 규칙은 CLAUDE.md로 |
| 명령어 단정 | AI가 존재하지 않는 플래그를 자신 있게 제안 | 중요한 명령은 공식 문서로 직접 확인 |
GUNIQ 실제 사례 — CLAUDE.md로 팀 규칙을 강제한다
주니크(GUNIQ)는 구형 워크스테이션(Intel Xeon E5-2690 v2, 20코어, 64GB RAM, GPU 없음, Ubuntu 24 서버) 한 대로 MSA 기반 서비스를 개발한다. Claude Code가 개발의 주체이고 사람은 판단·검증·오케스트레이션을 맡는다.
이 환경에서 CLAUDE.md가 하는 역할은 크게 세 가지다.
- 아키텍처 규칙 강제: “nginx는 reload만, 컨테이너 재시작 금지”, “DB 접근은 각 서비스 전용 계정만”처럼 실수하면 인프라가 흔들리는 규칙을 문서로 박아둔다.
- 경로·도구 일원화: WP-CLI 실행 방법, 시크릿 파일 위치, 로그 경로 등 매번 물어봐야 하는 정보를 CLAUDE.md 한 곳에 모아둔다.
- 금기사항 명시: “호스트에서 직접 캐시 rm 금지(컨테이너 내부에서만)”, “특정 config 파일 직접 편집 금지” 같은 규칙 — 적어두지 않으면 AI가 잘 모르고 실행해버린다.
결과는 단순하다. 같은 프로젝트 내에서 새 작업을 시작해도 AI가 규칙을 다시 배울 필요가 없다. 배포 완료 후 코드는 Gitea(셀프호스팅 git)에 푸시하고, Proxmox 내 각 VM으로 분산 배포한다. 이 흐름 전체를 Claude Code가 주도하고 사람이 최종 검증한다.
🎓 바로 쓰기 — 오늘 할 수 있는 것
- npm으로 Claude Code 설치 후 Anthropic 계정 인증 완료.
- 가장 자주 쓰는 프로젝트 루트에
CLAUDE.md파일 생성 — 아키텍처 2줄, 금기사항 3줄부터 시작. - 간단한 작업(함수 하나 추가, 테스트 작성)을 Claude Code에 맡기고 파일 수정 흐름을 직접 관찰.
- 대화가 5~6회 이상 길어지면 새 세션 — 컨텍스트 관리 습관 들이기.
FAQ
Claude Code란 무엇인가?
Anthropic이 만든 CLI 기반 AI 코딩 에이전트다. 터미널에서 실행하면 AI가 파일을 탐색·수정하고, 명령을 실행하며, 다단계 개발 작업을 수행한다. 단순 자동완성이 아니라 에이전틱 코딩(agentic coding) 도구다.
Claude Code는 유료인가?
사용량에 따라 Anthropic API 크레딧을 소모한다. 정확한 요금과 무료 범위는 Anthropic 공식 사이트에서 확인하자. 로컬 모델이 아닌 클라우드 모델이라 별도 하드웨어 비용은 없다.
어떤 프로젝트에 특히 효과적인가?
반복 패턴이 많은 프로젝트, 여러 파일에 걸친 리팩터링, 테스트 작성, 문서화처럼 “맥락을 이해하고 여러 파일을 동시에 다뤄야 하는” 작업에서 강하다. 단순 한 줄 수정보다 다단계 작업에서 효과가 두드러진다.
CLAUDE.md는 반드시 필요한가?
필수는 아니지만, 없으면 매 세션마다 같은 규칙을 반복해서 설명해야 한다. 프로젝트 규모가 커질수록, 또는 팀에서 공유할수록 CLAUDE.md의 효과는 커진다. 2~3줄짜리 간단한 규칙만 적어도 일관성이 눈에 띄게 올라간다.
다음 단계가 필요하다면
Claude Code 도입부터 MSA 파이프라인 구축까지, 실전 설계가 필요하다면 주니크에 문의하자. 직접 구축하고 운영하는 경험을 바탕으로 구체적인 방향을 잡아드린다.
『에이전틱 개발 파이프라인』 시리즈
← 이전: 02. GPU 없이 구형 Xeon으로 AI 개발 서버 구축
→ 다음: 04. Claude Code로 MSA 설계·구현
