백엔드 개발자를 위한 Claude Code 에이전틱 코딩

이미 돌아가고 있는 백엔드 코드베이스를 Claude Code와 함께
이해하고, 이어서 개발하고, 나중에 떼어낼 수 있는 구조로 만드는 방법을 다룹니다.

Prompt Engineering이 아니라 Agent Harness Engineering.

이 책의 전제

대부분의 백엔드 개발자는 빈 디렉터리에서 시작하지 않는다.

몇 년 된 모놀리스가 있고,
문서는 없거나 낡았고,
테스트는 일부만 있고,
건드리면 어디가 깨지는지 아무도 확신하지 못한다.

이 책은 그 상태에서 출발한다.

• 예시 스택은 Kotlin + Spring Boot 모놀리스
• 다른 언어에서 출발하는 경우는 37장과 8부 후반에서 따로 다룬다
• 목적지는 마이크로서비스 분리가 아니라 분리할 수 있는 상태
• 그 과정을 사람이 아니라 Agent가 수행하고 사람이 검증하는 방식으로 만든다

읽는 순서는 순차를 권한다.
다만 Claude Code를 이미 쓰고 있다면 2부를 훑고 7부로 건너가도 된다.

목차

1부. 에이전틱 코딩과 하네스

Agent가 무엇이고, 왜 모델이 아니라 환경이 결과를 만드는가. 이 책의 지도.

• 1장. AI 코딩은 어떻게 달라지고 있는가 — 자동완성에서 Coding Agent까지
• 2장. Agent를 이루는 것들 — Context · Tools · Memory · Environment · Feedback Loop
• 3장. Coding Agent는 어떻게 개발하는가 — 탐색 · 계획 · 구현 · 검증의 순환
• 4장. 좋은 모델만으로 좋은 Agent가 되지 않는 이유 — 하네스라는 개념
• 5장. Harness의 구성요소 — 아홉 개의 부품

2부. Claude Code 첫걸음

설치부터 첫 위임까지. 그리고 문서 없는 우리 레포에 처음 붙이는 날.

• 6장. 설치와 첫 실행 — 터미널에서 시작한다
• 7장. Claude Code가 쓰는 도구와 권한 — Read · Grep · Edit · Bash
• 8장. 문서 없는 레포에 Claude Code를 붙이는 날 — 읽기부터 시작한다
• 9장. 첫 에이전틱 코딩 — 버그 하나를 끝까지
• 10장. 질문이 아니라 작업을 주는 법 — 목표 · 제약 · 완료 조건
• 11장. 모델 선택과 비용 감각 — 어디에 Opus를 쓸 것인가

3부. Context와 프로젝트 지식

Agent의 성능은 무엇을 읽히느냐로 결정된다. 그리고 무엇을 남겨두느냐로.

• 12장. Context가 Agent의 성능을 결정한다 — Window의 한계와 Context Rot
• 13장. 필요한 Context만 주기 — 검색 → 선택 → 정밀 분석
• 14장. CLAUDE.md란 무엇인가 — Agent가 항상 알아야 하는 것
• 15장. 좋은 CLAUDE.md 만들기 — 짧게, 자주 틀리는 것만
• 16장. 계층화와 개선 루프 — Root · 모듈 · 도메인, 그리고 규칙의 수명

4부. Memory와 Session 운영

중요한 정보가 대화 안에만 존재하면 안 된다.

• 17장. Agent의 Memory란 무엇인가 — 기억시킬 것과 기억시키지 않을 것
• 18장. Session이 길어지면 무엇이 무너지는가 — 언제 새로 시작할까
• 19장. Session을 안전하게 넘기는 방법 — 작업 상태를 파일로 남긴다

5부. 작업을 설계하고 수렴시키기

좋은 결과는 좋은 프롬프트가 아니라 좋은 작업 정의와 피드백에서 나온다.

• 20장. 요구사항을 Agent Task로 — Goal · Scope · Constraints · Acceptance Criteria
• 21장. Plan First — 바로 구현시키지 않는다
• 22장. 큰 작업 분해하기 — 병렬 가능한 것과 순차적인 것
• 23장. 테스트를 Agent의 눈으로 쓰기 — 스스로 검증하게 만들기
• 24장. Feedback Loop 설계 — Observe · Think · Act · Verify
• 25장. Git을 Agent의 안전장치로 — 작은 커밋과 되돌리기

6부. 백엔드 실무에 Claude Code 활용하기

Kotlin · Spring Boot 코드베이스에서 매일 반복하는 작업들.

• 26장. API 개발 — 기존 Convention을 따르게 만들기
• 27장. Database 작업 — Schema · Query · Migration · Index
• 28장. 트랜잭션과 동시성 — 경계 · Lock · Race Condition
• 29장. 도메인 규칙을 깨뜨리지 않게 — Invariant와 Edge Case
• 30장. 외부 연동과 복원력 — Timeout · Retry · 멱등성 · Circuit Breaker
• 31장. 캐시와 비동기 처리 — Redis · Queue · Worker · DLQ
• 32장. 인증과 보안 — Token · Secret · Injection · 개인정보
• 33장. 장애와 성능 분석 — 로그에서 Root Cause까지, Slow Query와 N+1

7부. 레거시 모놀리스를 파악시키기

문서가 없는 코드베이스를 Agent와 함께 읽는다.

• 34장. 문서 없는 레거시를 Agent와 함께 읽기 — Entry Point에서 Side Effect까지
• 35장. 코드베이스 지도 만들기 — Module · Dependency · Domain · Data Flow
• 36장. Characterization Test — 리팩터링 전에 현재 동작을 고정한다
• 37장. 관례가 없는 코드베이스에서 — 자체 프레임워크와 계층 미분리

8부. 경계를 긋는 에이전틱 리팩터링

지금 나누지 않는다. 다만 나중에 떼어낼 수 있게 만든다. 이 책의 목적지.

• 38장. 코드에서 경계를 찾기 — 도메인 · 책임 · 데이터 소유권
• 39장. 무엇부터 정리할 것인가 — 경계 후보의 우선순위
• 40장. 모놀리스 내부 구조 개선 — Controller · Application · Domain · Infrastructure
• 41장. 대규모 패키지 이동을 Agent에게 맡기는 방법 — 작게, 검증하며
• 42장. 경계를 규칙으로 강제하기 — 의존성 테스트로 고정한다
• 43장. 데이터 경계 준비 — 공유 테이블과 조인부터 끊기
• 44장. 나중에 떼어내기 쉬운 구조 — 코드 · 데이터 · 트랜잭션 · API · 이벤트

9부. 다른 언어로 넘기기

경계가 정리된 도메인을 새 언어로. 번역보다 검증이 비싸다.

• 45장. 다른 언어로 옮기기 — 무엇부터, 어떻게 같음을 증명하는가
• 46장. 두 언어가 공존하는 기간 — 라우팅 · 데이터 · 운영

10부. 반복 가능한 Workflow — Skill · Hook · Subagent

한 번 잘된 작업 방식을 매번 다시 설명하지 않는다.

• 47장. Skill이란 무엇인가 — 반복되는 절차를 자산으로
• 48장. 백엔드 Skill 만들기 — API 구현 · 장애 분석 · Migration Review
• 49장. Hooks — 무조건 실행되어야 하는 것, 그리고 셋의 구분
• 50장. Subagent — 독립 Context와 역할 분리
• 51장. 전문 Agent 만들기 — Explorer · Planner · Implementer · Reviewer
• 52장. Agent Orchestration — 구현과 Review를 분리한다
• 53장. 병렬 Agent와 Git Worktree — 그리고 Multi-Agent가 나쁠 때

11부. MCP와 안전한 운영

Agent에게 실제 시스템을 보여주되, 할 수 있는 일의 범위를 정한다.

• 54장. MCP란 무엇인가 — Agent에게 실제 시스템을 보여주기
• 55장. 개발 도구 연결 — GitHub · Jira · Database · Monitoring
• 56장. 장애 대응 Agent — Issue에서 수정안까지
• 57장. Permission과 Sandbox — Allow · Ask · Deny, 그리고 격리
• 58장. Database와 Secret — 환경별 권한 정책
• 59장. Production에서의 원칙 — Human Approval · Audit · Rollback

12부. 우리 팀의 Agent Harness

개인의 요령을 팀의 환경으로 바꾼다. 5장의 구성요소를 실제로 조립한다.

• 60장. 좋은 하네스와 나쁜 하네스 — 무엇이 Agent를 무력화하는가
• 61장. 우리 프로젝트의 Harness 설계도 그리기
• 62장. Agent가 실패하기 어렵게 만들기 — 반복해서 틀리면 하네스를 고친다
• 63장. 팀에 도입하기 — .claude/ 공유와 CI 자동 Review

13부. 실전 종합

앞의 모든 것을 하나의 작업에 붙여본다.

• 64장. 실전 1 — 요구사항 하나로 기능 개발하기
• 65장. 실전 2 — 장애 티켓 하나로 문제 해결하기
• 66장. 실전 3 — 레거시 모듈 하나를 경계 밖으로 밀어내기
• 67장. 실전 4 — 서비스 하나를 다른 언어로 넘기기

이 책이 결국 말하는 것

같은 Claude Code를 쓰는데 결과가 다른 이유는 프롬프트가 아니다.

초급 단계에서는 이것을 배운다.

Claude에게 코드를 작성시키는 방법

중급 단계에서는 이것을 배운다.

Claude에게 개발 작업을 맡기는 방법

고급 단계에서 배우는 것은 다르다.

Claude가 개발을 잘할 수 있는 환경을 설계하는 방법

좋은 에이전틱 코딩 환경은 하나의 요소로 만들어지지 않는다.

flowchart TB
    subgraph Input
        C[Context]
        M[Memory]
        I[Instructions]
    end
    subgraph Capability
        T[Tools]
        S[Skills]
        P[Permissions]
    end
    subgraph Verify
        TS[Tests]
        F[Feedback Loop]
        H[Human Review]
    end
    Input --> Model --> Capability --> Verify
    Verify -->|수렴하지 않으면 하네스를 고친다| Input

이 루프를 설계하는 일이 백엔드 개발자의 새로운 업무다.

1장. AI 코딩은 어떻게 달라지고 있는가 — 자동완성에서 Coding Agent까지

“AI로 개발한다“는 말은 세 번 뜻이 바뀌었다

처음에는 커서 뒤에 붙는 회색 글자를 뜻했다.

그다음에는 브라우저 창에 코드를 붙여넣고 물어보는 일을 뜻했다.

지금은 터미널에 목표를 적어두고
결과를 검토하는 일을 뜻한다.

도구만 좋아진 것이 아니다.
개발자가 하는 일 자체가 옮겨갔다.

세대는 세 번 바뀌었다

1️⃣ 자동완성 세대

내가 타이핑을 시작하면 AI가 뒷부분을 이어 쓴다.

userRepository.findBy 까지 치면 나머지를 채워준다.
편리하다. 그러나 AI가 아는 것은 지금 열린 파일 몇 개뿐이다.

작업의 주도권은 100% 개발자에게 있다.
AI는 타이핑 시간을 줄여준다.

2️⃣ 대화 세대

코드를 복사해서 채팅창에 붙여넣고 물어본다.

“이 코드에서 동시성 문제가 있을까?”

설명은 훌륭하다.
그런데 AI는 우리 프로젝트를 본 적이 없다.

우리에게 없는 클래스를 쓰라고 하고,
이미 있는 유틸리티를 다시 만들라고 한다.

붙여넣기, 번역, 적용, 검증은 전부 사람의 일로 남는다.

3️⃣ Agent 세대

이제는 코드를 붙여넣지 않는다.

프로젝트 디렉터리에서 도구를 실행하고,
해야 할 일을 문장으로 적는다.

결제 취소 시 포인트가 두 번 환급되는 버그가 있다.
관련 코드를 찾아서 원인을 설명하고,
재현 테스트를 먼저 작성한 다음 수정해줘.

그러면 AI가 스스로 파일을 찾고, 읽고, 수정하고,
./gradlew test 를 실행해 결과를 확인한다.

실패하면 로그를 읽고 다시 고친다.

결정적 차이는 하나다

세 세대를 가르는 기준은 모델의 성능이 아니다.

다음 행동을 누가 결정하는가

자동완성과 대화형에서는 다음 행동을 항상 개발자가 정한다.
AI가 만들어내는 것은 텍스트뿐이다.

Agent는 다르다.
목표를 받으면 다음 행동을 스스로 고른다.

flowchart LR
    A[목표] --> B{다음 행동 선택}
    B --> C[파일 읽기]
    B --> D[코드 검색]
    B --> E[파일 수정]
    B --> F[명령 실행]
    C & D & E & F --> G[결과 관찰]
    G --> B

이 순환이 에이전틱 코딩의 전부다.

대화형 AI는 답을 준다.
Coding Agent는 행동을 한다.

같은 버그, 두 가지 방식

앞의 이중 환급 버그를 두 방식으로 처리해보자.

대화형에서 개발자는 이렇게 움직인다.

의심되는 파일을 열고,
PointRefundService 를 복사해 붙여넣고,
답변을 읽고,
우리 코드에 맞게 고쳐 쓰고,
테스트를 돌린다.

Agent에서는 이렇게 움직인다.

목표를 적고,
Agent가 찾아온 호출 흐름이 맞는지 확인하고,
제안한 수정 방향에 동의하거나 반대하고,
테스트가 실제로 그 버그를 잡는지 검토한다.

일이 줄어든 것이 아니다.
일의 종류가 바뀌었다.

Vibe Coding과 Agentic Coding

여기서 갈림길이 생긴다.

같은 도구를 쓰면서도 전혀 다른 두 가지 방식이 존재한다.

Vibe Coding은 나쁜 것이 아니다.
주말에 만드는 사이드 프로젝트라면 충분히 합리적이다.

문제는 우리가 다루는 것이다.

⚠️ 백엔드 개발자는 남의 돈, 남의 개인정보,
그리고 되돌릴 수 없는 트랜잭션을 다룬다.

“돌아가는 것 같다“로 통과시킬 수 없는 영역이다.

그래서 이 책은 Vibe Coding을 다루지 않는다.
검증 가능한 위임, 즉 Agentic Coding을 다룬다.

코드를 읽지 않아도 되는 것이 아니다.
읽어야 할 대상이 달라진다.

전체 구현을 한 줄씩 쓰는 대신,
변경된 경계와 테스트 결과를 읽는다.

시간은 어디로 옮겨가는가

기존 개발에서 시간 배분은 대략 이랬다.

코드 작성        ██████████████ 60%
코드 이해·탐색   ██████ 25%
검증·리뷰        ███ 15%

에이전틱 코딩에서는 이렇게 뒤집힌다.

작업 정의        ██████ 25%
환경·규칙 정비   ██████ 25%
검증·리뷰        ████████ 35%
직접 작성        ███ 15%

타이핑이 줄어든 자리에 들어오는 것은 여유가 아니다.

무엇을 맡길지 정하는 일,
Agent가 틀리지 않을 환경을 만드는 일,
결과가 맞는지 확인하는 일이 들어온다.

백엔드 개발자가 유리한 이유

이 변화는 백엔드 개발자에게 낯설지 않다.

우리는 이미 위임의 전문가다.

• 신규 입사자에게 온보딩 문서를 준다
• 요구사항을 티켓으로 쪼갠다
• 완료 조건을 정의한다
• CI로 자동 검증한다
• 코드 리뷰로 최종 확인한다

Agent를 다루는 방식은 이것과 거의 같다.

Agent는 마법이 아니다.
어제 합류해서 우리 코드를 아직 모르는,
그러나 대단히 빠르고 지치지 않는 동료에 가깝다.

그 동료가 성과를 내는지는 개인 역량보다
우리가 만들어둔 환경에 달려 있다.

이 환경을 이 책에서는 하네스(Harness) 라고 부른다.
4장과 5장에서 본격적으로 다룬다.

이 장의 핵심

• AI 코딩은 자동완성 → 대화 → Agent로 세 세대를 지나왔다
• 세대를 가르는 기준은 모델 성능이 아니라 다음 행동을 누가 정하느냐다
• 대화형 AI는 답을 주고, Coding Agent는 코드를 읽고 고치고 실행한다
• Vibe Coding은 프로토타입의 방식이고, 운영 백엔드에는 맞지 않는다
• 에이전틱 코딩은 코드를 안 읽는 방식이 아니라 읽을 대상을 바꾸는 방식이다
• 개발자의 시간은 타이핑에서 작업 정의·환경 정비·검증으로 이동한다
• 위임과 검증은 백엔드 개발자가 이미 팀에서 해온 일이다

2장. Agent를 이루는 것들 — Context · Tools · Memory · Environment · Feedback Loop

1장에서 Coding Agent는 다음 행동을 스스로 고른다고 했다.

그런데 LLM은 텍스트를 생성하는 모델이다.

파일을 열 수 없고,
./gradlew test 를 실행할 수 없고,
어제 한 일을 기억하지 못한다.

그런 모델이 어떻게 우리 레포를 고치는가.

LLM과 Agent의 차이

LLM 자체는 함수에 가깝다.

LLM    : 텍스트 → 텍스트
Agent  : 목표 → (관찰 → 판단 → 행동)* → 결과

모델은 상태를 갖지 않는다.
루프도, 손도, 기억도 모델 안에 없다.

모델은 판단만 한다.
나머지는 전부 모델 바깥에 있다.

그 ’바깥’을 이루는 것이 다섯 가지다.

flowchart TB
    E[Environment<br/>레포 · 빌드 · DB · 로그]
    C[Context] --> M((Model))
    T[Tools] --> M
    ME[Memory] --> M
    M -->|도구 호출| E
    E -->|Feedback| C

1️⃣ Context — 지금 보고 있는 것

모델은 매 순간 텍스트 한 덩어리만 본다.

우리 레포 전체가 아니다.
지금까지 읽힌 것뿐이다.

PointRefundService.kt 를 아직 읽지 않았다면
그 클래스는 Agent에게 존재하지 않는다.

여기서 초보자의 오해가 생긴다.

“프로젝트를 다 읽혀두면 똑똑해지겠지”

그렇지 않다.
읽힐 수 있는 양에는 한계가 있고,
쓸데없는 코드가 섞이면 판단이 흐려진다.

3부에서 본격적으로 다룬다.

2️⃣ Tools — 할 수 있는 행동

Agent가 가진 도구 목록이 곧 능력의 범위다.

• 파일 읽기
• 코드 검색
• 파일 수정
• 명령 실행
• Git 조작

도구가 없는 능력은 존재하지 않는다.

테스트를 실행할 도구가 없는 Agent는
“검증했다“고 말할 수 없다.
할 수 있는 것은 추측뿐이다.

7장에서 도구 하나하나를 본다.

3️⃣ Memory — 세션을 넘어 남는 것

대화창을 닫으면 Context는 사라진다.

남는 것은 파일에 쓴 것뿐이다.

• CLAUDE.md 에 적은 규칙
• 테스트 코드
• 커밋 메시지
• 작업 문서

대화 안에만 있는 지식은
없어질 지식이다.

이 원칙은 4부 전체를 관통한다.

4️⃣ Environment — 실제로 손을 대는 세계

Agent가 코드를 고친 다음 무엇을 할 수 있는지는
환경이 결정한다.

환경은 Agent에게 눈이다.

로컬에서 테스트가 아예 돌지 않는 프로젝트라면,
Agent는 눈을 감고 코드를 쓴다.

⚠️ 이 상태에서 Agent에게 자율성을 주면
틀린 방향으로 아주 빠르게 간다.

5️⃣ Feedback Loop — 틀렸다는 사실을 아는 방법

Agent가 스스로 수렴할 수 있는 이유는
반성 능력이 뛰어나서가 아니다.

틀렸다는 신호가 텍스트로 돌아오기 때문이다.

e: PointRefundService.kt:47:9 Type mismatch:
   inferred type is Long? but Long was expected

이 한 줄이 Context에 들어오면
다음 판단이 달라진다.

컴파일 에러, 테스트 실패, 로그, HTTP 응답.
모두 같은 역할을 한다.

24장에서 이 루프를 설계 대상으로 다시 본다.

다섯 요소로 다시 보는 이중 환급 버그

1장의 버그를 이 다섯 가지로 나누어 보자.

하나라도 비어 있으면 결과가 달라진다.

Memory가 없으면 우리 팀의 트랜잭션 규칙을 어기고,
Environment가 없으면 고쳤는지 확인하지 못하고,
Feedback이 없으면 틀린 채로 끝난다.

“스스로 작업한다“는 말의 실제 의미

자율성이라는 말은 종종 과장된다.

Agent의 자율성은 한 가지를 뜻한다.

다음 도구 호출을 스스로 고를 권한

그 이상도, 그 이하도 아니다.

그래서 자율성의 가치는 다섯 요소의 품질에 정비례한다.

읽을 것이 정확하고,
쓸 도구가 갖춰져 있고,
지켜야 할 규칙이 남아 있고,
실행할 환경이 있고,
결과가 신호로 돌아올 때
비로소 위임이 성립한다.

이 다섯 가지를 의도적으로 갖춰주는 일을
4장부터 하네스라고 부른다.

이 장의 핵심

• LLM은 텍스트 함수이고, Agent는 LLM에 루프와 도구를 붙인 구조다
• Agent를 이루는 것은 Context · Tools · Memory · Environment · Feedback Loop다
• Context에 없는 코드는 Agent에게 존재하지 않는다
• 도구 없는 능력은 없다 — 테스트 도구가 없으면 검증은 추측이 된다
• 대화 안에만 있는 지식은 세션이 끝나면 사라진다
• 환경은 Agent의 눈이고, 눈이 없으면 자율성은 위험해진다
• Agent의 자율성은 다음 도구 호출을 고를 권한을 뜻할 뿐이다

3장. Coding Agent는 어떻게 개발하는가 — 탐색 · 계획 · 구현 · 검증의 순환

2장에서 Agent의 구성요소를 봤다.

이제 그것들이 실제로 어떻게 맞물려 돌아가는지
작업 하나를 처음부터 끝까지 따라가 보자.

과제는 1장의 그 버그다.

결제 취소 시 포인트가 두 번 환급된다

사람이 하던 순서와 다르지 않다

Agent의 작업 순서는 우리가 하던 것과 거의 같다.

flowchart TB
    A[요구사항 이해] --> B[코드 탐색]
    B --> C[계획]
    C --> D[구현]
    D --> E[명령 실행]
    E --> F{결과 확인}
    F -->|실패| D
    F -->|성공| G[보고]

다른 점은 속도와 인내심이 아니라
어디서 사람이 끼어드는가 하나다.

1️⃣ 요구사항 이해

Agent가 가장 먼저 하는 일은 문장을 좁히는 것이다.

“두 번 환급된다“는 표현에는 여러 가능성이 있다.

• 취소 API가 두 번 호출된다
• 한 번의 호출에서 적립 이력이 두 건 쌓인다
• 환급 금액이 두 배로 계산된다

좋은 Agent는 여기서 되묻는다.
정보가 부족하면 추측하기보다 확인하는 편이 싸다.

이 되묻기를 유도하는 방법은 10장에서 다룬다.

2️⃣ 코드 탐색

이제 코드를 찾는다.

주의할 점은 Agent가 프로젝트를 통째로 읽지 않는다는 것이다.

> grep -rn "refundPoint" --include=*.kt

  point/PointRefundService.kt:42
  order/OrderCancelFacade.kt:88
  payment/PaymentCancelHandler.kt:61

세 곳이 나왔다.

Agent는 이 중 어디를 읽을지 고른다.
전부 읽으면 Context가 낭비되고 판단이 흐려진다.

탐색은 넓게, 정독은 좁게.

13장에서 이 원칙을 다시 다룬다.

3️⃣ 계획

읽어보니 구조가 이렇다.

OrderCancelFacade.cancel()
  ├─ PaymentCancelHandler.cancel()   → 결제 취소 후 이벤트 발행
  │     └─ PointRefundListener       → 포인트 환급 (1)
  └─ PointRefundService.refund()     → 포인트 환급 (2)

같은 환급이 리스너와 직접 호출로 두 번 일어난다.

Agent는 여기서 계획을 제시한다.

원인: 이벤트 리스너와 Facade의 직접 호출이 중복
수정 방향: Facade의 직접 호출 제거
영향 범위: 주문 취소, 부분 취소, 관리자 강제 취소
검증: 재현 테스트 + 기존 취소 테스트 6건

이 지점이 이 책에서 가장 중요한 순간이다.

🔥 코드를 고치기 전에 사람이 방향을 승인한다.

방향이 틀렸다면 여기서 멈추는 비용이 가장 싸다.
21장에서 이것을 Plan First 라고 부른다.

4️⃣ 구현

승인 후 Agent가 코드를 고친다.

순서가 중요하다.
좋은 Agent는 재현 테스트를 먼저 만든다.

@Test
fun `주문 취소 시 포인트 환급은 한 번만 발생한다`() {
    val order = 주문_생성(point = 1_000)

    orderCancelFacade.cancel(order.id)

    val histories = pointHistoryRepository
        .findAllByOrderId(order.id)
    assertThat(histories).hasSize(1)
}

지금은 이 테스트가 실패해야 정상이다.

실패하는 테스트는 버그의 존재 증명이다.
36장의 Characterization Test와 같은 원리다.

5️⃣ 명령 실행과 결과 확인

Agent가 직접 실행한다.

> ./gradlew test --tests '*OrderCancelTest'

  주문 취소 시 포인트 환급은 한 번만 발생한다  FAILED
    expected size: 1 but was: 2

원인이 확인됐다.
이제 중복 호출을 제거하고 다시 돌린다.

> ./gradlew test --tests '*OrderCancel*'

  BUILD SUCCESSFUL
  7 tests completed

여기까지가 한 바퀴다.

사람이 한 일은 방향 승인과 최종 검토 두 번이고,
나머지 왕복은 Agent가 했다.

6️⃣ 실패 후 재시도 — 그리고 그 위험

현실에서는 한 바퀴로 끝나지 않는다.

부분 취소 테스트가 깨질 수도 있고,
컴파일이 안 될 수도 있다.

Agent는 실패 로그를 읽고 다시 시도한다.
이것이 강력한 이유이자, 가장 위험한 지점이다.

⚠️ 재시도가 이렇게 흐를 때가 있다.

Agent가 나쁜 의도를 가진 것이 아니다.

“테스트를 통과시켜라“라는 목표에
가장 짧은 경로를 고른 것이다.

그래서 목표를 이렇게 주면 안 된다.

❌ 테스트가 통과하게 만들어줘

✅ 이 동작이 한 번만 일어나게 고치고,
기존 테스트를 수정하지 말고 통과시켜줘

지시를 잘 쓰는 문제로 보이지만,
결국 환경으로 막아야 하는 문제다.
42장에서 규칙을 의존성 테스트로 강제한다.

사람이 개입하는 두 지점

한 바퀴 전체에서 사람의 자리는 정해져 있다.

flowchart LR
    A[탐색] --> B[계획]
    B --> C{승인}
    C --> D[구현·검증 루프]
    D --> E{Diff 검토}
    E --> F[커밋]

앞에서 방향을 잡고,
뒤에서 결과를 본다.

중간의 왕복은 맡긴다.
그 왕복까지 사람이 따라가면 위임의 이점이 사라진다.

이 장의 핵심

• Agent의 작업 순서는 사람의 순서와 같다 — 이해 · 탐색 · 계획 · 구현 · 검증
• Agent는 프로젝트를 통째로 읽지 않는다. 탐색은 넓게, 정독은 좁게 한다
• 코드 수정 전 계획 승인이 가장 값싼 개입 지점이다
• 재현 테스트를 먼저 만들면 실패가 버그의 증명이 된다
• 재시도는 강력하지만, 검증을 약화시키는 방향으로 흐를 수 있다
• 목표를 “테스트 통과“로 주면 테스트를 지우는 경로가 열린다
• 사람의 자리는 앞의 방향 승인과 뒤의 Diff 검토, 두 곳이다

4장. 좋은 모델만으로 좋은 Agent가 되지 않는 이유 — 하네스라는 개념

3장에서 한 바퀴가 도는 과정을 봤다.

그 순환은 조건이 갖춰졌을 때의 이야기였다.

읽을 코드가 정리되어 있고,
돌아가는 테스트가 있고,
실패가 로그로 돌아오는 프로젝트.

그렇지 않은 프로젝트에서는 같은 도구가
전혀 다른 결과를 낸다.

같은 모델, 다른 결과

두 프로젝트에 똑같은 작업을 맡겨보자.

프로젝트 A에서 Agent는 이렇게 움직인다.

기존 코드와 다른 스타일로 클래스를 만들고,
이미 있는 유틸리티를 또 만들고,
고쳤다고 보고하지만 검증한 근거를 대지 못한다.

프로젝트 B에서는 3장의 순환이 돈다.

모델은 같다.
프롬프트도 같다.

차이는 모델이 아니라
모델을 둘러싼 환경에서 나왔다.

Model, Agent, Harness

세 단어를 구분해두면 이 책 전체가 쉬워진다.

하네스라는 단어는 말에 씌우는 마구에서 왔다.

마구는 말의 힘을 줄이는 장치가 아니다.
그 힘이 엉뚱한 방향으로 흩어지지 않게 만드는 장치다.

하네스는 Agent를 제약하는 장치가 아니라,
Agent의 힘을 일에 전달하는 장치다.

프롬프트로는 메울 수 없다

여기서 흔한 시도가 실패한다.

프롬프트를 더 정교하게 쓰면 될 것 같다.

반드시 테스트를 실행해서 검증한 뒤 보고해줘.
기존 컨벤션을 따르고, 중복 코드를 만들지 마.

프로젝트 A에서 이 지시는 아무 일도 하지 못한다.

실행할 테스트가 없고,
따를 컨벤션이 문서로도 코드로도 명확하지 않다.

지시는 조건을 만들지 못한다.

프롬프트는 이번 한 번에만 유효하다.
하네스는 모든 작업에 유효하다.

그래서 이 책의 초점은 프롬프트가 아니다.

상한선은 하네스가 정한다

모델 성능과 하네스 품질을 두 축으로 놓아보자.

가장 위험한 칸은 왼쪽 아래가 아니다.

⚠️ 강한 모델 + 나쁜 하네스.

그럴듯한 코드가 빠르게 쏟아지고,
검증할 방법이 없으니 그럴듯함이 곧 승인 근거가 된다.

Vibe Coding이 위험해지는 지점이 정확히 여기다.

반대로 하네스가 좋으면 모델의 실수가 걸러진다.
컴파일이 막고, 테스트가 막고, 의존성 규칙이 막는다.

모델은 성능의 기대값을 올린다.
하네스는 성능의 하한선을 올린다.

운영 시스템에서 중요한 것은 하한선이다.

이미 우리가 만들던 것들이다

하네스 엔지니어링이 새로운 기술처럼 들린다면
이렇게 보면 된다.

우리는 사람을 위해 이미 하네스를 만들어왔다.

• 신규 입사자가 첫날 실행할 수 있는 로컬 환경
• 실수를 막는 CI 파이프라인
• 운영 DB에 직접 붙지 못하게 하는 권한 정책
• 리뷰 없이는 머지되지 않는 브랜치 규칙

Agent에게 필요한 것과 목록이 거의 같다.

차이는 하나다.

사람은 문서에 없는 것을 옆자리에 물어본다.
Agent는 묻지 않고 추측한다.

그래서 사람에게는 관행으로 남겨도 되던 것을
Agent에게는 명시해야 한다.

암묵지를 파일로 꺼내는 일,
그것이 이 책에서 하는 작업의 절반이다.

우리가 고칠 대상은 Agent가 아니다

Agent가 같은 실수를 반복할 때
“이 모델은 별로다“로 끝내면 개선이 멈춘다.

질문을 바꿔야 한다.

읽을 것이 부족했는가        → Context
규칙이 어디에도 없었는가    → Instruction
검증할 수단이 없었는가      → Tests
할 수 있는 행동이 없었는가  → Tools
막아야 할 것을 열어뒀는가   → Permission
작업이 너무 컸는가          → Task 설계

이 목록이 곧 하네스의 부품 목록이다.

다음 장에서 부품 하나하나를 펼쳐본다.
그것이 이 책의 지도가 된다.

이 장의 핵심

• 같은 모델과 같은 프롬프트로도 프로젝트에 따라 결과가 갈린다
• Model은 판단, Agent는 실행체, Harness는 일하는 조건 전체를 뜻한다
• 하네스는 힘을 제약하는 장치가 아니라 방향을 주는 장치다
• 프롬프트는 지시를 전달하지만 조건을 만들지 못한다
• 가장 위험한 조합은 강한 모델과 나쁜 하네스다
• 모델은 기대값을 올리고, 하네스는 하한선을 올린다
• 사람에게 관행으로 남겨둔 암묵지를 Agent에게는 파일로 꺼내야 한다
• Agent가 반복해서 틀리면 고칠 대상은 모델이 아니라 하네스다

5장. Harness의 구성요소 — 아홉 개의 부품

4장에서 하네스가 결과를 만든다고 했다.

그렇다면 하네스는 무엇으로 조립하는가.

이 장은 부품 목록이다.
동시에 이 책의 지도다.

각 부품이 어느 장에서 다뤄지는지 표시해둔다.
지금 다 이해할 필요는 없다.

부품은 세 개의 질문으로 묶인다

아홉 개를 나열하면 외우기 어렵다.

세 가지 질문으로 나누면 구조가 보인다.

flowchart TB
    subgraph Q1["무엇을 아는가"]
        I[Instruction]
        C[Context]
        M[Memory]
    end
    subgraph Q2["무엇을 할 수 있는가"]
        T[Tools]
        S[Skills]
        P[Permission]
        SB[Sandbox]
    end
    subgraph Q3["무엇으로 확인하는가"]
        TS[Tests]
        H[Hooks]
    end
    Q1 --> Q2 --> Q3
    Q3 -->|Feedback| Q1

