Claude Code 기존 코드베이스 지도: 수정 전 45분 안전 워크플로

기존 코드베이스에 Claude Code를 투입할 때 첫 산출물은 코드 변경이 아니라 지도여야 합니다. repo map은 애플리케이션이 어디서 시작되는지, 중요한 디렉터리는 무엇인지, 오늘 건드리지 말아야 할 영역은 어디인지, 변경 후 어떤 명령으로 확인할지, 다음 담당자에게 무엇을 넘길지를 정리한 문서입니다. 이 지도가 없으면 작은 요청이 넓은 정리, 부수적인 리팩터링, 리뷰하기 어려운 변경으로 번지기 쉽습니다.

이 글은 수정 전에 기존 저장소를 읽는 45분 워크플로를 초보자도 따라 할 수 있게 정리합니다. 공식 Claude Code overview는 Claude Code가 코드베이스를 읽고, 파일을 편집하고, 명령을 실행할 수 있다고 설명합니다. 그래서 더더욱 에이전트가 움직이기 전에 경계를 먼저 정해야 합니다.

함께 읽을 글로는 기존 코드베이스 첫 프롬프트, Claude Code 권한 설정 가이드, CLAUDE.md starter template가 있습니다.

45분 repo map

처음 25분은 읽기 전용 조사, 10분은 지도 작성, 5분은 첫 안전 작업 선택, 5분은 계획 리뷰에 씁니다. 완벽한 아키텍처 문서를 만들 필요는 없습니다. 목표는 작고 되돌리기 쉬우며 검증 가능한 변경을 고르는 작업 지도입니다.

flowchart TD
  A["읽기 전용 인벤토리"] --> B["입구 찾기"]
  B --> C["안전 영역과 위험 영역 분리"]
  C --> D["첫 패치 하나 선택"]
  D --> E["검증 명령 고정"]
  E --> F["repo-map.md 작성"]

입구는 앱이 시작되는 지점입니다. 라우트 파일, API handler, 서버 bootstrap, CLI 명령, 예약 작업, 콘텐츠 로더가 여기에 해당합니다. 위험 영역은 작은 실수도 신뢰나 매출에 영향을 주는 곳입니다. 인증, 결제, 삭제, 운영 설정, secret, 배포 스크립트, 분석, 광고 태그가 대표적입니다.

Step 1: 읽기 전용으로 조사하기

먼저 저장소를 변경하지 않는 명령만 실행합니다. Windows PowerShell에서는 아래 세트로 첫 윤곽을 볼 수 있습니다.

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

기술 스택, 문서, 생성물, 캐시 디렉터리, 미커밋 변경을 확인합니다. 작업 트리가 이미 dirty라면, 그 변경이 누구의 것인지 먼저 확인해야 합니다. 그래야 다른 사람의 변경을 AI가 덮어쓰는 일을 피할 수 있습니다.

Claude Code에는 읽기 전용 경계를 명확히 적습니다.

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

Do not edit files yet는 꽤 강한 안전장치입니다. 계획이 리뷰 가능해질 때까지 세션을 조사 모드로 묶어 둡니다.

Step 2: repo-map.md 작성하기

조사 결과를 채팅에만 남기지 말고 repo-map.md로 저장합니다. 공식 memory 문서는 CLAUDE.md로 프로젝트 지시를 유지할 수 있다고 설명하지만, 첫 조사 결과를 모두 넣으면 파일이 금방 무거워집니다. 먼저 repo map으로 두고, 반복해서 쓰이는 규칙만 CLAUDE.md로 옮깁니다.

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

이 문서는 완전한 설계도가 아니라 첫 유용한 변경을 위한 가드레일입니다.

Step 3: 권한으로 경계 만들기

프롬프트 지시는 도움이 되지만 강제 장치는 아닙니다. 공식 permissions 문서는 allow, ask, deny 규칙을 설명합니다. 기존 저장소의 첫 세션에서는 읽기와 안전한 확인은 허용하고, build나 편집은 물어보게 하며, push, 삭제, secret 읽기는 거부하는 편이 좋습니다.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

이 JSON은 출발점입니다. 프로젝트에 npm run test가 없을 수도 있고, 편집 허용 경로도 달라질 수 있습니다. 중요한 것은 허용을 늘리기 전에 거부할 것을 먼저 정하는 습관입니다.

Step 4: 첫 안전 패치 고르기

지도가 생기면 작고, 되돌리기 쉽고, 검증하기 쉬운 작업을 고릅니다. 세 가지 실전 사례가 특히 좋습니다.

