Claude Code 실전 가이드

처음 30분부터 팀 도입까지

Claude Code를 처음 켜면 “이걸 어떻게 쓰지?”보다 “이걸 계속 써도 되는 건지”를 먼저 판단하게 된다. 그 판단이 첫 30분 안에 거의 결정된다

이 글은 그 30분을 잘 쓰는 것에서 시작해서, 팀으로 확장하는 것까지의 실전 흐름을 정리한다

첫 30분 – 큰 기능이 아니라 안전장치부터

많은 초보자가 Claude Code를 켜자마자 “새 기능 하나 만들어줘”로 시작한다. 이 방식은 거의 항상 문제를 만든다. 코드가 나쁜 게 아니라, 검증 기준이 없기 때문에 실패한다

첫 30분의 목적은 큰 기능을 끝내는 것이 아니다. “Claude Code가 어떤 변경을 만들고, 나는 어떤 기준으로 그 변경을 확인할지”를 몸에 익히는 것이다

1단계 (0-5분) – 최소 CLAUDE.md 만들기

이 저장소가 무엇인지, 어떻게 실행하는지, 어디를 건드리면 안 되는지만 적어도 충분하다

# Project Contract

## Commands
- dev: `pnpm dev`
- test: `pnpm test`
- lint: `pnpm lint`

## Safety
- never edit `.env*`
- ask before deleting files

2단계 (5~10분) – 최소 권한 경계 설정