이 세 층이 한 바퀴 도는 것이 3장에서 본 순환이다.

무엇을 아는가

1️⃣ Instruction

Agent가 항상 알아야 하는 규칙이다.

두 종류가 있다.

• 도구가 기본으로 갖고 있는 시스템 지침
• 우리가 쓰는 프로젝트 지침 — CLAUDE.md

우리가 손댈 수 있는 것은 후자다.

- 모든 금액은 Long, 원 단위로 다룬다
- Service 계층에서 다른 Service를 직접 호출하지 않는다
- 운영 DB에는 절대 접속하지 않는다

14장~16장에서 다룬다.

2️⃣ Context

이번 작업에서만 필요한 정보다.

관련 파일, 검색 결과, 실행 결과, 에러 로그.

Instruction은 항상,
Context는 이번만.

12장~13장에서 다룬다.

3️⃣ Memory

세션이 끝나도 남는 것이다.

docs/architecture.md
tasks/point-refund-fix.md
.claude/rules/

17장~19장에서 다룬다.

무엇을 할 수 있는가

4️⃣ Tools

파일 읽기, 검색, 수정, 명령 실행, Git.

여기에 MCP로 외부 시스템을 연결하면
GitHub 이슈나 모니터링 지표까지 도구가 된다.

7장, 그리고 54장~55장에서 다룬다.

5️⃣ Skills

반복되는 절차를 문서로 고정한 것이다.

“우리 팀에서 API 하나 추가하는 절차“를
매번 설명하지 않기 위한 부품이다.

47장~48장에서 다룬다.

6️⃣ Permission

무엇을 허용하고, 무엇을 물어보게 하고,
무엇을 금지할지 정한다.

57장에서 다룬다.

7️⃣ Sandbox

권한이 정책이라면 샌드박스는 물리적 격리다.

Docker 컨테이너, 별도 DB, 별도 네트워크.

⚠️ 정책은 실수로 넘길 수 있다.
격리는 넘길 수 없다.

57장에서 함께 다룬다.

무엇으로 확인하는가

8️⃣ Tests

Agent가 자기 결과를 확인하는 유일하게 값싼 수단이다.

테스트가 없는 프로젝트에서
Agent의 “수정 완료“는 의견에 불과하다.

23장, 36장에서 다룬다.

9️⃣ Hooks

무조건 실행되어야 하는 것을 자동화한다.

• 파일을 고치면 포매터가 돈다
• 커밋 전에 의존성 규칙 검사가 돈다

지시는 잊힐 수 있지만 훅은 잊히지 않는다.

49장에서 다룬다.

한눈에 보는 지도

12부에서 이 아홉 개를 실제로 조립한다.

지금 아홉 개를 다 만들지 않는다

이 목록을 보고 하네스 구축 프로젝트를 시작하고 싶어진다면
잠깐 멈추는 편이 좋다.

처음부터 다 만든 하네스는 대개 틀린다.

Agent가 실제로 어디서 틀리는지 모르는 상태에서
쓴 규칙은 추측이다.

🔥 최소 구성은 셋이면 충분하다.

1. CLAUDE.md 한 장
   - 빌드·테스트 명령
   - 디렉터리 구조 한 줄 설명
   - 절대 하지 말 것 세 줄

2. 돌아가는 테스트 명령 하나

3. 위험 명령 차단
   - 운영 접속, force push, DB 삭제

8장에서 문서 없는 레포에 이 최소 구성을 붙인다.

나머지 부품은 필요가 생길 때 추가한다.

같은 실수를 두 번 보면 Instruction을 늘리고,
같은 절차를 세 번 설명하면 Skill로 만들고,
지시를 계속 잊으면 Hook으로 내린다.

하네스는 설계되는 것이 아니라 자란다.

이 장의 핵심

• 하네스는 아홉 개의 부품으로 조립된다
• 부품은 아는 것 · 할 수 있는 것 · 확인하는 것 세 층으로 묶인다
• Instruction은 항상 유효하고 Context는 이번 작업에만 유효하다
• Permission은 정책이고 Sandbox는 넘을 수 없는 물리적 격리다
• 테스트가 없으면 Agent의 완료 보고는 의견에 불과하다
• 지시는 잊히고 Hook은 잊히지 않는다
• 처음부터 아홉 개를 다 만들지 않는다 — 규칙 한 장, 테스트 하나, 금지 목록으로 시작한다
• 하네스는 Agent가 틀리는 지점을 보면서 자란다

6장. 설치와 첫 실행 — 터미널에서 시작한다

5장에서 최소 구성 세 가지를 정했다.

규칙 한 장, 테스트 명령 하나, 금지 목록.

그런데 그것을 만들기 전에 먼저 해야 할 일이 있다.

일단 켜보는 것이다.

설치

Node.js 18 이상이 있으면 한 줄이다.

npm install -g @anthropic-ai/claude-code

설치 후 프로젝트 디렉터리에서 실행한다.

cd ~/work/order-service
claude

첫 실행에서 로그인 절차가 진행된다.
브라우저가 열리고, 계정을 인증하면 터미널로 돌아온다.

어디서 실행하는지가 중요하다

이 부분을 가볍게 넘기면 나중에 고생한다.

Claude Code를 실행한 디렉터리가 작업 범위가 된다.

• 그 아래의 파일을 읽고 수정한다
• 그 위치에서 명령을 실행한다
• 그곳의 CLAUDE.md 를 규칙으로 읽는다

⚠️ 홈 디렉터리에서 실행하면 안 된다.

cd ~          # 위험
claude

~/.aws/credentials, ~/.ssh, 다른 프로젝트가
모두 사정권에 들어온다.

항상 하나의 프로젝트 루트에서 시작한다.

기본 조작만 알면 된다

처음부터 모든 기능을 알 필요는 없다.
아래 정도면 첫 주를 보낼 수 있다.

입력 중에 쓰는 두 가지 접두사도 함께 익혀두면 편하다.

• @ — 파일을 직접 지목한다 @src/main/kotlin/order/OrderCancelFacade.kt 이 흐름 설명해줘
• ! — 명령을 직접 실행하고 결과를 대화에 넣는다 !git log --oneline -20

! 는 특히 유용하다.

Agent가 대신 실행하는 것이 아니라
내가 실행한 결과를 Context에 넣어주는 방식이다.

첫날의 명령은 읽기만

처음 켠 날 코드를 고치게 하지 않는다.

읽기만 시켜본다.

이 프로젝트의 디렉터리 구조와 주요 모듈을 설명해줘.
코드는 수정하지 마.

테스트는 어떻게 실행해? 실행 명령만 찾아서 알려줘.

주문 취소 요청이 들어오면 어떤 클래스를 거쳐 처리되는지
호출 순서대로 정리해줘.

이 세 가지 답을 받아보면 두 가지를 동시에 알게 된다.

Claude Code가 무엇을 할 수 있는지,
그리고 우리 프로젝트가 얼마나 설명하기 어려운 상태인지.

두 번째가 더 중요하다.
8장에서 그 상태를 다룬다.

첫날 하지 말 것

⚠️ 다음 세 가지는 첫 주에 하지 않는다.

특히 첫 번째가 사고를 만든다.

작업 전에 git status 가 깨끗해야 한다.
그러면 무엇을 하든 되돌릴 수 있다.

이 원칙은 25장에서 다시 다룬다.

왜 터미널인가

Claude Code는 터미널, 데스크톱 앱, 웹, IDE 확장으로 쓸 수 있다.

이 책은 터미널을 기준으로 설명한다.
이유는 취향이 아니다.

2장에서 Environment를 Agent의 눈이라고 했다.

백엔드 개발자의 그 눈은 이미 터미널에 있다.

flowchart LR
    T[터미널] --> B[Gradle]
    T --> G[Git]
    T --> D[Docker]
    T --> DB[psql · mysql]
    T --> L[로그]

빌드, 테스트, 마이그레이션, 컨테이너, 로그 조회.

우리가 하루에 수십 번 치는 명령이 전부 여기 있다.

그래서 여기에 Agent를 놓으면
별도 연동 없이 검증 수단이 곧바로 갖춰진다.

Agent를 우리 작업 환경으로 데려오는 것이지,
우리가 Agent의 환경으로 가는 것이 아니다.

모델은 일단 기본값으로

/model 로 모델을 바꿀 수 있지만
첫 주에는 기본값을 쓰는 편이 좋다.

무엇이 느리고 무엇이 비싼지 감이 없는 상태에서
모델을 바꾸면 원인 분석이 어려워진다.

작업 유형별로 모델을 배치하는 방법은 11장에서 다룬다.

이 장의 핵심

• 설치는 npm install -g @anthropic-ai/claude-code 한 줄이다
• 실행한 디렉터리가 작업 범위가 된다 — 홈 디렉터리에서 실행하지 않는다
• /init, /clear, /compact, /model, Esc, Shift+Tab 정도면 첫 주는 충분하다
• @ 로 파일을 지목하고, ! 로 내 명령 결과를 Context에 넣는다
• 첫날은 읽기만 시킨다 — 그 답변이 프로젝트 상태를 알려준다
• 작업 전 git status 가 깨끗해야 되돌릴 수 있다
• 터미널을 쓰는 이유는 빌드·테스트·Git·로그가 이미 거기에 있기 때문이다

7장. Claude Code가 쓰는 도구와 권한 — Read · Grep · Edit · Bash

2장에서 이렇게 말했다.

도구가 없는 능력은 존재하지 않는다.

그러니 Claude Code가 실제로 무엇을 할 수 있는지는
도구 목록을 보면 정확히 알 수 있다.

목록은 짧다.

도구는 다섯 종류로 충분히 설명된다

1️⃣ 읽기 — Read

파일 내용을 읽는다.

전체를 읽을 수도 있고 특정 구간만 읽을 수도 있다.
Agent는 보통 필요한 부분만 읽는다.

한 번 읽은 내용은 Context에 남는다.
그래서 큰 파일을 여러 개 읽히면 대가가 있다.

2️⃣ 찾기 — Glob과 Grep

Glob 은 파일 경로 패턴으로 찾는다.

