Claude Code 첫 30분 체크리스트: 초보자를 위한 안전한 시작

첫 30분은 큰 패치를 만드는 시간이 아니라 신뢰를 만드는 시간입니다

Claude Code를 처음 쓸 때 가장 흔한 실수는 너무 큰 일을 바로 맡기는 것입니다. “이 기능을 완성해 줘”, “전체 코드를 정리해 줘”, “랜딩 페이지를 다시 만들어 줘”처럼 시작하면 30분 뒤에는 검토하기 어려운 diff만 남을 수 있습니다. 초보자의 첫 목표는 작아야 합니다. 저장소 구조를 이해하고, 하나의 작은 성과를 만들고, 검증 증거와 다음 단계를 남기는 것이 좋습니다.

공식 Claude Code overview는 Claude Code가 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 연동할 수 있다고 설명합니다. 그래서 더더욱 처음에는 경계를 명확히 해야 합니다. 무엇을 읽을지, 무엇을 수정할지, 어떤 명령으로 확인할지를 먼저 정해야 합니다.

이 글은 First Task Runbook, Repo Map First Pass, Session Handoff Template, Verification Receipt Workflow와 함께 쓰면 좋습니다. 이 30분 흐름을 익히면 버그 분석, 테스트 보강, 콘텐츠 수정, 팀 온보딩에도 확장할 수 있습니다.

초보자가 먼저 알아야 할 개념

저장소는 코드, 테스트, 설정, 스크립트, 문서가 들어 있는 프로젝트 폴더입니다. 에이전트는 지시를 받아 조사, 편집, 명령 실행, 검증까지 진행하는 실행자입니다. 권한은 Claude Code가 무엇을 읽고, 무엇을 수정하고, 어떤 명령을 실행할 수 있는지 정하는 안전장치입니다. 공식 permissions 문서는 allow, ask, deny 규칙과 권한 모드를 설명합니다.

CLAUDE.md는 프로젝트 설명서입니다. 코딩 규칙, 아키텍처 메모, 금지 명령, 빌드 명령, 리뷰 기준을 적어 두면 매 세션마다 같은 설명을 반복하지 않아도 됩니다. 공식 memory 문서는 프로젝트 지시와 메모리가 어떻게 다음 작업을 돕는지 이해하는 데 좋습니다.

검증은 결과가 맞다는 증거입니다. npm run build, 테스트 통과, 화면 확인, 로그 확인, 또는 아직 확인하지 못한 항목을 적은 메모가 될 수 있습니다. “괜찮아 보인다”는 검증이 아닙니다. 첫 세션에서는 수정 전에 검증 방법부터 정해야 합니다.

30분 뒤에 남아야 할 것

결과물	내용	이유
저장소 지도	진입점, 주요 디렉터리, 실행 명령, 위험 영역	구조를 모르고 수정하지 않기 위해
작은 성과	하나의 진단, 링크 수정, 테스트 설명, 재현 메모	검토 가능한 크기를 유지하기 위해
검증 메모	실행한 명령, 성공/실패, 남은 불확실성	리뷰어가 같은 증거를 볼 수 있게 하기 위해
다음 단계	다음 세션의 최소 작업	두 번째 세션을 빠르게 시작하기 위해

큰 변경은 나중에 해도 됩니다. 처음에는 작은 성공을 안전하게 반복하는 습관이 더 중요합니다.

0분에서 5분: 구현보다 맥락을 먼저 요청합니다

첫 프롬프트는 읽기 전용 조사로 시작합니다. Claude Code가 프로젝트를 이해하는지 확인한 뒤에 수정해야 합니다.

Read this repository and tell me:
1. the main entry points
2. the commands I will probably need
3. the risky directories I should avoid first
4. the safest high-value first task for a 30-minute session

Do not edit files yet. Give me a short plan and the proof command you would run.

이 프롬프트는 진입점, 명령, 위험 디렉터리, 첫 작업 후보를 한 번에 요구합니다. 공식 common workflows에서도 탐색, 계획, 구현, 검증 흐름을 확인할 수 있습니다. 첫 5분은 코드를 쓰는 시간이 아니라 프로젝트를 읽는 시간입니다.

5분에서 20분: 온보딩 사례 하나만 고릅니다

첫 번째 사례는 실패 테스트 설명입니다. 바로 수정하지 말고 어떤 테스트가 실패했는지, 기대값과 실제값이 무엇인지, 관련 파일이 어디인지 설명하게 합니다. 실패 모양이 명확해지면 이미 성과입니다.

두 번째 사례는 작은 콘텐츠 또는 CTA 수정입니다. 예를 들어 제품 링크가 /products/를 가리키는지, 상담 링크가 /training/을 가리키는지, 버튼 문구가 독자에게 다음 행동을 설명하는지 확인합니다. 수익 경로가 있는 사이트에서는 작은 링크 하나도 중요합니다.

