8장. 문서 없는 레포에 Claude Code를 붙이는 날 — 읽기부터 시작한다

여기까지가 준비였다.

이제 실제 상황이다.

order-service/
  커밋 41,000개
  최초 커밋 5년 전
  Kotlin + Spring Boot, Gradle 단일 모듈
  패키지 200개 남짓
  테스트 일부 (커버리지 미상)
  README 세 줄
  아는 사람: 절반은 퇴사

이 레포에 Claude Code를 붙이는 첫날,
무엇을 먼저 하는가.

순서를 뒤집지 않는다

가장 흔한 실패는 첫날 코드를 고치게 하는 것이다.

Agent는 우리 컨벤션을 모르고,
어디를 건드리면 무엇이 깨지는지 모른다.

그 상태에서 수정을 시작하면
검토할 수 없는 Diff가 쏟아진다.

첫날의 순서는 이렇다.

flowchart LR
    A[읽기만] --> B[지도 요청]
    B --> C[CLAUDE.md 초안]
    C --> D[초안 검증]
    D --> E[금지 목록]
    E --> F[첫 커밋]

수정은 다음 장에서 시작한다.

1️⃣ 계획 모드로 고정한다

Shift+Tab 으로 계획 모드로 들어간다.

읽기와 검색은 되고, 수정은 되지 않는다.

이 상태에서 하루를 보낸다.
안전장치가 아니라 학습 장치다.

Agent가 무엇을 어떻게 찾는지 관찰할 수 있다.

2️⃣ 지도를 요청한다

첫 질문 다섯 개를 정해두면 편하다.

1. 이 프로젝트의 진입점을 모두 찾아줘.
   HTTP Controller, 메시지 Consumer, 스케줄러, CLI 전부.

2. 패키지 구조를 도메인 기준으로 묶어서 정리해줘.
   각 묶음이 무슨 일을 하는지 한 줄씩.

3. 빌드·테스트·로컬 실행 명령을 찾아줘.
   추측하지 말고 실제 파일에 있는 것만.

4. 외부 시스템 의존을 전부 찾아줘.
   DB, Redis, 메시지 브로커, 외부 API, 파일 저장소.

5. 테스트가 있는 영역과 없는 영역을 나눠줘.

전부 읽기만으로 답할 수 있는 질문이다.

이 다섯 개의 답이 35장에서 만들 코드베이스 지도의 초안이 된다.

⚠️ 3번의 “추측하지 말고” 는 장식이 아니다.

이 단서가 없으면 Agent는 일반적인 Spring 프로젝트의
관습적인 명령을 그럴듯하게 알려준다.

3️⃣ /init 으로 초안을 만든다

이제 계획 모드를 벗어나 CLAUDE.md 초안을 만든다.

/init

Claude Code가 프로젝트를 훑고 초안을 만들어준다.

빌드 명령, 디렉터리 구조, 아키텍처 요약이 들어온다.

여기서 대부분의 사람이 실수한다.

초안을 그대로 커밋한다.

4️⃣ 초안은 검증하지 않으면 거짓말이 된다

/init 결과는 코드에서 유추한 내용이다.
유추는 자주 맞고 때때로 틀린다.

세 가지만 직접 확인한다.

# 정말 되는지 실행해본다
./gradlew build
./gradlew test

# 정말 이 흐름인지 코드로 확인한다

특히 자주 틀리는 항목이 있다.

마지막 항목이 중요하다.

레거시에는 과거의 컨벤션과 현재의 컨벤션이 함께 있다.
Agent는 둘 다 보고 평균을 낸다.

우리는 현재 쓰는 쪽을 골라 적어줘야 한다.

## Coding Convention

- 신규 코드는 `com.company.order.v2` 패키지 구조를 따른다
- `v1` 패키지는 읽기 전용으로 취급한다 (마이그레이션 대상)
- 금액은 Long, 원 단위

🔥 이 세 줄이 /init 초안 전체보다 가치 있다.

Agent가 알 수 없는 정보이기 때문이다.

5️⃣ 금지 목록을 손으로 쓴다

초안이 절대 만들어주지 않는 부분이다.

## 절대 하지 말 것

- 운영·스테이징 DB에 접속하지 않는다
- 마이그레이션 파일을 실행하지 않는다 (작성까지만)
- `v1` 패키지의 기존 동작을 변경하지 않는다
- 외부 결제·알림 API를 실제로 호출하지 않는다

여기에 7장의 .claude/settings.json 을 함께 둔다.

문장으로 적은 것은 지침이고,
설정으로 막은 것은 조건이다.

4장에서 본 차이가 그대로 적용된다.

프롬프트는 지시를 전달하고,
하네스는 조건을 만든다.

6️⃣ 첫 커밋

첫날의 산출물은 코드 변경이 아니다.

git add CLAUDE.md .claude/settings.json
git commit -m "chore: Claude Code 초기 설정 추가"

두 파일이다.

이것이 5장에서 말한 최소 구성이다.

• CLAUDE.md — 규칙 한 장
• 검증된 테스트 명령 하나
• 금지 목록

첫 주에 하지 말 것

특히 마지막 항목.

첫날 신나서 열 페이지를 쓰면
Agent가 지키지 않는 규칙이 아홉 페이지가 된다.

한 장으로 시작한다.
Agent가 틀리는 것을 보면서 늘린다.

이 장에서 실제로 얻은 것

코드는 한 줄도 바뀌지 않았다.

그런데 세 가지가 생겼다.

• 우리 코드베이스에 대한 문서화된 요약
• 검증된 빌드·테스트 명령
• 팀 공용 금지 목록

세 번째는 사람에게도 필요했던 것이다.

에이전틱 코딩 도입이 종종
“드디어 미뤄둔 문서를 쓰게 된 계기” 가 되는 이유다.

이 장의 핵심

• 첫날 코드를 고치게 하지 않는다 — 읽기부터 시작한다
• 계획 모드로 하루를 보내면 Agent의 탐색 방식을 배울 수 있다
• 첫 질문은 진입점 · 구조 · 명령 · 외부 의존 · 테스트 유무 다섯 개다
• “추측하지 말고 실제 파일에 있는 것만” 이라는 단서가 필요하다
• /init 초안은 유추다 — 빌드·테스트·컨벤션은 직접 검증한다
• 레거시에는 과거와 현재의 컨벤션이 함께 있고, 고르는 일은 사람이 한다
• 금지 목록은 초안이 만들어주지 않는다 — 손으로 쓴다
• 첫날의 산출물은 코드 변경이 아니라 CLAUDE.md 와 .claude/settings.json 이다