**/*Repository.kt

Grep 은 파일 내용으로 찾는다.

refundPoint

이 두 도구가 3장의 “탐색은 넓게” 를 담당한다.

찾기는 싸고 읽기는 비싸다.
좋은 Agent는 찾은 다음에 읽는다.

3️⃣ 수정 — Edit과 Write

Edit 은 파일의 일부 문자열을 교체한다.
Write 는 파일을 새로 쓰거나 통째로 덮어쓴다.

둘의 차이가 안전성 차이다.

⚠️ Write 는 기존 파일을 덮어쓸 수 있다.
그래서 도구를 다루는 규칙에서 이 차이가 자주 등장한다.

4️⃣ 실행 — Bash

여기가 가장 강력하고 가장 위험하다.

./gradlew test
git diff
docker compose up -d
psql -c "select count(*) from orders"

빌드, 테스트, 마이그레이션, 컨테이너, DB 접속.
전부 이 하나의 도구를 통과한다.

에이전틱 코딩이 성립하는 이유도,
사고가 나는 이유도 같은 도구다.

5️⃣ 위임 — Subagent

Agent가 별도 Context를 가진 Agent를 띄운다.

탐색처럼 읽을 양이 많은 작업을 넘겨두고
결과 요약만 받는다.

50장에서 본격적으로 다룬다.

권한은 세 겹이다

도구가 위험을 만들고, 권한이 그 위험을 통제한다.

flowchart TB
    A[Agent의 도구 호출] --> B{설정 파일 규칙}
    B -->|deny| X[차단]
    B -->|allow| R[즉시 실행]
    B -->|해당 없음| C{세션 중 승인 요청}
    C -->|승인| R
    C -->|거절| X

세션 중 승인

처음에는 대부분 여기서 걸린다.

Bash 명령을 실행하려고 합니다
  ./gradlew test --tests '*OrderCancelTest'

  1. 예
  2. 예, 이후 이 명령은 자동 승인
  3. 아니오

2번을 고르면 그 규칙이 설정에 쌓인다.

첫 주에는 이 프롬프트를 귀찮게 여기지 않는 편이 좋다.
Agent가 실제로 무슨 명령을 만드는지 배우는 시간이다.

설정 파일 규칙

반복되는 판단은 .claude/settings.json 에 적는다.

{
  "permissions": {
    "allow": [
      "Bash(./gradlew test:*)",
      "Bash(./gradlew build)",
      "Bash(git diff:*)",
      "Bash(git status)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(git push --force:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

allow 는 매번 묻지 않게 하는 목록이고,
deny 는 물어보지도 않고 막는 목록이다.

이 파일은 Git에 커밋한다.
팀 전체의 안전선이 되기 때문이다. 63장에서 다룬다.

권한 모드

Shift+Tab 으로 전환한다.

🔥 계획 모드는 이 책에서 가장 자주 쓰게 될 모드다.

읽고 분석하되 손대지 않는다.
8장의 첫날과 21장의 Plan First가 모두 이 모드 위에 있다.

자동 승인은 편하다.
그리고 편한 만큼 위험하다. 57장까지는 쓰지 않는다.

백엔드 개발자의 금지 목록

우리 도메인에서는 이 목록이 특히 구체적이어야 한다.

목록을 외우는 것이 목적이 아니다.

기준은 하나다.

되돌릴 수 없는 일은 사람이 결정한다.

도구가 없으면 무슨 일이 안 되는가

권한을 조일 때 함께 봐야 할 것이 있다.

무엇을 막으면 무엇이 불가능해지는지다.

⚠️ 안전을 이유로 모든 실행을 막으면
4장의 나쁜 하네스가 된다.

Agent는 코드를 쓸 수만 있고 확인할 수는 없게 된다.

그래서 권한 설계의 목표는 최소화가 아니다.

로컬에서는 넓게,
운영으로 갈수록 좁게.

58장에서 이 원칙을 환경별 정책으로 구체화한다.

이 장의 핵심

• 도구는 읽기 · 찾기 · 수정 · 실행 · 위임 다섯 종류로 설명된다
• 찾기는 싸고 읽기는 비싸다 — 좋은 Agent는 찾은 다음에 읽는다
• Bash 하나에 빌드·테스트·DB·컨테이너가 모두 걸려 있다
• 권한은 설정 규칙 · 세션 승인 · 권한 모드의 세 겹으로 작동한다
• 계획 모드는 읽되 수정하지 않는 모드이고, 이 책에서 가장 자주 쓴다
• .claude/settings.json 은 팀의 안전선이므로 Git에 커밋한다
• 되돌릴 수 없는 일은 사람이 결정한다
• 모든 실행을 막으면 Agent는 검증할 수 없게 된다 — 로컬은 넓게, 운영은 좁게

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 이다

9장. 첫 에이전틱 코딩 — 버그 하나를 끝까지

8장에서 CLAUDE.md 와 권한 설정을 커밋했다.

이제 처음으로 코드를 고친다.

3장에서 개념으로 훑은 그 버그를,
이번에는 실제 세션으로 처음부터 끝까지 진행한다.

첫 작업은 고르는 것부터가 실력이다

무엇을 첫 작업으로 삼느냐가 결과의 절반이다.

좋은 첫 작업의 조건은 세 가지다.

반대로 첫 작업으로 최악인 것들이 있다.

⚠️ 성능 개선, 컨벤션 일괄 정리, 원인 불명 간헐적 장애.

셋 다 “고쳐졌다” 를 판정할 기준이 없다.

우리 과제는 조건에 맞는다.

결제 취소 시 포인트가 두 번 환급된다

1️⃣ 계획 모드로 시작한다

Shift+Tab 으로 계획 모드에 들어간 뒤 작업을 준다.

결제 취소 시 포인트가 두 번 환급되는 버그가 있다.

관련 코드를 찾아서 원인을 설명하고, 수정 계획을 제시해줘.
아직 코드는 수정하지 마.

- 영향받는 취소 경로를 전부 확인해줘 (전체 취소, 부분 취소, 관리자 강제 취소)
- 기존 테스트를 수정하는 방향은 제외해줘

두 번째 제약이 3장에서 본 위험한 재시도를 미리 막는다.

2️⃣ Agent가 찾아온 것을 검토한다

> grep -rn "refundPoint" --include=*.kt

  point/PointRefundService.kt:42
  order/OrderCancelFacade.kt:88
  payment/PaymentCancelHandler.kt:61

이어서 호출 흐름 정리가 돌아온다.

OrderCancelFacade.cancel()
  ├─ PaymentCancelHandler.cancel()
  │     → PaymentCancelledEvent 발행
  │        └─ PointRefundListener.handle()  → 환급 (1)
  └─ PointRefundService.refund()            → 환급 (2)

원인: 이벤트 리스너와 Facade의 직접 호출이 중복

여기서 개발자가 할 일은 승인이 아니다.

의심이다.

PointRefundListener는 언제 추가됐어? git log로 확인해줘.

> git log --oneline -- src/main/kotlin/point/PointRefundListener.kt

  a3f9c21 feat: 결제 취소 이벤트 기반 포인트 환급 (3개월 전)

이 한 줄이 판단을 바꾼다.

세 달 전에 이벤트 방식이 추가되면서
Facade의 기존 직접 호출을 지우지 않은 것이다.

그러면 지울 쪽은 오래된 직접 호출이다.

🔥 이 확인을 건너뛰면 반대쪽을 지울 수도 있었다.

Agent는 코드만 보고, 사람은 이력을 본다.

3️⃣ 계획을 승인한다

수정 방향: OrderCancelFacade의 PointRefundService.refund() 직접 호출 제거
영향 범위: 전체 취소, 부분 취소, 관리자 강제 취소
검증: 재현 테스트 신규 1건 + 기존 취소 테스트 6건

동의하면 계획 모드를 벗어난다.

이 지점이 21장 Plan First의 실제 모습이다.

4️⃣ 재현 테스트를 먼저 만든다

먼저 이 버그를 재현하는 테스트를 추가해줘.
지금은 실패해야 정상이야.

@Test
fun `주문 취소 시 포인트 환급은 한 번만 발생한다`() {
    val order = 주문_생성(usedPoint = 1_000)

    orderCancelFacade.cancel(order.id)

    val histories = pointHistoryRepository
        .findAllByOrderId(order.id)
    assertThat(histories).hasSize(1)
}

> ./gradlew test --tests '*OrderCancelTest'

  주문 취소 시 포인트 환급은 한 번만 발생한다  FAILED
    expected size: 1 but was: 2

실패를 확인하는 이 단계를 생략하지 않는다.

실패하지 않는 재현 테스트는 아무것도 증명하지 않는다.

5️⃣ 수정하고 다시 돌린다

> ./gradlew test --tests '*OrderCancel*'

  BUILD SUCCESSFUL
  7 tests completed

여기서 끝내고 싶어진다.

아직 아니다.

6️⃣ Diff는 반드시 읽는다

git diff

이 단계가 에이전틱 코딩에서 가장 자주 생략되고,
가장 자주 후회하는 단계다.

세 가지를 확인한다.

세 번째는 사소해 보이지만
Diff 200줄 중 190줄이 포맷 변경이면 리뷰는 사실상 불가능해진다.

발견하면 되돌린다.

포맷 변경은 되돌리고 로직 수정만 남겨줘.

7️⃣ 커밋은 작게

git add -p
git commit -m "fix: 주문 취소 시 포인트 이중 환급 수정

이벤트 기반 환급(a3f9c21) 도입 시 제거되지 않은
Facade의 직접 호출을 제거.
재현 테스트 추가."

커밋 메시지에 원인 커밋을 남겨두면
다음 사람이 이 판단을 다시 하지 않는다.

19장에서 말하는 외부화의 가장 값싼 형태다.

잘못됐을 때 되돌리는 법

세 가지 층이 있다.

작업 전 git status 가 깨끗했다면
세 방법 모두 즉시 통한다.

그래서 6장에서 그 조건을 강조했다.

세션을 멈춰야 하는 신호

첫 작업에서 이런 상황이 오면 이어가지 않는다.

⚠️ 같은 수정을 두 번째로 반복한다
⚠️ 테스트를 통과시키려 검증을 약화시킨다
⚠️ 설명이 처음 설명과 달라진다

세 신호 모두 같은 뜻이다.

Context가 오염됐다.

/clear 로 새 Session을 시작하고,
방금 알아낸 사실만 정리해서 다시 넘긴다.

18장에서 이 판단 기준을 다룬다.

이 장의 핵심

• 첫 작업은 재현 가능하고, 범위가 좁고, 되돌리기 쉬운 것으로 고른다
• 성능 개선과 컨벤션 정리는 첫 작업으로 최악이다 — 판정 기준이 없다
• 계획 모드에서 시작해 원인과 계획을 먼저 받는다
• Agent는 코드를 보고, 사람은 git log 를 본다 — 이력이 판단을 바꾼다
• 실패하지 않는 재현 테스트는 아무것도 증명하지 않는다
• Diff를 읽지 않고 커밋하는 것은 에이전틱 코딩이 아니다
• 커밋 메시지에 원인 커밋을 남기면 판단이 재사용된다
• 같은 수정 반복 · 검증 약화 · 설명 변경은 Session을 끊으라는 신호다

10장. 질문이 아니라 작업을 주는 법 — 목표 · 제약 · 완료 조건

9장에서 버그 하나를 끝까지 처리했다.

돌아보면 그 세션의 품질은
Agent의 능력보다 처음 준 문장에서 결정됐다.

이 장은 그 문장을 쓰는 방법이다.

질문과 작업은 다른 것이다

두 문장을 비교해보자.

이 코드에 동시성 문제가 있을까?

이 코드의 동시성 문제를 찾아서, 재현 테스트를 만들고 수정해줘.

첫 번째는 질문이다.
답변이 돌아온다.

두 번째는 작업이다.
파일이 바뀐다.

둘 다 필요하다.
문제는 섞어 쓰는 것이다.

질문을 주면서 수정을 기대하거나,
작업을 주면서 완료 조건을 안 주는 경우다.

질문에는 답변이,
작업에는 완료 조건이 필요하다.

나쁜 지시와 좋은 지시

세 쌍을 보면 패턴이 보인다.

1️⃣ 목표가 없는 지시

❌ 주문 조회 API 좀 개선해줘

무엇이 개선인지 정의되지 않았다.
Agent는 자기 기준으로 리팩터링을 시작한다.

✅ 주문 목록 API가 200ms를 넘는다.
N+1을 찾아 제거하고, 응답 스펙은 그대로 유지해줘.

2️⃣ 제약이 없는 지시

❌ 결제 실패 시 재시도 로직 추가해줘

라이브러리를 새로 추가할지, 스레드를 쓸지,
멱등성을 어떻게 처리할지 전부 Agent가 정한다.

✅ 결제 실패 시 재시도를 추가해줘.
이미 쓰고 있는 Spring Retry를 사용하고,
라이브러리는 추가하지 마.
재시도 중 중복 결제가 발생하지 않아야 해.

3️⃣ 완료 조건이 없는 지시

❌ 이 테스트 통과하게 해줘

3장에서 본 그 함정이다.
가장 짧은 경로는 테스트를 지우는 것이다.

✅ 이 테스트가 검증하는 동작을 실제로 고쳐줘.
테스트 코드는 수정하지 말고,
기존 테스트 전체가 통과하는 상태로 끝내줘.

작업 지시의 네 요소

앞의 좋은 예시들은 모두 같은 구조를 가진다.

flowchart TB
    G[목표<br/>무엇이 달라지는가] --> C[제약<br/>지켜야 할 것]
    C --> D[완료 조건<br/>어떻게 확인하는가]
    D --> N[금지<br/>하지 말 것]

1️⃣ 목표 — 무엇이 달라지는가

현재 상태와 원하는 상태를 함께 쓴다.

현재: 주문 취소 시 포인트가 2건 적립된다
목표: 1건만 적립된다

2️⃣ 제약 — 지켜야 할 것

우리 프로젝트에만 있는 사정이다.

- 응답 스펙 변경 불가 (앱 클라이언트 배포 주기 때문)
- 새 라이브러리 추가 금지
- v1 패키지 수정 금지

CLAUDE.md 에 적을 것과 여기 적을 것의 차이는 하나다.

항상 유효하면 CLAUDE.md,
이번만 유효하면 작업 지시.

5장의 Instruction과 Context의 차이가 그대로 적용된다.

3️⃣ 완료 조건 — 어떻게 확인하는가

가장 자주 빠지고, 가장 큰 차이를 만든다.

검증 가능한 문장으로 쓴다.

기준은 하나다.

Agent가 스스로 실행해서 판정할 수 있는가.

이것이 24장 Feedback Loop의 입력이 된다.

4️⃣ 금지 — 하지 말 것

Agent가 목표를 향해 갈 때 열릴 수 있는
지름길을 미리 막는다.

- 테스트 코드를 수정하지 마
- @Disabled 를 추가하지 마
- 예외를 잡아서 무시하지 마

세 줄 모두 3장에서 본 위험한 재시도 경로다.

템플릿

매번 네 요소를 떠올리기 어려우면
이 틀을 그대로 쓴다.

## 목표
(현재 상태 → 원하는 상태)

## 제약
-
-

## 완료 조건
- 테스트:
- 검증 명령:

## 하지 말 것
-

이 틀이 익숙해지면
20장에서 요구사항을 Task로 바꾸는 작업이 쉬워진다.

반복되면 47장에서 Skill로 만든다.

구현 방법까지 지정해야 할 때

모든 작업에 네 요소를 다 쓸 필요는 없다.
어디까지 지정할지 판단 기준이 필요하다.

⚠️ 방법을 과하게 지정하면 두 가지를 잃는다.

Agent가 더 나은 방법을 찾을 기회,
그리고 우리가 그것을 배울 기회.

반대로 되돌릴 수 없는 결정을 맡기면
나중에 사람이 수습한다.

판단이 필요한 곳에는 방법을 주고,
탐색이 필요한 곳에는 목표만 준다.

되묻게 만드는 것도 설계다

정보가 부족할 때 추측하는 것보다
되묻는 편이 훨씬 싸다.

지시 끝에 한 줄을 붙여둔다.

정보가 부족하면 추측하지 말고 먼저 물어봐.

CLAUDE.md 에 넣어두면 매번 쓰지 않아도 된다.

특히 레거시에서 효과가 크다.
추측할 여지가 많은 코드베이스이기 때문이다.

이 장의 핵심

• 질문에는 답변이 돌아오고, 작업에는 파일이 바뀐다 — 섞어 쓰지 않는다
• 작업 지시는 목표 · 제약 · 완료 조건 · 금지 네 요소로 구성된다
• 목표는 현재 상태와 원하는 상태를 함께 쓴다
• 항상 유효한 제약은 CLAUDE.md 로, 이번만 유효한 제약은 작업 지시로
• 완료 조건의 기준은 Agent가 스스로 실행해 판정할 수 있는지다
• 금지 항목은 목표로 가는 위험한 지름길을 미리 막는다
• 되돌릴 수 없는 결정에는 방법을 주고, 탐색에는 목표만 준다
• “정보가 부족하면 먼저 물어봐” 한 줄이 추측을 줄인다

11장. 모델 선택과 비용 감각 — 어디에 Opus를 쓸 것인가

10장까지 왔으면 이제 매일 쓸 수 있다.

그러면 곧 다음 질문이 온다.

이거 얼마나 나오는 거야?

팀에 도입할 때 반드시 답해야 하는 질문이고,
개인의 작업 습관도 여기서 갈린다.

두 가지 지불 방식

Claude Code는 두 경로로 쓸 수 있다.

구독제를 쓰면 단가를 계산할 일이 없다.
그래도 이 장을 읽을 이유가 있다.

한도에 걸리는 속도와 작업 습관이 정확히 비례하기 때문이다.

이하의 단가는 종량제 기준으로 감각을 잡기 위한 것이다.

모델 티어

2026년 8월 기준, 100만 토큰당 단가다.

⚠️ 단가와 모델 구성은 바뀐다.
숫자 자체보다 비율을 기억하는 편이 유용하다.

세 가지 비율이 판단의 근거가 된다.

• 출력이 입력보다 5배 비싸다
• Opus는 Haiku보다 5배 비싸다
• Opus와 Sonnet의 차이는 1.7배 정도다

마지막 비율이 의외로 중요하다.

Opus와 Sonnet은 흔히 생각하는 만큼 차이 나지 않는다.
같은 작업을 Opus가 절반의 시도로 끝낸다면 오히려 싸다.

티어별 성격

핵심은 난이도가 아니라 작업의 길이다.

한 번에 끝나는 일은 어느 모델이든 비슷하다.
여러 번 왕복하는 일에서 차이가 벌어진다.

짧은 작업은 싼 모델로,
긴 작업은 좋은 모델로.

긴 작업에서 약한 모델을 쓰면
왕복 횟수가 늘어 결국 더 비싸진다.

토큰은 어디로 사라지는가

세션 하나에서 토큰이 쓰이는 곳은 대략 이렇다.

flowchart TB
    A[대화 전체 재전송] --> M((모델))
    B[읽은 파일 내용] --> M
    C[명령·테스트 출력] --> M
    D[CLAUDE.md] --> M
    M --> E[생성한 코드·설명]

여기서 놓치기 쉬운 사실이 하나 있다.

🔥 매 턴마다 대화 전체가 다시 입력된다.

API는 상태를 갖지 않는다.
그래서 30번째 턴은 29턴 분량을 다시 실어 보낸다.

세션이 길어지면 턴당 비용이 계속 오른다는 뜻이다.

가장 비싼 낭비 세 가지는 이렇다.

프롬프트 캐싱이 계산을 바꾼다

다행히 재전송분에는 캐싱이 작동한다.

동일한 앞부분이 반복되면 캐시에서 읽는다.

읽기가 10분의 1이다.

이 수치가 실무에서 뜻하는 것은 하나다.

같은 맥락으로 이어지는 작업은
세션을 유지하는 편이 싸다.

반대로 /clear 를 습관적으로 누르면
매번 캐시를 새로 쓴다.

여기서 판단 기준이 생긴다.

⚠️ 마지막 줄이 중요하다.

캐시를 아끼려고 오염된 Context를 끌고 가면
틀린 작업을 저렴하게 반복하는 셈이다.

18장에서 이 판단을 자세히 다룬다.

작업별 모델 배치

실무에서 쓸 만한 배치는 이렇다.

/model 로 세션 중에도 바꿀 수 있다.

⚠️ 다만 모델을 바꾸면 캐시는 무효화된다.
모델은 세션 단위로 정하는 편이 낫다.

실전 절약 다섯 가지

1. 파일을 지목해서 읽힌다 @ 로 경로를 주면 탐색 왕복이 줄어든다
2. 명령 출력을 줄인다 테스트는 --tests 로 좁히고, 로그는 tail -n 으로 자른다
3. 탐색은 Subagent에 맡긴다 읽은 양은 그쪽 Context에 남고 요약만 돌아온다 (50장)
4. CLAUDE.md 를 짧게 유지한다 매 요청에 실려 간다
5. 작업이 끝나면 세션을 닫는다 길어진 세션의 다음 턴은 계속 비싸진다

여기에 하나 더.

/fast 로 켜는 빠른 모드는 출력 속도를 올려주지만
프리미엄 단가가 붙는다.

사람이 기다리는 대화형 작업에는 값을 하고,
백그라운드 작업에는 낭비다.

비용 최적화가 품질을 깎는 지점

절약이 손해로 바뀌는 선이 있다.

⚠️ 이 세 가지는 하지 않는다.

토큰보다 비싼 것은 사람의 시간이고,
사람의 시간보다 비싼 것은 잘못 배포된 코드다.

비용 감각의 목적은 절약이 아니다.
같은 예산으로 더 어려운 문제를 푸는 것이다.

이 장의 핵심

• 구독제와 API 종량제 두 경로가 있고, 어느 쪽이든 작업 습관이 사용량을 결정한다
• 출력은 입력보다 5배 비싸고, Opus와 Sonnet의 차이는 1.7배 정도다
• 모델 선택 기준은 난이도보다 작업의 길이다 — 긴 작업일수록 좋은 모델이 싸다
• 매 턴마다 대화 전체가 다시 입력된다 — 긴 세션은 턴당 비용이 계속 오른다
• 캐시 읽기는 약 10분의 1이므로 같은 맥락의 작업은 세션을 유지하는 편이 싸다
• 오염된 Context를 비용 때문에 끌고 가면 틀린 작업을 저렴하게 반복한다
• 조사는 싼 모델, 판단과 Review는 좋은 모델에 배치한다
• 검증 생략·계획 생략은 절약이 아니라 손실이다

12장. Context가 Agent의 성능을 결정한다 — Window의 한계와 Context Rot

11장에서 토큰이 어디로 사라지는지 봤다.

그런데 Context는 비용 문제만이 아니다.

같은 Agent가 같은 작업을 하면서도
읽힌 것에 따라 전혀 다른 판단을 한다.

이 장은 그 이유를 다룬다.

Context Window는 넉넉하다

현재 모델의 Context Window는 100만 토큰 규모다.

우리 모놀리스 소스가 대략 30만 줄이라면
이론상 상당 부분이 들어간다.

그러면 이렇게 하면 되지 않을까.

프로젝트 전체를 읽고 시작해줘.

이 요청은 대개 결과를 나쁘게 만든다.

Window가 부족해서가 아니다.

Context는 넣을 수 있는 양이 아니라
판단에 쓰이는 재료다.

재료가 많아지면 요리가 좋아지는 것이 아니다.

다 읽히면 나빠지는 세 가지 이유

1️⃣ Context Pollution — 관련 없는 정보가 섞인다

Agent는 Context에 있는 것을 모두 유효한 정보로 취급한다.

order/v1/OrderCancelService.kt      (2년 전, 사용 중단)
order/v2/OrderCancelFacade.kt       (현재)

두 파일이 함께 읽히면
Agent는 둘 중 어느 쪽이 현재인지 모른다.

그리고 v1 의 패턴을 그대로 따라 코드를 쓴다.

레거시에서 이 문제가 특히 심각하다.
죽은 코드와 산 코드가 같은 레포에 있기 때문이다.

2️⃣ Context Rot — 앞의 정보가 삭는다

긴 세션에서 벌어지는 현상이다.

초반에 확인한 사실이 뒤로 밀리면서
후반의 추측에 덮인다.

턴 3   "이 API는 인증이 필요 없다" (실제 코드 확인)
턴 40  "인증 처리를 추가하겠습니다"  ← 앞의 확인이 흐려짐

정보가 사라진 것은 아니다.
하지만 무게가 달라진다.

⚠️ 그리고 더 흔한 형태가 있다.

한번 잘못 세운 가정이 세션 끝까지 살아남는 것이다.

Agent는 자기가 앞에서 한 말을 근거로 삼는다.
틀린 근거도 마찬가지다.

3️⃣ 비용과 지연

11장에서 본 그대로다.

읽힌 것은 세션이 끝날 때까지 매 턴 재전송된다.
불필요한 파일 하나가 끝까지 따라온다.

백엔드 개발자의 Context 함정

우리 작업에는 특유의 오염원이 있다.

각각은 무해해 보인다.

문제는 한 세션에서 이것들이 겹칠 때다.

> ./gradlew test
  (2,400줄)

> docker logs order-service --tail 500
  (500줄)

> psql -c "\d+ orders"
  (컬럼 60개)

세 명령으로 Context의 상당 부분이 채워진다.
그리고 정작 고칠 코드는 아직 읽지 않았다.

압축은 무손실이 아니다

세션이 길어지면 자동 또는 수동으로 압축이 일어난다.

/compact

대화를 요약해 이어가는 기능이다.
유용하고, 동시에 손실이 있다.

flowchart LR
    A[턴 1~40<br/>상세 내용] --> C[요약]
    C --> B[턴 41~<br/>요약 + 새 내용]

요약에서 살아남는 것은 결론이고,
사라지는 것은 세부사항이다.

🔥 그래서 압축 전에 중요한 사실은 파일로 꺼내야 한다.

지금까지 확인한 사실을 tasks/point-refund.md 에 정리해줘.
그 다음 /compact 하자.

19장에서 이것을 Session 인계라고 부른다.

Context는 예산이다

이 장의 결론은 한 줄이다.

읽힐 수 있는 양이 아니라,
쓰기로 결정한 양이 Context다.

예산처럼 다루면 판단이 쉬워진다.

오른쪽 열이 전부 “혹시 필요할까 봐” 넣는 것들이다.

혹시 필요하면 그때 읽히면 된다.
Agent는 필요할 때 다시 찾을 수 있다.

그래서 무엇을 해야 하는가

원칙은 셋이다.

1. 탐색은 넓게, 정독은 좁게 (13장)
2. 항상 필요한 규칙은 Context가 아니라 Instruction으로 (14장)
3. 세션이 길어지면 사실을 파일로 꺼낸다 (19장)

다음 장에서 첫 번째를 구체적인 작업 방식으로 만든다.

이 장의 핵심

• Context Window가 커도 전체를 읽히는 것은 나쁜 선택이다
• Agent는 Context에 있는 모든 것을 유효한 정보로 취급한다
• 죽은 코드와 산 코드가 함께 읽히면 죽은 쪽의 패턴을 따라 쓴다
• 긴 세션에서는 초반에 확인한 사실이 후반의 추측에 덮인다
• 한번 세운 잘못된 가정은 세션 끝까지 근거로 재사용된다
• 테스트 출력·로그·스키마 덤프가 백엔드 작업의 주된 오염원이다
• 압축은 결론을 남기고 세부사항을 버린다 — 압축 전에 파일로 꺼낸다
• Context는 넣을 수 있는 양이 아니라 쓰기로 결정한 예산이다

13장. 필요한 Context만 주기 — 검색 → 선택 → 정밀 분석

12장의 결론은 Context가 예산이라는 것이었다.

그러면 그 예산을 어떻게 쓰는가.

3장에서 한 줄로 지나간 원칙이 여기서 작업 방식이 된다.

탐색은 넓게, 정독은 좁게.

세 단계로 나눈다

flowchart LR
    A[검색<br/>싸다] --> B[선택<br/>사람이 개입]
    B --> C[정밀 분석<br/>비싸다]

각 단계의 비용이 다르다는 것이 핵심이다.

검색은 거의 공짜고 정독은 비싸다.
그래서 순서를 지키는 것 자체가 절약이다.

1️⃣ 검색 — 후보를 찾는다

포인트 환급과 관련된 코드를 찾아줘.
파일을 읽지는 말고 경로와 매칭된 라인만 보여줘.

두 번째 문장이 이 단계를 지킨다.

> grep -rn "refundPoint\|PointRefund" --include=*.kt

  point/PointRefundService.kt:42
  point/PointRefundListener.kt:18
  order/OrderCancelFacade.kt:88
  payment/PaymentCancelHandler.kt:61
  admin/AdminOrderService.kt:203

다섯 곳이 나왔다.
여기까지 들어온 Context는 다섯 줄이다.

2️⃣ 선택 — 여기서 사람이 개입한다

가장 값싸고 효과가 큰 개입 지점이다.

admin/AdminOrderService.kt 는 이번 작업 범위가 아니야.
나머지 네 곳의 호출 관계만 파악해줘.

한 줄로 20%를 걷어냈다.

이 판단은 사람이 훨씬 잘한다.
우리는 프로젝트의 맥락을 알고 있다.

⚠️ 반대로 이 단계를 생략하면
Agent는 다섯 파일을 전부 읽는다.

“혹시 관련 있을까 봐” 는 Agent의 기본값이다.

3️⃣ 정밀 분석 — 좁게 읽힌다

이제 읽힌다.

@order/OrderCancelFacade.kt 의 cancel 메서드와
@point/PointRefundListener.kt 를 읽고
환급이 몇 번 일어나는지 확인해줘.

@ 로 지목하면 탐색 왕복이 사라진다.

파일이 크면 범위를 좁힌다.

OrderCancelFacade 전체는 800줄이야.
cancel 관련 메서드만 읽어줘.

나쁜 요청과 좋은 요청

같은 목적, 다른 Context 비용.

❌ 나쁜 요청

주문 도메인 전체를 파악하고 포인트 이중 환급 버그를 찾아줘.

Agent는 order 패키지를 훑기 시작한다.
파일 40개가 Context에 들어온다.

✅ 좋은 요청

포인트 환급 호출 지점을 grep으로 찾아줘. (읽지는 말고)
그중 주문 취소 경로에 해당하는 것만 골라서 읽어줘.

같은 답에 도달하지만 Context 사용량이 한 자릿수 배 차이 난다.

명령 출력을 잘라내는 습관

백엔드 작업에서 가장 큰 오염원은 코드가 아니라 출력이다.

12장에서 본 세 가지를 이렇게 줄인다.

Agent에게 이 습관을 넘기는 방법도 있다.

CLAUDE.md 에 한 줄 적어두는 것이다.

- 테스트는 항상 `--tests` 로 범위를 좁혀 실행한다
- 로그는 `--tail` 로 최근 50줄만 확인한다

14장에서 이런 규칙을 모아 쓴다.

큰 파일을 다루는 방법

레거시에는 1,000줄짜리 Service가 있다.

세 가지 방법이 있다.

1️⃣ 구간을 지정한다

OrderService.kt 의 400~520줄만 읽어줘.

2️⃣ 구조만 먼저 본다

OrderService.kt 의 public 메서드 목록과 각각의 역할을
한 줄씩 정리해줘. 본문은 읽지 마.

3️⃣ 호출 흐름으로 접근한다

cancel() 에서 시작해서 실제로 실행되는 메서드만 따라가줘.

세 번째가 가장 효율적이다.
파일 단위가 아니라 실행 경로 단위로 읽는다.

탐색을 Subagent에 넘긴다

읽을 양이 많을 때 쓰는 방법이다.

Subagent로 이 모놀리스의 주문 관련 모듈 구조를 조사하고
요약만 가져와줘.

효과가 두 가지다.

flowchart TB
    M[Main Agent<br/>요약만 보유] -->|위임| S[Subagent<br/>파일 40개 읽음]
    S -->|요약 15줄| M

• Main Agent의 Context가 깨끗하게 유지된다
• 조사에 쓴 토큰이 이후 턴에 재전송되지 않는다

두 번째가 특히 크다.
Subagent의 Context는 그 작업이 끝나면 사라진다.

50장에서 자세히 다룬다.

세션을 용도로 나눈다

Context 관리의 가장 단순한 방법이 남아 있다.

세션 하나에 한 가지 목적만 담는 것이다.

조사 세션의 산출물이 문서라면
구현 세션은 파일 40개가 아니라 문서 한 장으로 시작할 수 있다.

19장의 Session 인계가 이 방식이고,
66장의 12주짜리 작업이 이렇게 진행된다.

이 장의 핵심

• 검색은 거의 공짜고 정독은 비싸다 — 순서를 지키는 것이 절약이다
• 검색 단계에서는 “읽지는 말고” 를 명시한다
• 후보를 걷어내는 선택 단계가 가장 값싼 개입 지점이다
• “혹시 관련 있을까 봐 전부 읽기” 는 Agent의 기본값이다
• @ 로 파일을 지목하면 탐색 왕복이 사라진다
• 테스트·로그·스키마 출력은 범위를 좁혀 실행한다
• 큰 파일은 파일 단위가 아니라 실행 경로 단위로 읽힌다
• 탐색을 Subagent에 넘기면 그 토큰이 이후 턴에 재전송되지 않는다
• 세션 하나에 한 가지 목적만 담는다

14장. CLAUDE.md란 무엇인가 — Agent가 항상 알아야 하는 것

12장과 13장은 이번 작업에 필요한 것을 다뤘다.

이제 반대쪽이다.

작업이 무엇이든 항상 알아야 하는 것.
그것이 CLAUDE.md 다.

매 요청에 함께 실려 가는 문서

CLAUDE.md 의 성격은 위치가 아니라 이 사실에서 나온다.

flowchart LR
    C[CLAUDE.md] --> R[모든 요청]
    F[읽은 파일] -->|이번 세션만| R

Context는 세션이 끝나면 사라진다.
CLAUDE.md 는 다음 세션에도 실려 간다.

여기서 두 가지가 따라온다.

• 매번 설명하기 지친 것은 여기에 적는다
• 여기 적은 것은 매번 비용을 낸다

두 번째 때문에 15장이 필요해진다.

어디에 두는가

프로젝트 루트에 두는 것이 기본이다.

order-service/
  CLAUDE.md              ← 프로젝트 전체 규칙
  .claude/
    settings.json        ← 권한 (7장)
  src/

이 파일은 Git에 커밋한다.
팀 공용 문서다.

개인적인 취향은 여기 적지 않는다.
그것은 개인 설정으로 분리한다.

하위 디렉터리에도 둘 수 있다.
16장에서 계층화를 다룬다.

무엇을 적는가

여섯 종류다.

1️⃣ 실행 명령

Agent가 가장 자주 필요하고, 추측하면 가장 자주 틀린다.

## 개발 명령

- 빌드: `./gradlew build`
- 전체 테스트: `./gradlew test` (약 4분)
- 단일 테스트: `./gradlew test --tests '*OrderCancelTest'`
- 린트: `./gradlew ktlintCheck`
- 로컬 실행: `docker compose up -d` 후 `./gradlew bootRun`

소요 시간을 적어두면 Agent의 선택이 달라진다.
4분짜리 전체 테스트를 무턱대고 돌리지 않는다.

2️⃣ 구조

전체 트리가 아니라 어디에 무엇이 있는지다.

## 구조

- `order/` 주문 도메인 (현재 개발 중심)
- `payment/` 결제. 외부 PG 연동 포함
- `point/` 포인트 적립·환급
- `common/` 공통 유틸. 새 코드 추가 전 여기 먼저 확인
- `legacy/` 사용 중단. 읽기 전용

마지막 두 줄이 실제 가치다.

12장의 Context Pollution을 문서로 막는 것이다.

3️⃣ 아키텍처 규칙

호출 방향과 계층 경계를 적는다.

## Architecture

Controller → Facade → Service → Repository

- Service가 다른 도메인의 Service를 직접 호출하지 않는다
  도메인 간 조합은 Facade에서 한다
- Repository는 자기 도메인의 테이블만 접근한다
- 도메인 간 조회는 필요하면 Facade에서 각각 호출해 조합한다

🔥 이 규칙이 8부의 경계 작업 전체의 출발점이 된다.

지금 문장으로 적어둔 것을
42장에서 의존성 테스트로 강제하게 된다.

4️⃣ 코딩 컨벤션

Agent가 코드에서 유추할 수 없는 것만 적는다.

## Convention

- 금액은 `Long`, 원 단위. `BigDecimal`을 쓰지 않는다
- 시간은 `Instant`. `LocalDateTime`은 새로 쓰지 않는다
- 신규 코드는 `order/v2` 구조를 따른다 (`v1`은 마이그레이션 대상)
- 테스트 이름은 한글 백틱 (`fun \`주문 취소 시 ...\`()`)

8장에서 본 그 판단이다.

레거시에는 두 세대의 컨벤션이 함께 있고,
어느 쪽이 현재인지는 사람만 안다.

5️⃣ 도메인 용어

백엔드 프로젝트에는 반드시 있다.

## 도메인 용어

- 취소(cancel): 결제 완료 후 되돌리는 것
- 철회(withdraw): 결제 완료 전 주문을 없애는 것
- 부분 취소: 주문의 일부 상품만 취소. 포인트는 비례 배분
- 포인트 환급: 사용한 포인트를 되돌려주는 것 (적립과 구분)

이 네 줄이 없으면 Agent는
cancel 과 withdraw 를 섞어 쓴다.

우리 팀도 신규 입사자에게 이걸 설명한다.
같은 문서를 쓰는 것이다.

6️⃣ 금지사항

8장에서 손으로 썼던 그 목록이다.

## 절대 하지 말 것

- 운영·스테이징 DB에 접속하지 않는다
- 마이그레이션을 실행하지 않는다 (작성까지만)
- `legacy/` 의 동작을 변경하지 않는다
- 외부 PG·알림 API를 실제로 호출하지 않는다
- 테스트를 삭제하거나 `@Disabled` 를 추가하지 않는다

마지막 줄은 3장에서 본 위험한 재시도를 막는다.

여기에 적지 않는 것

경계가 흐려지기 쉬운 부분이다.

⚠️ 세 번째와 네 번째를 여기 적으면
CLAUDE.md 가 절차서가 되어 길어진다.

기준은 5장에서 정한 그대로다.

항상 알아야 하는 것 → CLAUDE.md
필요할 때 수행하는 절차 → Skill
무조건 실행되어야 하는 것 → Hook

지금 만들 수 있는 한 장

앞의 여섯 절을 합치면 이 정도가 된다.

# order-service

Kotlin + Spring Boot 모놀리스. 주문·결제·포인트.

## 개발 명령
## 구조
## Architecture
## Convention
## 도메인 용어
## 절대 하지 말 것

한 화면에서 두 화면 사이.

이것이 목표 분량이다.
이유는 다음 장에서 다룬다.

이 장의 핵심

• CLAUDE.md 는 모든 요청에 함께 실려 가는 유일한 문서다
• Context는 세션과 함께 사라지고, 이 문서는 남는다
• 팀 공용 문서이므로 Git에 커밋한다
• 적을 것은 실행 명령 · 구조 · 아키텍처 · 컨벤션 · 도메인 용어 · 금지사항 여섯 가지다
• 테스트 소요 시간을 적어두면 Agent의 선택이 달라진다
• “사용 중단” 표시가 Context Pollution을 문서로 막는다
• 아키텍처 규칙은 나중에 의존성 테스트로 강제할 대상이 된다
• 도메인 용어는 신규 입사자에게 설명하던 것과 같다
• 반복 절차는 Skill로, 강제 검사는 Hook으로 분리한다

15장. 좋은 CLAUDE.md 만들기 — 짧게, 자주 틀리는 것만

14장에서 무엇을 적는지 봤다.

이 장은 그 반대다.

무엇을 적지 않을지, 그리고 어떻게 적을지.

실무에서 차이를 만드는 쪽은 이쪽이다.

긴 CLAUDE.md가 나쁜 두 가지 이유

1️⃣ 매 요청에 비용을 낸다

CLAUDE.md 가 3,000줄이면
그 3,000줄이 모든 요청에 실려 간다.

11장에서 본 구조 그대로다.
캐싱이 완화해주지만 공짜는 아니다.

2️⃣ 지시가 희석된다

이쪽이 더 심각하다.

규칙이 100개면 Agent는 100개를 동등하게 취급한다.
그중 진짜 중요한 5개가 묻힌다.

규칙 5개  → 대체로 지킨다
규칙 50개 → 절반쯤 지킨다
규칙 200개 → 무엇을 지켰는지 알 수 없다

⚠️ 규칙을 늘리는 것으로 통제를 강화할 수 없다.

이 사실이 이 장 전체의 전제다.

코드에 이미 있는 것을 반복하지 않는다

가장 흔한 낭비다.

❌ 적을 필요 없는 것

- Spring Boot를 사용한다
- JPA로 데이터에 접근한다
- Controller는 @RestController 를 붙인다
- Repository는 JpaRepository 를 상속한다
- 테스트는 JUnit5를 쓴다

전부 코드를 열면 3초 안에 알 수 있다.

Agent는 이런 것을 놓치지 않는다.
이건 사람이 신입에게 쓰는 문서의 습관이 남은 것이다.

✅ 적어야 하는 것

- `common/util` 에 이미 있는 것을 다시 만들지 않는다
  (특히 날짜·금액 포맷팅, ID 생성)
- `@Transactional` 은 Facade 계층에만 붙인다
  Service에 붙어 있는 기존 코드는 마이그레이션 대상

기준은 하나다.

코드를 읽어서 알 수 있으면 적지 않는다.
코드를 읽어도 알 수 없으면 적는다.

두 번째 범주가 무엇인지 정리하면 이렇다.

Agent가 자주 틀리는 것만 남긴다

그러면 무엇을 적어야 할지 어떻게 아는가.

답은 예측이 아니라 관찰이다.

flowchart LR
    A[작업 진행] --> B[Agent가 틀린다]
    B --> C{두 번째인가}
    C -->|아니오| D[그 자리에서 고친다]
    C -->|예| E[CLAUDE.md에 추가]

🔥 한 번 틀린 것은 규칙으로 만들지 않는다.

한 번은 우연일 수 있다.
두 번이면 패턴이다.

이 기준이 없으면 CLAUDE.md 는
세션마다 한 줄씩 늘어나 결국 아무도 읽지 않게 된다.

Kotlin + Spring 레거시에서 실제로 반복되는 항목들이다.

- 새 예외를 만들지 말고 `common/exception` 의 기존 예외를 쓴다
- 테스트에서 `@SpringBootTest` 를 새로 추가하지 않는다
  기존 `IntegrationTestBase` 를 상속한다
- 응답 DTO에 엔티티를 직접 담지 않는다

셋 다 Agent가 한 번쯤 틀리고,
코드만 봐서는 판단이 어려운 것들이다.

명확하게 쓴다

같은 규칙도 문장에 따라 지켜지는 정도가 다르다.

왼쪽 열은 사실 규칙이 아니다.
덕목이다.

덕목은 Agent가 이미 가지고 있다.
그래서 아무 효과가 없다.

판정 가능한 문장이어야 규칙이 된다.

10장의 완료 조건과 같은 기준이다.

Agent가 스스로 위반 여부를 판단할 수 있는가.

이유를 한 줄 붙인다

이유가 있는 규칙은 응용된다.

이유 없는 규칙

- 외부 API 호출을 `@Transactional` 안에서 하지 않는다

이유 있는 규칙

- 외부 API 호출을 `@Transactional` 안에서 하지 않는다
  (커넥션을 물고 대기해서 커넥션 풀이 마른 장애가 있었다)

두 번째를 읽은 Agent는
비슷한 상황도 알아서 피한다.

Redis 호출, 파일 업로드, 메시지 발행에도 적용한다.

한 줄 추가가 규칙 세 개를 대신한다.

강조는 인플레이션을 일으킨다

여기서 실무자가 가장 많이 실패한다.

Agent가 규칙을 어기면 이렇게 하고 싶어진다.

- **반드시** 테스트를 실행한다
- **절대** 엔티티를 직접 반환하지 마라
- **중요:** 트랜잭션 경계를 지켜라
- ⚠️ **매우 중요:** 마이그레이션을 실행하지 마라
- 🚨 **경고:** legacy 패키지를 수정하지 마라

처음 한두 개는 효과가 있다.

다섯 개가 되면 강조가 정보를 잃는다.
전부 중요하면 아무것도 중요하지 않다.

⚠️ 부작용이 하나 더 있다.

과한 강조는 과잉 반응을 만든다.
“반드시 테스트를 실행한다” 를 강하게 써두면
한 줄 주석을 고친 뒤에도 4분짜리 전체 테스트를 돌린다.

원칙은 이렇다.

필요한 것을 평범한 문장으로 쓴다.
강조는 진짜 위험한 두세 개에만 남긴다.

그리고 기억할 것이 있다.

문장으로 막아야 하는 것과
설정으로 막아야 하는 것은 다르다.

4장에서 본 그 차이다.

🔥 CLAUDE.md 에 대문자로 세 번 써도
운영 DB 접속은 막히지 않는다.

막고 싶으면 settings.json 에 적어야 한다.

분량 기준

숫자로 정해두면 관리가 쉽다.

이 기준을 넘어가려 할 때 선택지는 셋이다.

1. 이유가 사라진 오래된 규칙을 지운다 (16장)
2. 하위 디렉터리로 계층화한다 (16장)
3. 절차라면 Skill로 옮긴다 (47장)

늘리는 것보다 이 셋 중 하나를 고르는 편이 거의 항상 낫다.

이 장의 핵심

• 긴 CLAUDE.md 는 비용을 늘리고 지시를 희석시킨다
• 규칙을 늘리는 것으로 통제를 강화할 수 없다
• 코드를 읽어서 알 수 있는 것은 적지 않는다
• 무엇이 현재 표준인지, 무엇이 사라질 예정인지는 코드로 알 수 없다 — 그것을 적는다
• 한 번 틀린 것은 그 자리에서 고치고, 두 번 틀린 것만 규칙으로 만든다
• 덕목은 규칙이 아니다 — 판정 가능한 문장이어야 규칙이 된다
• 이유를 한 줄 붙이면 규칙이 응용된다
• 강조를 남발하면 강조가 정보를 잃고, 과잉 반응을 부른다
• 되돌릴 수 없는 일은 문장이 아니라 권한 설정으로 막는다

16장. 계층화와 개선 루프 — Root · 모듈 · 도메인, 그리고 규칙의 수명

15장에서 분량 기준을 정했다.

스크롤 두 번.

그런데 모놀리스에서 이 기준은 곧 깨진다.
도메인이 열 개면 도메인별 규칙도 열 벌이다.

여기서 두 가지가 필요해진다.

계층화와, 규칙을 버리는 방법.

계층화 — 규칙을 코드 옆에 둔다

CLAUDE.md 는 여러 위치에 둘 수 있다.

order-service/
  CLAUDE.md                    ← 프로젝트 전체
  src/main/kotlin/
    order/
      CLAUDE.md                ← 주문 도메인
    payment/
      CLAUDE.md                ← 결제 도메인
    legacy/
      CLAUDE.md                ← 손대지 않는 영역

하위 파일은 상위를 대체하지 않는다.
더해진다.

flowchart TB
    R[Root CLAUDE.md<br/>공통 규칙] --> W[해당 작업의 규칙]
    D[payment/CLAUDE.md<br/>도메인 규칙] --> W

결제 코드를 고칠 때는 두 파일이 함께 유효하다.

무엇을 어디에 두는가

기준은 적용 범위다.

도메인별 파일의 실제 예시를 보면 감이 온다.

payment/CLAUDE.md

# 결제 도메인

## 절대 규칙

- 결제 요청은 멱등키(`idempotencyKey`) 없이 만들지 않는다
- PG 응답 코드는 절대 하드코딩하지 않는다 (`PgResultCode` 사용)
- 결제 상태 전이는 `PaymentStatus.canTransitTo()` 를 통과해야 한다

## 로컬 테스트

- PG는 `MockPgClient` 로만 테스트한다
- 실제 PG 샌드박스 호출은 사람이 수동으로만 한다

legacy/CLAUDE.md

# legacy — 읽기 전용

이 디렉터리의 코드는 동작을 변경하지 않는다.

- 참고용으로 읽는 것은 괜찮다
- 여기 있는 패턴을 새 코드에 따라 쓰지 않는다
- 버그를 발견하면 수정하지 말고 보고한다

⚠️ 두 번째 파일이 12장의 Context Pollution을
구조적으로 막는 장치다.

Agent가 그 디렉터리를 읽을 때마다
“따라 쓰지 마라” 를 함께 읽는다.

계층화는 경계 선언의 시작이다

여기서 이 책의 목적지와 연결된다.

도메인별 CLAUDE.md 를 쓰려고 하면
반드시 이 질문이 나온다.

결제 도메인의 규칙이 뭐지?
그 규칙은 어디까지 적용되지?
주문 도메인이 결제 코드를 직접 호출하고 있는데,
이건 누구 규칙을 따라야 하지?

🔥 이 질문에 답하는 과정이 곧 경계를 찾는 과정이다.

flowchart LR
    A[도메인별 규칙을 쓴다] --> B[경계가 애매한 곳이 드러난다]
    B --> C[8부: 경계를 긋는다]

38장에서 “코드에서 경계를 찾기” 를 다루는데,
그 작업의 가장 값싼 예비 조사가 이것이다.

파일을 옮기지 않고, 문서만 써보면서
경계가 성립하는지 확인한다.

규칙에는 수명이 있다

계층화가 분량 문제의 절반을 해결한다.

나머지 절반은 버리는 일이다.

규칙은 세 가지 이유로 죽는다.

두 번째가 특히 흔하고, 특히 해롭다.

Hook이나 테스트로 강제한 규칙을 문장으로도 남겨두면
Agent는 같은 것을 두 번 확인한다.

⚠️ 그리고 지켜지지 않는 규칙이 하나라도 있으면
다른 규칙의 권위도 함께 떨어진다.

지킬 수 없는 규칙은
지켜야 할 규칙의 신뢰를 깎는다.

개선 루프

규칙을 늘리고 줄이는 과정을 루프로 만든다.

flowchart TB
    A[Agent가 틀린다] --> B{두 번째인가}
    B -->|아니오| Z[그 자리에서 고친다]
    B -->|예| C[규칙 추가]
    C --> D[다음 작업에서 관찰]
    D --> E{지켜지는가}
    E -->|예| F[유지]
    E -->|아니오| G[에스컬레이션]

15장의 두 번 규칙에 뒷단이 붙은 형태다.

핵심은 마지막 갈래다.

규칙을 적었는데도 지켜지지 않을 때 무엇을 하는가.

여기서 규칙을 더 강하게 쓰는 것은 답이 아니다.
15장에서 본 강조의 인플레이션이 시작된다.

대신 수단을 올린다.

문장으로 적는다          (CLAUDE.md)
      ↓ 그래도 어긴다
절차로 만든다            (Skill · 47장)
      ↓ 그래도 어긴다
자동으로 실행시킨다      (Hook · 49장)
      ↓ 되돌릴 수 없는 일이다
아예 막는다              (Permission · 7장)

같은 규칙을 네 번 강조하는 것보다
한 단계 위의 수단으로 올리는 편이 항상 낫다.

62장에서 이것을 하네스 개선이라고 부른다.

언제 점검하는가

정기 점검은 대개 지켜지지 않는다.
계기에 붙여두는 편이 현실적이다.

네 번째가 의외로 효과적이다.

CLAUDE.md 는 사람에게도 읽히는 문서다.
신규 입사자가 읽고 이해가 안 되는 부분은
Agent도 이해하지 못한다.

점검은 Agent에게, 판단은 사람이

목록을 뽑는 일은 위임할 수 있다.

CLAUDE.md 에서 지금 코드베이스와 맞지 않는 항목을 찾아줘.
사라진 클래스를 언급하는 규칙, 테스트로 이미 강제되는 규칙,
코드만 봐도 아는 규칙. 수정은 하지 말고 목록만.

⚠️ 삭제 판단은 사람이 한다.

Agent는 규칙이 왜 생겼는지 모른다.
장애 하나 때문에 생긴 규칙을 “코드로 보이니 불필요” 로 분류한다.

15장에서 이유를 한 줄 붙이라고 한 것이 여기서도 작동한다.

이 장의 핵심

• 하위 CLAUDE.md 는 상위를 대체하지 않고 더해진다
• 배치 기준은 적용 범위다 — 모든 코드 / 한 도메인 / 한 디렉터리
• legacy/CLAUDE.md 는 Context Pollution을 구조적으로 막는 장치다
• 도메인별 규칙을 쓰려 하면 경계가 애매한 곳이 드러난다 — 8부의 예비 조사다
• 규칙은 원인이 사라지거나, 코드가 대신 막거나, 틀렸을 때 죽는다
• 지킬 수 없는 규칙은 지켜야 할 규칙의 신뢰를 깎는다
• 규칙이 안 지켜지면 강조를 올리지 말고 수단을 올린다 — 문장 → Skill → Hook → 권한
• 점검은 정기 일정보다 계기에 붙인다
• 규칙 삭제 판단은 사람이 한다 — Agent는 규칙이 생긴 이유를 모른다

17장. Agent의 Memory란 무엇인가 — 기억시킬 것과 기억시키지 않을 것

3부에서 두 가지를 나눴다.

이번 작업에만 필요한 것은 Context,
언제나 필요한 것은 CLAUDE.md.

그런데 그 사이에 끼는 것이 있다.

이 버그의 원인은 이벤트 리스너 중복이었다
결제 취소 흐름은 Facade에서 시작한다
v1 마이그레이션은 3분기까지 끝내기로 했다

이번 세션이 끝나면 사라지기엔 아깝고,
영구 규칙으로 삼기엔 맞지 않는 것들이다.

모델은 기억하지 않는다

먼저 사실 하나를 정확히 해두자.

LLM은 대화를 기억하지 않는다.

턴 1  → [질문]                        을 보낸다
턴 2  → [질문, 답변, 질문]              을 보낸다
턴 3  → [질문, 답변, 질문, 답변, 질문]   을 보낸다

11장에서 본 그 구조다.

기억처럼 보이는 것은
매번 다시 실어 보내고 있기 때문이다.

그래서 Agent의 Memory는 이렇게 정의된다.

다음 요청에 다시 실을 수 있도록
대화 밖에 남겨둔 것.

기억이 아니라 저장이고,
저장의 형태는 결국 파일이다.

세 층으로 나뉜다

flowchart TB
    S[Session Memory<br/>대화 — 세션과 함께 소멸]
    P[Project Memory<br/>CLAUDE.md · .claude — 레포에 상주]
    E[외부화된 Memory<br/>코드 · 테스트 · 커밋 · 문서]
    S -->|끝나면 사라진다| X[소멸]
    S -->|꺼내두면| P
    S -->|꺼내두면| E

세 번째가 이 장의 주제다.

코드 자체가 가장 강한 Memory다

백엔드 개발자에게는 익숙한 이야기다.

문서로 적힌 규칙과
테스트로 고정된 규칙 중 어느 쪽이 오래 사는가.

# CLAUDE.md
- 주문 취소 시 포인트 환급은 한 번만 발생한다

@Test
fun `주문 취소 시 포인트 환급은 한 번만 발생한다`() { ... }

두 번째가 압도적으로 강하다.

이유는 셋이다.

• 어기면 즉시 알려준다
• 사람도 Agent도 동일하게 구속된다
• 코드가 바뀌면 함께 실패해서 갱신을 강제한다

🔥 그래서 백엔드 프로젝트에서 가장 좋은 Memory는
테스트다.

23장과 36장에서 이 관점을 확장한다.

문서로 남길지 테스트로 남길지 고민된다면
테스트로 남길 수 있는지부터 확인한다.

기억시킬 것과 기억시키지 않을 것

마지막 줄이 가장 중요하다.

⚠️ 추측을 사실처럼 남기면
12장의 Context Rot이 영구화된다.

# ❌ 위험
결제 취소는 항상 비동기로 처리된다

# ✅ 안전
결제 취소는 PaymentCancelHandler에서 이벤트로 처리된다
(2026-08 확인. OrderCancelFacade.cancel() 기준)

두 번째는 틀렸을 때 반증할 수 있다.
첫 번째는 계속 인용되며 살아남는다.

어디에 남길 것인가

판단은 두 질문으로 끝난다.

flowchart TB
    A[남길 가치가 있는가] -->|아니오| X[버린다]
    A -->|예| B{코드로 강제할 수 있는가}
    B -->|예| T[테스트 · 의존성 규칙]
    B -->|아니오| C{항상 유효한가}
    C -->|예| M[CLAUDE.md]
    C -->|아니오| D[tasks · docs · 커밋 메시지]

세 갈래의 실제 모습은 이렇다.

테스트로

@Test
fun `외부 API 호출은 트랜잭션 밖에서 일어난다`() { ... }

CLAUDE.md 로

- 외부 API 호출을 `@Transactional` 안에서 하지 않는다
  (커넥션 풀 고갈 장애 이력)

작업 문서로

# tasks/point-refund-fix.md
## 확인한 사실
- 환급 경로는 2개 (Facade 직접 호출 + 이벤트 리스너)
- 이벤트 방식이 3개월 전 도입 (a3f9c21)

세 번째는 작업이 끝나면 폐기되거나,
살아남을 가치가 있으면 위 두 층으로 승격된다.

승격과 폐기

작업 문서를 계속 쌓아두면 그것도 부채가 된다.

작업이 끝나면 셋 중 하나를 고른다.

⚠️ 승격하지 않고 그냥 두는 것이 최악이다.

세 달 뒤에 남아 있는 tasks/*.md 는
사실인지 아닌지 아무도 확신하지 못하는 문서가 된다.

16장에서 규칙에 수명이 있다고 했다.
작업 문서에는 더 짧은 수명이 있다.

커밋 메시지는 무료 Memory다

가장 저평가된 저장소다.

git commit -m "fix: 주문 취소 시 포인트 이중 환급 수정

이벤트 기반 환급(a3f9c21) 도입 시 제거되지 않은
Facade의 직접 호출을 제거."

이 메시지는 세 가지 성질을 갖는다.

• 코드와 함께 영구히 남는다
• 해당 코드를 볼 때 git log 로 찾을 수 있다
• 별도 관리 비용이 0이다

Agent도 git log 를 읽는다.
9장에서 판단을 뒤집은 그 방법이다.

코드 옆에 붙어 있는 설명이
가장 오래 살아남는다.

이 장의 핵심

• 모델은 기억하지 않는다 — 매번 다시 실어 보낼 뿐이다
• Agent의 Memory는 대화 밖에 남겨둔 파일이다
• 층은 셋이다 — Session(소멸), Project(레포), 외부화(코드와 함께)
• 백엔드에서 가장 강한 Memory는 테스트다 — 어기면 즉시 알려준다
• 문서로 남길지 고민되면 테스트로 남길 수 있는지부터 본다
• 추측을 사실처럼 남기면 Context Rot이 영구화된다
• 확인한 사실에는 근거와 시점을 함께 적어 반증 가능하게 만든다
• 작업 문서는 끝나면 승격하거나 삭제한다 — 방치가 최악이다
• 커밋 메시지는 관리 비용 없이 코드 옆에 남는 Memory다

18장. Session이 길어지면 무엇이 무너지는가 — 언제 새로 시작할까

에이전틱 코딩을 며칠 해보면 이런 순간이 온다.

오전 내내 잘 되던 세션이
오후부터 이상해진다.

같은 Agent, 같은 프로젝트, 같은 사람인데
답변이 눈에 띄게 나빠진다.

이 장은 그 현상과 대처법이다.

무너지는 다섯 가지

1️⃣ 중요한 정보가 묻힌다

세션 초반에 확인한 핵심 사실이
수십 턴 뒤의 잡다한 정보에 파묻힌다.

12장의 Context Rot이다.

2️⃣ 낡은 가정이 근거로 재사용된다

가장 위험한 증상이다.

턴 8   "이 서비스는 단일 인스턴스로 뜬다" (당시 추측)
턴 45  "단일 인스턴스이므로 로컬 캐시로 충분합니다"

턴 8의 추측이 턴 45에서 전제가 된다.

Agent는 자기가 앞에서 한 말을 사실로 취급한다.
틀린 말도 마찬가지다.

3️⃣ 방향을 고집한다

한번 잡은 접근을 계속 밀어붙인다.

"이 방식으로는 안 될 것 같은데"
"조금만 더 수정하면 됩니다"   ← 세 번째 반복

⚠️ 이때 지시를 더 정교하게 쓰는 것은 대개 효과가 없다.

Context 안에 이미 그 방향을 지지하는
자기 발언이 수십 개 쌓여 있기 때문이다.

4️⃣ 압축에서 세부가 사라진다

세션이 길어지면 압축이 일어난다.

결론은 남고 근거는 사라진다.
그래서 “왜 그렇게 결정했더라” 가 재현되지 않는다.

5️⃣ 비용이 계속 오른다

11장의 구조다.
긴 세션의 다음 한 턴은 계속 비싸진다.

끊어야 할 신호

증상으로 판단하는 편이 정확하다.

마지막 줄이 실무에서 가장 자주 놓친다.

작업이 끝났는데 그 세션에서 다음 작업을 시작하면
끝난 작업의 Context를 전부 짊어지고 간다.

세션은 작업 단위로 닫는다.

/clear · /compact · /resume

세 가지 도구의 성격이 다르다.

판단 기준은 이렇다.

flowchart TB
    A{작업이 끝났는가} -->|예| C[/clear/]
    A -->|아니오| B{Agent가 틀린 가정을 고집하는가}
    B -->|예| C
    B -->|아니오| D{맥락이 여전히 유효한가}
    D -->|예| E[/compact/]
    D -->|아니오| C

🔥 핵심은 두 번째 갈래다.

틀린 가정이 문제라면 /compact 는 해결책이 아니다.
요약에 그 가정이 함께 실려 간다.

오염된 물을 반쯤 버려도 여전히 오염된 물이다.

이때는 /clear 하고,
검증된 사실만 골라 다시 넘긴다.

반대 함정 — 너무 자주 끊는다

이 장을 읽고 나면 반대로 가기 쉽다.

⚠️ 세션을 너무 자주 끊으면 그 나름의 대가가 있다.

기준은 하나다.

맥락이 유효하면 유지하고,
맥락이 오염됐으면 끊는다.

시간이나 턴 수가 기준이 아니다.

30분짜리 세션도 오염될 수 있고,
3시간짜리 세션도 깨끗할 수 있다.

세션을 나누는 자연스러운 경계

미리 정해두면 판단할 일이 줄어든다.

flowchart LR
    A[조사] --> B[설계]
    B --> C[구현]
    C --> D[Review]

각 전환에서 세션을 바꾼다.

세 번째가 특히 중요하다.

구현한 세션에는
“이렇게 하기로 했다” 는 합의가 쌓여 있다.

같은 Context에서 Review를 시키면
그 합의를 다시 확인할 뿐이다.

52장에서 이것을 독립 Review로 다룬다.

실전 리듬

하루를 이렇게 쪼갠다.

오전
  세션 1  이 기능이 어떻게 동작하는지 조사
          → docs/order-cancel-flow.md 작성 후 종료

  세션 2  그 문서를 읽히고 수정 계획 수립 · 승인
          → tasks/refund-fix.md 작성 후 종료

오후
  세션 3  계획대로 구현 + 테스트
          → 커밋 후 종료

  세션 4  Diff만 읽히고 독립 Review

각 세션은 앞 세션의 결과물로 시작한다.
대화가 아니라 파일로 이어진다.

이 방식이 성립하려면 인계가 필요하다.

다음 장의 주제다.

이 장의 핵심

• 긴 세션에서는 정보가 묻히고, 낡은 가정이 근거로 재사용된다
• Agent는 자기가 앞에서 한 말을 사실로 취급한다 — 틀린 말도 마찬가지다
• 방향을 고집할 때 지시를 정교하게 쓰는 것은 대개 효과가 없다
• 작업이 끝나면 세션도 닫는다 — 다음 작업이 이전 Context를 짊어지지 않게
• 틀린 가정이 문제라면 /compact 가 아니라 /clear 다
• 너무 자주 끊으면 캐시·탐색 결과·합의된 맥락을 잃는다
• 기준은 시간이나 턴 수가 아니라 맥락이 오염됐는지다
• 조사 → 설계 → 구현 → Review 전환에서 세션을 바꾼다
• 구현한 세션에서 Review를 시키면 합의를 재확인할 뿐이다

19장. Session을 안전하게 넘기는 방법 — 작업 상태를 파일로 남긴다

18장에서 세션을 나누는 리듬을 봤다.

그런데 세션을 끊으면 문제가 하나 생긴다.

다음 세션은 아무것도 모른다.

그래서 이런 일이 벌어진다.

세션 1  (2시간 조사) → /clear
세션 2  "이 프로젝트 구조부터 설명해줘"   ← 처음부터 다시

인계 없이 끊으면 끊을수록 손해다.

원칙 한 줄

4부 전체가 이 문장으로 압축된다.

중요한 정보가 Claude와의 대화 안에만
존재하면 안 된다.

대화는 반드시 사라진다.

압축으로 사라지거나, 세션 종료로 사라지거나,
사라지지 않더라도 12장처럼 무게를 잃는다.

그러니 사라지기 전에 꺼낸다.

언제 꺼내는가

세 시점이다.

세 번째가 실무에서 가장 값지다.

접근이 틀렸다고 판단했을 때
전부 버리면 조사한 사실까지 함께 버린다.

지금까지 확인한 사실만 tasks/refund-fix.md 에 정리해줘.
시도했던 접근과 그게 왜 안 됐는지도 같이 남겨줘.

작업 문서에 무엇을 적는가

여덟 개 항목이면 충분하다.

# 포인트 이중 환급 수정

## 목표
주문 취소 시 포인트 환급이 1건만 발생하게 한다

## 현재 구조
OrderCancelFacade.cancel()
  ├─ PaymentCancelHandler → 이벤트 → PointRefundListener (환급 1)
  └─ PointRefundService.refund()                        (환급 2)

## 확인한 사실
- 이벤트 방식은 3개월 전 도입 (a3f9c21)
- 관리자 강제 취소는 Facade를 거치지 않는다 (AdminOrderService:203)
- 부분 취소는 비례 배분 로직이 별도로 있다

## 확인하지 못한 것
- 배치성 자동 취소 경로가 있는지 (스케줄러 미확인)

## 결정된 사항
- Facade의 직접 호출을 제거한다 (이벤트 방식이 최신)
- 관리자 경로는 이번 범위에서 제외

## 변경된 파일
- OrderCancelFacade.kt (직접 호출 제거)
- OrderCancelTest.kt (재현 테스트 추가)

## 남은 작업
- 부분 취소 케이스 테스트 추가
- 관리자 경로는 별도 티켓으로

## 검증 방법
./gradlew test --tests '*OrderCancel*'

이 문서 하나면 새 세션이 30초 만에 따라잡는다.

확인한 것과 확인하지 못한 것을 나눈다

🔥 위 템플릿에서 가장 중요한 항목은
확인하지 못한 것 이다.

17장에서 추측을 사실처럼 남기면
Context Rot이 영구화된다고 했다.

이 절이 그 방지 장치다.

# ❌ 위험한 인계
결제 취소 경로는 3개다

# ✅ 안전한 인계
## 확인한 사실
- 취소 경로 3개 확인 (Facade, 관리자, 배치)
  근거: grep "cancel(" 결과 + 호출 추적

## 확인하지 못한 것
- 외부 CS 어드민에서 직접 호출하는 경로가 있는지

다음 세션의 Agent는
아래쪽을 “확인해야 할 것” 으로 다룬다.

위쪽처럼 쓰면 “이미 확정된 사실” 로 다룬다.

어디에 남기는가

문서 하나가 전부는 아니다.

디렉터리 구조는 이 정도면 된다.

order-service/
  CLAUDE.md
  docs/
    order-cancel-flow.md      ← 구조 이해
  tasks/
    refund-fix.md             ← 진행 중인 작업
  .claude/
    settings.json

⚠️ tasks/ 를 Git에 커밋할지는 팀이 정한다.

커밋하면 팀이 공유하고,
커밋하지 않으면 개인 작업 공간이 된다.

둘 다 유효하다.
정하지 않는 것이 문제다.

새 세션을 시작하는 문장

인계 문서가 있으면 시작이 짧아진다.

@tasks/refund-fix.md 를 읽고 이어서 작업하자.

"남은 작업" 의 첫 항목인 부분 취소 케이스 테스트부터 시작해줘.
"확인하지 못한 것" 은 아직 확인되지 않았으니 전제로 삼지 마.

세 번째 문장이 인계를 완성한다.

인계를 Agent에게 시킨다

매번 손으로 쓸 필요는 없다.

이번 세션에서 확인한 것을 tasks/refund-fix.md 에 정리해줘.

- 코드로 직접 확인한 것과 추론한 것을 구분해줘
- 추론한 것에는 어떻게 확인할 수 있는지 방법을 적어줘
- 시도했다가 버린 접근도 이유와 함께 남겨줘

두 번째 항목이 핵심이다.

이 요청을 그대로 쓰는 일이 반복되면
47장에서 Skill로 만든다.

긴 작업은 이렇게 이어진다

며칠짜리 작업의 실제 모습이다.

flowchart LR
    S1[조사] --> D1[docs/flow.md]
    D1 --> S2[설계]
    S2 --> D2[tasks/plan.md]
    D2 --> S3[구현]
    S3 --> C[코드 · 테스트 · 커밋]
    C --> S4[독립 Review]

세션은 서로를 모른다.
파일만 안다.

이 구조에는 부수 효과가 하나 있다.

사람이 중간에 빠졌다 들어와도 똑같이 작동한다.
휴가 뒤에 돌아온 동료에게도 같은 문서를 준다.

Agent를 위해 만든 인계 문서가
사람에게도 그대로 쓸모 있다.

66장의 최종 실전에서 이 구조를 그대로 쓴다.

이 장의 핵심

• 중요한 정보가 대화 안에만 존재하면 안 된다
• 꺼내는 시점은 압축 직전 · 세션 종료 전 · 방향 전환 직전이다
• 방향을 바꿀 때 전부 버리면 조사한 사실까지 버린다
• 작업 문서에는 목표 · 구조 · 확인한 사실 · 결정 · 남은 작업 · 검증 방법을 적는다
• 확인하지 못한 것 절이 추측의 영구화를 막는다
• 확인한 사실에는 근거를 함께 적는다
• 동작은 테스트로, 규칙은 CLAUDE.md 로, 이유는 커밋 메시지로 나눠 남긴다
• 인계 문서 작성도 Agent에게 맡기되, 사실과 추론을 구분하게 한다
• 세션은 서로를 모르고 파일만 안다 — 사람이 끼어들어도 같은 구조가 작동한다

20장. 요구사항을 Agent Task로 — Goal · Scope · Constraints · Acceptance Criteria

10장에서 작업 지시 한 문장을 쓰는 법을 봤다.

실무에서는 그렇게 시작하지 않는다.

티켓이 통째로 온다.

[PAY-2841] 결제 실패 시 재시도 지원

고객사에서 PG 일시 오류로 결제가 실패하는 건이
하루 30건 정도 발생. 자동 재시도가 필요합니다.

이 세 줄로 Agent에게 작업을 시킬 수는 없다.

요구사항과 Task는 다르다

이 변환은 원래 우리가 하던 일이다.

티켓을 받으면 머릿속에서
“그러면 이거랑 저건 어떻게 하지” 를 정리한다.

에이전틱 코딩에서는 그 정리를 밖으로 꺼내야 한다.

머릿속에 있으면 Agent는 모른다.

다섯 요소

10장의 네 요소에 하나가 추가된다.

flowchart TB
    G[Goal] --> S[Scope]
    S --> N[Non-goals]
    N --> C[Constraints]
    C --> A[Acceptance Criteria]

새로 들어온 것이 Non-goals 다.

Goal — 무엇을 달성하는가

한 문장으로 쓴다.

## Goal
PG 일시 오류로 실패한 결제를 자동 재시도해
수동 처리 건수를 줄인다

Scope — 어디까지 건드리는가

파일이나 모듈 수준으로 적는다.

## Scope
- `payment/` 결제 요청·응답 처리
- 재시도 대상은 PG 타임아웃과 5xx 응답만

Non-goals — 무엇을 하지 않는가

🔥 이 항목이 다섯 중 가장 값지다.

## Non-goals
- 카드사 한도 초과·잔액 부족은 재시도하지 않는다
- 결제 수단 변경 UX는 이번 범위가 아니다
- 재시도 이력 조회 화면은 만들지 않는다
- PG 연동 라이브러리를 교체하지 않는다

Agent는 도움이 될 것 같은 일을 추가한다.

재시도를 붙이면서 이력 테이블을 만들고,
관리자 조회 API를 하나 더 만든다.

⚠️ 이것을 나중에 Diff에서 발견하면
전부 되돌려야 한다.

앞에서 한 줄로 막는 편이 훨씬 싸다.

Scope는 갈 곳을 정하고,
Non-goals는 가지 않을 곳을 정한다.

Constraints — 지켜야 할 조건

## Constraints
- 재시도 중 중복 결제가 발생하면 안 된다 (멱등키 필수)
- 최대 3회, 지수 백오프
- 기존 Spring Retry를 쓴다. 새 라이브러리 추가 금지
- 결제 응답 스펙 변경 불가 (앱 배포 주기)

Acceptance Criteria — 어떻게 확인하는가

10장의 완료 조건이다.
Agent가 실행해서 판정할 수 있어야 한다.

## Acceptance Criteria
- PG 타임아웃 시 3회까지 재시도하는 테스트 통과
- 동일 멱등키로 재시도해도 결제가 1건만 생성되는 테스트 통과
- 잔액 부족 응답은 재시도하지 않는 테스트 통과
- `./gradlew test` 전체 통과
- `./gradlew ktlintCheck` 통과

티켓에 없지만 항상 물어야 하는 것

백엔드 요구사항에는 늘 빠지는 항목이 있다.

기획자는 이것을 쓰지 않는다.
우리가 아는 것이기 때문이다.

⚠️ 이 여섯 개를 Task에 답해두지 않으면
Agent가 알아서 정한다.

그리고 그 결정은 대개 그럴듯하고, 때때로 틀리다.

변환 전과 후

앞의 티켓이 이렇게 바뀐다.

# PAY-2841 결제 재시도

## Goal
PG 일시 오류로 실패한 결제를 자동 재시도한다

## Scope
- `payment/` 요청·응답 처리
- 재시도 대상: PG 타임아웃, 5xx

## Non-goals
- 카드 한도·잔액 부족 재시도
- 이력 조회 화면, 관리자 API
- PG 라이브러리 교체

## Constraints
- 멱등키 필수, 중복 결제 0건
- 최대 3회 지수 백오프
- Spring Retry 사용, 신규 의존성 금지
- 응답 스펙 변경 불가

## 결정 필요 (사람이 답함)
- 재시도 이력을 별도 테이블로 둘 것인가 → 아니오. payment 테이블 컬럼 추가
- 3회 실패 후 알림 → 기존 슬랙 알림 채널 재사용

## Acceptance Criteria
- (위 5개 항목)

결정 필요 절이 하나 늘었다.

이 절이 있으면 Agent가 추측하지 않는다.

변환도 위임할 수 있다

단, 결정은 사람이 한다.

@tickets/PAY-2841.md 를 읽고 작업 Task로 변환해줘.

- 코드를 확인해서 영향받을 파일을 Scope에 넣어줘
- 티켓에 명시되지 않아서 내가 결정해야 하는 항목을
  "결정 필요" 로 따로 모아줘
- 아직 구현은 하지 마

두 번째 지시가 핵심이다.

Agent가 잘하는 일은 빠진 것을 찾아내는 것이고,
사람이 해야 하는 일은 그것을 정하는 것이다.

이 요청을 반복하게 되면 48장에서 Skill로 만든다.

이 장의 핵심

• 요구사항은 원하는 결과이고, Task는 실행 가능한 단위다
• 머릿속에서 하던 정리를 밖으로 꺼내야 Agent가 안다
• Goal · Scope · Non-goals · Constraints · Acceptance Criteria 다섯이다
• Non-goals가 가장 값지다 — Agent는 도움이 될 것 같은 일을 추가한다
• Scope는 갈 곳을, Non-goals는 가지 않을 곳을 정한다
• 동시성 · 멱등성 · 마이그레이션 · 기존 데이터 · 실패 처리 · 권한은 티켓에 없다
• 답해두지 않으면 Agent가 알아서 정한다 — 그럴듯하고 때때로 틀리다
• 결정 필요 절을 만들면 추측이 사라진다
• 변환은 위임하고 결정은 사람이 한다

21장. Plan First — 바로 구현시키지 않는다

Task가 준비됐다.

이제 바로 구현시키고 싶어진다.
Agent는 몇 분이면 코드를 내놓는다.

그런데 그 몇 분이 가장 비싼 몇 분이 될 수 있다.

실패 비용은 뒤로 갈수록 커진다

방향이 틀렸을 때 되돌리는 비용이다.

flowchart LR
    A[계획 단계<br/>1분] --> B[구현 직후<br/>20분]
    B --> C[리뷰 단계<br/>1시간]
    C --> D[배포 후<br/>???]

Agent가 생기면서 이 곡선이 더 가팔라졌다.

사람은 방향이 이상하면 중간에 멈춘다.
Agent는 멈추지 않는다.

⚠️ 틀린 방향으로 300줄을 완주한다.

그리고 그 300줄은 그럴듯하다.
테스트도 통과한다. 틀린 것을 정확히 구현했기 때문이다.

계획 단계의 1분이
뒤의 한 시간을 산다.

계획 모드를 쓴다

7장에서 본 그 모드다.

Shift+Tab 으로 들어가면 읽기만 한다.

@tasks/PAY-2841.md 의 작업을 하려고 해.

먼저 현재 코드가 어떻게 되어 있는지 확인하고
수정 계획을 세워줘. 코드는 수정하지 마.

계획 모드는 “수정하지 마” 를 잊어버릴 수 없게 만든다.
문장이 아니라 조건이다.

4장에서 본 차이가 여기서 실용적으로 쓰인다.

좋은 계획의 다섯 요소

## 1. 현재 구조
PaymentService.pay()
  → PgClient.request()   (RestTemplate, 타임아웃 3초)
  → 실패 시 PaymentFailedException 던짐
  → PaymentController에서 500 응답

## 2. 근거
- PgClient.kt:44 에서 예외를 그대로 전파
- 재시도 로직 없음 (grep "Retry" 결과 0건)
- 멱등키는 이미 있음 (PaymentRequest.idempotencyKey)

## 3. 변경 계획
- PgClient.request() 에 @Retryable 적용 (3회, 지수 백오프)
- 재시도 대상 예외를 PgTimeoutException, PgServerException 으로 한정
- PaymentEntity 에 retryCount 컬럼 추가 (마이그레이션 V32)

## 4. 영향 범위
- 결제 요청 경로 전체
- 결제 취소는 별도 클라이언트라 영향 없음
- 배치 정산은 PgClient를 공유함 ← 확인 필요

## 5. 검증 방법
- PG 타임아웃 mock 테스트 3건
- 멱등성 테스트 1건
- 기존 결제 테스트 24건 회귀

이 다섯 개가 다 있어야 검토가 가능하다.

특히 2번과 4번이 없는 계획은 검토할 수 없다.
근거 없이 “이렇게 하겠습니다” 만 있는 셈이다.

승인 전에 물어볼 세 가지

계획을 그냥 승인하면 Plan First의 절반만 쓰는 것이다.

1️⃣ 근거를 요구한다

"재시도 로직이 없다" 는 어떻게 확인했어?
검색한 명령과 결과를 보여줘.

Agent가 코드를 확인하고 말한 것인지,
일반적인 지식으로 말한 것인지 여기서 갈린다.

2️⃣ 영향 범위를 도전한다

PgClient를 쓰는 곳을 전부 찾아줘.
배치 정산 말고 다른 호출자는 없어?

계획서의 “확인 필요” 는 대개 진짜 확인이 필요하다.

3️⃣ 대안을 물어본다

@Retryable 말고 다른 방법도 있어?
각각의 단점은?

대안을 물으면 두 가지를 얻는다.

• Agent가 첫 번째 아이디어에 고착됐는지 알 수 있다
• 우리가 몰랐던 선택지를 본다

그럴듯한데 틀린 계획

가장 위험한 유형이다.

세 가지 냄새로 구별할 수 있다.

# ❌ 확인 안 한 계획
PaymentRetryConfig 에 재시도 정책을 정의하고
RetryTemplate 을 주입받아 처리합니다

# ✅ 확인한 계획
PgClient.kt:44 의 request() 에 @Retryable 을 붙입니다
(RetryConfig 는 없어서 새로 만들어야 합니다)

🔥 계획서에서 파일 경로와 줄 번호를 요구하는 습관 하나가
이 문제의 대부분을 걸러낸다.

언제 생략해도 되는가

모든 작업에 계획이 필요한 것은 아니다.

기준은 되돌리기 비용이다.

git checkout 한 번으로 끝나면 생략해도 된다.
마이그레이션이 끼면 예외 없이 계획한다.

계획은 문서로 남긴다

승인한 계획은 대화 안에만 두지 않는다.

19장의 원칙 그대로다.

이 계획을 tasks/PAY-2841.md 의 "결정된 사항" 에 추가해줘.
그 다음 계획 모드를 벗어나서 구현을 시작하자.

이렇게 하면 세 가지가 가능해진다.

• 세션이 끊겨도 계획이 살아남는다
• 구현 중에 계획과 어긋나면 대조할 수 있다
• Review 세션에서 “계획대로 됐는지” 를 볼 수 있다

세 번째가 특히 강력하다.

Review의 기준이 “잘 짰는가” 가 아니라
“합의한 대로 됐는가” 가 된다.

이 장의 핵심

• 방향이 틀렸을 때의 비용은 뒤로 갈수록 가파르게 커진다
• 사람은 이상하면 멈추지만 Agent는 틀린 방향으로 완주한다
• 틀린 것을 정확히 구현한 코드는 테스트도 통과한다
• 계획 모드는 “수정하지 마” 를 문장이 아니라 조건으로 만든다
• 좋은 계획에는 현재 구조 · 근거 · 변경 계획 · 영향 범위 · 검증 방법이 있다
• 승인 전에 근거를 요구하고, 영향 범위를 도전하고, 대안을 묻는다
• 파일 경로와 줄 번호가 없는 계획은 코드를 확인하지 않은 계획이다
• 되돌리기 비용이 크면 계획하고, git checkout 으로 끝나면 생략해도 된다
• 승인한 계획을 문서로 남기면 Review 기준이 “합의한 대로 됐는가” 가 된다

22장. 큰 작업 분해하기 — 병렬 가능한 것과 순차적인 것

계획까지 세웠다.

그런데 계획서를 보니 파일 12개가 바뀐다.
마이그레이션도 있고 새 클래스도 넷이다.

이것을 한 세션에서 시키면 어떻게 되는가.

큰 작업이 실패하는 세 가지 이유

1️⃣ Context가 감당하지 못한다

12개 파일을 읽고 고치는 동안
초반에 읽은 파일의 내용이 흐려진다.

12장의 Rot이 한 작업 안에서 일어난다.

2️⃣ Diff를 검토할 수 없다

800줄짜리 Diff를 끝까지 읽는 사람은 없다.

⚠️ 읽지 않은 Diff를 승인하는 순간
에이전틱 코딩이 아니라 그냥 위임이 된다.

3️⃣ 되돌릴 단위가 없다

12개 중 3개가 잘못됐을 때
전부 버리거나 전부 안고 가야 한다.

분해의 기준은 되돌리기다

여러 기준이 있지만 실무에서 통하는 것은 하나다.

커밋 하나 = 되돌릴 수 있는 단위

이 기준으로 쪼개면 나머지가 따라온다.

각 단위가 갖춰야 할 조건은 셋이다.

Epic → Task → Step

세 층으로 본다.

Epic   결제 재시도 지원              (티켓 하나)
 ├ Task  1. 재시도 예외 분류 도입      (커밋 하나)
 ├ Task  2. 멱등키 검증 강화          (커밋 하나)
 ├ Task  3. retryCount 컬럼 마이그레이션
 ├ Task  4. PgClient 재시도 적용
 ├ Task  5. 3회 실패 시 알림
 └ Task  6. 통합 테스트 보강

Step은 Task 안의 순서다.
문서로 쓰지 않고 Agent에게 맡긴다.

🔥 Task 층이 사람이 관리하는 층이다.

여기가 커밋 단위이고, Review 단위이고,
세션 단위다.

의존성을 그린다

쪼갠 다음 순서를 정한다.

flowchart TB
    T1[1. 예외 분류] --> T4[4. 재시도 적용]
    T2[2. 멱등키 검증] --> T4
    T3[3. 컬럼 마이그레이션] --> T4
    T4 --> T5[5. 실패 알림]
    T4 --> T6[6. 통합 테스트]

여기서 병렬 가능성이 보인다.

• 1, 2, 3은 서로 독립이다
• 4는 셋 다 필요하다
• 5, 6은 4 이후 독립이다

병렬 가능한가를 판단하는 법

두 질문이면 충분하다.

둘 다 아니면 병렬이다.

⚠️ 첫 번째 질문을 자주 놓친다.

논리적으로 독립인 두 작업이
같은 PaymentService.kt 를 고치면 충돌한다.

Agent 두 개를 동시에 돌리면 그대로 덮어쓴다.

파일이 겹치면 순차로 돌리거나,
53장의 Git Worktree로 격리한다.

실제로는 이렇게 진행한다

병렬이 가능해도 첫 시도는 순차를 권한다.

세션 1  Task 1 → 커밋
세션 2  Task 2 → 커밋
세션 3  Task 3 → 커밋 (마이그레이션이라 별도 확인)
세션 4  Task 4 → 커밋
...

이유는 두 가지다.

• 앞 Task에서 배운 것이 뒤에 반영된다
• 어디서 어긋났는지 즉시 안다

병렬은 작업이 확실히 독립이고
검증 수단이 갖춰졌을 때 쓴다. 53장에서 다룬다.

각 Task를 어떻게 넘기는가

Task마다 20장의 다섯 요소를 다시 쓰지 않는다.

상위 문서를 참조하고 이번 범위만 좁힌다.

@tasks/PAY-2841.md 를 읽고 Task 4만 진행하자.

이번 범위:
- PgClient.request() 에 재시도 적용
- Task 1의 예외 분류를 사용한다

이번 범위 아님:
- 알림 (Task 5)
- 통합 테스트 (Task 6)

완료 조건:
- 재시도 단위 테스트 3건 통과
- 기존 결제 테스트 24건 통과

이번 범위 아님 이 20장의 Non-goals다.

Task를 쪼갤수록 이 항목이 중요해진다.
Agent는 인접 Task를 같이 해버리려 한다.

과잉 분해의 비용

⚠️ 반대 방향으로도 실패할 수 있다.

한 줄짜리 Task 20개는 관리 비용만 늘린다.

기준은 아까와 같다.

되돌릴 필요가 없는 것은 따로 되돌릴 수 있게
만들 필요도 없다.

분해도 위임할 수 있다

@tasks/PAY-2841.md 의 계획을 커밋 단위로 쪼개줘.

- 각 단위는 단독으로 머지 가능해야 해
- 각 단위의 완료 조건을 테스트로 쓸 수 있게 적어줘
- 순서와 의존 관계를 표시해줘
- 같은 파일을 건드리는 단위끼리 표시해줘

쪼개기만 하고 구현은 하지 마.

마지막 요구가 유용하다.

파일 충돌 정보는 Agent가 코드를 보고 판단하는 편이
사람의 기억보다 정확하다.

이 장의 핵심

• 큰 작업은 Context가 감당 못 하고, Diff를 검토할 수 없고, 되돌릴 단위가 없다
• 읽지 않은 Diff를 승인하면 에이전틱 코딩이 아니라 그냥 위임이다
• 분해 기준은 하나다 — 커밋 하나가 되돌릴 수 있는 단위
• 각 단위는 단독 머지 가능하고, 자체 검증되고, 한 세션에 들어가야 한다
• Task 층이 커밋 단위이자 Review 단위이자 세션 단위다
• 같은 파일을 고치거나 앞 결과가 필요하면 순차, 아니면 병렬이다
• 논리적으로 독립이어도 파일이 겹치면 충돌한다
• 병렬은 나중에 — 첫 시도는 순차로 하면서 배운 것을 뒤에 반영한다
• 잘게 쪼갠 Task일수록 “이번 범위 아님” 을 명시해야 한다

23장. 테스트를 Agent의 눈으로 쓰기 — 스스로 검증하게 만들기

5장에서 한 줄로 지나간 문장이 있다.

테스트가 없는 프로젝트에서
Agent의 “수정 완료” 는 의견에 불과하다.

이 장은 그 문장을 실무로 옮긴다.

관점 하나만 바꾸면 된다.

테스트는 품질 보증 장치이기 전에
Agent가 세상을 보는 유일한 창이다.

사람과 Agent가 테스트를 쓰는 방식은 다르다

🔥 세 번째가 핵심이다.

Agent에게 “통과” 는 완료의 근거다.

그래서 테스트가 약하면
Agent는 약한 근거로 자신 있게 완료를 보고한다.

세 가지 용도

에이전틱 코딩에서 테스트는 세 역할을 한다.

1️⃣ 현재 동작을 고정한다

레거시를 고칠 때 가장 먼저 필요한 것이다.

@Test
fun `부분 취소 시 포인트는 비례 배분된다`() {
    // 지금 이렇게 동작한다 (옳은지는 별개)
}

옳고 그름을 판단하지 않고 현재를 박제한다.
36장의 Characterization Test다.

2️⃣ 버그를 증명한다

9장에서 본 재현 테스트다.

실패하는 테스트가 있으면
Agent는 목표를 정확히 안다.

3️⃣ 회귀를 막는다

가장 익숙한 용도이고,
Agent 시대에 가치가 몇 배로 올랐다.

사람은 하루 세 번 코드를 고치지만
Agent는 한 시간에 세 번 고친다.

Agent에게 좋은 테스트의 조건

세 가지다.

빠르다

⚠️ 느린 테스트는 없는 테스트에 수렴한다.

Feedback Loop가 4분마다 한 바퀴 돌면
Agent는 검증 없이 여러 수정을 몰아서 한다.

그래서 실패했을 때 원인을 짚기도 어려워진다.

빠른 단위 테스트를 따로 분리해두는 것이
에이전틱 코딩에서는 큰 투자 대비 효과를 낸다.

./gradlew test --tests '*UnitTest'    # 12초
./gradlew test                        # 4분

결정적이다

가끔 실패하는 테스트는 최악이다.

1차 시도  실패 → Agent가 코드를 고친다
2차 시도  통과 → "고쳐졌습니다"

⚠️ 고친 것이 아니라 운이 좋았던 것인데
Agent는 자기 수정이 효과가 있었다고 학습한다.

그리고 그 잘못된 인과가 Context에 남는다.

시간·랜덤·외부 호출·실행 순서 의존은
Agent와 함께 일하기 전에 정리해야 한다.

실패 메시지가 말을 한다

Agent가 받는 유일한 단서다.

❌ expected: true but was: false

✅ 주문 취소 시 포인트 환급은 한 번만 발생한다
   expected size: 1 but was: 2
   actual: [PointHistory(+1000, REFUND), PointHistory(+1000, REFUND)]

두 번째를 받은 Agent는
“환급이 두 번 일어났다” 를 즉시 안다.

첫 번째를 받으면 코드를 다시 읽어야 한다.
Context를 더 쓰고, 추측이 늘어난다.

좋은 실패 메시지는
Agent의 Context를 아껴준다.

테스트 작성을 시킬 때

기존 테스트를 먼저 읽히는 것이 순서다.

@src/test/kotlin/order/OrderCancelTest.kt 를 읽고
같은 스타일로 부분 취소 케이스를 추가해줘.

- 새 테스트 기반 클래스를 만들지 마
- 기존 IntegrationTestBase 를 그대로 상속해
- given/when/then 주석 스타일을 유지해

⚠️ 이 지시가 없으면 Agent는 새 스타일을 만든다.

일반적으로 좋은 스타일일 수는 있다.
하지만 테스트 파일마다 스타일이 다른 프로젝트가 된다.

Agent가 테스트를 망가뜨리는 네 가지 패턴

3장에서 예고한 그 문제다.

세 번째가 가장 자주 일어나고 가장 위험하다.

// Agent의 수정
assertThat(histories).hasSize(1)   →   assertThat(histories).hasSize(2)

버그가 명세가 됐다.

방지는 세 겹으로 한다.

# CLAUDE.md
- 테스트를 삭제하거나 @Disabled 를 추가하지 않는다
- 실패하는 테스트의 기댓값을 바꾸지 않는다
  (기댓값이 틀렸다고 판단되면 수정하지 말고 보고한다)

# 작업 지시
테스트 코드는 수정하지 말고 구현만 고쳐줘

# Diff 검토
git diff --stat src/test/

세 번째가 마지막 방어선이다.
테스트 디렉터리의 변경량만 먼저 본다.

테스트가 아예 없는 영역

레거시에서는 흔한 상황이다.

이때 순서는 이렇다.

flowchart LR
    A[현재 동작 파악] --> B[Characterization Test]
    B --> C[통과 확인]
    C --> D[그 다음에 수정]

⚠️ 테스트 없이 수정부터 하지 않는다.

무엇이 깨졌는지 알 방법이 없는 상태에서
Agent의 속도는 위험이 된다.

36장에서 이 작업을 본격적으로 다룬다.

이 장의 핵심

• 테스트는 Agent가 세상을 보는 유일한 창이다
• Agent에게 “통과” 는 완료의 근거다 — 약한 테스트는 약한 근거를 만든다
• 용도는 셋이다 — 현재 동작 고정, 버그 증명, 회귀 방지
• 느린 테스트는 없는 테스트에 수렴한다 — 빠른 단위 테스트를 분리한다
• 가끔 실패하는 테스트는 Agent에게 잘못된 인과를 학습시킨다
• 좋은 실패 메시지는 Agent의 Context를 아껴준다
• 기존 테스트를 먼저 읽히지 않으면 새 스타일이 생긴다
• 기댓값을 실제값으로 고치는 수정이 가장 위험하다 — 버그가 명세가 된다
• 테스트 디렉터리의 변경량을 따로 확인하는 것이 마지막 방어선이다

24장. Feedback Loop 설계 — Observe · Think · Act · Verify

2장에서 Agent의 다섯 요소 중 마지막이 Feedback Loop였다.

Agent가 스스로 수렴하는 이유는
반성 능력이 아니라 틀렸다는 신호가 텍스트로 돌아오기 때문이라고 했다.

이 장은 그 신호를 설계 대상으로 다룬다.

루프의 모양

flowchart LR
    O[Observe<br/>결과를 본다] --> T[Think<br/>원인을 판단]
    T --> A[Act<br/>수정한다]
    A --> V[Verify<br/>실행해 확인]
    V --> O

Agent가 잘 도는 프로젝트와 그렇지 않은 프로젝트의 차이는
Verify 에서 무엇이 돌아오느냐에 있다.

돌아오는 것이 없으면
루프가 아니라 직선이 된다.

Think → Act → (끝)

2장에서 환경을 Agent의 눈이라고 했다.
눈이 없는 상태다.

좋은 피드백의 네 조건

네 조건을 모두 만족하는 것이 컴파일 에러다.

그래서 정적 타입 언어를 쓰는 우리는
에이전틱 코딩에서 유리한 출발선에 있다.

Kotlin 컴파일러가 이미 훌륭한 피드백 장치다.

피드백에는 계층이 있다

백엔드 작업에서 실제로 쓰는 층들이다.

🔥 순서가 중요하다.

싼 것부터 태워야 한다.

컴파일 실패 → 여기서 멈춘다 (12초 낭비)

컴파일도 안 되는 코드로 통합 테스트를 돌리면
4분을 버린다.

Agent에게 이 순서를 알려주는 것은 한 줄이면 된다.

# CLAUDE.md
- 수정 후 순서: ktlintCheck → 관련 단위 테스트 → 필요 시 전체 테스트

로그를 피드백으로 만들기

테스트로 못 잡는 것이 있다.

실제로 돌려봐야 아는 문제다.

이때 로그가 피드백이 되려면 조건이 있다.

# ❌ 피드백이 안 되는 로그
2026-08-14 10:23:44 ERROR 결제 처리 실패

# ✅ 피드백이 되는 로그
2026-08-14 10:23:44 ERROR PgClient - 결제 실패
  paymentId=P20260814-0031 pgCode=TIMEOUT retryCount=3
  traceId=8f3a91c2

두 번째는 Agent가 다음 행동을 정할 수 있다.

traceId 로 관련 로그만 골라낼 수 있고,
13장에서 말한 로그 잘라내기가 가능해진다.

docker logs order-service | grep 8f3a91c2

⚠️ 구조화되지 않은 로그는
Context만 먹고 판단은 못 준다.

관측 가능성 개선이 에이전틱 코딩 투자와 겹치는 지점이다.

수렴하지 않을 때

루프가 항상 답으로 수렴하지는 않는다.

발산하는 신호는 셋이다.

세 번째가 나오면 즉시 멈춘다.
3장에서 본 그 경로다.

멈추는 조건을 미리 지시에 넣어두면 좋다.

같은 테스트를 세 번 고쳐도 통과하지 못하면
멈추고 지금까지 확인한 것과 막힌 지점을 정리해줘.

🔥 이 한 줄이 없으면 Agent는 계속 시도한다.

Agent에게는 “포기” 라는 기본값이 없다.
비용과 오염이 함께 쌓인다.

62장에서 이것을 중단 조건 설계로 다룬다.

사람이 개입하는 지점

루프 전체를 사람이 지켜볼 필요는 없다.

가운데를 지켜보고 있으면
위임의 이점이 사라진다.

3장에서 본 그림 그대로다.

루프를 갖추는 최소 투자

지금 프로젝트에서 오늘 할 수 있는 것들이다.

1. 빠른 단위 테스트 명령을 분리한다      (12초짜리)
2. 그 명령을 CLAUDE.md에 적는다
3. 검증 순서를 한 줄로 적는다
4. 중단 조건을 작업 지시에 넣는다

넷 다 30분이면 된다.

그리고 이 넷이 있으면
Agent의 결과물 품질이 눈에 띄게 달라진다.

모델을 바꾸는 것보다
루프를 만드는 편이 효과가 크다.

4장의 결론이 여기서 실행 가능한 형태가 된다.

이 장의 핵심

• Agent가 수렴하는 이유는 틀렸다는 신호가 텍스트로 돌아오기 때문이다
• Verify에서 돌아오는 것이 없으면 루프가 아니라 직선이다
• 좋은 피드백은 빠르고, 구체적이고, 자동이고, 위치를 지목한다
• 컴파일 에러가 네 조건을 모두 만족한다 — 정적 타입 언어는 유리한 출발선이다
• 피드백에는 계층이 있고, 싼 것부터 태워야 한다
• 검증 순서를 CLAUDE.md 에 한 줄로 적어둔다
• 구조화되지 않은 로그는 Context만 먹고 판단은 주지 않는다
• 검증을 약화시키기 시작하면 즉시 멈춘다
• Agent에게는 포기라는 기본값이 없다 — 중단 조건을 지시에 넣는다
• 루프의 중간을 지켜보면 위임의 이점이 사라진다

25장. Git을 Agent의 안전장치로 — 작은 커밋과 되돌리기

5부의 마지막 장이다.

지금까지 작업을 정의하고, 계획하고, 쪼개고,
검증 수단을 만들고, 루프를 돌렸다.

마지막으로 필요한 것은 틀렸을 때 돌아갈 곳이다.

우리에겐 이미 있다.

Git은 하네스의 일부다

Git이 에이전틱 코딩에서 하는 일은 둘이다.

flowchart LR
    G[Git] --> R[되돌리기<br/>실패 비용을 0으로]
    G --> D[검토 단위<br/>Diff와 커밋]

5장의 부품 목록에는 Git이 없었다.

Tools와 Tests 사이에 조용히 끼어 있다.
그리고 실무에서는 가장 자주 우리를 구한다.

작업 전 조건

6장에서 강조한 그 조건이다.

git status        # clean이어야 한다
git switch -c feat/payment-retry

이 두 줄이 안전망 전체의 전제다.

⚠️ 커밋하지 않은 변경 위에서 Agent를 돌리면
내 변경과 Agent의 변경이 섞인다.

그러면 되돌리기가 불가능해진다.
어디까지가 내 것인지 구별할 수 없기 때문이다.

CLAUDE.md 에 이렇게 적어두는 팀도 있다.

- 작업 시작 전 `git status` 가 clean인지 확인한다
  clean이 아니면 작업을 시작하지 말고 알려준다

커밋은 되돌릴 수 있는 단위로

22장의 분해 기준과 같은 문장이다.

❌ "결제 재시도 기능 구현"          (12 파일, 800줄)
✅ "feat: PG 재시도 대상 예외 분류"   (3 파일, 60줄)
   "feat: PgClient 재시도 적용"      (2 파일, 40줄)
   "chore: retryCount 컬럼 추가"     (1 파일, 12줄)

작은 커밋의 이점은 되돌리기만이 아니다.

🔥 두 번째가 에이전틱 코딩에서 가장 중요하다.

22장에서 말한 그대로다.
읽지 않은 Diff를 승인하면 위임이 아니라 방치다.

Diff를 읽는 순서

9장에서 세 가지를 확인했다.
실무에서는 순서를 정해두면 빨라진다.

# 1. 규모부터
git diff --stat

# 2. 테스트가 약해지지 않았는지
git diff src/test/

# 3. 위험한 곳부터
git diff src/main/resources/db/migration/
git diff --  '*Config.kt' '*Properties.kt'

# 4. 나머지
git diff src/main/

순서의 이유는 이렇다.

⚠️ --stat 에서 예상과 크게 다르면
그 자리에서 되돌리는 편이 낫다.

계획에 없던 파일이 6개 바뀌었어.
계획 범위(PgClient, PaymentEntity)만 남기고 되돌려줘.

Agent에게 커밋을 맡길 때

맡겨도 된다. 규칙이 필요할 뿐이다.

# CLAUDE.md
## Git

- 커밋은 논리적 단위로 나눈다. 여러 목적을 한 커밋에 담지 않는다
- 커밋 메시지: `type: 요약` + 빈 줄 + 이유
- 사람이 Diff를 확인하기 전에는 커밋하지 않는다
- 브랜치 생성·전환은 사람이 한다
- `git push` 는 하지 않는다

마지막 두 줄이 경계선이다.

로컬에 기록을 쌓는 것과
원격에 내보내는 것은 성격이 다르다.

17장에서 커밋 메시지를 무료 Memory라고 했다.
그 이점은 메시지를 잘 쓸 때만 생긴다.

# ❌
git commit -m "fix bug"

# ✅
git commit -m "fix: 주문 취소 시 포인트 이중 환급 수정

이벤트 기반 환급(a3f9c21) 도입 시 제거되지 않은
Facade의 직접 호출을 제거."

위험한 Git 명령

7장의 deny 목록에 반드시 들어가야 하는 것들이다.

{
  "permissions": {
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Bash(git clean:*)"
    ]
  }
}

⚠️ 세 번째를 자주 빠뜨린다.

git clean -fd 는 .env.local 처럼
추적하지 않는 로컬 설정 파일을 지운다.

Git에 없으니 되돌릴 수도 없다.

되돌리기 3단계

상황별로 방법이 다르다.

flowchart TB
    A{커밋했는가} -->|아니오| B[git checkout -- 파일]
    A -->|예, 로컬만| C[git reset --soft HEAD~1]
    A -->|예, 공유됨| D[git revert]

세 번째가 Agent와 함께 일할 때 기본값이다.

이력을 지우지 않고 되돌린다.
무엇이 왜 되돌려졌는지가 기록에 남는다.

격리가 필요할 때

병렬 작업에서는 브랜치만으로 부족하다.

Agent 두 개가 같은 작업 디렉터리를 쓰면
서로의 파일을 덮어쓴다.

git worktree add ../order-service-retry feat/payment-retry

작업 디렉터리 자체를 분리한다.

22장에서 파일이 겹치면 순차로 하라고 했는데,
Worktree는 그 제약을 푸는 방법이다.

53장에서 다룬다.

PR을 Review 경계로

마지막 안전장치는 사람과 사람 사이에 있다.

flowchart LR
    A[Agent 구현] --> B[사람 Diff 검토]
    B --> C[독립 Review 세션]
    C --> D[PR]
    D --> E[팀 리뷰]

세 층의 검토가 겹친다.

18장에서 구현 세션과 Review 세션을 나눈 이유,
52장의 구현·Review 분리가 이 그림 위에 있다.

Agent가 빨라질수록
검토 단위는 작아져야 한다.

이 장의 핵심

• Git은 하네스의 부품이다 — 되돌리기와 검토 단위를 제공한다
• 작업 전 git status 가 clean이어야 안전망이 작동한다
• 커밋하지 않은 변경 위에서 작업하면 내 것과 Agent 것이 섞인다
• 커밋은 되돌릴 수 있는 단위로 나눈다 — 22장의 분해 기준과 같다
• Diff는 규모 → 테스트 → 마이그레이션·설정 → 나머지 순으로 읽는다
• --stat 에서 예상과 다르면 그 자리에서 되돌린다
• 커밋은 맡기되 push와 브랜치 조작은 사람이 한다
• git clean 은 추적하지 않는 파일을 지워서 되돌릴 수 없다
• 공유된 이력은 revert 로 되돌린다 — 이유가 기록에 남는다
• Agent가 빨라질수록 검토 단위는 작아져야 한다

26장. API 개발 — 기존 Convention을 따르게 만들기

6부는 매일 하는 작업들이다.

첫 번째는 API 추가.

Agent가 가장 빠르게 해내는 작업이면서,
가장 티 나게 틀리는 작업이기도 하다.

문제는 만드는 것이 아니다

“주문 취소 API를 만들어줘” 라고 하면
Agent는 30초 만에 완성도 높은 코드를 낸다.

Controller, Service, DTO, 예외 처리까지 갖춰져 있다.

문제는 그 코드가 우리 프로젝트의 것처럼 보이지 않는다는 점이다.

우리 프로젝트          Agent가 만든 것
────────────────      ────────────────
ApiResponse<T> 래핑    바로 DTO 반환
BusinessException      IllegalArgumentException
Facade에서 조합        Controller에서 Service 두 개 호출
@field:NotNull         @NotNull

각각은 틀린 코드가 아니다.
다만 우리 것이 아니다.

API 개발에서 Agent에게 시킬 일은
새로 만드는 것이 아니라 닮게 만드는 것이다.

유사 API를 지목한다

가장 효과가 큰 지시 방법이다.

주문 취소 API를 추가해줘.

@src/main/kotlin/order/OrderConfirmController.kt 와
@src/main/kotlin/order/OrderConfirmFacade.kt 를 먼저 읽고
같은 구조로 만들어줘.

다른 점은 이것뿐이야:
- 취소는 이미 배송이 시작된 주문이면 400을 반환한다

이 지시가 하는 일은 셋이다.

• 컨벤션을 문서가 아니라 코드로 전달한다
• Agent가 탐색할 필요가 없다 (13장)
• 차이점만 판단하면 되니 실수가 줄어든다

⚠️ 이때 지목하는 파일은
가장 최근에 잘 만든 것이어야 한다.

레거시에는 세대가 섞여 있다.
오래된 것을 지목하면 오래된 패턴이 복제된다.

계층별 실패 패턴

Kotlin + Spring 프로젝트에서 반복되는 것들이다.

🔥 이 중 두 개는 매번 나온다.

엔티티 직접 반환과 새 예외 생성이다.

둘 다 Agent 입장에서는 자연스러운 선택이다.
엔티티에 필요한 필드가 다 있고, 새 예외가 의미를 정확히 표현한다.

우리 사정을 모르면 그렇게 한다.

반복되는 것은 규칙으로

같은 지적을 두 번 했다면 CLAUDE.md 로 올린다.
15장의 기준이다.

## API Convention

- 응답은 `ApiResponse<T>` 로 감싼다. 엔티티를 직접 반환하지 않는다
- 예외는 `common/exception` 의 기존 것을 쓴다. 새로 만들지 않는다
- 도메인 간 조합은 Facade에서 한다. Controller는 Facade 하나만 호출한다
- 요청 검증은 DTO의 `@field:` 애노테이션으로 한다
- 상태 코드: 검증 실패 400, 권한 403, 없음 404, 도메인 규칙 위반 409

마지막 줄이 특히 값지다.

상태 코드 선택은 정답이 없어서
Agent가 매번 다르게 고른다.

우리 팀의 답을 한 줄로 적어두면 끝난다.

계약을 먼저 정한다

구현 전에 스펙을 확정하면 되돌릴 일이 줄어든다.

구현하기 전에 API 스펙만 먼저 제시해줘.

- 경로, 메서드, 요청/응답 JSON
- 실패 케이스별 상태 코드와 에러 코드
- 기존 API와 다른 점

동의하면 그때 구현하자.

21장의 Plan First를 API 작업에 맞춘 형태다.

스펙은 되돌리기 비용이 큰 결정이다.
클라이언트가 이미 붙었으면 바꿀 수 없다.

완료 조건

10장의 형식으로 쓰면 이 정도다.

## Acceptance Criteria
- 정상 취소 요청 200 + ApiResponse 래핑 확인 테스트
- 배송 시작된 주문 취소 시 409 + 에러 코드 `ORDER_ALREADY_SHIPPED`
- 존재하지 않는 주문 404
- 권한 없는 사용자 403
- `./gradlew test --tests '*OrderCancelApi*'` 통과
- `./gradlew ktlintCheck` 통과

⚠️ 실패 케이스를 완료 조건에 넣지 않으면
Agent는 happy path만 만들고 끝낸다.

30장에서 이 성향을 다시 다룬다.

API 문서와 클라이언트 영향

잊기 쉬운 두 가지다.

이 API 추가가 영향을 주는 곳을 확인해줘.

- OpenAPI 스펙 파일 갱신이 필요한가
- 기존 응답 스펙이 바뀌는가 (클라이언트 배포 필요 여부)
- 이 엔드포인트를 호출하는 내부 서비스가 있는가

세 번째가 모놀리스에서 특히 중요하다.

같은 레포 안에서 다른 모듈이
이 Service를 직접 호출하고 있을 수 있다.

38장에서 이 호출 관계가 경계 탐색의 재료가 된다.

이 장의 핵심

• Agent는 API를 잘 만든다 — 다만 우리 프로젝트의 것처럼 보이지 않는다
• 시킬 일은 새로 만드는 것이 아니라 기존 것과 닮게 만드는 것이다
• 유사 API를 지목하면 컨벤션이 문서가 아니라 코드로 전달된다
• 지목할 파일은 가장 최근에 잘 만든 것이어야 한다
• 엔티티 직접 반환과 새 예외 생성은 매번 나오는 두 가지다
• 상태 코드 선택 기준을 한 줄로 적어두면 매번 흔들리지 않는다
• 스펙은 되돌리기 비용이 크다 — 구현 전에 확정한다
• 실패 케이스를 완료 조건에 넣지 않으면 happy path만 만들어진다
• 모놀리스에서는 내부 호출자 확인이 빠지기 쉽다

27장. Database 작업 — Schema · Query · Migration · Index

DB 작업은 성격이 둘로 갈린다.

읽는 쪽은 되돌릴 수 있고,
쓰는 쪽은 되돌릴 수 없다.

에이전틱 코딩에서 이 구분이 그대로 경계선이 된다.

스키마를 파악시키는 방법

12장에서 스키마 덤프를 오염원으로 꼽았다.

테이블 200개짜리 모놀리스에서
\d+ 를 전부 넣으면 Context가 바로 찬다.

필요한 것만 넣는다.

주문 취소와 관련된 테이블 구조를 확인해줘.

- 엔티티 클래스에서 먼저 찾아줘 (order, payment, point 패키지)
- 실제 DDL이 필요하면 해당 테이블만 조회해줘

🔥 JPA를 쓴다면 엔티티가 스키마 문서다.

@Entity 클래스를 읽는 편이
DB에 붙는 것보다 싸고 정확하다.

다만 둘이 어긋나 있을 수 있다.
레거시에서는 흔하다.

OrderEntity 와 실제 orders 테이블의 컬럼이 일치하는지 확인해줘.
차이가 있으면 목록만 보여줘.

쿼리 — 잘 쓰지만 계획은 모른다

Agent는 쿼리를 잘 쓴다.

JPQL, QueryDSL, 네이티브 쿼리 모두
문법적으로 정확하게 만든다.

⚠️ 그런데 그 쿼리가 어떻게 실행되는지는 모른다.

인덱스가 있는지, 데이터가 몇 건인지,
카디널리티가 어떤지 코드에는 없다.

그래서 습관 하나가 필요하다.

이 쿼리의 실행 계획을 확인해줘.

EXPLAIN 결과를 보여주고,
풀스캔이 있으면 어떤 인덱스가 필요한지 알려줘.

로컬 DB에 운영과 비슷한 데이터가 없으면
실행 계획도 의미가 없다.

그 사실을 CLAUDE.md 에 적어둔다.

- 로컬 DB는 데이터가 적어 실행 계획이 운영과 다르다
  쿼리 성능 판단은 사람에게 확인을 요청한다

마이그레이션이 특별한 이유

DB 작업에서 유일하게 되돌릴 수 없는 부분이다.

flowchart LR
    A[마이그레이션 작성] -->|Agent| B[검토]
    B -->|사람| C[실행]
    C -->|사람| D[운영 반영]

Agent는 작성까지만 한다.

# CLAUDE.md
- 마이그레이션 파일 작성까지만 한다. 실행하지 않는다
- `flyway migrate`, `liquibase update` 를 실행하지 않는다

{
  "permissions": {
    "deny": [
      "Bash(./gradlew flywayMigrate:*)",
      "Bash(psql:*)"
    ]
  }
}

7장의 원칙 그대로다.

되돌릴 수 없는 일은 사람이 결정한다.

위험한 마이그레이션 패턴

Agent가 만든 마이그레이션에서 반드시 확인할 것들이다.

⚠️ 두 번째와 세 번째가 배포 사고의 단골이다.

Agent는 최종 상태만 본다.
배포 중간에 구버전과 신버전이 함께 도는 시간을 고려하지 않는다.

확장-수축 패턴을 규칙으로

무중단 배포에서 쓰는 순서다.

이것을 CLAUDE.md 에 적어두면
Agent가 매번 맞게 만든다.

## 마이그레이션 규칙

컬럼 변경은 3단계로 나눈다 (배포 3회)

1. 확장: 새 컬럼 추가 (nullable, 기본값 없음)
2. 이행: 양쪽 쓰기 → 백필 → 읽기 전환
3. 수축: 구 컬럼 제거

- `NOT NULL` 은 백필 완료 후 별도 마이그레이션으로 건다
- 컬럼 rename은 하지 않는다 (추가 → 이행 → 제거)
- 100만 건 이상 테이블 인덱스는 온라인 방식으로 생성한다

🔥 이 열 줄이 마이그레이션 사고의 대부분을 막는다.

Agent가 몰라서 틀리는 것이지,
알려주면 정확히 지킨다.

인덱스 판단은 사람이 한다

인덱스는 코드만 봐서는 결정할 수 없다.

그래서 이렇게 나눈다.

인덱스가 필요해 보이는 쿼리를 찾아줘.

- 어떤 컬럼 조합이 필요한지 후보만 제시해줘
- 기존 인덱스로 커버되는지 확인해줘
- 마이그레이션은 아직 만들지 마

후보 도출은 Agent가, 결정은 사람이.

트랜잭션 경계는 다음 장에서

DB 작업에서 가장 자주 나는 사고는
사실 쿼리도 마이그레이션도 아니다.

트랜잭션 경계다.

28장에서 따로 다룬다.

완료 조건 예시

## Acceptance Criteria
- 마이그레이션 파일이 V32 번호로 생성됨 (실행하지 않음)
- 로컬에서 `flyway migrate` 를 사람이 실행해 성공 확인
- 롤백 스크립트 또는 되돌리는 방법이 문서화됨
- 신규 컬럼은 nullable, 기본값 없음
- 기존 24개 결제 테스트 통과

⚠️ 세 번째 항목을 자주 빠뜨린다.

되돌리는 방법이 없는 마이그레이션은
배포 후에 손이 묶인다.

이 장의 핵심

• DB 작업은 읽는 쪽과 쓰는 쪽의 성격이 다르다
• JPA 엔티티가 가장 싼 스키마 문서다 — 다만 실제 DDL과 어긋날 수 있다
• Agent는 쿼리를 잘 쓰지만 실행 계획은 모른다
• 로컬 데이터가 적으면 실행 계획도 신뢰할 수 없다 — 그 사실을 적어둔다
• 마이그레이션은 작성까지만 맡기고 실행은 사람이 한다
• Agent는 최종 상태만 보고 배포 중간 상태를 고려하지 않는다
• 확장-수축 3단계를 규칙으로 적어두면 대부분의 사고가 막힌다
• 인덱스 후보는 Agent가 뽑고 결정은 사람이 한다
• 되돌리는 방법이 없는 마이그레이션은 배포 후 손을 묶는다

28장. 트랜잭션과 동시성 — 경계 · Lock · Race Condition

이 장의 주제는 Agent가 가장 자주 틀리는 영역이다.

이유는 분명하다.

트랜잭션과 동시성 문제는
코드를 읽어서는 보이지 않는다.

컴파일도 되고, 테스트도 통과하고,
로컬에서 잘 돈다.

그리고 운영에서 터진다.

Agent는 순차 실행을 가정한다

이것이 이 장 전체의 전제다.

fun usePoint(userId: Long, amount: Long) {
    val point = pointRepository.findByUserId(userId)
    if (point.balance < amount) throw InsufficientPointException()
    point.balance -= amount
    pointRepository.save(point)
}

Agent에게 이 코드는 완벽하다.

잔액을 확인하고, 부족하면 예외를 던지고, 차감한다.
논리적으로 흠이 없다.

⚠️ 동시에 두 요청이 들어오면 둘 다 통과한다.

Agent가 이 문제를 못 보는 것이 아니다.
물어보면 정확히 설명한다.

묻지 않으면 떠올리지 않을 뿐이다.

동시성은 지시하지 않으면 고려되지 않는다.

전제를 문서로 박아둔다

가장 값싼 방어책이다.

# CLAUDE.md

## 실행 환경 전제

- 이 서비스는 항상 2대 이상의 인스턴스로 뜬다
- 따라서 JVM 단위 동기화(`synchronized`, `ReentrantLock`)와
  로컬 캐시는 정합성 보장 수단이 될 수 없다
- 잔액·재고·상태 전이는 DB 락 또는 분산 락으로 보호한다

이 세 줄이 없으면 Agent는
synchronized 로 해결한 코드를 자신 있게 내놓는다.

단일 인스턴스에서는 실제로 통과한다.
그래서 더 위험하다.

@Transactional 4대 실수

Kotlin + Spring에서 반복되는 것들이다.

1️⃣ 자기 호출

fun cancel(orderId: Long) {
    this.doCancel(orderId)      // 프록시를 안 거친다
}

@Transactional
fun doCancel(orderId: Long) { ... }

트랜잭션이 아예 걸리지 않는다.
조용히.

2️⃣ 외부 호출을 트랜잭션 안에 둔다

@Transactional
fun pay(request: PayRequest) {
    val payment = paymentRepository.save(...)
    pgClient.request(payment)          // ← 3초 대기
    payment.status = PAID
}

15장에서 예시로 든 그 규칙이다.

커넥션을 물고 외부 응답을 기다린다.
PG가 느려지면 커넥션 풀이 마른다.

3️⃣ 조회에 readOnly 를 빠뜨린다

성능뿐 아니라 실수 방지 효과도 잃는다.

4️⃣ 경계를 너무 넓게 잡는다

@Transactional
fun processDailySettlement() {
    orders.forEach { ... }    // 10만 건
}

락 유지 시간이 길어지고, 실패하면 전부 롤백된다.

규칙으로 고정하기

네 가지 모두 문장으로 막을 수 있다.

## Transaction

- `@Transactional` 은 Facade 계층에만 붙인다
- 같은 클래스 내부 호출로 트랜잭션을 기대하지 않는다
- 외부 API·Redis·파일 I/O 는 트랜잭션 밖에서 한다
  (커넥션 풀 고갈 장애 이력 있음)
- 조회 전용은 `@Transactional(readOnly = true)`
- 배치성 반복 처리는 건별 트랜잭션으로 쪼갠다

15장에서 말한 대로 이유를 한 줄 붙인다.
세 번째 규칙이 Redis와 파일 I/O에도 응용된다.

Race Condition을 테스트로 증명한다

23장의 재현 테스트를 동시성에 적용하면 이렇게 된다.

@Test
fun `동시에 포인트를 사용해도 잔액보다 많이 차감되지 않는다`() {
    val userId = 사용자_생성(balance = 1_000)
    val executor = Executors.newFixedThreadPool(10)
    val latch = CountDownLatch(10)

    repeat(10) {
        executor.submit {
            try { pointService.usePoint(userId, 1_000) }
            catch (e: Exception) { /* 실패는 정상 */ }
            finally { latch.countDown() }
        }
    }
    latch.await()

    val balance = pointRepository.findByUserId(userId).balance
    assertThat(balance).isEqualTo(0)   // -9,000 이 되면 안 된다
}