세 번째 사례는 모호한 버그를 재현 메모로 바꾸는 것입니다. “가끔 깨진다”는 작업이 아닙니다. 환경, 단계, 기대 결과, 실제 결과, 로그, 후보 파일로 정리하면 다음 세션에서 수정이 훨씬 쉬워집니다.

네 번째 사례는 최소 CLAUDE.md 작성입니다. 완벽한 팀 규칙을 한 번에 쓰지 않습니다. 금지 명령, 빌드 명령, 테스트 명령, 스타일 규칙, 리뷰 증거만 적어도 충분합니다. 공유 설정으로 확장할 때는 공식 settings 문서를 참고합니다.

복사해서 실행할 수 있는 스크립트

macOS, Linux, WSL에서는 저장소 루트에서 이 스크립트를 실행합니다. 상태만 읽고 파일을 수정하지 않습니다.

#!/usr/bin/env bash
set -euo pipefail

echo "== location =="
pwd

echo "== git status =="
git status --short

echo "== package scripts =="
if [ -f package.json ]; then
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
else
  echo "package.json not found"
fi

echo "== likely docs =="
find . -maxdepth 2 \( -name 'README*' -o -name 'CLAUDE.md' -o -name 'AGENTS.md' \) -print

echo "== recent changed files =="
git diff --name-only

Windows PowerShell에서는 다음 버전을 씁니다.

$ErrorActionPreference = "Stop"

Write-Host "== location =="
Get-Location

Write-Host "== git status =="
git status --short

Write-Host "== package scripts =="
if (Test-Path package.json) {
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
} else {
  Write-Host "package.json not found"
}

Write-Host "== likely docs =="
Get-ChildItem -Force -File -Include README*,CLAUDE.md,AGENTS.md -Recurse -Depth 2 |
  Select-Object -ExpandProperty FullName

Write-Host "== recent changed files =="
git diff --name-only

작업 후 인수인계 메모는 first-30-handoff.mjs로 저장해 실행할 수 있습니다.

const handoff = {
  outcome: "Adjusted one CTA sentence and confirmed the product/training links stayed visible.",
  verified: ["git status --short", "npm run build"],
  notVerified: ["Mobile visual check"],
  nextStep: "Open the page locally and inspect the CTA area at 390px width.",
};

for (const [label, value] of Object.entries(handoff)) {
  const body = Array.isArray(value) ? value.map((item) => `- ${item}`).join("\n") : value;
  console.log(`## ${label}\n${body}\n`);
}

권한은 보수적으로 시작합니다. 아래 예시는 유효한 JSON이며, 실제 명령은 프로젝트에 맞게 바꿉니다.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run build)",
      "Bash(npm test *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

피해야 할 구체적인 실패

첫 번째 실패는 “전부 고쳐 줘”라고 말하는 것입니다. 범위가 넓고 성공 기준이 없습니다. “실패 테스트 하나를 설명해 줘” 또는 “CTA 블록 하나만 수정하고 링크를 검증해 줘”로 줄여야 합니다.

두 번째 실패는 일반 작업 트리에서 강한 권한 모드를 쓰는 것입니다. 강한 권한은 격리 환경에서만 신중하게 써야 합니다. 비밀값이나 고객 데이터가 있는 프로젝트라면 공식 security 문서를 읽고 .env 접근을 막아야 합니다.

세 번째 실패는 검증 명령을 정하지 않는 것입니다. diff가 그럴듯해 보여도 증거가 없으면 리뷰하기 어렵습니다. npm run build, 테스트, JSON 파싱, 화면 확인 중 무엇을 증거로 삼을지 먼저 적습니다.

네 번째 실패는 세션 종료 메모를 남기지 않는 것입니다. 변경점, 확인한 증거, 남은 위험, 다음 단계를 쓰지 않으면 다음에도 같은 탐색을 반복합니다.

다음 단계와 수익 경로

개인 연습은 무료 치트시트로 안전한 프롬프트와 확인 명령을 손에 익히는 것부터 시작하면 됩니다. 재사용 가능한 프롬프트, CLAUDE.md 템플릿, 리뷰 체크리스트가 필요하면 ClaudeCodeLab products를 보세요. 팀이 권한, hooks, 검증 기록, 온보딩 교육을 정리해야 한다면 Claude Code training and consultation이 맞습니다.

실제 저장소에서 써 보니 가장 효과가 컸던 것은 “수정 전에 저장소 지도를 만들고, 끝날 때 git status --short를 보는 습관”이었습니다. 일본어 메모는 다음과 같습니다: 実際に試した結果, 첫 작업을 작게 제한할수록 diff를 더 쉽게 믿을 수 있었고 두 번째 Claude Code 세션도 훨씬 빠르게 이어졌습니다.