Claude Code 실전 가이드 1편입니다. 전체 5부작이고, 이번 편은 설치와 첫 세션, 그리고 프로젝트 규칙을 CLAUDE.md 에 박아서 매번 같은 지시를 반복하지 않게 만드는 법까지입니다. 컨텍스트 관리, 서브에이전트, MCP, 자율주행에 가까운 워크플로는 이후 편에서 각각 따로 다룹니다.
설치와 첫 세션
Claude Code 는 터미널에서 도는 CLI 도구입니다. npm 으로 전역 설치하는 게 가장 흔한 경로입니다.
npm install -g @anthropic-ai/claude-code
설치 후에는 작업할 레포 디렉터리로 들어가서 claude 를 실행하면 세션이 시작됩니다.
cd ~/workspace/gitlab.doksam.com/www
claude
첫 실행에서는 계정 인증을 한 번 거칩니다. 이후로는 같은 명령으로 바로 세션이 열립니다. 세션 안에서 / 로 시작하는 슬래시 명령을 쓸 수 있고, /help 를 치면 지금 쓸 수 있는 명령 목록이 나옵니다. 이 글에서 뒤에 나오는 /init, 그리고 2편에서 다룰 /clear·/compact 도 전부 그 목록에 있는 것들입니다.
여기서 중요한 건 어느 디렉터리에서 실행하느냐입니다. Claude Code 는 실행한 디렉터리를 작업 루트로 잡고, 그 아래의 파일과 설정을 읽습니다. 레포 루트에서 여는 것과 하위 디렉터리에서 여는 것은 읽히는 컨텍스트가 다릅니다. 특별한 이유가 없으면 레포 루트에서 여는 게 기본입니다.
첫 세션에서 코드를 바로 고치게 하기보다는, "이 레포 구조 설명해줘" 같은 읽기 작업부터 시켜보길 권합니다. 어떤 파일을 어떤 순서로 뒤지는지 보이고, 그 과정에서 "이건 매번 설명해야 하는구나" 싶은 것들이 눈에 띕니다. 그게 바로 다음 절의 CLAUDE.md 후보입니다.
왜 CLAUDE.md 인가
Claude Code 를 처음 쓰면 매 세션마다 같은 말을 반복하게 됩니다. "이 레포는 pnpm 쓴다", "커밋 메시지에 이런 트레일러 넣지 마라", "브랜치는 이슈 번호 붙여서 만들어라" 같은 것들입니다. 세션이 끝나면 대화 컨텍스트도 같이 사라지니, 다음 세션을 열면 처음부터 다시 설명해야 합니다.
CLAUDE.md 는 이 반복을 없애는 파일입니다. 프로젝트 루트(또는 홈 디렉터리)에 두면 세션을 시작할 때 자동으로 읽혀서, 매번 프롬프트로 알려주던 규칙과 사실들을 미리 주입해둘 수 있습니다. 사람으로 치면 "새로 온 팀원에게 온보딩 문서를 던져주는 것"과 비슷합니다. 다만 온보딩 문서와 달리 이건 매 세션 실제로 다시 읽힙니다.
핵심은 이겁니다. CLAUDE.md 에 적은 규칙은 "말 안 해도 지켜지는 것"이 되고, 안 적은 규칙은 매번 말해야 합니다. 그래서 자주 반복하게 되는 지시일수록 CLAUDE.md 로 옮길 후보입니다.
제가 쓰는 판단 기준은 단순합니다. 같은 지시를 세 번 이상 했으면 그건 프롬프트가 아니라 규칙입니다. 두 번까지는 그때그때 말하고, 세 번째에 파일로 옮깁니다. 반대로 한 번 쓰고 말 지시(이번 작업에서만 유효한 조건 같은 것)를 파일에 적으면, 나중에 그게 낡은 전제로 남아서 오히려 방해가 됩니다.
전역 CLAUDE.md 와 프로젝트 CLAUDE.md
CLAUDE.md 는 두 군데에 둘 수 있고, 역할이 다릅니다.
전역(홈 디렉터리, ~/.claude/CLAUDE.md) — 어떤 레포에서 세션을 열든 항상 적용되는 규칙입니다. "이 사람이 어떻게 일하는가"에 해당하는 것들입니다. 예를 들면:
- 응답 말투나 톤 같은 커뮤니케이션 스타일
- git 커밋/브랜치/PR 워크플로 규칙 (트레일러 형식, 이슈 우선 원칙 등)
- 여러 프로젝트에 공통으로 걸쳐 있는 인프라 사실 (SSH 접속 정보, 공유 DB 클러스터 위치, 사내 서비스 주소 등)
- 시크릿 다루는 원칙 (로그에 노출 금지, 특정 플래그 금지 등)
프로젝트 CLAUDE.md(레포 루트) — 그 레포에서만 의미 있는 규칙입니다:
- 이 레포가 쓰는 프레임워크·패키지 매니저·빌드 명령
- 디렉터리 구조와 어디에 뭘 두는지
- 이 레포만의 코딩 컨벤션이나 금지 사항
- 테스트/린트/배포 명령어
역할이 갈리는 이유는 단순합니다. 전역 파일에 "이 레포는 pnpm 쓴다"를 적으면 pnpm 을 안 쓰는 다른 레포에서 세션 열 때마다 틀린 전제가 주입됩니다. 반대로 "커밋에 이런 트레일러 넣지 마라"를 프로젝트마다 반복해서 적으면 레포 수만큼 유지보수해야 합니다. 자주 바뀌지 않고 여러 곳에 걸치는 것은 전역, 그 레포에서만 참인 것은 프로젝트 파일로 나누는 게 원칙입니다.
두 파일은 동시에 읽힙니다. 전역이 "이 사람의 기본값", 프로젝트가 "이 레포에서의 예외/구체화"라고 생각하면 됩니다.
좋은 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 는 파일을 고치거나 셸 명령을 실행하기 전에 사용자에게 권한을 확인합니다. 매번 승인을 누르는 게 번거로우면 자주 쓰는 동작을 허용 목록에 올려둘 수 있고, 현재 허용 상태는 세션 안에서 /permissions 로 확인·수정합니다.
무엇을 먼저 열어둘지는 되돌릴 수 있느냐로 가르는 게 제일 깔끔합니다.
- 먼저 열어도 되는 것: 파일 읽기,
git status·git diff·git log같은 조회성 명령, 빌드·타입체크·테스트 실행처럼 실패해도 원상복구가 되는 동작 - 매번 확인받는 게 나은 것: 강제 push 나
reset --hard처럼 이력을 날리는 git 명령, 운영 DB 에 쓰는 작업, 외부 API 대량 호출, 설정 파일 자체를 고치는 동작
허용 범위는 한 번에 넓게 열기보다, 실제로 반복해서 승인 버튼을 누르고 있는 동작이 눈에 띌 때마다 하나씩 추가하는 편이 사고를 줄입니다. "귀찮아서 전부 허용"으로 시작하면, 정작 막았어야 할 명령이 언제 지나갔는지 알 수 없게 됩니다.
실사례 — 87개 레포를 혼자 굴리면서
제 경우 셀프호스팅 GitLab 에 미러를 제외하고 87개 레포가 있습니다. 웹은 TypeScript, 데몬은 Go, AI 쪽은 Python, 운영 스크립트는 Shell — 이렇게 역할별로 언어가 수렴해 있고, 레포마다 사람은 저 혼자입니다.
이 규모에서 제일 크게 체감한 건 워크플로 규칙이었습니다. "코드 변경 작업은 이슈부터 등록하고, 그 이슈 번호를 브랜치와 커밋에 박고, 브랜치를 만들어서 작업하고, MR 을 올리고, CI 를 지켜보고, 머지한다" — 이 순서를 레포마다, 세션마다 매번 설명하는 건 비효율적입니다. 이걸 전역 CLAUDE.md 에 한 번 적어두니, 새 레포에서 세션을 열어도 다시 설명할 필요가 없어졌습니다. "이슈 먼저" 라고만 말해도 되고, 사실 그 말조차 안 해도 알아서 이슈부터 찾습니다.
여러 세션이나 서브에이전트가 같은 레포를 동시에 건드릴 때 브랜치가 꼬이는 문제도 있었는데, 이건 "세션 하나 = 작업 디렉터리 하나(worktree) = 이슈 하나 = 브랜치 하나" 라는 규칙을 전역 CLAUDE.md 에 박아두면서 정리됐습니다. 이 부분은 여러 세션을 동시에 굴리는 이야기라 3편(서브에이전트·병렬)에서 더 다루겠습니다.
반대로 "이 서비스는 이 포트를 쓴다", "이 레포는 이 패키지 매니저를 쓴다" 같은 건 그 레포의 CLAUDE.md 에만 적었습니다. 전역에 넣었다면 87개 레포 전부에 안 맞는 전제가 섞였을 겁니다.
인프라 사실을 전역에 적을 때는 대가도 같이 옵니다. 서버 IP 하나를 바꾸거나 서비스를 다른 호스트로 옮기면, 파일에 남아 있는 옛 주소가 그대로 다음 세션에 주입됩니다. 사람은 "아 그거 옮겼지" 하고 넘어가지만 에이전트는 적힌 대로 접속을 시도합니다. 그래서 저는 전역 파일에 인프라 사실을 적을 때 변경 시점을 같이 적어두고, 오래된 항목은 그대로 믿고 행동하기 전에 한 번 확인하는 걸 규칙으로 넣어뒀습니다. CLAUDE.md 는 한 번 쓰고 끝나는 문서가 아니라 코드처럼 계속 손봐야 하는 파일입니다.
정리
1편에서 정한 건 두 가지입니다. 하나, 자주 반복하는 지시는 프롬프트가 아니라 CLAUDE.md 로 옮긴다 — 전역에는 "내가 일하는 방식", 프로젝트 파일에는 "이 레포에서만 참인 것". 둘, 권한은 되돌릴 수 있는 동작부터 열고 되돌릴 수 없는 동작은 계속 확인받는다.
여기까지 하면 세션 시작 비용이 확 줄어듭니다. 다음 문제는 세션이 길어질 때입니다. 대화가 쌓이면 컨텍스트가 차고, 차면 모델이 정작 중요한 걸 놓칩니다. 2편에서는 무엇이 컨텍스트를 잡아먹는지, /clear 와 /compact 를 각각 언제 쓰는지를 다룹니다.