🔥 이 테스트가 이 장의 핵심 도구다.

동시성 문제는 말로 설명하면 흐지부지되지만
실패하는 테스트가 있으면 논쟁이 끝난다.

Agent에게 이렇게 지시한다.

포인트 차감에 동시성 문제가 있는지 확인하고,
있다면 먼저 재현 테스트를 만들어줘.
스레드 10개로 동시 요청하는 형태로.

수정은 테스트가 실패하는 걸 확인한 다음에 하자.

락 선택은 사람이 한다

재현이 됐으면 해결 방법을 고른다.

⚠️ Agent는 이 중 하나를 골라 바로 적용한다.

대개 비관적 락이다.
가장 확실해 보이기 때문이다.

그런데 이 선택은 트래픽 패턴을 알아야 한다.
충돌 빈도, 트랜잭션 길이, 데드락 이력.

코드에 없는 정보다.

가능한 해결 방법을 세 가지 제시하고
각각의 단점을 알려줘. 적용은 내가 고른 다음에.

21장에서 대안을 물으라고 한 이유가 여기서도 작동한다.

데드락은 순서 문제다

여러 테이블을 잠그는 코드에서 나온다.

트랜잭션 A: orders → payments 순으로 잠금
트랜잭션 B: payments → orders 순으로 잠금