{
  "permissions": {
    "allow": [
      "Read", "Edit", "Write", "Glob", "Grep",
      "Bash(pnpm lint)", "Bash(pnpm test)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

3단계 (10~15분) – 작업 버그 하나 고르기

오타 수정, 버튼 비활성화 버그, 빈 값 제출 버그처럼 범위가 좁고 검증이 쉬운 것을 고른다

4단계 (15분~20분) – 바로 수정하지 말고 plan부터

CLAUDE.md와 src/features/signup/, tests/signup.test.ts를 읽어라.
바로 수정하지 말고 다음을 먼저 알려줘:
1. 버그 원인
2. 수정할 파일 후보
3. 완료 기준
4. 회귀 위험

5단계 (20~30분) – 구현 후 검증으로 마무리

pnpm test -- signup
pnpm lint

이 루틴을 한 번만 제대로 밟으면, Claude Code를 “코드 생성기”가 아니라 “수정-검증 작업흐름”으로 읽기 시작하게 된다

세 파일의 역할 – CLAUDE.md, rules, settings.json

이 세 파일은 비슷해 보이지만 다루는 층이 다르다. 초보자가 가장 자주 하는 실수는 세 가지를 모두 CLAUDE.md 한 파일에 몰아넣는 것이다. 그러면 규칙도 흐려지도, 권한 경계도 약해지고, 컨텍스트도 무거워진다

파일역할비유
CLAUDE.md항상 읽는 기분 운영 계약안내문
./claude.rules/*.md경로나 관심사별 세부 규칙부서 운영 규칙
./claude/settings.json허용 · 차단 경계문 잠금장치

이 셋을 분리하는 이유는 “설명”과 “강제”를 섞지 않기 위해서다. 프롬프트는 어디까지나 부탁에 가깝지만, settings는 실제 경계다

권장 프로젝트 구조

repo/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── rules/
│   │   ├── api.md          # API 파일에만 적용할 규칙
│   │   └── testing.md      # 테스트 작성 기준
│   └── skills/
├── src/
└── tests/

팀 공유용 vs 개인 로컬용도 처음부터 분리한다

  • 팀 규약 → CLAUDE.md, .claude/settings.json
  • 개인 실험 → CLAUDE.local.md, .claude/settings.local.json

권한 설정 – 빠름과 무방비는 다르다

Claude Code를 처음 쓰면 매번 승인 창이 뜨는 게 거슬린다. 그렇다고 바로 전체 권한을 건너뛰면 위험하다.

permission rule 평가 순서: deny → ask → allow. 첫 매칭 규칙이 적용된다.

실무에서 권장하는 순서는 이렇다.

  1. allowlist로 반복 승인 피로를 줄인다: pnpm test, pnpm lint처럼 자주 쓰고 안전한 명령을 미리 허용
  2. 민감 경로는 명시적으로 차단한다: .env, secrets/
  3. 삭제·배포·DB 변경은 여전히 승인 단계로 남긴다

주의: Read(./.env)를 막아도 Bash(cat .env)까지 자동으로 막히지 않는다. 실제 민감 정보 차단은 permission rule과 sandbox 정책을 함께 봐야 한다.

7일 세팅 플랜

첫날부터 모든 것을 만들려 하면 금방 지친다. 아래 순서대로 하루에 하나씩 붙이면 된다

Day1

CLAUDE.md이 저장소가 무엇인지, 실행 명령, 절대 건드리면 안 되는 곳, 완료 기준. 이 네 가지만 적어도 충분하다

Day2

검증 명령 정리 test, lint, build 명령을 CLAUDE.md 명시한다. 초보자가 Claude Code에서 자주 겪는 문제는 “겉보기엔 됐는데 실제론 안 되는 결과”다. 이 문제를 줄이는 가장 빠른 방법이 검증 명령을 분명히 적는 것이다

Day3

.claude/settings.json 허용할 Bash 명령, 금지 경로, .env 차단을 설정한다. 이때 생기는 사고는 대부분 실력 부족보다 경계 부족에서 나온다

Day4

rules 하나 자주 틀리는 영역 하나만 .claude/rules/로 분리한다. API 규칙이든, 테스트 규칙이든 한 가지만 해도 “공통 계약서와 경로별 규칙은 다르다”는 감각이 생긴다

Day5

plan 루틴 한 번 작은 버그 하나를 잡더라도 아래 순서를 한 번 제대로 밟아본다

문제 설명 → 관련 파일 후보 → 완료 기준 → 구현 → 검증

Day6

review 세션 분리 구현도 Claude, 리뷰도 같은 세션에서 하면 구현 세션은 자신의 가정에 익숙해진다. 별도 세션은 fresh eyes 역할을 한다

Day7

handoff.md 오늘 바뀐 것, 아직 안 된 것, 다음에 볼 파일, 남은 위험만 적어두면 충분하다. 이 습관이 생기면 세션이 끊겨도 다시 시작 비용이 크게 줄어즌다

plan부터쓰고 바로 수정하지 않는 이유

큰 작업일수록 “바로 수정”은 되레 느려진다

이유는 세 가지다. 어떤 파일을 건드릴지 합의 없이 시작하게 되고, 완료 기준이 불명확한 채로 구현이 커지고, 중간에 방향이 틀어지면 되돌리기 어렵다

plan은 속도를 늦추는 절차가 아니라, 재작업을 줄이는 장치다

초보자일수록 코드베이스를 아직 잘 모르는 상태에서 바로 구현을 맡기기 쉽다. 결과가 좋아 보여도 나중에 보면 잘못된 파일을 건드렸거나, 팀 규약을 어겼거나, 테스트가 빠져 있거나, 변경 범위가 너무 커진 경우가 많다

세션 관리 – 언제 새 세션으로 갈아타야 하나

컨텍스트가 쌓일수록 결과가 또렷해시는 게 아니다. 어느 시점부터는 누적 컨텍스트가 오히려 부담이 된다

아래 상황에서는 새 새션으로 넘어갈 타이밍이다

  • 같은 방향 수정도 두 번 이상 빗나갔다
  • 원래 작업과 무관한 설명이 늘어나기 시작했다
  • 컨텍스트 사용량이 높은데 핵심 판단이 흐려진다

새 새션으로 갈 때는 그냥 대화를 버리는 게 아니라 plan.md나 HANDOFF.md에 지금까지 합의한 범위와 남은 위험을 남겨두면 품질 손실 없이 갈아탈 수 있다

토큰도 아껴야 한다. 세 가지 습관만 지켜도 체감이 크다

  • “인증을 개선해줘”보다 “이 파일의 이 함수만 고쳐줘”
  • 긴 로그 전체보다 실패 원인에 필요한 핵심 줄만
  • 구현이 끝나면 handoff 남기고 새 세션으로 이동

생산성이 올라가는 패턴

실제로 살아남는 패턴은 화려하지 않다

  • 큰 일일수록 바로 수정하지 않고 plan.md를 먼저 만든다
  • 구현 세션과 리뷰 세션을 분리한다
  • 실수는 프롬프트가 아니라 hooks 같은 클라이언트 레이어에서 걸러낸다
  • 에디터와 터미널을 같이 열어 파일을 보는 눈과 실행하는 손을 분리한다

Claude Code의 생산성은 결국 세 가지 병목과 싸우는 일이다. 컨텍스트 손실, 검증 누락, 작업 전환 비용, plan 파일, handoff, 병렬 세션 분리는 각각 이 세 병목 중 하나 이상을 줄이기 때문에 반복해서 살아남는다

정리

Claude Code는 강력해서, 잘못 쓰면 빠르게 망가뜨리는 도구가 된다

처음 시작하는 사람에게 필요한 것은 많지 않다. CLAUDE.md 하나로 운영 계약을 잡고, settings.json으로 권한 경계를 정하고, .claude/rules/로 세부 규칙을 분리하고, 최소 하나의 검증 루틴을 붙이면 기본 골격은 갖춰진다.

한 줄로 요약하면 이렇게

먼저 끝의 모습을 적고, 바로 손대지 말고 계획부터 만들고, 큰 덩어리보다 작은 변경으로 쪼개고, 테스트와 린트를 끝 기준에 포함하고, 구현과 리뷰는 분리하라.

이 다섯 가지는 원칙이라기 보다 "나중에 후회하지 않기 위한 순서"에 가깝다

출처 – Claude Code Claude Cowork 마스터 가이즈 – 제작자 CHOI