첫째, 콘텐츠 CTA 수정입니다. 인기 글에서 제품 목록과 Claude Code 교육 상담으로 자연스럽게 이어지는지 확인합니다. 보통 콘텐츠 파일 하나만 바꾸고 build와 preview로 검증할 수 있습니다.

둘째, README나 CLAUDE.md에 검증 명령을 추가하는 작업입니다. 확인된 build, test, lint, preview 명령을 짧게 남기면 다음 세션의 탐색 비용이 줄어듭니다.

셋째, 한 화면의 표시 문구나 날짜 형식 수정입니다. 변경 파일을 한두 개로 제한하고 테스트, 스크린샷, 로컬 preview로 확인합니다. 인증, 결제, 권한, 삭제는 첫 작업에서 제외합니다.

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

이렇게 쓰면 넓은 요청이 리뷰 가능한 작은 패치로 바뀝니다.

Step 5: 지도 자체도 확인하기

repo map은 문서지만 최소 섹션 존재 여부는 스크립트로 확인할 수 있습니다. 다음 코드를 check-repo-map.js로 저장해 실행합니다.

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

단순한 스크립트지만 매번 같은 형식의 인수인계를 남기게 만드는 효과가 있습니다.

흔한 실패

실패 1은 요청이 너무 넓은 경우입니다. “전체를 리팩터링해줘” 또는 “품질을 올려줘”는 변경 범위와 완료 조건이 모호합니다. 읽기 전용 조사, 최대 파일 수, 오늘 건드리지 않을 영역, 검증 명령을 먼저 지정합니다.

실패 2는 생성물을 지도에 섞는 것입니다. dist, .astro, .next, coverage, node_modules는 저장소를 크게 보이게 하지만 첫 이해에는 방해가 될 수 있습니다. 실제 배포 산출물을 확인해야 하는 상황이 아니라면 제외합니다.

실패 3은 외부 서비스 연계를 가볍게 보는 것입니다. 메일 발송, 결제 webhook, 광고 태그, 분석, CRM 연계는 코드가 짧아도 사업 영향이 큽니다. 첫 세션에서는 읽기만 하고, 편집은 별도 작업으로 분리합니다.

실패 4는 build만 보고 끝내는 것입니다. build가 통과해도 모바일 레이아웃, 코드 블록, CTA, 내부 링크가 깨질 수 있습니다. 콘텐츠 사이트라면 preview에서 본문, 코드 블록, /products/, /training/을 직접 확인합니다.

리뷰 체크리스트

관점	확인할 것	나쁜 신호
Diff	요청한 파일만 바뀌었는가	대량의 부수 포맷팅
Entry	변경이 어떻게 로드되는가	읽히지 않는 파일을 수정
Risk	인증, 결제, 삭제, 운영 설정 미접촉	secret이나 deploy 변경
Proof	명령 또는 수동 확인이 있는가	”아마 괜찮음”만 있음
Funnel	CTA와 내부 링크가 자연스러운가	상품 링크가 억지로 붙음
Handoff	남은 위험이 적혀 있는가	다음 세션이 같은 조사를 반복

이 체크리스트는 Claude Code를 불신하기 위한 것이 아니라 작업을 반복 가능하게 만들기 위한 것입니다.

수익 경로도 지도에 넣기

ClaudeCodeLab 같은 콘텐츠 사이트에서는 코드 지도에 수익 경로도 포함해야 합니다. 어떤 글이 검색 유입을 만들고, 독자가 어디서 무료 다운로드, 템플릿 상품, 상담 페이지로 이동하는지 봅니다. 바로 쓸 수 있는 템플릿은 제품 라이브러리에서 확인할 수 있고, 팀 도입과 권한 설계가 필요하면 Claude Code 교육 상담이 적합합니다.

수익 경로가 지도에 있으면 작은 CTA 수정도 단순 문구 변경으로 끝나지 않습니다. 내부 링크, 상품 페이지, 폼, 분석, 광고 위치까지 함께 확인하게 됩니다. 코드가 맞아도 독자의 다음 행동이 분명하지 않으면 매출은 생기지 않습니다.

정리

기존 코드베이스에서 Claude Code를 쓸 때 첫 45분은 구현이 아니라 지도 작성에 쓰세요. 저장소를 조사하고, 입구를 찾고, 위험 영역을 표시하고, 첫 안전 작업과 검증 명령을 정한 뒤 repo-map.md를 남깁니다. 그 다음 한두 파일짜리 작은 변경을 하면 리뷰가 훨씬 쉬워집니다.