Agent에게 확인시킬 수 있다.

이 코드에서 여러 테이블을 잠그는 경로를 찾아줘.
잠그는 순서가 서로 다른 경로가 있으면 알려줘.

이런 정적 확인은 Agent가 사람보다 빠르다.
호출 경로를 전부 따라가는 일이기 때문이다.

완료 조건에 동시성을 넣는다

## Acceptance Criteria
- 동시 10요청 시 잔액이 음수가 되지 않는 테스트 통과
- 동시 취소 요청 시 환급이 1건만 발생하는 테스트 통과
- 트랜잭션 안에서 외부 호출이 없음을 확인
- 기존 포인트 테스트 18건 통과

⚠️ 세 번째 항목은 사람이 Diff로 확인한다.

42장에서 이런 규칙을 자동 검사로 만드는 방법을 다룬다.

이 장의 핵심

• 트랜잭션과 동시성 문제는 코드를 읽어서는 보이지 않는다
• Agent는 순차 실행을 가정한다 — 묻지 않으면 동시성을 떠올리지 않는다
• 인스턴스가 2대 이상이라는 전제를 문서로 박아둔다
• 그것이 없으면 synchronized 로 해결한 코드가 나온다 — 로컬에서는 통과한다
• 자기 호출·외부 호출 포함·readOnly 누락·넓은 경계가 4대 실수다
• 동시성 문제는 재현 테스트가 있으면 논쟁이 끝난다
• 락 선택은 트래픽 패턴을 알아야 하므로 사람이 결정한다
• Agent는 대개 비관적 락을 고른다 — 가장 확실해 보이기 때문이다
• 잠금 순서가 다른 경로를 찾는 정적 확인은 Agent가 사람보다 빠르다

