2026-11-18 기준으로 고쳤습니다. 처음 쓴 날은 2026-08-04 이고, 명령과 옵션은 Claude Code 2.1.326 에서 확인했습니다.
Claude Code 실전 가이드 1편입니다. 전체 5부작이고, 이번 편은 설치와 첫 세션, 그리고 프로젝트 규칙을 CLAUDE.md 에 박아서 매번 같은 지시를 반복하지 않게 만드는 법까지입니다. 컨텍스트 관리, 서브에이전트, MCP, 자율주행에 가까운 워크플로는 이후 편에서 각각 따로 다룹니다. Codex 와 agy(구글 Antigravity CLI)를 다루는 자매 연재도 올리고 있습니다. Codex 실전 가이드와 agy 실전 가이드입니다.
설치와 첫 세션
Claude Code 는 터미널에서 도는 CLI 도구입니다. 공식 문서는 네이티브 설치를 권장하고, npm 전역 설치는 고급 설치 옵션으로 둡니다.
curl -fsSL https://claude.ai/install.sh | bash # macOS·Linux·WSL
설치 후에는 작업할 레포 디렉터리로 들어가서 claude 를 실행하면 세션이 시작됩니다.
cd ~/workspace/gitlab.doksam.com/www
claude
첫 실행에서는 계정 인증을 한 번 거칩니다. 이후로는 같은 명령으로 바로 세션이 열립니다. 세션 안에서 / 로 시작하는 슬래시 명령을 쓸 수 있고, /help 를 치면 지금 쓸 수 있는 명령 목록이 나옵니다. 이 글에서 뒤에 나오는 /init, 그리고 2편에서 다룰 /clear·/compact 도 전부 그 목록에 있습니다.
여기서 중요한 건 어느 디렉터리에서 실행하느냐입니다. Claude Code 는 실행한 디렉터리를 작업 루트로 잡고, 그 디렉터리를 기준으로 파일과 설정을 읽습니다. 하위 디렉터리에서 열어도 상위의 CLAUDE.md 는 읽히지만, 레포 루트의 .claude/settings.json 은 읽히지 않습니다. 특별한 이유가 없으면 레포 루트에서 여는 게 기본입니다.
첫 세션에서 코드를 바로 고치게 하기보다 “이 레포 구조 설명해줘” 같은 읽기 작업부터 시켜보길 권합니다. 어떤 파일을 어떤 순서로 뒤지는지 보입니다. 그 과정에서 “이건 매번 설명해야 하는구나” 싶은 것들이 눈에 띕니다. 그게 바로 다음 절의 CLAUDE.md 후보입니다.
왜 CLAUDE.md 인가
Claude Code 를 처음 쓰면 세션마다 같은 말을 반복하게 됩니다. “이 레포는 pnpm 쓴다”, “커밋 메시지에 이런 트레일러 넣지 마라”, “브랜치는 이슈 번호 붙여서 만들어라” 같은 것들입니다. 새 세션은 이전 대화를 자동으로 이어받지 않으니, 다음 세션을 열면 처음부터 다시 설명해야 합니다.
CLAUDE.md 는 이 반복을 없애는 파일입니다. 프로젝트 루트(또는 홈 디렉터리의 ~/.claude/)에 두면 세션을 시작할 때 자동으로 읽힙니다. 그래서 매번 프롬프트로 알려주던 규칙과 사실을 미리 주입해둘 수 있습니다. 사람으로 치면 “새로 온 팀원에게 온보딩 문서를 던져주는 것"과 비슷합니다. 다만 온보딩 문서와 달리 이건 매 세션 실제로 다시 읽힙니다.
핵심은 이겁니다. CLAUDE.md 에 적은 규칙은 “말 안 해도 대체로 지켜지는 것"이 되고, 안 적은 규칙은 매번 말해야 합니다. 그래서 자주 반복하게 되는 지시일수록 CLAUDE.md 로 옮길 후보입니다.
제가 쓰는 판단 기준은 단순합니다. 같은 지시를 세 번 이상 했으면 그건 프롬프트가 아니라 규칙입니다. 두 번까지는 그때그때 말하고, 세 번째에 파일로 옮깁니다. 반대로 한 번 쓰고 말 지시(이번 작업에서만 유효한 조건 같은 것)를 파일에 적으면, 나중에 그게 낡은 전제로 남아서 오히려 방해가 됩니다.
전역 CLAUDE.md 와 프로젝트 CLAUDE.md
CLAUDE.md 는 두 군데에 둘 수 있고, 역할이 다릅니다.
전역(홈 디렉터리, ~/.claude/CLAUDE.md) — 어떤 레포에서 세션을 열든 항상 적용되는 규칙입니다. “이 사람이 어떻게 일하는가"에 해당하는 것들입니다. 예를 들면:
- 응답 말투나 톤 같은 커뮤니케이션 스타일
- git 커밋/브랜치/PR 워크플로 규칙 (트레일러 형식, 이슈 우선 원칙 등)
- 여러 프로젝트에 공통인 인프라 사실 (SSH 접속 정보, 공유 DB 클러스터 위치, 사내 서비스 주소 등)
- 시크릿 다루는 원칙 (로그에 노출 금지, 특정 플래그 금지 등)
프로젝트 CLAUDE.md(레포 루트) — 그 레포에서만 의미 있는 규칙입니다:
- 이 레포가 쓰는 프레임워크·패키지 매니저·빌드 명령
- 디렉터리 구조와 어디에 뭘 두는지
- 이 레포만의 코딩 컨벤션이나 금지 사항
- 테스트/린트/배포 명령어
역할이 갈리는 이유는 단순합니다. 전역 파일에 “이 레포는 pnpm 쓴다"를 적으면 pnpm 을 안 쓰는 다른 레포에서 세션을 열 때마다 틀린 전제가 주입됩니다. 반대로 “커밋에 이런 트레일러 넣지 마라"를 프로젝트마다 반복해서 적으면 레포 수만큼 유지보수해야 합니다. 자주 바뀌지 않고 여러 곳에 걸치는 것은 전역에, 그 레포에서만 참인 것은 프로젝트 파일에 두는 게 원칙입니다.
두 파일은 동시에 읽힙니다. 전역이 “이 사람의 기본값”, 프로젝트가 “이 레포의 예외/구체화"라고 생각하면 됩니다.
제 레포에서는 프로젝트 파일을 CLAUDE.md 대신 AGENTS.md 로 두는 게 표준입니다. 공식 문서 기준으로 Claude Code 는 v2.1.277 부터 AGENTS.md 를 읽습니다. 작업 디렉터리와 그 위에 CLAUDE.md 가 없을 때 그 자리를 대신합니다. Codex 와 agy 도 같은 파일을 읽어서, 에이전트마다 지침을 따로 쓰지 않아도 됩니다. 다만 레포에 CLAUDE.md 를 함께 두면 CLAUDE.md 만 읽히고 AGENTS.md 는 빠집니다. 둘 다 읽히게 하려면 CLAUDE.md 안에서 @AGENTS.md 로 불러옵니다. 전역 ~/.claude/CLAUDE.md 는 이 판단에 들지 않아서 AGENTS.md 와 함께 계속 읽힙니다. 기계가 읽을 정보(구성요소·명령·환경변수 이름)는 AGENTS.yaml 에 따로 적습니다. 그 구조와 경로는 검증 스크립트가 확인합니다.
좋은 CLAUDE.md 와 나쁜 CLAUDE.md
CLAUDE.md 를 처음 쓰면 흔히 프로젝트 설명서처럼 장황하게 쓰는 실수를 저지릅니다. “이 프로젝트는 사용자에게 훌륭한 경험을 제공하기 위해…” 같은 문장은 실행에 아무 영향이 없습니다. CLAUDE.md 는 매 세션 컨텍스트를 잡아먹는 파일이라, 행동을 바꾸는 내용만 남기는 게 맞습니다.
나쁜 예
## 프로젝트 소개
이 프로젝트는 사용자들이 편리하게 이용할 수 있는 훌륭한 웹 서비스를 만들기 위한
것으로, 최신 기술 스택을 활용하여 유지보수가 쉽고 확장 가능한 구조로 설계되었습니다.
이런 문장은 지워도 아무것도 안 바뀝니다. 규칙도 아니고 사실도 아니고, 그냥 소개글입니다.
좋은 예
## 워크플로
- 커밋 메시지에 Co-Authored-By 트레일러 넣지 말 것
- 모든 작업은 GitLab 이슈 먼저 등록 → 브랜치 → MR → 머지. trivial typo 는 예외
- 파괴적 git 명령(force push, reset --hard)은 사용자 확인 후에만 실행
## 인프라
- PostgreSQL 은 단일 클러스터를 여러 서비스가 공유한다 (서비스별 DB 분리 없음)
- 배포 호스트는 rootless podman + Quadlet 조합, 리버스프록시는 호스트 nginx
차이는 명확합니다. 좋은 CLAUDE.md 는 “규칙"이거나 “사실"입니다. 규칙은 지켜야 할 행동 지침, 사실은 몰라서 틀리면 안 되는 환경 정보입니다. 설명이나 배경 서술은 최소화하고, 필요하면 예시 하나 정도만 곁들입니다.
그리고 한 항목이 길어지면 대개 규칙이 아니라 설명으로 새고 있는 겁니다. 세 줄을 넘어가면 “이걸 읽고 행동이 달라지나"를 다시 물어보고, 아니면 줄이거나 뺍니다.
/init 으로 초안 만들기
빈 CLAUDE.md 를 처음부터 쓰는 것보다, /init 명령으로 초안을 만들고 손보는 게 빠릅니다. /init 은 현재 레포를 훑어서 CLAUDE.md 초안을 채워줍니다. 디렉터리 구조, 사용 중인 패키지 매니저, 빌드/테스트 명령 같은 것을 자동으로 파악해 넣습니다.
다만 자동 생성 초안은 “이 레포가 뭘로 만들어졌는가"까지만 잘 잡아냅니다. “어떻게 일해야 하는가” 같은 워크플로 규칙은 사람이 직접 채워야 합니다. /init 으로 뼈대를 만든 뒤, 반복해서 지시하던 규칙을 하나씩 얹어가는 방식이 실전에서 제일 매끄러웠습니다.
권한 — 처음엔 좁게, 쓰면서 넓히기
Claude Code 는 권한 모드에 따라 파일을 고치거나 셸 명령을 실행하기 전에 확인을 받습니다. 동작마다 사람이 승인하는 모드가 Manual(설정값 default)입니다. 공식 문서 기준으로 v2.1.283 부터 대화형 세션은 Manual 이 아니라 auto 모드로 시작합니다. auto 모드에서 동작을 검토하는 쪽은 사람이 아니라 분류 모델(classifier)입니다. 모드는 세션 안에서 Shift+Tab 으로 바꾸고, 시작 모드는 설정 파일의 permissions.defaultMode 로 정합니다. 제 설정도 auto 입니다. 매번 승인을 누르는 게 번거로우면 자주 쓰는 동작을 허용 목록에 올려둘 수 있습니다. 현재 허용 상태는 세션 안에서 /permissions 로 확인·수정합니다.
무엇을 먼저 열어둘지는 되돌릴 수 있느냐로 가르는 게 제일 깔끔합니다.
- 먼저 열어도 되는 것: 빌드·타입체크·테스트 실행처럼 실패해도 원상복구가 되는 동작 (작업 디렉터리 안 파일 읽기와
git status·git diff·git log같은 조회성 명령은 처음부터 확인 없이 실행됩니다) - 매번 확인받는 게 나은 것: 강제 push 나
reset --hard처럼 이력을 날리는 git 명령, 운영 DB 에 쓰는 작업, 외부 API 대량 호출, 설정 파일 자체를 고치는 동작
허용 범위는 한 번에 넓게 열기보다 하나씩 늘리는 편이 사고를 줄입니다. 실제로 반복해서 승인 버튼을 누르는 동작이 눈에 띌 때마다 추가하면 됩니다. “귀찮아서 전부 허용"으로 시작하면, 정작 막았어야 할 명령이 언제 지나갔는지 알 수 없게 됩니다.
실사례 — 90개 레포를 혼자 굴리면서
제 경우 셀프호스팅 GitLab 에 미러를 제외하고 90개 레포가 있습니다(2026-08-16 집계). 웹은 TypeScript, 데몬은 Go, AI 쪽은 Python, 운영 스크립트는 Shell — 이렇게 역할별로 언어가 수렴해 있습니다. 레포마다 사람은 저 혼자입니다.
이 규모에서 제일 크게 체감한 건 워크플로 규칙이었습니다. “코드 변경 작업은 이슈부터 등록하고, 그 이슈 번호를 커밋과 MR 에 박고, 브랜치를 만들어서 작업하고, MR 을 올리고, CI 를 지켜보고, 머지한다” — 이 순서를 레포마다, 세션마다 매번 설명하는 건 비효율적입니다. 이걸 전역 CLAUDE.md 에 한 번 적어두니, 새 레포에서 세션을 열어도 다시 설명할 일이 없어졌습니다. “이슈 먼저"라고만 말해도 되고, 사실 그 말조차 안 해도 알아서 이슈부터 찾습니다.
여러 세션이나 서브에이전트가 같은 레포를 동시에 건드릴 때 브랜치가 꼬이는 문제도 있었습니다. 이건 “동시에 도는 에이전트 하나 = 브랜치 하나 = 작업 디렉터리 하나(worktree)“라는 규칙을 전역 지침에 박아두면서 정리됐습니다. 2026-08 에는 “세션 하나 = worktree 하나 = 이슈 하나 = 브랜치 하나"였고, 지금은 작업이 실제로 겹칠 때만 worktree 를 씁니다. 이 부분은 여러 세션을 동시에 굴리는 이야기라 3편(서브에이전트·병렬)에서 더 다루겠습니다.
반대로 “이 서비스는 이 포트를 쓴다”, “이 레포는 이 패키지 매니저를 쓴다” 같은 건 그 레포의 CLAUDE.md 에만 적었습니다. 전역에 넣었다면 90개 레포 전부에 안 맞는 전제가 섞였을 겁니다.
인프라 사실을 전역에 적을 때는 대가도 같이 옵니다. 서버 IP 하나를 바꾸거나 서비스를 다른 호스트로 옮기면 파일에는 옛 주소가 남습니다. 그 주소가 그대로 다음 세션에 주입됩니다. 사람은 “아 그거 옮겼지” 하고 넘어가지만 에이전트는 적힌 대로 접속을 시도합니다. 그래서 저는 전역 파일에 인프라 사실을 적을 때 변경 시점을 같이 적어둡니다. 오래된 항목은 그대로 믿고 행동하기 전에 한 번 확인하라는 규칙도 넣어뒀습니다. CLAUDE.md 는 한 번 쓰고 끝나는 문서가 아니라 코드처럼 계속 손봐야 하는 파일입니다.
손볼 때는 줄이는 쪽도 봅니다. CLAUDE.md 는 매 세션 통째로 실리니, 규칙이 쌓이면 그만큼 컨텍스트를 먹습니다. 그래서 2026-08 부터 근거와 이력, 세부 절차를 ~/.claude/ref-*.md·~/.claude/infra-*.md 로 떼어 냈습니다. CLAUDE.md 에는 규칙 요약과 “이 작업 전에 이 파일을 읽어라"는 포인터만 남깁니다. 2026-09-24 백업본은 28KB 였고, 2026-11-18 지금은 17KB·104줄입니다. 이슈 등록부터 머지까지 같은 여러 단계 절차는 스킬로 옮겼습니다. 스킬은 설명만 미리 실리고, 본문은 그 스킬을 쓸 때 불러옵니다. 공식 문서도 여러 단계 절차나 코드 일부에만 해당하는 지시는 스킬이나 경로별 규칙(.claude/rules/)으로 옮기라고 권합니다.
정리
1편에서 정한 건 두 가지입니다. 하나, 자주 반복하는 지시는 프롬프트가 아니라 CLAUDE.md 로 옮긴다 — 전역에는 “내가 일하는 방식”, 프로젝트 파일에는 “이 레포에서만 참인 것”. 둘, 권한은 되돌릴 수 있는 동작부터 열고 되돌릴 수 없는 동작은 계속 확인받는다.
여기까지 하면 세션 시작 비용이 확 줄어듭니다. 다음 문제는 세션이 길어질 때입니다. 대화가 쌓이면 컨텍스트가 차고, 차면 모델이 정작 중요한 걸 놓칩니다. 2편에서는 무엇이 컨텍스트를 잡아먹는지, /clear 와 /compact 를 각각 언제 쓰는지를 다룹니다.