29장. 도메인 규칙을 깨뜨리지 않게 — Invariant와 Edge Case

28장의 문제는 코드에 안 보이는 것이었다.

이 장의 문제는 더 나아간다.

어디에도 안 적혀 있다.

우리 팀 사람들의 머릿속에만 있다.

도메인 규칙이 숨어 있는 곳

"부분 취소는 최대 3번까지만 돼요"
"포인트로 결제한 건은 포인트로만 환급해요"
"배송 시작 후에는 취소가 아니라 반품이에요"
"쿠폰은 취소해도 복구 안 해줘요. 정책이 그래요"

이 네 줄이 코드 어디에 있는가.

• 첫 번째는 if (cancelCount >= 3) 로 흩어져 있다
• 두 번째는 Service 중간에 조건문으로 들어 있다
• 세 번째는 상태 전이 로직 안에 있다
• 네 번째는 아예 없다. 그냥 구현하지 않았다

Agent가 이것을 알 방법은 없다.

⚠️ 그리고 모르면 일반 상식으로 대체한다.

“취소하면 쿠폰도 복구해주는 게 맞겠지” 라고 판단하고
친절하게 복구 로직을 추가한다.

Agent가 도메인 규칙을 어기는 세 가지 방식

세 번째가 가장 자주 일어난다.

Agent는 대표 케이스를 정확히 구현하고
경계값에서 무너진다.

정상: 10,000원 중 3,000원 포인트 사용 → 비례 배분
경계: 10,000원 전액 포인트 사용     → 카드 환불 0원 요청 발생

Invariant를 문장으로 꺼낸다

이 장의 핵심 작업이다.

불변식은 “항상 참이어야 하는 것” 이다.

## 주문 도메인 불변식

- 주문 금액 = 상품 금액 합 - 할인 - 포인트 사용액
- 취소된 금액의 합은 결제 금액을 초과할 수 없다
- 포인트 환급액은 사용액을 초과할 수 없다
- 배송 시작된 주문은 취소 상태로 갈 수 없다
- 취소 이력은 삭제되지 않는다 (감사 대상)

이 다섯 줄을 어디에 두는가.

16장의 계층화가 여기서 쓰인다.

src/main/kotlin/order/CLAUDE.md

도메인 옆에 둔다.
그 도메인을 건드릴 때만 실려 간다.

Agent에게 꺼내게 시킨다

머릿속에서 다 꺼내기는 어렵다.
Agent가 코드에서 후보를 뽑아줄 수 있다.

주문 취소 로직에서 도메인 규칙으로 보이는 조건들을 찾아줘.

- 매직넘버, if 조건, 예외 발생 지점을 근거로
- 각 조건이 어떤 규칙을 표현하는지 추정해줘
- 파일과 줄 번호를 함께 적어줘
- 규칙끼리 서로 모순되는 곳이 있으면 표시해줘

수정은 하지 마.

마지막 요구가 흥미로운 결과를 준다.

레거시에서는 같은 규칙이
세 곳에서 서로 다르게 구현되어 있는 경우가 많다.

OrderCancelFacade:88     cancelCount >= 3
AdminOrderService:203    cancelCount > 3      ← 다르다
BatchCancelJob:41        제한 없음            ← 아예 없다

🔥 이 목록이 나오면 그 자체로 가치가 있다.

Agent를 도입하지 않았어도 필요했던 정리다.

규칙을 고정하는 세 가지 수단

강한 순서대로다.

flowchart TB
    T[타입<br/>애초에 표현 불가] --> TE[테스트<br/>어기면 실패]
    TE --> D[문서<br/>읽어야 지킴]

타입으로 막기

Kotlin의 강점이 여기서 나온다.

@JvmInline
value class Money(val amount: Long) {
    init { require(amount >= 0) { "금액은 음수일 수 없다" } }
}

sealed interface OrderStatus {
    data object Created : OrderStatus
    data object Paid : OrderStatus
    data object Shipped : OrderStatus
    data object Cancelled : OrderStatus
}

Money 를 쓰면 음수 금액이 애초에 만들어지지 않는다.
Agent가 실수할 여지 자체가 사라진다.

문서로 지키게 하는 것보다
타입으로 못 하게 하는 편이 강하다.

상태 전이를 코드로

fun OrderStatus.canTransitTo(next: OrderStatus): Boolean = when (this) {
    Created -> next in setOf(Paid, Cancelled)
    Paid -> next in setOf(Shipped, Cancelled)
    Shipped -> next == Returned          // 취소 불가
    Cancelled, Returned -> false
}

이 함수가 있으면
“배송 후에는 취소가 아니라 반품” 이 코드가 된다.

Agent가 새 경로를 만들어도 이 함수를 거치면 막힌다.

테스트로 고정

타입으로 표현 못 하는 규칙은 테스트로 간다.

@Test
fun `취소 금액 합계는 결제 금액을 초과할 수 없다`() { ... }

@Test
fun `전액 포인트 결제 건은 카드 환불을 요청하지 않는다`() { ... }

두 번째가 아까의 경계값이다.

Edge Case를 먼저 요구한다

구현 전에 목록을 받아두면 사고가 줄어든다.

주문 취소 로직을 수정하기 전에,
경계 케이스 목록부터 만들어줘.

- 금액이 0인 경우
- 전액 포인트 결제
- 이미 취소된 주문
- 부분 취소가 여러 번 누적된 경우
- 결제와 취소가 동시에 들어온 경우

이 외에 놓치기 쉬운 것도 추가해줘.
각각 현재 코드가 어떻게 동작하는지도 확인해줘.

⚠️ 마지막 문장이 중요하다.

목록만 받으면 “이론적으로 있을 수 있는 케이스” 가 나온다.
현재 동작까지 확인시키면 실제 문제가 드러난다.

규칙과 요구사항의 충돌

가끔 이런 일이 생긴다.

요구사항: 배송 시작된 주문도 취소 가능하게 해주세요
불변식:   배송 시작된 주문은 취소 상태로 갈 수 없다

Agent는 요구사항을 따른다.
불변식을 조용히 수정한다.

이것을 막는 규칙이 필요하다.

- 불변식과 충돌하는 요구사항이 오면
  구현하지 말고 충돌 내용을 보고한다

이 한 줄이 도메인 지식을 지킨다.

이 장의 핵심

• 도메인 규칙은 코드에 안 보일 뿐 아니라 어디에도 안 적혀 있다
• 모르면 Agent는 일반 상식으로 대체한다 — 없던 로직을 친절하게 추가한다
• Agent는 대표 케이스를 정확히 구현하고 경계값에서 무너진다
• 불변식을 문장으로 꺼내 도메인 디렉터리의 CLAUDE.md 에 둔다
• 코드에서 규칙 후보를 뽑는 일은 Agent가 잘한다 — 모순도 함께 찾아준다
• 같은 규칙이 세 곳에서 다르게 구현된 목록은 그 자체로 가치가 있다
• 고정 수단은 타입 > 테스트 > 문서 순으로 강하다
• value class 와 sealed 상태 전이 함수가 실수 여지를 없앤다
• 경계 케이스는 현재 동작 확인까지 함께 요구해야 실제 문제가 드러난다
• 불변식과 충돌하는 요구사항은 구현이 아니라 보고 대상이다

30장. 외부 연동과 복원력 — Timeout · Retry · 멱등성 · Circuit Breaker

Agent는 happy path를 아주 잘 만든다.

fun pay(request: PayRequest): PayResult {
    val response = pgClient.request(request)
    return PayResult.from(response)
}

깔끔하다.

그리고 외부 시스템은 이 코드가 가정한 대로
동작하지 않는다.

반드시 물어야 하는 네 가지

외부 연동 코드를 볼 때마다 던지는 질문이다.

🔥 세 번째와 네 번째가 백엔드의 진짜 문제다.

앞의 둘은 설정이지만
뒤의 둘은 설계다.

Agent는 앞의 둘을 잘 붙이고
뒤의 둘은 묻지 않으면 다루지 않는다.

타임아웃 없는 코드를 찾는다

Agent가 잘하는 정적 확인 작업이다.

외부 시스템을 호출하는 코드를 전부 찾아줘.

- HTTP 클라이언트, 메시지 발행, Redis, 파일 저장소 전부
- 각각의 연결 타임아웃과 읽기 타임아웃 설정값을 표로 만들어줘
- 설정이 없는 곳은 "미설정" 으로 표시해줘

수정은 하지 마.

레거시에서 이 표를 처음 뽑으면
대개 절반이 “미설정” 이다.

기본값이 무한대인 클라이언트가 섞여 있다.

재시도의 전제는 멱등성이다

여기가 이 장에서 가장 중요하다.

재시도 = 같은 요청을 다시 보낸다

받는 쪽이 두 번 처리하면
재시도는 개선이 아니라 사고다.

⚠️ Agent는 이 순서를 뒤집는다.

@Retryable 을 먼저 붙이고,
멱등성은 언급하지 않는다.

지시로 순서를 고정한다.

PG 호출에 재시도를 추가하려고 해.

먼저 확인해줘:
- 이 API가 멱등한가 (같은 요청 두 번 = 한 번과 같은가)
- 멱등키를 보내고 있는가
- PG 문서상 재시도 안전한 응답 코드는 무엇인가

멱등성이 보장되지 않으면 재시도를 붙이지 말고 알려줘.

무엇을 재시도하고 무엇을 안 하는가

⚠️ 타임아웃이 까다롭다.

요청은 도달했는데 응답만 못 받았을 수 있다.
저쪽에서는 성공한 상태다.

그래서 타임아웃 재시도는
멱등키가 있을 때만 안전하다.

이 판단을 규칙으로 적어둔다.

## 외부 연동

- 재시도는 멱등키가 있는 요청에만 적용한다
- 4xx 는 재시도하지 않는다 (429 제외)
- 재시도는 최대 3회, 지수 백오프
- 타임아웃은 반드시 명시한다 (기본값에 의존하지 않는다)
- 외부 호출은 트랜잭션 밖에서 한다 (28장)

실패했을 때 우리 상태

Agent가 가장 자주 빠뜨리는 부분이다.

@Transactional
fun pay(request: PayRequest) {
    val payment = paymentRepository.save(Payment.pending(request))
    val result = pgClient.request(request)   // 여기서 타임아웃
    payment.complete(result)                 // 실행 안 됨
}

payment 는 PENDING 으로 남는다.

그런데 PG 쪽에서는 결제가 성공했을 수 있다.

이 불일치를 어떻게 해소하는가.

외부 호출이 타임아웃됐을 때
우리 데이터가 어떤 상태로 남는지 확인해줘.

- 저쪽은 성공했는데 우리는 모르는 경우가 가능한가
- 그 상태를 나중에 어떻게 확인하는가 (조회 API가 있는가)
- 그 확인은 누가 언제 하는가 (배치? 사용자 재조회?)

세 번째 질문의 답이 없으면
그 데이터는 영원히 애매한 상태로 남는다.

대개 답은 정합성 배치다.
그리고 그 배치를 만드는 것까지가 이 작업의 범위다.

Circuit Breaker

외부가 죽었을 때 우리까지 죽지 않게 한다.

Agent는 이것을 잘 붙인다.
설정값만 정해주면 된다.

- 실패율 50% 이상, 최소 20건 → Open
- Open 유지 30초 → Half-Open
- 폴백: 결제는 폴백 없음(즉시 실패), 조회는 캐시된 값

⚠️ 폴백 정책이 도메인 판단이다.

조회는 옛 데이터를 주는 편이 나을 수 있지만
결제는 절대 아니다.

Agent에게 맡기면 “안전하게” 폴백을 넣는다.

실패를 테스트한다

30장의 완료 조건은 실패 시나리오로 채워진다.

@Test
fun `PG 타임아웃 시 3회까지 재시도한다`() {
    mockPg.enqueue(MockResponse().setSocketPolicy(NO_RESPONSE))
    ...
}

@Test
fun `잔액 부족 응답은 재시도하지 않는다`() { ... }

@Test
fun `같은 멱등키로 재시도해도 결제는 1건만 생성된다`() { ... }

@Test
fun `PG 장애 시 서킷이 열려 즉시 실패한다`() { ... }

MockWebServer나 WireMock으로
지연·에러·연결 끊김을 주입한다.

🔥 실패 주입 테스트가 없으면
복원력 코드는 검증된 적 없는 코드다.

실제 호출은 막는다

7장의 금지 목록에 반드시 들어간다.

- 외부 PG·알림·메시지 API를 실제로 호출하지 않는다
- 테스트는 MockPgClient 또는 MockWebServer 로만 한다
- 샌드박스 환경 호출도 사람이 수동으로만 한다

⚠️ 알림 API가 특히 위험하다.

Agent가 테스트하다가
실제 고객에게 문자가 나간다.

되돌릴 수 없는 일이다.

이 장의 핵심

• Agent는 happy path를 잘 만들고 외부 시스템은 그대로 동작하지 않는다
• 타임아웃·재시도는 설정이고, 멱등성·실패 후 상태는 설계다
• Agent는 설정은 잘 붙이고 설계는 묻지 않으면 다루지 않는다
• 타임아웃 미설정 코드를 찾는 정적 확인은 Agent가 빠르다
• 재시도의 전제는 멱등성이다 — 순서를 지시로 고정한다
• 타임아웃은 요청이 도달했을 수 있어서 멱등키 없이는 재시도가 위험하다
• 실패 후 우리 상태가 애매하게 남는지, 누가 언제 해소하는지까지가 작업 범위다
• 폴백 정책은 도메인 판단이다 — 조회와 결제의 답이 다르다
• 실패 주입 테스트가 없으면 복원력 코드는 검증된 적 없는 코드다
• 알림 API 호출은 되돌릴 수 없다 — 권한으로 막는다

31장. 캐시와 비동기 처리 — Redis · Queue · Worker · DLQ

이 장의 두 주제에는 공통점이 있다.

추가하기는 쉽고 되돌리기는 어렵다.

캐시를 붙이는 코드는 세 줄이고,
그 캐시가 만든 정합성 문제는 몇 달 뒤에 나타난다.

Agent는 세 줄을 아주 잘 쓴다.

캐시는 정합성 부채다

@Cacheable("product")
fun getProduct(id: Long): Product = productRepository.findById(id)

Agent에게 “이 조회가 느려” 라고 하면
이 코드가 나온다.

즉시 빨라진다.

⚠️ 그리고 상품 정보를 수정해도 반영되지 않는다.

캐시를 추가할 때 함께 결정해야 하는 것이 넷이다.

네 번째가 도메인 판단이다.

상품 이름은 5분 늦어도 되지만
재고와 가격은 그렇지 않다.

이 데이터를 캐시하려고 해.

먼저 물어볼게:
- 이 값이 바뀌는 경로를 전부 찾아줘
- 각 경로에서 무효화가 필요한지 판단해줘
- 몇 초까지 옛 값이 보여도 되는지는 내가 정할게

첫 번째 요구가 핵심이다.

🔥 캐시 사고의 대부분은
무효화를 안 한 경로가 하나 남아서 생긴다.

Agent는 그 경로를 전부 찾는 일을 잘한다.

로컬 캐시는 분산 환경에서 위험하다

28장의 전제가 여기서도 작동한다.

private val cache = ConcurrentHashMap<Long, Product>()

인스턴스가 2대면 캐시도 2벌이다.

한쪽에서 무효화해도 다른 쪽은 옛 값을 준다.

# CLAUDE.md
- 캐시는 Redis 를 쓴다. 애플리케이션 로컬 캐시를 새로 만들지 않는다
  (인스턴스가 여러 대이므로 무효화가 전파되지 않는다)

캐시 스탬피드

TTL이 만료되는 순간 요청이 몰리면
전부 DB로 간다.

캐시 만료 → 100개 요청 동시 도착 → DB에 100개 쿼리

Agent는 이 문제를 묻기 전에는 다루지 않는다.

트래픽이 큰 키에서만 신경 쓰면 된다.

이 캐시 키에 요청이 몰릴 가능성이 있어.
만료 시점에 DB로 몰리지 않게 하려면 어떤 방법이 있어?
각각의 복잡도와 함께 알려줘.

메시지는 세 가지를 보장하지 않는다

비동기 처리로 넘어간다.

Agent가 만드는 Consumer는 대개 이렇게 생겼다.

@KafkaListener(topics = ["order-cancelled"])
fun handle(event: OrderCancelledEvent) {
    pointService.refund(event.orderId, event.point)
}

논리적으로 맞다.

그리고 메시지 시스템은 세 가지를 보장하지 않는다.

1장부터 따라온 그 버그가
여기서 또 다른 형태로 나타난다.

Consumer는 멱등해야 한다

30장의 원칙이 그대로 적용된다.

@KafkaListener(topics = ["order-cancelled"])
fun handle(event: OrderCancelledEvent) {
    if (pointHistoryRepository.existsByEventId(event.id)) return
    pointService.refund(event.orderId, event.point, event.id)
}

처리 이력을 남기고 중복을 걸러낸다.

- 모든 Consumer 는 멱등해야 한다
  이벤트 ID 또는 비즈니스 키로 중복 처리를 방어한다
- 이벤트 처리는 재시도를 전제로 작성한다

⚠️ 이 규칙이 없으면 Agent는
“메시지는 한 번 온다” 를 전제로 코드를 쓴다.

로컬 테스트에서는 실제로 한 번 온다.

순서와 유실

나머지 두 가지도 처리 방법이 있다.

DLQ를 만들 때 함께 정할 것이 있다.

DLQ에 쌓인 메시지는 누가 언제 보는가.

🔥 이 질문에 답이 없는 DLQ는
메시지를 조용히 버리는 곳이다.

Agent에게 DLQ를 만들라고 하면 만든다.
모니터링과 재처리 절차까지는 만들지 않는다.

비동기는 테스트하기 어렵다

그래서 테스트 전략을 미리 정해둔다.

세 번째와 네 번째가 이 장의 핵심 테스트다.

@Test
fun `같은 취소 이벤트가 두 번 와도 환급은 한 번만 발생한다`() {
    val event = OrderCancelledEvent(id = "evt-1", ...)

    handler.handle(event)
    handler.handle(event)      // 중복 수신

    assertThat(pointHistories).hasSize(1)
}

⚠️ 이 테스트가 없으면
멱등성 코드는 검증된 적 없는 코드다.

30장과 같은 결론이다.

동기와 비동기의 선택

마지막으로 짚을 것이 하나 있다.

Agent에게 “이 처리를 비동기로 바꿔줘” 라고 하면
아주 잘 바꿔준다.

그런데 비동기로 바꾸는 순간
이 장의 모든 문제가 따라온다.

비동기로 바꾸기 전에 확인하자.

- 이 처리가 실패하면 사용자가 알아야 하는가
- 순서가 중요한가
- 결과를 언제까지 보장해야 하는가

셋 다 아니면 비동기가 맞고,
하나라도 해당하면 동기로 두는 게 낫지 않을까?

비동기는 성능 개선이 아니라
결합도와 정합성의 교환이다.

이 판단은 사람이 한다.

이 장의 핵심

• 캐시와 비동기는 추가하기 쉽고 되돌리기 어렵다
• 캐시는 키·TTL·무효화 시점·허용 지연 넷을 함께 정해야 한다
• 캐시 사고의 대부분은 무효화가 안 된 경로 하나가 남아서 생긴다
• 값이 바뀌는 경로를 전부 찾는 일은 Agent가 잘한다
• 로컬 캐시는 인스턴스가 여러 대면 무효화가 전파되지 않는다
• 메시지는 한 번만·순서대로·반드시 도착하지 않는다
• Consumer는 멱등해야 한다 — 로컬 테스트에서는 메시지가 한 번 온다
• 누가 언제 보는지 정하지 않은 DLQ는 메시지를 조용히 버리는 곳이다
• 중복 수신과 순서 역전 테스트가 없으면 멱등성 코드는 미검증 코드다
• 비동기 전환은 성능 개선이 아니라 결합도와 정합성의 교환이다

32장. 인증과 보안 — Token · Secret · Injection · 개인정보

보안 결함에는 다른 결함과 구별되는 성질이 하나 있다.

조용하다.

권한 체크가 빠진 API는 테스트를 통과한다.
빌드도 되고, 응답도 정상이고, 아무도 모른다.

누군가 찾아낼 때까지.

Agent가 만드는 코드에서
이 성질이 특히 위험해진다.

가장 흔한 실패는 권한 누락이다

26장에서 API를 복제할 때 이런 일이 생긴다.

// 참고한 API
@GetMapping("/orders/{id}")
@PreAuthorize("@orderAuth.canRead(#id)")
fun getOrder(@PathVariable id: Long) = ...

// Agent가 만든 API
@GetMapping("/orders/{id}/payments")
fun getPayments(@PathVariable id: Long) = ...   // 권한 체크 없음

⚠️ 애노테이션 하나가 빠졌다.

기능은 완벽하게 동작한다.
남의 주문 결제 내역도 아주 잘 조회된다.

이것을 막는 방법은 셋이다.

# CLAUDE.md
- 모든 조회·수정 API는 리소스 소유자 검증을 거친다
- 신규 엔드포인트는 `@PreAuthorize` 또는 명시적 권한 검사가 필수다
- 권한 검사를 생략해야 하는 경우 이유를 주석으로 남긴다

# 작업 지시
이 API에 필요한 권한 검사를 명시해줘.
참고한 API와 권한 정책이 같아야 해.

// 테스트
@Test
fun `다른 사용자의 주문 결제 내역은 조회할 수 없다`() { ... }

🔥 세 번째가 가장 강하다.

권한 테스트는 API마다 한 건씩 쌓아두면
Agent가 새 API를 만들 때 같은 패턴을 복제한다.

시크릿은 Context에 넣지 않는다

7장에서 deny 목록에 넣은 이유다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./src/main/resources/application-prod.yml)",
      "Read(**/*credentials*)",
      "Bash(env)",
      "Bash(printenv:*)"
    ]
  }
}

한 번 읽히면 그 세션 내내 Context에 남는다.
대화 기록에도 남는다.

⚠️ 그리고 Agent가 만든 코드에서도 확인한다.

이번 변경에서 다음이 없는지 확인해줘.

- 하드코딩된 키·토큰·비밀번호
- 테스트 코드의 실제 자격증명
- 설정 파일에 추가된 평문 값
- 로그에 시크릿이 찍히는 코드

두 번째가 자주 나온다.

Agent가 테스트를 만들면서
"test-api-key-abc123" 같은 값을 넣는데,
그게 실제 개발 환경 키인 경우가 있다.

Injection

Agent는 대개 파라미터 바인딩을 쓴다.

문제는 레거시를 흉내 낼 때다.

// 기존 코드에 이런 게 있으면
val sql = "SELECT * FROM orders WHERE status = '$status'"

// Agent가 같은 스타일로 새 쿼리를 만든다

26장에서 말한 그 문제다.
지목한 파일이 나쁘면 나쁜 패턴이 복제된다.

- 네이티브 쿼리에 문자열 연결을 쓰지 않는다
  기존 코드에 있어도 새 코드는 파라미터 바인딩을 쓴다
- 동적 정렬·필터는 화이트리스트로 검증한다

두 번째가 놓치기 쉽다.

// 정렬 컬럼을 그대로 받으면 SQL이 뚫린다
fun findOrders(sortBy: String) = 
    jdbcTemplate.query("SELECT * FROM orders ORDER BY $sortBy")

개인정보가 새는 세 곳

첫 번째가 압도적으로 많다.

24장에서 로그를 피드백으로 쓰라고 했는데,
그 로그에 주민번호가 들어가면 안 된다.

- 요청·응답 객체를 통째로 로그에 찍지 않는다
- 개인정보(이름·연락처·주소·카드번호)는 마스킹한다
- 마스킹 유틸은 `common/log/Masking.kt` 를 쓴다

두 번째는 26장의 “엔티티 직접 반환” 과 같은 뿌리다.

한 규칙이 두 문제를 막는다.

보안 리뷰는 별도 세션으로

18장에서 구현 세션과 Review 세션을 나눴다.

보안은 그 분리가 특히 중요하다.

구현 세션에는
“이렇게 하기로 했다” 는 합의가 쌓여 있다.

같은 Context에서 보안 검토를 시키면
그 합의를 근거로 “문제 없습니다” 를 확인한다.

# 새 세션에서
@.git 의 최근 커밋 3개 Diff만 읽고 보안 관점에서 검토해줘.

확인할 것:
- 인증·인가 검사 누락
- 입력 검증 누락
- 시크릿 하드코딩
- 개인정보 로깅·노출
- SQL/커맨드 injection
- 권한 상승 가능 경로

각 항목마다 확인했음/문제있음 을 명시하고,
문제는 파일과 줄 번호를 함께 알려줘.

⚠️ 마지막 요구가 중요하다.

“특별한 문제가 없습니다” 만 오면
검토를 한 것인지 알 수 없다.

항목별로 답하게 하면 빠뜨린 것이 보인다.

이 요청은 48장에서 Skill로 만들기 좋은 형태다.

Agent에게 맡기지 않는 것

이 영역에는 위임 금지선이 있다.

Agent가 잘하는 것은 다른 쪽이다.

• 누락 찾기 (권한 체크 없는 엔드포인트 목록)
• 패턴 검색 (문자열 연결 쿼리 전수 조사)
• 일관성 확인 (같은 리소스인데 정책이 다른 곳)

보안에서 Agent는 설계자가 아니라
아주 성실한 점검자다.

이 장의 핵심

• 보안 결함은 조용하다 — 테스트도 통과하고 응답도 정상이다
• 가장 흔한 실패는 API 복제 과정의 권한 검사 누락이다
• 권한 테스트를 API마다 쌓아두면 Agent가 그 패턴을 복제한다
• 시크릿은 한 번 읽히면 세션 내내 Context와 대화 기록에 남는다
• 테스트 코드에 실제 개발 환경 키가 들어가는 사고가 자주 난다
• 나쁜 레거시 패턴을 지목하면 injection 취약점이 복제된다
• 동적 정렬·필터 컬럼은 화이트리스트로 검증한다
• 개인정보는 로그·응답·테스트 fixture 세 곳으로 샌다
• 보안 검토는 구현과 다른 세션에서, 항목별로 답하게 한다
• Agent는 보안의 설계자가 아니라 성실한 점검자다

33장. 장애와 성능 분석 — 로그에서 Root Cause까지, Slow Query와 N+1

6부의 마지막 장이다.

앞의 일곱 장은 Agent가 실수하는 지점을 다뤘다.

이 장은 반대다.

Agent가 사람보다 확실히 잘하는 영역이 있다.

왜 이 영역에서 강한가

장애 분석은 두 가지 일의 반복이다.

넓게 훑기 → 가설 세우기 → 확인 → 다시 훑기

이 중 첫 번째가 사람에게는 지루하고 느리다.

호출 경로를 열 단계 따라가고,
로그 형식이 다른 파일 세 개를 대조하고,
비슷한 이름의 메서드 여섯 개를 구별하는 일.

Agent는 이것을 지치지 않고 한다.

🔥 그리고 가설을 여러 개 동시에 세운다.

사람은 하나를 붙잡고 파는데,
Agent는 다섯 개를 나열하고 각각의 확인 방법을 제시한다.

장애 분석의 순서

flowchart LR
    A[증상] --> B[시간·범위 특정]
    B --> C[로그]
    C --> D[코드 경로]
    D --> E[가설]
    E --> F[재현 테스트]
    F --> G[수정]

F 가 종착점이다.
재현 테스트 없이 수정하면 고쳤는지 알 수 없다.

23장의 원칙이 장애 대응에서도 그대로다.

증상부터 정확히 준다

가장 흔한 실수는 결론을 먼저 주는 것이다.

# ❌ 결론을 준 지시
포인트 환급 로직에 버그가 있는 것 같아. 찾아줘.

# ✅ 증상을 준 지시
어제 14시경 일부 사용자의 포인트 잔액이 음수가 됐어.

- 발생 건수: 12건
- 공통점: 전부 부분 취소를 2회 이상 한 주문
- 로그: PointHistory 에 REFUND 가 3건씩 있음
- 정상 케이스와의 차이는 아직 모름

원인 가설을 세워줘. 코드는 아직 고치지 마.

⚠️ 결론을 주면 Agent는 그 결론을 뒷받침한다.

12장에서 본 오염이 시작부터 들어가는 것이다.

증상만 주면 우리가 생각 못 한 경로를 찾아온다.

로그는 잘라서 준다

13장의 원칙이다.

# ❌
docker logs order-service > all.log        # 200MB

# ✅
docker logs order-service --since 14:00 --until 14:30 \
  | grep "8f3a91c2" | head -100

24장에서 traceId 를 강조한 이유가 여기서 회수된다.

추적 ID가 있으면 한 요청의 전체 흐름을
100줄 안으로 뽑을 수 있다.

없으면 시간 범위로 자르고, 그래도 크면
Agent에게 먼저 필터 조건을 만들게 한다.

이 장애와 관련된 로그를 찾으려고 해.
어떤 키워드로 grep 하면 좋을지 먼저 알려줘.

가설을 여러 개 받는다

Agent의 강점을 쓰는 방법이다.

가능한 원인을 3개 이상 제시해줘.

각각에 대해:
- 근거가 되는 코드 위치 (파일:줄)
- 이 가설이 맞다면 로그에 무엇이 남아 있어야 하는가
- 어떻게 확인할 수 있는가

가장 유력한 것부터 정렬해줘.

두 번째 항목이 특히 유용하다.

가설을 반증 가능한 형태로 만들면
확인이 빨라진다.

가설 2: 부분 취소 시 이전 취소분을 차감하지 않는다
  → 맞다면 3번째 취소의 refundAmount 가
     남은 금액보다 클 것
  → 확인: PointHistory 의 금액 합 vs 원 결제 금액

재현이 종착점

원인을 찾았으면 테스트로 만든다.

이 원인이 맞다면 재현되는 테스트를 만들어줘.
부분 취소를 3회 하는 시나리오로.

지금은 실패해야 정상이야.

실패를 확인한 다음에 수정한다.

9장과 같은 흐름이고,
장애 대응에서 이 순서를 지키기가 더 어렵다.

⚠️ 급하기 때문이다.

그래서 규칙으로 적어둘 가치가 있다.

- 장애 수정은 재현 테스트를 먼저 만든 뒤에 한다
  (핫픽스가 급하면 수정을 먼저 하되, 테스트 추가 없이 종료하지 않는다)

괄호 안이 현실적인 타협이다.

성능 — 측정 없이 최적화하지 않는다

여기서 Agent의 성향이 함정이 된다.

“이 API가 느려” 라고 하면
Agent는 즉시 개선안을 낸다.

캐시를 붙이고, 쿼리를 합치고, 인덱스를 제안한다.

⚠️ 전부 그럴듯하고, 대개 원인이 아니다.

# ❌
주문 목록 API가 느려. 개선해줘.

# ✅
주문 목록 API가 느려 (p95 1.8초).

먼저 원인을 특정하자.
- 실행되는 쿼리를 전부 찾아줘 (JPA 로그 기준)
- 쿼리 개수와 각각의 실행 계획을 확인해줘
- 애플리케이션 로직에서 느릴 만한 곳도 확인해줘

개선안은 원인이 확인된 다음에.

N+1은 Agent가 잘 찾는다

가장 흔한 성능 문제이자
정적 분석으로 잡히는 문제다.

주문 목록 조회에서 N+1이 발생하는 지점을 찾아줘.

- 엔티티 연관관계의 fetch 전략을 확인해줘
- 루프 안에서 lazy 필드에 접근하는 곳을 찾아줘
- 실제 실행되는 쿼리 개수를 로그로 확인해줘

세 번째가 확인 단계다.

logging.level.org.hibernate.SQL=debug

쿼리 개수가 1 + N이면 확정이다.

해결 방법은 여러 개다.

Agent는 대개 fetch join 을 제안한다.
페이징이 있으면 그게 함정이다.

개선은 숫자로 확인한다

완료 조건에 측정을 넣는다.

## Acceptance Criteria
- 주문 목록 조회 시 실행 쿼리 3개 이하 (기존 41개)
- 로컬 1,000건 데이터에서 응답 200ms 이하
- 실행 계획에 풀스캔 없음
- 기존 주문 테스트 32건 통과

⚠️ 로컬 측정은 참고값이다.

27장에서 말한 대로 데이터 분포가 다르다.
쿼리 개수는 신뢰할 수 있고, 시간은 아니다.

그래서 첫 번째 항목이 가장 확실한 기준이다.

6부를 마치며

여덟 장을 관통하는 패턴이 있다.

왼쪽에 맡기고 오른쪽을 지킨다.

이 구분이 7부와 8부에서
레거시를 다룰 때 그대로 이어진다.

이 장의 핵심

• 장애 분석은 Agent가 사람보다 확실히 잘하는 영역이다
• 지치지 않고 훑고, 가설을 여러 개 동시에 세운다
• 결론을 주면 Agent는 그 결론을 뒷받침한다 — 증상만 준다
• traceId 가 있으면 한 요청 흐름을 100줄로 뽑을 수 있다
• 가설은 반증 가능한 형태로 받는다 — “맞다면 무엇이 남아 있어야 하는가”
• 재현 테스트가 장애 분석의 종착점이다
• 급할수록 이 순서를 어기게 되므로 규칙으로 적어둔다
• “느려” 라고만 하면 그럴듯하고 대개 틀린 개선안이 나온다
• N+1은 쿼리 개수로 확정하고, fetch join 은 페이징과 함께 쓸 때 함정이 있다
• 로컬에서 쿼리 개수는 신뢰할 수 있고 응답 시간은 참고값이다

34장. 문서 없는 레거시를 Agent와 함께 읽기 — Entry Point에서 Side Effect까지

8장에서 첫날을 보냈다.

CLAUDE.md 초안과 금지 목록을 만들었고,
개략적인 구조를 파악했다.

이제 본격적인 조사다.

목적이 달라졌기 때문이다.

8장의 목적: Agent가 일할 수 있게 만들기
34장의 목적: 경계를 그을 수 있을 만큼 이해하기

레거시를 읽는 일이 어려운 이유

⚠️ 뒤의 두 줄이 Agent에게 특히 위험하다.

Agent는 읽은 코드를 모두 유효한 것으로 취급하는데,
레거시에서는 그 절반이 유효하지 않다.

12장의 Context Pollution이 여기서 실제 피해가 된다.
그래서 조사 단계에서 무엇이 살아 있는지를 함께 확인해야 한다.

진입점을 전수 조사한다

모든 흐름은 진입점에서 시작한다.

그런데 진입점은 Controller만이 아니다.

이 프로젝트의 진입점을 전부 찾아줘. 종류별로 나눠서.

- HTTP: @RestController, @Controller
- 메시지: @KafkaListener, @RabbitListener, @SqsListener
- 스케줄러: @Scheduled, Quartz Job
- 배치: Spring Batch Job, main 함수를 가진 클래스
- 이벤트: @EventListener, @TransactionalEventListener
- 관리자: 별도 포트나 경로로 열린 것
- 웹훅: 외부에서 호출하는 콜백 엔드포인트

각각 개수와 파일 위치를 표로 만들어줘.

🔥 이 목록에서 대개 놀란다.

Controller 40개는 알고 있었는데
스케줄러 17개와 이벤트 리스너 23개는 몰랐던 경우가 흔하다.

그리고 8장에서 만든 CLAUDE.md 의 구조 설명이
얼마나 부실했는지도 여기서 드러난다.

흐름 하나를 끝까지 따라간다

목록이 나오면 그중 하나를 정해 파고든다.

POST /orders/{id}/cancel 요청이 들어왔을 때
실제로 실행되는 코드를 순서대로 따라가줘.

- 각 단계의 파일과 메서드를 적어줘
- 조건에 따라 갈라지는 지점을 표시해줘
- 트랜잭션이 시작되고 끝나는 지점을 표시해줘
- 비동기로 넘어가는 지점을 표시해줘

마지막 두 요구가 백엔드 조사의 핵심이다.

OrderCancelController.cancel()
  └─ [TX 시작] OrderCancelFacade.cancel()
       ├─ OrderService.validateCancellable()
       │    └─ 분기: 배송 상태에 따라 예외
       ├─ PaymentCancelHandler.cancel()
       │    └─ [외부] PgClient.cancel()      ← TX 안에서 외부 호출
       ├─ PointRefundService.refund()
       └─ [이벤트 발행] OrderCancelledEvent
  [TX 종료]
       └─ [비동기] NotificationListener.handle()

이 한 장이 나오면
28장에서 다룬 문제(트랜잭션 안 외부 호출)가 눈에 보인다.

조사가 곧 문제 발견이다.

Side Effect를 추적한다

이 절이 이 장에서 가장 중요하다.

리팩터링할 때 실제로 위험한 것은
계산 로직이 아니라 부작용이다.

주문 취소 흐름에서 발생하는 모든 Side Effect를 찾아줘.

- DB 쓰기 (어느 테이블에 무엇을)
- 외부 API 호출
- 메시지·이벤트 발행
- 캐시 조작
- 파일 쓰기
- 알림 발송

각각이 트랜잭션 안인지 밖인지도 표시해줘.

결과는 이런 표가 된다.

⚠️ 이 표가 없으면 리팩터링에서 사고가 난다.

메서드를 옮기다가 알림 발송이 두 번 일어나거나,
캐시 무효화가 빠지는 식이다.

31장에서 본 그 문제다.

죽은 코드를 판별한다

레거시 조사에서 가장 조심할 부분이다.

이 클래스를 호출하는 곳이 없어 보입니다. 삭제 가능합니다.

🔥 Agent의 이 판정을 그대로 믿으면 안 된다.

정적 분석으로 잡히지 않는 호출 경로가 있다.

그래서 판정을 이렇게 나눈다.

사용되지 않아 보이는 클래스를 찾아줘.

단, 다음을 함께 확인하고 판정 근거를 적어줘:
- 리플렉션이나 문자열로 참조되는지
- @Profile, @ConditionalOn* 이 붙어 있는지
- 설정 파일에서 클래스명이 언급되는지

"확실히 미사용" 과 "확인 필요" 로 나눠서 보여줘.

그리고 실제 삭제 판단은
운영 로그나 APM 지표로 확인한 뒤에 한다.

정적으로는 “호출하는 코드가 없다” 까지만 알 수 있고,
“실행되지 않는다” 는 운영 데이터가 말해준다.

git log 를 읽힌다

코드에 없는 정보를 얻는 방법이다.
9장에서 판단을 뒤집었던 그 방법의 확장이다.

최근 1년 커밋 통계를 뽑아줘.

- 변경 빈도가 높은 파일 상위 20개
- 1년 이상 변경되지 않은 패키지
- 한 커밋에서 자주 함께 바뀌는 파일 쌍

세 번째가 8부의 직접적인 입력이 된다.

order 와 point 의 파일이 늘 함께 바뀐다면
두 도메인 사이의 경계가 실제로는 작동하지 않는 것이다.

조사 결과는 문서로

19장의 원칙이다.

지금까지 조사한 것을 docs/order-cancel-flow.md 에 정리해줘.

- 진입점과 호출 흐름
- Side Effect 표
- 확인한 사실과 확인하지 못한 것을 구분해서
- 조사 과정에서 발견한 이상한 점도 별도 절로

마지막 항목이 유용하다.

조사 중에 눈에 걸린 것들은
그 자리에서 고치지 않고 모아둔다.

## 발견한 이상한 점
- PG 취소가 트랜잭션 안에서 호출됨 (28장 규칙 위반)
- AdminOrderService 는 Facade를 거치지 않고 Service 직접 호출
- 부분 취소 횟수 제한이 세 곳에서 다르게 구현됨

이 목록이 나중에 티켓이 된다.

이 장의 핵심

• 8장의 목적은 Agent를 일하게 하는 것, 이 장의 목적은 경계를 그을 만큼 이해하는 것이다
• 레거시에는 죽은 코드와 여러 세대의 방식이 섞여 있다
• 진입점은 Controller만이 아니다 — 스케줄러·리스너·배치·웹훅까지 전수 조사한다
• 흐름을 따라갈 때 트랜잭션 경계와 비동기 전환 지점을 함께 표시하게 한다
• 리팩터링에서 위험한 것은 계산 로직이 아니라 Side Effect다
• Agent의 “미사용” 판정을 그대로 믿지 않는다 — 리플렉션·프로파일·설정 기반 호출이 있다
• 정적으로는 “호출하는 코드가 없다” 까지만 알 수 있다
• 함께 자주 바뀌는 파일 쌍은 경계가 잘못 그어졌다는 신호다
• 조사 중 발견한 이상한 점은 고치지 말고 모아서 티켓으로 만든다

35장. 코드베이스 지도 만들기 — Module · Dependency · Domain · Data Flow

34장에서 흐름 하나를 끝까지 따라갔다.

그런 흐름이 마흔 개 있다.

전부 따라가면 3주가 걸리고,
따라가는 동안 앞의 것을 잊는다.

필요한 것은 지도다.

지도를 만드는 이유

한 번 만들면 이후 모든 작업이 싸진다.

지도가 없을 때        지도가 있을 때
────────────────     ────────────────
매 세션 탐색부터      @docs/dependency-map.md 로 시작
파일 40개 읽힘        문서 한 장
30분 소요             1분

12장의 Context 예산이 근본적으로 달라진다.

그리고 지도는 사람도 쓴다.
신규 입사자 온보딩 문서가 동시에 만들어진다.

네 종류를 만든다

flowchart TB
    M[Module Map<br/>무엇이 어디에] --> D[Dependency Map<br/>무엇이 무엇에 의존]
    D --> DM[Domain Map<br/>비즈니스 단위]
    DM --> F[Data Flow<br/>누가 어느 데이터를 쓰나]

뒤로 갈수록 만들기 어렵고,
8부에 더 중요하다.

1️⃣ Module Map

가장 쉽다. 8장에서 만든 구조 설명의 확장이다.

패키지별로 정리해줘.

- 각 패키지의 역할 한 줄
- 클래스 수, 총 라인 수
- 주요 진입점
- 최근 1년 변경 커밋 수

표로 만들고 docs/module-map.md 에 저장해줘.

🔥 마지막 두 열이 판단 재료다.

legacy 가 전체의 3분의 1인데 커밋은 4건.
common 이 91건이면 공통 모듈이 계속 자라고 있다는 뜻이다.

2️⃣ Dependency Map

여기서부터 가치가 커진다.

패키지 간 의존 관계를 분석해줘.

- 어느 패키지가 어느 패키지를 참조하는가
- 참조 횟수(import 기준)도 함께
- 순환 의존이 있으면 별도로 표시해줘

Mermaid 다이어그램과 표 둘 다 만들어줘.

flowchart LR
    O[order] --> P[payment]
    O --> PT[point]
    P --> PT
    PT --> O
    O --> C[common]
    P --> C

⚠️ point → order 화살표가 보인다.

order 가 point 를 쓰는 것은 자연스러운데
point 가 order 를 다시 참조하고 있다.

순환이다.

point → order 참조를 전부 찾아줘.
각각 무엇 때문에 필요한지 확인해줘.

대개 이유는 셋 중 하나다.

🔥 순환 의존은 경계가 없다는 증거다.

이 목록이 8부에서 가장 먼저 손댈 작업이 된다.

3️⃣ Domain Map

패키지 구조와 비즈니스 도메인이
일치하지 않는 것이 레거시의 특징이다.

비즈니스 도메인 기준으로 코드를 묶어줘.

패키지 구조가 아니라 실제 하는 일 기준으로.
한 도메인의 코드가 여러 패키지에 흩어져 있으면
전부 찾아서 목록으로 만들어줘.

결과가 이렇게 나오면 문제가 보인다.

## 포인트 도메인
- point/                         (본체)
- order/OrderPointCalculator.kt  ← 흩어짐
- payment/PointPaymentHandler.kt ← 흩어짐
- legacy/PointMigrationJob.kt    ← 흩어짐
- common/PointFormatter.kt       ← 흩어짐

포인트 로직이 네 곳에 있다.

⚠️ 이 상태에서 “포인트를 떼어내자” 는 불가능하다.

39장에서 무엇부터 정리할지 정할 때
이 흩어짐 정도가 우선순위 기준이 된다.

4️⃣ Data Flow와 데이터 소유권

8부에 가장 직접적으로 쓰이는 지도다.

각 테이블에 누가 쓰기를 하는지 조사해줘.

- 테이블별로 INSERT/UPDATE/DELETE 하는 클래스 목록
- 어느 패키지에서 하는지
- 읽기만 하는 곳도 별도로

Repository, JPQL, 네이티브 쿼리, 마이그레이션 전부 확인해줘.

⚠️ 표시된 두 곳이 문제다.

order 가 point_histories 에 직접 쓰고 있다.

이러면 포인트 도메인은 자기 데이터의 주인이 아니다.
나중에 떼어낼 때 이 지점이 그대로 걸린다.

코드 경계보다 데이터 경계가 더 완고하다.

43장에서 이 표를 다시 꺼낸다.

지도는 낡는다

⚠️ 지도의 가장 큰 위험은 틀린 지도다.

없는 것보다 나쁘다.
Agent가 그것을 사실로 읽기 때문이다.

<!-- docs/dependency-map.md -->
> 작성: 2026-08-14
> 기준 커밋: a3f9c21

기준 커밋을 적어두면 얼마나 낡았는지 즉시 안다.

42장에서 의존성 규칙을 테스트로 만들면
지도의 일부는 자동으로 검증된다.

지도를 Agent가 쓰게 만든다

만들어놓고 안 쓰면 의미가 없다.

CLAUDE.md 에서 가리킨다.

## 코드베이스 지도

작업 전에 관련 지도를 먼저 읽는다.

- `docs/module-map.md` 패키지 구조와 규모
- `docs/dependency-map.md` 패키지 간 의존 (순환 포함)
- `docs/domain-map.md` 도메인별 코드 위치
- `docs/data-ownership.md` 테이블 쓰기 주체

지도와 코드가 다르면 코드를 따르고, 차이를 보고한다.

마지막 줄이 안전장치다.

지도가 낡았을 때
Agent가 조용히 틀린 정보를 쓰는 것을 막는다.

한 번에 다 만들지 않는다

작업하면서 필요한 것부터 만든다.

목적지로 가려면 결국 넷 다 필요하지만,
순서는 지금 하는 일이 정한다.

이 장의 핵심

• 지도를 한 번 만들면 이후 모든 세션의 Context 비용이 달라진다
• Module → Dependency → Domain → Data Flow 순으로 어렵고, 뒤로 갈수록 8부에 중요하다
• 패키지 규모와 최근 커밋 수를 함께 보면 판단 재료가 된다
• 순환 의존은 경계가 없다는 증거다 — 8부에서 가장 먼저 손댈 목록이 된다
• 레거시에서는 패키지 구조와 비즈니스 도메인이 일치하지 않는다
• 한 도메인의 코드가 흩어진 정도가 정리 우선순위의 기준이 된다
• 데이터 소유권 표에서 남의 테이블에 쓰는 곳이 분리의 걸림돌이다
• 코드 경계보다 데이터 경계가 더 완고하다
• 틀린 지도는 없는 지도보다 나쁘다 — 기준 커밋을 함께 적는다
• “지도와 코드가 다르면 코드를 따르고 보고한다” 를 규칙으로 둔다

36장. Characterization Test — 리팩터링 전에 현재 동작을 고정한다

지도가 생겼다.

의존이 어떻게 얽혀 있는지,
어느 도메인이 어디에 흩어져 있는지 안다.

이제 손을 대고 싶어진다.

⚠️ 아직 하나가 남았다.

무엇이 깨졌는지 알 방법이다.

테스트가 없는 상태에서의 리팩터링

레거시의 현실은 대개 이렇다.

order 패키지    테스트 커버리지 34%
payment 패키지  22%
legacy 패키지   0%

이 상태에서 Agent에게 리팩터링을 시키면
빠르고 조용하게 망가진다.

23장의 문장이 여기서 가장 무겁다.

테스트가 없으면
Agent의 “수정 완료” 는 의견에 불과하다.

그래서 8부로 넘어가기 전에
이 장의 작업이 반드시 선행된다.

일반 테스트와 무엇이 다른가

Characterization Test는 옳은지 묻지 않는다.

🔥 세 번째 줄이 이 기법의 핵심이자
사람들이 가장 거부감을 느끼는 부분이다.

버그를 테스트로 박제한다.

의도적이다.

리팩터링의 목표는 동작을 바꾸지 않는 것이다.
버그도 동작의 일부다.

버그 수정과 구조 변경을 동시에 하면
무엇 때문에 깨졌는지 알 수 없다.

1단계  현재 동작 고정 (버그 포함)
2단계  구조 변경 — 테스트가 계속 통과해야 함
3단계  버그 수정 — 이때 테스트를 의도적으로 수정

25장의 작은 커밋 원칙과 같은 이유다.
한 번에 한 가지만 바꾼다.

어디에 씌우는가

경계에 씌운다. 안쪽이 아니다.

flowchart LR
    A[HTTP 요청] --> B[Facade]
    B --> C[Service]
    C --> D[Repository]
    A -.테스트 지점.-> A
    B -.테스트 지점.-> B

Service 나 Repository 에 씌우면
리팩터링할 때 테스트도 함께 깨진다.

그러면 테스트가 안전망이 아니라 짐이 된다.

바꿀 것의 바깥에 테스트를 둔다.

Agent와 함께 만드는 절차

여섯 단계다.

1️⃣ 대상 경로를 고른다

35장의 지도에서 고른다.

docs/domain-map.md 를 읽고,
포인트 도메인이 관여하는 API 엔드포인트를 전부 찾아줘.

2️⃣ 입력 조합을 뽑는다

여기서 Agent가 강하다.

POST /orders/{id}/cancel 의 입력 조합을 나열해줘.

코드의 분기를 근거로:
- 주문 상태별 (생성/결제완료/배송중/배송완료)
- 결제 수단별 (카드/포인트/혼합)
- 취소 이력별 (없음/부분취소 1회/2회/3회)
- 경계값 (금액 0, 전액 포인트, 최소 단위)

각 조합에서 어느 분기로 가는지도 표시해줘.

29장에서 경계 케이스를 요구한 것과 같은 방법이다.

3️⃣ 현재 결과를 수집한다

각 조합에 대해 현재 코드가 무엇을 반환하고
어떤 Side Effect를 만드는지 확인해줘.

- 응답 상태 코드와 본문
- DB 변경 (어느 테이블에 무엇이)
- 발행되는 이벤트
- 외부 호출 여부

실행해서 확인하고, 결과를 표로 정리해줘.

⚠️ 여기서 “이건 버그 같은데요” 가 나온다.

경계 케이스 (전액 포인트 결제 + 부분 취소 3회):
현재 동작은 4번째 취소를 허용합니다.
제한이 3회인데 조건이 `> 3` 으로 되어 있습니다.

29장에서 본 그 불일치다.

고치지 않는다. 기록만 한다.

4️⃣ 테스트로 옮긴다

위 표를 그대로 테스트로 만들어줘.

- 현재 동작을 그대로 검증해 (옳은지 판단하지 마)
- 버그로 의심되는 것은 테스트 이름에 표시해줘
  예: `현재 동작_부분취소_4회까지_허용됨_BUG의심`
- 기존 IntegrationTestBase 를 상속해

테스트 이름에 남기면
나중에 정리할 목록이 자동으로 생긴다.

5️⃣ 전부 통과하는지 확인한다

./gradlew test --tests '*OrderCancelCharacterization*'

여기서 실패하면 테스트가 틀린 것이다.
현재 동작을 잘못 기록했다는 뜻이니 고친다.

6️⃣ 커밋한다

git commit -m "test: 주문 취소 현재 동작 고정 (characterization)

리팩터링 전 안전망. 버그 의심 3건은 테스트 이름에 표시."

골든 마스터

응답이 크면 하나씩 단정하기 어렵다.
이때는 결과 전체를 파일로 저장해 비교한다.

@Test
fun `주문 상세 응답 - 골든 마스터`() {
    val response = api.get("/orders/1001")
    approvals.verifyJson(response)   // 저장된 스냅샷과 비교
}

⚠️ 23장의 “기댓값을 실제값으로 수정” 이
스냅샷에서는 훨씬 쉽게 일어난다. 파일 하나 덮어쓰면 끝이다.

- 골든 마스터 스냅샷을 임의로 갱신하지 않는다
  차이가 나면 갱신하지 말고 보고한다

커버리지가 아니라 경로

전부 덮으려 하면 시작도 못 한다.

❌ order 패키지 커버리지 80% 달성
✅ 취소 흐름의 주요 경로 12개 고정

기준은 이렇다.

🔥 2번이 실용적인 기준이다.

바꾸지 않을 코드에 테스트를 씌우는 것은
지금 필요한 일이 아니다.

리팩터링이 끝난 뒤

Characterization Test는 한시적이다.

작업이 끝나면 셋 중 하나를 고른다.

17장에서 작업 문서를 승격하거나 삭제하라고 한 것과 같다.

방치하면 “왜 이런 이상한 동작을 검증하지” 하는
테스트가 몇 년 남는다.

이제 8부가 가능해진다

34장  무엇이 어떻게 동작하는지 안다
35장  무엇이 무엇에 의존하는지 안다
36장  바꿔도 깨졌는지 알 수 있다

세 번째가 없으면 앞의 둘은 지식일 뿐이다.

경계를 긋는 작업은 코드를 대규모로 옮기는 일이고,
안전망 없이는 시작하지 않는다.

이 장의 핵심

• Characterization Test는 옳은지 묻지 않고 지금 동작을 기록한다
• 버그도 함께 고정한다 — 리팩터링의 목표는 동작을 바꾸지 않는 것이다
• 구조 변경과 버그 수정을 동시에 하면 무엇 때문에 깨졌는지 알 수 없다
• 바꿀 것의 바깥에 테스트를 둔다 — API 레벨이 가장 안전하다
• 입력 조합을 코드 분기 근거로 뽑는 일은 Agent가 강하다
• 수집 중 발견한 버그는 고치지 말고 테스트 이름에 표시한다
• 골든 마스터 스냅샷은 파일 하나 덮어쓰면 되므로 갱신을 금지한다
• 목표는 커버리지가 아니라 이번에 바꿀 코드가 지나는 경로다
• 작업이 끝나면 승격하거나 삭제한다 — 방치하면 이상한 테스트가 남는다
• 안전망 없이 경계 작업을 시작하지 않는다

37장. 관례가 없는 코드베이스에서 — 자체 프레임워크와 계층 미분리

지금까지의 예시에는 조용한 전제가 하나 있었다.

Spring이라는 것.

@RestController 를 보면 Agent는 무엇인지 알고,
JPA 엔티티를 읽으면 스키마를 안다.
이 사전 지식 위에 이 책의 상당 부분이 서 있다.

그런데 이런 코드베이스가 있다.

자체 프레임워크 (10년 전 사내 개발)
Controller 에 비즈니스 로직이 그대로
데이터 접근은 자체 쿼리 빌더
계층이라 부를 만한 것이 없음

드문 상황이 아니다. 그리고 앞의 전제가 깨진다.

무엇이 달라지는가

34~36장은 그대로 통한다.
진입점 조사, 지도, 특성화 테스트는 프레임워크와 무관하다.

문제는 이 셋이다.

그리고 책이 아예 다루지 않은 문제가 하나 더 있다.

가장 큰 문제 — Agent가 아는 척한다

⚠️ 이것이 이 장의 핵심이다.

Agent는 모르면 멈추지 않는다.
비슷하게 생긴 것의 관례를 가져다 쓴다.

// 우리 쿼리 빌더
Query.from("orders").where("status", "=", "PAID").list()

// Agent가 QueryDSL 관례로 쓴 것
Query.from("orders").where(order.status.eq("PAID")).fetch()

이건 컴파일 에러라 차라리 낫다.

🔥 무서운 것은 이름은 같은데 동작이 다른 경우다.
.limit(10) 이 우리는 페이지당 개수인데
다른 라이브러리 관례로는 전체 상한이라면, 아무도 모른다.

DI도 같다. @Autowired 를 붙였는데
우리 컨테이너의 주입 시점이 다르면 운영에서 NPE가 난다.

방어 1 — “이건 무엇이 아니다” 를 먼저 쓴다

14장에서 CLAUDE.md 에 무엇을 적을지 다뤘다.
이 상황에서는 아닌 것을 먼저 적는다.

# order-service

⚠️ 이 프로젝트는 Spring 을 쓰지 않는다.
자체 프레임워크(`core/`)와 자체 쿼리 빌더(`core/query/`)를 쓴다.

## 절대 가정하지 말 것

- Spring 애노테이션은 존재하지 않는다. 쓰면 컴파일되지 않거나 무시된다
- JPA·Hibernate 는 없다
- 쿼리 빌더는 QueryDSL·jOOQ 와 이름만 비슷하다.
  용법은 `docs/query-builder.md` 를 반드시 확인한다
- 모르는 API 는 추측하지 말고 `core/` 에서 실제 정의를 찾아 확인한다

마지막 줄이 핵심이다.

15장에서 “덕목은 규칙이 아니다” 라고 했는데
이건 덕목이 아니라 판정 가능한 행동 지시다.

core/ 를 열어봤는지는 도구 호출 기록에 남는다.

방어 2 — 프레임워크 레퍼런스를 만든다

문제의 뿌리는 참고할 문서가 없다는 것이다.
Spring은 학습 데이터에 있지만 우리 프레임워크는 어디에도 없다.

만들어야 하고, 이것도 Agent가 돕는다.

core/query/ 의 쿼리 빌더 API 문서를 만들어줘.

- public 메서드 전부와 시그니처
- 각 메서드가 실제로 생성하는 SQL (구현을 읽고 확인해줘)
- 이름이 비슷한 공개 라이브러리와 동작이 다른 부분

추측하지 말고 구현 코드에서 확인한 것만 적어줘.
확인 안 되는 건 "확인 필요" 로 남겨줘.

⚠️ 마지막 두 줄이 없으면 QueryDSL 문서를 재현해온다.

🔥 이 문서 하나가 투자 대비 효과가 가장 크다.
없으면 매 세션 같은 실수가 반복된다.

방어 3 — 자주 틀리는 대비표

15장의 “자주 틀리는 것만 남긴다” 를
이 상황에 맞게 쓰면 대비표가 된다.

사고가 날 때마다 한 줄씩 늘어난다.
16장의 개선 루프가 여기서는 훨씬 빨리 돈다.

참고할 좋은 예시가 없을 때

26장의 핵심 전략이 무력화된다.

가장 최근에 잘 만든 것을 지목하라

그런 파일이 없으면 하나를 만든다.

새 요구사항 중 가장 작은 것을 골라
사람이 목표 구조대로 직접 구현하고, 기준으로 지정한다.

## 기준 구현

신규 코드는 아래를 본보기로 삼는다.

- `order/CreateOrderHandler.kt` — 핸들러 구조
- `order/OrderService.kt` — 로직 분리
- `order/OrderQuery.kt` — 데이터 접근

⚠️ 위 세 파일 외의 기존 코드는 본보기가 아니다.

⚠️ 이때 Agent를 쓰지 않는 것이 중요하다.

기준이 될 파일은 관례가 없는 상태에서 만들어진다.
Agent가 만들면 다른 프레임워크의 관례가 섞이고,
그것이 이후 모든 코드에 복제된다.

계층이 아예 없을 때

40장은 계층을 재배치하는 이야기였다.
여기서는 신설이라 규모가 다르다.

⚠️ 전면 재배치는 실패한다.
파일 400개를 옮기는 동안 기능 개발이 멈춘다.

handler/ service/ query/   ← 새 구조 (신규 코드만)
legacy/                    ← 기존 전부 (건드리지 않음)

- 기존 파일을 수정할 일이 생기면
  그 파일의 비즈니스 로직만 service/ 로 분리한다
- 분리 전에 그 경로의 특성화 테스트를 먼저 만든다 (36장)
- 한 번에 한 파일만. 옮기는 김에 주변을 정리하지 않는다

그리고 신구조 비율을 지표로 본다. 4% → 17% → 31%.

🔥 이 숫자가 있으면 “언제 끝나냐” 에
“이 속도면 2년” 이라고 답할 수 있다.

스키마를 어떻게 파악시키는가

27장은 JPA 엔티티를 스키마 문서로 썼다.
여기서는 테이블·컬럼이 문자열로 흩어져 있다.

Query.from("orders").select("id", "user_id", "total_amount")

DDL 덤프와 코드 문자열을 대조하는 편이 낫다.

코드에서 참조하는 테이블·컬럼 문자열을 전부 추출해줘.
그다음 실제 DDL과 대조해서 세 가지로 나눠줘.

- 코드에도 있고 DB에도 있다
- 코드에는 있는데 DB에 없다 (⚠️ 오타 또는 죽은 코드)
- DB에는 있는데 코드에서 안 쓴다 (죽은 컬럼 후보)

⚠️ 두 번째 목록이 나오면 대개 놀란다.

문자열이라 컴파일러가 안 잡아준다.
조건 분기 안에 있으면 몇 년간 아무도 모른다.

35장의 데이터 소유권 표는 이 결과 위에서 만든다.

아키텍처 테스트를 어떻게 거는가

42장의 의존성 테스트는 패키지 참조를 검사하므로
프레임워크와 무관하게 쓸 수 있다.

⚠️ 그런데 이 상황의 핵심 문제는 안 잡힌다.

“Controller에 비즈니스 로직이 있다” 는
의존성 규칙으로 표현되지 않는다.

증상으로 대신 잡는다.

@Test fun `handler 메서드는 40줄을 넘지 않는다`()
@Test fun `handler 에서 Query 를 직접 만들지 않는다`()   // 문자열 검사
@Test fun `handler 의 조건 분기는 5개를 넘지 않는다`()

셋 다 거칠다.
로직이 있는지가 아니라 로직이 있을 때 나타나는 증상을 본다.

🔥 그래도 효과가 있다.
핸들러에 로직을 쓰기 시작하면 길이나 분기 수에서 걸린다.

42장의 baseline 방식으로
기존 위반을 예외 목록에 넣고 시작한다.

우선순위가 바뀐다

39장의 축을 그대로 쓰되 가중치가 달라진다.

⚠️ 경계 작업을 미루는 것이 맞다.

38장에서 “경계는 코드가 알려준다” 고 했는데,
그 코드가 아무 말도 하지 않는 상태다.

안전망(특성화 테스트) → 언어(레퍼런스) → 본보기(기준 구현)
→ 방벽(길이·분기 규칙) → 축적(새 코드부터) → 그다음에 경계

그래도 나아지는 것

🔥 마지막 줄이 크다.

자체 프레임워크 프로젝트의 가장 큰 비용은
사람이 적응하는 시간이고, 그 레퍼런스가 그것을 직접 줄인다.

4장에서 말한 그대로다.

사람에게 관행으로 남겨둔 암묵지를
Agent에게는 파일로 꺼내야 한다.

관행조차 없던 프로젝트에서는
그 작업이 곧 관행을 만드는 일이 된다.

이 장의 핵심

• 이 책의 예시는 Spring이라는 전제 위에 있고, 자체 프레임워크에서는 깨진다
• 34~36장의 조사·지도·특성화 테스트는 프레임워크와 무관하게 통한다
• Agent는 모르면 멈추지 않고 비슷하게 생긴 것의 관례를 가져다 쓴다
• 이름은 같은데 동작이 다른 API가 가장 위험하다
• CLAUDE.md 첫 줄에 “이것은 무엇이 아니다” 를 적는다
• 프레임워크 레퍼런스 문서가 투자 대비 효과가 가장 크다
• 참고할 좋은 예시가 없으면 사람이 하나를 직접 만들어 기준으로 삼는다
• 기준 구현을 Agent에게 맡기면 다른 관례가 섞여 이후 전부에 복제된다
• 계층이 없으면 재배치가 아니라 신설이다 — 새 코드부터, 비율을 지표로
• 테이블·컬럼 문자열과 DDL을 대조하면 죽은 코드와 오타가 드러난다
• 의존성 규칙으로는 “핸들러에 로직 있음” 을 못 잡는다 — 길이·분기 수로 대신한다
• 경계 작업은 뒤로 미룬다. 코드가 아무 말도 하지 않는 상태이기 때문이다

38장. 코드에서 경계를 찾기 — 도메인 · 책임 · 데이터 소유권

7부에서 준비를 마쳤다.

지도가 있고, 안전망이 있다.

이제 선을 긋는다.

그런데 어디에 긋는가.

경계는 발명이 아니라 발견이다

가장 흔한 실수는 경계를 설계하려는 것이다.

화이트보드에 이상적인 도메인 구조를 그리고
코드를 거기에 맞추려 한다.

레거시에서 이 방식은 거의 실패한다.

이미 5년간 만들어진 결합이 있고,
그 결합에는 대부분 이유가 있다.

경계는 코드가 이미 알려주고 있다.
우리가 할 일은 읽어내는 것이다.

Agent가 특히 잘하는 일이 바로 이 읽어내기다.

네 가지 신호

경계 후보는 네 방향에서 드러난다.

flowchart TB
    A[도메인 언어] --> B((경계 후보))
    C[함께 변경되는 코드] --> B
    D[데이터 소유] --> B
    E[트랜잭션 범위] --> B

각각을 Agent에게 수집시킬 수 있다.

1️⃣ 도메인 언어

같은 단어를 쓰는 코드는 대개 같은 편이다.

코드에 등장하는 도메인 용어를 추출해줘.

- 클래스명, 메서드명, 필드명, DB 컬럼명 기준
- 어떤 용어가 어느 패키지에 몰려 있는지 표로
- 같은 개념을 다른 이름으로 부르는 곳이 있으면 표시해줘

마지막 요구가 유용하다.

"결제 금액" 을 부르는 이름
  payment.amount        (payment 패키지)
  paidAmount            (order 패키지)
  settlement_price      (legacy 패키지)

⚠️ 이름이 갈리는 지점이 경계일 때가 많다.

29장에서 도메인 용어를 정리한 것이 여기서 회수된다.

2️⃣ 함께 변경되는 코드

34장에서 뽑은 신호다.

최근 1년간 한 커밋에서 함께 변경된 파일 쌍을
빈도순으로 20개 뽑아줘. 패키지가 다른 쌍만.

패키지는 다른데 늘 함께 바뀐다면
그 둘은 사실 하나다.

🔥 이 신호는 코드를 읽어서는 절대 안 보인다.
이력에만 있다.

3️⃣ 데이터 소유

35장의 데이터 소유권 표다.

docs/data-ownership.md 를 읽고,
한 테이블에 두 개 이상의 패키지가 쓰기를 하는 경우를 찾아줘.

쓰기 주체가 여럿인 테이블은
경계가 성립하지 않은 곳이다.

4️⃣ 트랜잭션 범위

가장 완고한 신호다.

하나의 트랜잭션 안에서 함께 수정되는 테이블 조합을 찾아줘.
@Transactional 메서드 기준으로.

같은 트랜잭션에 묶인 테이블은
나중에 서비스를 나눌 때 가장 큰 장애물이 된다.

44장에서 이 문제를 다룬다.

신호가 엇갈릴 때

네 신호가 항상 같은 답을 주지는 않는다.

마지막 줄이 중요하다.

나누지 않는다는 결론도 결론이다.

⚠️ 경계를 찾는 작업이 곧 나누는 작업은 아니다.

Agent에게 경계를 정하게 하지 않는다

이 장에서 가장 조심할 부분이다.

# ❌ 이렇게 물으면
이 코드베이스를 어떤 도메인으로 나누면 좋을까?

Agent는 답한다.
아주 그럴듯하게.

주문, 결제, 배송, 회원, 상품, 정산.
전자상거래 교과서에 나오는 그 구분이다.

⚠️ 우리 코드와 무관하게 나온 답이다.

우리 회사에서 “정산” 이 실제로 무엇을 뜻하는지,
왜 배송과 주문이 한 몸인지 반영되지 않았다.

# ✅ 이렇게 묻는다
docs/dependency-map.md 와 docs/data-ownership.md 를 읽고,
결합이 약해서 떼어낼 수 있어 보이는 후보를 찾아줘.

- 근거가 되는 데이터를 함께 제시해줘
- 각 후보의 외부 의존 개수를 세어줘
- 판단은 하지 말고 후보와 근거만 보여줘

33장의 결론을 미리 주지 않는 원칙과 같다.

Agent에게 정답을 묻지 말고
근거를 모으게 한다.

경계 카드로 정리한다

후보가 나오면 하나씩 카드로 만든다.

# 경계 후보: 포인트

## 범위
- point/ 전체 (22 클래스)
- order/OrderPointCalculator.kt        ← 이동 필요
- payment/PointPaymentHandler.kt       ← 이동 필요
- common/PointFormatter.kt             ← 이동 필요

## 소유 데이터
- point_histories (쓰기: point, order ⚠️)
- point_balances  (쓰기: point 단독 ✅)

## 외부에서 들어오는 의존
- order → point.refund()      (12곳)
- payment → point.use()       (5곳)

## 밖으로 나가는 의존
- point → order.getOrder()    (3곳) ⚠️ 순환

## 트랜잭션 결합
- 주문 취소 트랜잭션이 orders + point_histories 동시 수정

## 떼어내기 전 해결할 것
1. point → order 역참조 3곳 제거
2. order 가 point_histories 에 직접 쓰는 경로 정리
3. 흩어진 3개 파일 이동

이 카드가 39장의 우선순위 판단 재료가 되고,
41~43장의 작업 목록이 된다.

문서로 먼저 검증한다

16장에서 예고한 방법이다.

코드를 옮기기 전에
경계가 성립하는지 문서로 확인할 수 있다.

경계 카드의 범위를 전제로,
포인트 도메인의 규칙만 담은 CLAUDE.md 초안을 써줘.

- 이 도메인의 불변식
- 이 도메인이 소유한 데이터
- 다른 도메인과 주고받는 것

쓰다가 "이건 어느 쪽 규칙인지 모르겠다" 싶은 게 나오면
그것도 적어줘.

🔥 마지막 요구가 검증 장치다.

애매한 항목이 많이 나오면
경계가 아직 명확하지 않다는 뜻이다.

파일 하나 옮기지 않고 가설을 검증했다.

이 장의 핵심

• 경계는 설계하는 것이 아니라 코드에서 발견하는 것이다
• 신호는 넷이다 — 도메인 언어, 함께 변경, 데이터 소유, 트랜잭션 범위
• 같은 개념을 다른 이름으로 부르는 지점이 경계일 때가 많다
• 함께 변경되는 파일 쌍은 코드가 아니라 이력에만 있는 신호다
• 쓰기 주체가 여럿인 테이블은 경계가 성립하지 않은 곳이다
• 신호가 엇갈리면 해석이 달라지고, “나누지 않는다” 도 결론이다
• Agent에게 도메인 구분을 물으면 교과서적 답이 나온다
• 정답을 묻지 말고 근거를 모으게 한다
• 경계 카드가 이후 작업의 목록이 된다
• 도메인 규칙 문서를 써보면 코드를 옮기기 전에 경계를 검증할 수 있다

39장. 무엇부터 정리할 것인가 — 경계 후보의 우선순위

경계 카드가 다섯 장 나왔다.

포인트, 알림, 정산, 배송, 회원.

전부 정리할 수는 없다.

우리에겐 기능 개발도 있고,
이 작업에 쓸 수 있는 시간은 한 달에 며칠이다.

네 축으로 본다

flowchart TB
    V[가치<br/>정리하면 무엇이 좋아지나] --> P((우선순위))
    C[비용<br/>얼마나 걸리나] --> P
    R[위험<br/>깨지면 얼마나 아픈가] --> P
    RD[준비도<br/>안전망이 있나] --> P

각 축을 Agent가 측정할 수 있다.

가치 — 변경 빈도

정리 효과는 앞으로 얼마나 자주 만지느냐에 비례한다.

경계 후보별로 최근 1년 커밋 수를 세어줘.
해당 도메인 파일이 포함된 커밋 기준으로.

1년에 9번 만지는 코드를 정리하는 것은
지금 할 일이 아니다.

비용 — 결합도와 흩어짐

경계 카드별로 다음을 세어줘.

- 밖에서 들어오는 의존 개수
- 밖으로 나가는 의존 개수 (순환 포함)
- 도메인 코드가 흩어진 패키지 수
- 공유 테이블 수

🔥 나감 이 비용의 핵심 지표다.

들어오는 의존은 인터페이스로 정리하면 되지만,
나가는 의존은 그 도메인이 남에게 매달려 있다는 뜻이다.

알림은 나가는 의존이 0이다.
떼어내기 가장 쉽다.

위험 — 깨지면 얼마나 아픈가

측정이 아니라 판단이다.

⚠️ 첫 대상으로 최상 등급을 고르지 않는다.

방법이 익숙해지기 전에 가장 위험한 곳을 건드린다.

준비도 — 안전망

36장의 결과다.

경계 후보별 테스트 커버리지와
Characterization Test 존재 여부를 정리해줘.

준비도가 낮으면 우선순위와 무관하게
36장으로 돌아가야 한다.

매트릭스에 놓는다

가치와 비용 두 축이면 대개 결정된다.

             비용 낮음        비용 높음
          ┌──────────────┬──────────────┐
가치 높음 │  ① 먼저 한다  │ ③ 쪼개서 한다 │
          ├──────────────┼──────────────┤
가치 낮음 │ ② 연습용      │  ④ 안 한다   │
          └──────────────┴──────────────┘

앞의 표를 놓아보면 이렇다.

• 포인트 — 가치 중, 비용 중 → ①에 가깝다
• 알림 — 가치 낮음, 비용 낮음 → ②
• 정산 — 가치 낮음, 비용 높음 → ④
• 주문 — 가치 최상, 비용 최상 → ③

첫 대상은 ②에서 고른다

의외의 결론이지만 실무에서 맞다.

첫 번째 작업의 목적은 성과가 아니라 방법 습득이다.

41장의 대규모 이동,
42장의 규칙 강제,
43장의 데이터 정리.

이 셋을 처음 해보는 자리로
가장 위험한 도메인을 고르면 안 된다.

알림 도메인이 좋은 첫 대상인 이유는 이렇다.

🔥 여기서 배운 절차로 포인트를 하고,
포인트에서 배운 것으로 결제를 한다.

첫 경계는 가장 중요한 곳이 아니라
가장 안전한 곳에 긋는다.

순서를 로드맵으로

결정을 문서로 남긴다. 19장의 원칙이다.

# 경계 정리 로드맵

## 1차 (연습) — 알림
목표: 절차 확립. 의존성 테스트 도입.
예상: 2주

## 2차 — 포인트
목표: 순환 의존 제거, 데이터 소유권 회복
선행: point → order 역참조 3곳 제거
예상: 6주

## 3차 — 정산 배치
목표: 계층 정리만. 분리는 하지 않음

## 보류 — 주문·결제
이유: 변경이 잦아 리팩터링과 기능 개발이 충돌
재검토: 2차 완료 후

## 하지 않음 — legacy
이유: 신규 개발 없음. 제거 대상

⚠️ 하지 않음 절이 중요하다.

적어두지 않으면 6개월 뒤에
“이건 왜 안 했지” 를 다시 논의한다.

20장의 Non-goals와 같은 역할이다.

Agent에게 우선순위를 묻지 않는다

38장과 같은 이유다.

# ❌
어느 도메인부터 정리하면 좋을까?

# ✅
docs/boundaries/ 의 경계 카드들을 읽고
각 후보의 지표를 표로 정리해줘.

- 최근 1년 커밋 수
- 들어오는/나가는 의존 개수
- 흩어진 패키지 수
- 공유 테이블 수
- 테스트 커버리지

순위는 내가 정할게.

위험 판단과 조직 사정은 코드에 없다.

• 다음 분기에 이 도메인을 크게 개편할 예정이다
• 이 영역 담당자가 다음 달에 퇴사한다
• 규제 감사가 있어서 정산은 건드릴 수 없다

세 가지 모두 우선순위를 뒤집는 정보이고,
Agent는 알 수 없다.

이 장의 핵심

• 전부 정리할 수 없으므로 순서를 정해야 한다
• 축은 넷이다 — 가치(변경 빈도), 비용(결합도), 위험, 준비도
• 나가는 의존이 비용의 핵심 지표다 — 그 도메인이 남에게 매달려 있다는 뜻이다
• 들어오는 의존은 인터페이스로 정리할 수 있다
• 첫 대상으로 가장 위험한 도메인을 고르지 않는다
• 첫 작업의 목적은 성과가 아니라 방법 습득이다
• 첫 경계는 가장 중요한 곳이 아니라 가장 안전한 곳에 긋는다
• 로드맵에 “하지 않음” 과 그 이유를 함께 적는다
• 위험 판단과 조직 사정은 코드에 없다 — 순위는 사람이 정한다

40장. 모놀리스 내부 구조 개선 — Controller · Application · Domain · Infrastructure

첫 대상을 정했다.

바로 도메인을 떼어내고 싶지만
그 전에 할 일이 하나 있다.

계층 정리다.

왜 계층이 먼저인가

도메인 경계는 세로선이고,
계층 경계는 가로선이다.

              order    payment    point
Controller      │         │         │
Application     │         │         │
Domain          │         │         │
Infrastructure  │         │         │

세로선을 그으려면
가로선이 먼저 정리되어 있어야 한다.

이유는 실용적이다.

⚠️ 도메인 로직이 Controller와 Repository에 섞여 있으면
그 도메인을 통째로 옮길 수 없다.

// Controller에 도메인 로직이 있는 경우
@PostMapping("/orders/{id}/cancel")
fun cancel(@PathVariable id: Long) {
    val order = orderRepository.findById(id)
    if (order.status == SHIPPED) throw ...        // 도메인 규칙
    val refund = order.paidAmount * 0.9           // 도메인 규칙
    ...
}

이 코드는 어느 도메인의 것인가.

옮길 수도, 남길 수도 없다.

목표 구조

flowchart TB
    C[Controller<br/>HTTP 변환] --> A[Application<br/>흐름 조합 · 트랜잭션]
    A --> D[Domain<br/>규칙 · 불변식]
    A --> I[Infrastructure<br/>DB · 외부 · 메시지]
    I -.구현.-> D

각 층의 책임은 한 줄로 정의된다.

🔥 화살표 방향이 핵심이다.

Infrastructure → Domain 이 아니라
Domain 이 인터페이스를 정의하고 Infrastructure 가 구현한다.

이 방향이 지켜지면
Domain 코드는 Spring도 JPA도 모른다.

그리고 통째로 옮길 수 있다.

현재와의 갭 측정

Agent에게 시킨다.

포인트 도메인의 코드를 목표 계층에 매핑해줘.

각 클래스가 실제로 하는 일을 기준으로:
- Controller / Application / Domain / Infrastructure 중 어디에 속하는지
- 현재 위치와 다르면 표시해줘
- 한 클래스가 여러 층의 일을 하고 있으면 별도로 표시해줘

세 번째가 진짜 문제를 드러낸다.

PointService.kt (412줄)
  - 잔액 계산 로직        → Domain
  - 트랜잭션 관리         → Application
  - Redis 캐시 접근       → Infrastructure
  - 응답 DTO 변환         → Controller
  ⚠️ 네 층의 일을 한 클래스에서 함

이런 클래스가 계층 정리의 실제 대상이다.

순수한 도메인 모델

Kotlin + JPA에서 자주 부딪히는 문제다.

@Entity
@Table(name = "point_balances")
class PointBalance(
    @Id val userId: Long,
    var balance: Long
) {
    fun use(amount: Long) {
        require(balance >= amount)
        balance -= amount
    }
}

도메인 규칙과 JPA 매핑이 한 클래스에 있다.

⚠️ 이 상태로는 Domain 층이 Infrastructure에 의존한다.

완전히 분리하면 이렇게 된다.

// Domain — 기술 의존 없음
class PointBalance(val userId: Long, val balance: Money) {
    fun use(amount: Money): PointBalance { ... }
}

// Infrastructure — 매핑 전용
@Entity
@Table(name = "point_balances")
class PointBalanceEntity(...) {
    fun toDomain(): PointBalance = ...
}

깨끗하다.
그리고 코드가 두 배가 된다.

이 선택은 팀이 한다.

🔥 Agent에게 물으면 대개 완전 분리를 권한다.

교과서적으로 옳기 때문이다.
비용은 우리가 낸다.

완전 분리 방식과 엔티티에 규칙을 두는 방식의
코드량 차이가 어느 정도인지 샘플로 보여줘.
포인트 잔액 하나만 두 방식으로 만들어봐.

숫자를 보고 결정한다.

한 번에 다 하지 않는다

전체를 목표 구조로 옮기는 것은 몇 달짜리다.

그 사이 기능 개발이 멈춘다.
현실적이지 않다.

# CLAUDE.md
## 계층 규칙

- 신규 코드는 목표 구조를 따른다
- 기존 코드는 그 파일을 수정할 때 함께 정리한다
- 정리를 위한 정리는 하지 않는다

세 번째 줄이 브레이크다.

Agent에게 파일 하나 수정을 시켰는데
주변 열 개를 함께 정리해 오는 일을 막는다.

20장의 Non-goals가 규칙 형태로 들어간 것이다.

두 세대가 공존하는 기간

이 방식의 대가는 공존이다.

point/
  domain/          ← 새 구조
  application/
  infrastructure/
  PointService.kt  ← 옛 구조 (아직)

⚠️ 12장의 Context Pollution이 여기서 다시 나온다.

Agent가 옛 구조를 보고 그것을 따라 쓴다.

방어는 문서로 한다.

# point/CLAUDE.md
- `domain/`, `application/`, `infrastructure/` 가 현재 구조다
- 루트에 있는 `PointService.kt`, `PointFacade.kt` 는 마이그레이션 대상
  참고하되 새 코드의 본보기로 삼지 않는다

16장의 계층화가 여기서 실제로 쓰인다.

계층 이동 자체는 41장에서

계층을 정리하려면 파일을 옮겨야 하고,
파일을 옮기는 것이 생각보다 큰 작업이다.

41장에서 그 방법을 다룬다.

완료 조건

## Acceptance Criteria
- PointService 가 네 층으로 분리됨
- Domain 패키지에 Spring/JPA import 가 없음
- Characterization Test 24건 그대로 통과
- 외부에서 point 를 호출하는 17곳의 시그니처 변경 없음
- 의존성 테스트 추가 (42장)

🔥 두 번째와 네 번째가 이 작업의 진짜 기준이다.

Domain이 기술을 모르는가.
그리고 밖에서 볼 때 아무것도 안 바뀌었는가.

이 장의 핵심

• 도메인 경계는 세로선이고 계층 경계는 가로선이다 — 가로선이 먼저다
• 도메인 로직이 Controller와 Repository에 섞여 있으면 옮길 수 없다
• Domain이 인터페이스를 정의하고 Infrastructure가 구현한다
• 한 클래스가 여러 층의 일을 하는 곳이 계층 정리의 실제 대상이다
• JPA 엔티티에서 도메인 모델을 분리하면 깨끗해지고 코드가 두 배가 된다
• Agent는 교과서적으로 옳은 완전 분리를 권한다 — 비용은 우리가 낸다
• 신규 코드부터 적용하고, 기존 코드는 만질 때 함께 정리한다
• “정리를 위한 정리는 하지 않는다” 를 규칙으로 둔다
• 두 구조가 공존하는 동안 옛 구조를 본보기로 삼지 않게 문서로 막는다
• 완료 기준은 Domain이 기술을 모르는지, 밖에서 볼 때 안 바뀌었는지다

41장. 대규모 패키지 이동을 Agent에게 맡기는 방법 — 작게, 검증하며

40장에서 목표 구조를 정했다.

이제 파일 84개를 옮겨야 한다.

이 작업은 에이전틱 코딩에서
가장 극적으로 성패가 갈리는 작업이다.

잘하면 하루,
잘못하면 일주일간 컴파일이 안 된다.

왜 어려운가

파일 하나를 옮기면 연쇄가 시작된다.

PointService.kt 이동
  → 이 파일을 import 하던 31개 파일 수정
  → 그중 일부는 패키지 순환이 생김
  → 순환을 풀려면 인터페이스 추출
  → 인터페이스를 어디에 둘지 결정
  → 결정에 따라 또 다른 파일 이동

⚠️ 그리고 중간에 컴파일이 안 되면
피드백 루프가 끊긴다.

24장에서 본 그 문제다.
검증 없이 계속 수정하는 상태가 된다.

Agent가 잘하는 것과 못하는 것

🔥 오른쪽 열의 세 번째가 이 장의 핵심 위험이다.

Agent는 컴파일 에러 200개를 보면
200개를 다 고치려 한다.

중간에 “이 방향이 틀렸다” 를 판단하지 않는다.

IDE와 Agent의 역할 분담

여기서 실무적인 판단이 하나 있다.

IntelliJ의 Move/Rename 리팩터링은
이 작업을 정확하게 한다.

⚠️ 순수한 이동을 Agent에게 시키는 것은
대개 비효율이다.

IDE가 1초에 정확히 하는 일을
Agent는 몇 분간 토큰을 쓰며 한다.

그리고 놓칠 수 있다.
문자열로 참조되는 클래스명, 설정 파일의 FQCN 같은 것들.

기계적으로 정확한 일은 기계에게,
판단이 필요한 일은 Agent에게.

이 원칙이 대규모 이동에서 특히 중요하다.

여섯 단계

1️⃣ 이동 대상을 확정한다

40장의 계층 매핑 결과를 바탕으로 이동 계획표를 만들어줘.

| 현재 경로 | 목표 경로 | 참조 파일 수 | 순환 위험 |

- 참조 파일 수는 실제로 세어줘
- 이동하면 순환이 생길 수 있는 것을 표시해줘
- 이동 순서도 제안해줘 (의존이 적은 것부터)

2️⃣ 순서를 정한다

의존이 적은 것부터 옮긴다.

1. Money, PointAmount        (아무것도 참조 안 함)
2. PointBalance              (Money만 참조)
3. PointPolicy               (위 둘 참조)
4. PointRepository 인터페이스
5. PointBalanceEntity        (Infrastructure)
6. PointApplicationService

⚠️ 반대 순서로 하면
매 단계마다 컴파일이 깨진다.

3️⃣ 한 덩어리씩 옮긴다

한 커밋에 한 덩어리다. 22장의 기준이다.

1단계만 진행하자.

Money, PointAmount 를 point/domain/model/ 로 옮겨줘.

- 이동은 했지만 로직은 한 줄도 바꾸지 마
- import 수정만 해줘
- 옮긴 뒤 컴파일이 되는지 확인해줘

🔥 두 번째 요구가 이 장에서 가장 중요한 규칙이다.

이동과 수정을 섞지 않는다.

Agent는 파일을 옮기면서
“이왕 하는 김에” 코드를 개선하려 한다.

그러면 Diff에서 이동과 변경이 뒤섞여
검토가 불가능해진다.

# 이동만 했다면 이렇게 보인다
git diff -M --stat
  rename point/{ => domain/model}/Money.kt (100%)

100% 가 아니면 뭔가 바뀐 것이다.

4️⃣ 컴파일과 테스트

./gradlew compileKotlin
./gradlew test --tests '*Point*'

단계마다 돈다.
깨지면 그 단계 안에서 해결한다.

5️⃣ 커밋

git commit -m "refactor: Money, PointAmount 를 domain/model 로 이동

로직 변경 없음. import 수정만."

메시지에 “로직 변경 없음” 을 명시한다.
리뷰어가 Diff를 읽는 방식이 달라진다.

6️⃣ 다음 단계

여섯 단계를 여섯 번 반복한다.

이동 중에 발견되는 것들

이 작업의 부수 효과다.

⚠️ PointService 를 옮기려는데
   legacy/PointMigrationJob 이 참조하고 있습니다.
   이 Job은 @Profile("migration") 으로 활성화됩니다.

34장에서 말한 숨은 의존이
이동 단계에서 확실하게 드러난다.

정적 조사에서 놓친 것도
컴파일러가 잡아준다.

발견하면 그 자리에서 고치지 않는다.

발견한 예상 밖 의존을 tasks/point-move.md 에 기록해줘.
이번 이동 범위에서는 제외하고, 컴파일만 되게 최소한으로 처리해줘.

검증을 자동화한다

단계가 많아지면 사람이 매번 확인하기 어렵다.

#!/bin/bash
# scripts/verify-move.sh
set -e
./gradlew compileKotlin compileTestKotlin
./gradlew test --tests '*Point*'
./gradlew ktlintCheck
git diff -M --stat | grep -v "100%" && echo "⚠️ 순수 이동이 아닌 변경 있음"

이 스크립트를 CLAUDE.md 에 적어두면
Agent가 매 단계 실행한다.

49장에서 이것을 Hook으로 만든다.

중단 조건

24장의 원칙이 여기서 특히 필요하다.

컴파일 에러가 20개를 넘으면 멈추고 상황을 알려줘.
고치지 말고, 무엇 때문에 이렇게 됐는지 분석해줘.

에러 200개는 대개 방향이 틀렸다는 뜻이다.

⚠️ 그 상태에서 Agent가 200개를 고치면
코드는 컴파일되지만 구조는 엉망이 된다.

되돌리는 편이 낫다.

git reset --hard HEAD    # 사람이 직접 실행

25장에서 이 명령을 deny 에 넣은 이유이기도 하다.
되돌리기는 사람의 결정이다.

이 장의 핵심

• 파일 하나를 옮기면 연쇄가 시작되고, 중간에 컴파일이 깨지면 피드백 루프가 끊긴다
• Agent는 컴파일 에러 200개를 보면 200개를 다 고치려 한다
• 중간에 방향이 틀렸다고 판단하지 않는다
• 순수한 이동은 IDE가 1초에 정확히 한다 — Agent에게 시키는 것은 비효율이다
• 기계적으로 정확한 일은 기계에게, 판단이 필요한 일은 Agent에게 맡긴다
• 의존이 적은 것부터 옮긴다 — 반대 순서면 매 단계 컴파일이 깨진다
• 이동과 수정을 섞지 않는다 — git diff -M 이 100%가 아니면 뭔가 바뀐 것이다
• 이동 중 드러나는 숨은 의존은 기록만 하고 범위에서 제외한다
• 컴파일 에러가 임계치를 넘으면 고치지 말고 멈춘다
• 에러 200개는 대개 방향이 틀렸다는 뜻이다 — 되돌리는 편이 낫다

42장. 경계를 규칙으로 강제하기 — 의존성 테스트로 고정한다

포인트 도메인을 정리했다.

계층이 나뉘었고, 순환이 사라졌고,
Domain 패키지에 JPA import가 없다.

그리고 3주 뒤 다시 보면 이렇게 되어 있다.

// point/domain/PointPolicy.kt
import org.springframework.stereotype.Component
import com.company.order.OrderRepository        // ⚠️

문서로 그은 경계는 무너진다

이유는 악의가 아니다.

급한 기능이 있었고,
그 자리에서 그게 가장 빠른 방법이었다.

사람도 그렇고 Agent는 더하다.

15장에서 본 그대로다.

CLAUDE.md 에 대문자로 세 번 써도
import 한 줄을 막지는 못한다.

16장의 에스컬레이션이 여기서 필요해진다.

문장 → Skill → Hook → 권한

경계는 테스트로 올라간다.

의존성 테스트

JVM 진영에는 ArchUnit이 있고,
Kotlin에는 Konsist가 있다.

둘 다 “코드 구조를 검증하는 테스트” 다.

@Test
fun `domain 패키지는 Spring에 의존하지 않는다`() {
    Konsist.scopeFromPackage("..point.domain..")
        .files
        .assertFalse { it.hasImport { imp ->
            imp.name.startsWith("org.springframework")
        }}
}

@Test
fun `point 도메인은 order 를 참조하지 않는다`() {
    Konsist.scopeFromPackage("..point..")
        .files
        .assertFalse { it.hasImport { imp ->
            imp.name.startsWith("com.company.order")
        }}
}

이 테스트가 있으면
앞의 import는 CI에서 빨간불이 된다.

🔥 그리고 Agent에게는 즉각적인 피드백이 된다.

> ./gradlew test --tests '*ArchitectureTest'

  point 도메인은 order 를 참조하지 않는다  FAILED
    Import 'com.company.order.OrderRepository' found in
    point/domain/PointPolicy.kt

24장의 좋은 피드백 네 조건을 모두 만족한다.
빠르고, 구체적이고, 자동이고, 위치를 지목한다.

Agent는 이 메시지를 받으면 다른 방법을 찾는다.

무엇을 규칙으로 만드는가

경계 카드에서 그대로 나온다.

⚠️ 마지막 두 개가 특히 값지다.

28장과 30장에서 문장으로 적었던 규칙이
여기서 실행 가능한 검사로 승격된다.

기존 위반은 baseline으로

현실적인 문제가 하나 있다.

> ./gradlew test --tests '*ArchitectureTest'
  FAILED — 위반 147건

레거시에 규칙을 걸면 처음엔 전부 실패한다.

두 가지 방법이 있다.

예외 목록을 명시한다

private val KNOWN_VIOLATIONS = setOf(
    "point/PointService.kt",          // 마이그레이션 대상
    "legacy/PointMigrationJob.kt",    // 제거 예정
)

@Test
fun `point 도메인은 order 를 참조하지 않는다`() {
    Konsist.scopeFromPackage("..point..")
        .files
        .filterNot { it.path in KNOWN_VIOLATIONS }
        .assertFalse { ... }
}

🔥 목록이 있으면 두 가지가 생긴다.

• 새로운 위반은 즉시 막힌다
• 남은 부채가 눈에 보인다

목록이 줄어드는 것이 진척도다.

새 코드에만 적용한다

@Test
fun `새 구조의 domain 패키지는 프레임워크에 의존하지 않는다`() {
    Konsist.scopeFromPackage("..point.domain..")   // 새 구조만
        .files.assertFalse { ... }
}

40장에서 “신규 코드부터” 라고 한 것과 같은 전략이다.

언제 검사할 것인가

같은 테스트라도 언제 도느냐로 효과가 달라진다.

세 번째가 가장 좋다.

Agent가 경계를 넘는 import를 추가한 그 순간
실패가 돌아오면 즉시 다른 방법을 찾는다.

⚠️ 다만 검사가 느리면 작업이 답답해진다.

Konsist/ArchUnit 검사는 대개 수 초 안에 끝난다.
느리면 시점을 커밋 전으로 미룬다.

파일 수정 직후에 검사를 자동으로 돌리는 방법이
Claude Code의 Hook이다. 49장에서 설정과 함께 다룬다.

지금은 CI에 걸어두는 것만으로도 충분하다.
경계가 무너지는 것은 막을 수 있다.

규칙이 개발을 막을 때

⚠️ 여기서 판단이 필요한 순간이 온다.

급한 장애 수정인데 아키텍처 테스트가 막습니다.
KNOWN_VIOLATIONS 에 추가할까요?

Agent가 이렇게 물어오면 사람이 답한다.

세 가지 선택지가 있다.

세 번째가 실제로 있다.

규칙을 만들 때 몰랐던 사정이 나중에 드러나면
규칙이 현실과 안 맞는 것이다.

16장의 “규칙에는 수명이 있다” 가 여기에도 적용된다.

- 아키텍처 규칙을 우회해야 하면
  임의로 예외를 추가하지 말고 먼저 물어본다

이 한 줄이 없으면 Agent가 조용히 예외를 늘린다.

규칙이 만드는 진짜 변화

이 장의 작업이 끝나면
Agent와 일하는 방식이 달라진다.

flowchart LR
    A[Agent가 코드를 쓴다] --> B{구조 검사}
    B -->|위반| C[즉시 실패 · 다른 방법 탐색]
    B -->|통과| D[진행]

경계가 문서가 아니라 조건이 됐다.

4장에서 말한 그 차이다.

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

이제 새 팀원이 와도, Agent가 바뀌어도
경계는 유지된다.

🔥 이것이 8부에서 가장 오래 남는 산출물이다.

옮긴 파일은 다시 흩어질 수 있지만
테스트는 흩어지는 것을 막는다.

이 장의 핵심

• 문서로 그은 경계는 급한 기능 하나에 무너진다
• CLAUDE.md 는 import 한 줄을 막지 못한다
• 경계는 의존성 테스트로 승격시킨다 (ArchUnit / Konsist)
• 구조 검사 실패 메시지는 좋은 피드백의 네 조건을 모두 만족한다
• 문장으로 적었던 트랜잭션·외부호출 규칙이 실행 가능한 검사가 된다
• 레거시에 규칙을 걸면 처음엔 전부 실패한다 — 기존 위반은 예외 목록으로 명시한다
• 예외 목록이 줄어드는 것이 진척도다
• 같은 테스트라도 언제 도느냐로 효과가 다르다 — 수정 직후가 가장 좋다
• 규칙이 개발을 막으면 우회·예외·규칙 수정 중 사람이 고른다
• Agent가 임의로 예외를 추가하지 못하게 규칙을 하나 더 둔다
• 옮긴 파일은 다시 흩어질 수 있지만 테스트는 흩어지는 것을 막는다

43장. 데이터 경계 준비 — 공유 테이블과 조인부터 끊기

코드는 나뉘었다.

패키지가 정리됐고, 의존성 테스트가 지키고 있다.

그런데 DB를 열어보면 아무것도 안 바뀌었다.

SELECT o.id, o.amount, p.balance
FROM orders o
JOIN point_balances p ON o.user_id = p.user_id
WHERE ...

주문 쿼리가 포인트 테이블을 조인한다.

코드 경계보다 데이터 경계가 더 완고하다.

35장의 그 문장이 여기서 실제 작업이 된다.

왜 데이터가 마지막 장벽인가

코드는 옮기면 끝이다.

데이터는 그렇지 않다.

그래서 이 작업은 분리하기 위해서 하는 것이 아니다.

당장 분리하지 않아도
데이터 경계를 정리하면 얻는 것이 있다.

• 어느 도메인이 무엇을 소유하는지 명확해진다
• 스키마 변경의 영향 범위가 좁아진다
• 나중에 떼어낼 수 있는 상태가 된다

세 단계

flowchart LR
    A[1. 조인 끊기] --> B[2. 쓰기 주체 단일화]
    B --> C[3. 스키마 분리]

3단계까지 갈지는 나중에 정해도 된다.
1, 2단계만으로도 충분한 가치가 있다.

1️⃣ 조인을 전수 조사한다

도메인 경계를 넘는 조인을 전부 찾아줘.

- JPQL, QueryDSL, 네이티브 쿼리, @Query 전부
- 엔티티 연관관계(@ManyToOne 등)도 포함
- 어느 도메인 테이블과 어느 도메인 테이블을 조인하는지
- 각 조인이 어떤 화면·API에서 쓰이는지

표로 정리하고 docs/cross-domain-joins.md 에 저장해줘.

⚠️ 엔티티 연관관계를 빠뜨리기 쉽다.

@Entity
class Order(
    @ManyToOne val pointBalance: PointBalance   // 조인이다
)

이것도 조인이고, 33장의 N+1 원인이기도 하다.

조인을 무엇으로 대체하는가

세 가지 방법이 있고, 각각 대가가 다르다.

첫 번째부터 시작한다.

// 전
val orders = orderRepository.findWithPointBalance(userId)

// 후
val orders = orderRepository.findByUserId(userId)
val balance = pointQueryService.getBalance(userId)   // 도메인 API
return OrderListResponse.of(orders, balance)

🔥 여기서 pointQueryService 가 핵심이다.

지금은 같은 프로세스 안의 클래스지만,
나중에 HTTP 호출로 바꿀 수 있는 지점이 된다.

44장에서 이 인터페이스를 다시 다룬다.

성능은 실제로 나빠진다

⚠️ 이 사실을 숨기지 않는 편이 낫다.

조인 하나가 쿼리 두 개가 되고,
목록 조회에서는 N+1이 될 수도 있다.

이 조인을 제거하면 쿼리가 어떻게 바뀌는지 보여줘.

- 현재: 쿼리 1개
- 변경 후: 쿼리 몇 개
- 100건 조회 시 각각 몇 번 실행되는지

33장의 원칙이 여기서도 적용된다.
측정하고 판단한다.

대개 이렇게 해결한다.