[이제와서 시작하는 Claude AI 마스터하기 #17] 의도 기반 코딩 마스터하기

Editor’s Note AI에게 코드를 시킬 때 답답함을 느꼈다면, 그것은 AI 탓이 아니라 지시 방식(Protocol)의 문제일 확률이 높습니다.
이번 편에서는 구현의 디테일이 아닌 설계의 의도(Intent)를 전달하여, 시니어 엔지니어급의 결과물을 받아내는 프롬프트 엔지니어링을 다룹니다.

---

1. The Paradigm Shift: Imperative vs Declarative

우리는 코딩을 배울 때 “어떻게(How)”에 집중했습니다. “for문을 돌리고, if문으로 체크해서…” 하지만 Claude Code와 같은 Agentic AI에게는 “선언적(Declarative)”으로 명령해야 합니다.

Level	명령어 예시	AI의 반응
Junior	“A 파일 열어서 3번째 줄 함수 고쳐줘.”	시키는 대로만 함 (사이드 이펙트 발생 위험)
Senior	“이 로직 좀 이상한데 고쳐줘.”	문맥을 파악 못해 엉뚱한 코드 생성
Master	“사용자 인증 흐름에서 토큰 갱신 실패 시 재시도 로직이 누락된 것 같아. 표준 재시도 정책(Exponential Backoff)을 적용해줘.”	문맥 파악 + 모범 사례 적용 + 검증

---

2. Master Pattern: The “R.I.P” Prompting

제가 정립한 R.I.P 프롬프트 패턴을 소개합니다. 이 구조는 실패를 줄여주지만, 결과를 보장하지는 않습니다. 마지막에는 반드시 테스트, diff, 리뷰 기준으로 확인해야 합니다.

1. Role & Context (역할 및 맥락)

“너는 10년 차 백엔드 아키텍트야. 지금 우리는 MSA로 전환 중이고, 이 코드는 결제 모듈의 핵심부야.”

2. Intent & Constraint (의도 및 제약)

“현재 동기식(Sync)으로 처리되는 알림 발송 로직을 비동기(Async) 큐 기반으로 변경하고 싶어. (Intent)
단, Redis가 아닌 기존에 깔려있는 RabbitMQ를 사용해야 하고, 실패 시 Dead Letter Queue로 빠져야 해. (Constraint)”

3. Plan & Verify (계획 및 검증)

“코드를 건드리기 전에 먼저 변경 계획(Step-by-step)을 브리핑해. 그리고 수정 후에는 단위 테스트를 추가해서 안전함을 증명해.”

여기서 중요한 것은 “계획을 말하게 하는 것”보다 “검증 기준을 먼저 정하는 것”입니다.

**Verify**
- 기존 테스트 중 관련 범위를 먼저 실행한다.
- 버그 재현 테스트를 하나 추가한다.
- 수정 후 같은 테스트가 통과하는지 확인한다.
- `git diff` 기준으로 변경 범위가 의도와 맞는지 요약한다.
- 실패한 검증이 있으면 숨기지 말고 원인과 다음 선택지를 말한다.

AI에게 맡길수록 완료 기준은 더 구체적이어야 합니다. “고쳐줘”는 열린 지시이고, “이 테스트가 통과할 때까지 고쳐줘”는 닫힌 지시입니다.

---

3. Real World Case: Legacy Refactoring

실제 현업에서 가장 골치 아픈 “수천 라인짜리 스파게티 코드”를 리팩토링하는 시나리오입니다.

❌ Bad Approach

“이 파일 너무 기니까 함수로 좀 쪼개줘.” -> 결과: 의미 없는 func1, func2로 쪼개진 더 난해한 코드가 됨.

✅ Expert Approach (R.I.P 적용)

**Context**: `OrderController.java`가 3000줄이 넘어서 유지보수가 불가능해.
**Intent**: 이 클래스를 **단일 책임 원칙(SRP)**에 따라 분리하고 싶어.
**Strategy**:

1. 비즈니스 로직은 `OrderService`로 이동
2. 유효성 검사는 `OrderValidator`로 이동
3. 응답 포맷팅은 `OrderDtoMapper`로 이동
   **Action**:

- 각 클래스를 생성하고 코드를 이동시켜.
- 기존 Controller는 위 클래스들을 주입(DI)받아 위임(Delegate)하는 형태로 얇게 만들어.
- 기능이 100% 동일하게 동작함을 보장하는 통합 테스트를 먼저 작성하고 리팩토링해.

이렇게 지시하면 Claude Code는 단순한 텍스트 편집이 아니라, 아키텍처 리설계(Re-architecting)를 수행합니다.

---

4. Pro Tip: TDD (Test-Driven Debugging)

버그를 고칠 때도 순서를 바꾸십시오. 이것이 마스터의 방식입니다.

1. “버그를 재현하는 테스트 코드부터 짜줘.” (Red)
2. “이제 그 테스트가 통과하도록 로직을 수정해.” (Green)
3. “코드를 더 깔끔하게 다듬어.” (Refactor)

이 순서를 강제하면, AI가 “고쳤다고 거짓말(Hallucination)”하는 것을 원천 차단할 수 있습니다. 테스트가 통과했다는 증거가 있으니까요.

실무용 안전장치

TDD를 적용할 때는 다음 체크리스트를 함께 둡니다.

단계	확인할 것
Red	새 테스트가 실제로 실패했는가?
Green	최소 수정으로 테스트가 통과했는가?
Refactor	테스트 결과가 유지되는가?
Diff review	관련 없는 파일을 건드리지 않았는가?
Regression	기존 핵심 테스트가 함께 통과하는가?

특히 레거시 리팩토링에서는 한 번에 큰 구조 변경을 맡기지 마세요. “테스트 추가 PR”, “동작 보존 리팩토링 PR”, “새 기능 PR”처럼 작업 단위를 쪼개면 AI의 실수도 빨리 발견됩니다.

---

5. Claude Code에서 의도를 고정하는 방법

의도 기반 코딩은 프롬프트 한 번으로 끝나지 않습니다. 프로젝트에 반복 가능한 기억과 명령을 남겨야 합니다.

CLAUDE.md에 의도 저장

# Project Intent

이 프로젝트는 결제 안정성이 최우선이다.

## Change Rules
- 결제 금액 계산 로직은 테스트 없이 수정하지 않는다.
- 환불/취소 로직은 통합 테스트를 함께 갱신한다.
- 외부 API 실패는 retry와 idempotency key를 함께 검토한다.

## Verification
- pnpm test payment
- pnpm typecheck
- pnpm lint

Slash command로 반복 지시 줄이기

---
description: Create an intent-based refactoring plan
---

Refactor target:
$ARGUMENTS

Before editing, return:
1. Current responsibility map
2. Target responsibility map
3. Files likely to change
4. Tests to add first
5. Risks and rollback strategy

이렇게 .claude/commands/refactor-plan.md로 저장하면 매번 긴 프롬프트를 다시 쓰지 않아도 됩니다.

---

6. Takeaway

AI는 당신의 거울입니다. 당신이 “코더(Coder)”처럼 말하면 AI도 코딩만 하고, 당신이 “아키텍트(Architect)”처럼 말하면 AI도 설계를 합니다.

Action Item: 오늘 당장 팀 내에서 가장 복잡한 모듈을 하나 골라, 위 R.I.P 패턴으로 리팩토링 계획만 먼저 받아보십시오. 바로 수정시키지 말고, 테스트 후보와 위험 요약이 충분한지 리뷰한 뒤 작은 단위로 실행하세요.

---

“이제와서 시작하는 Claude AI 마스터하기” 시리즈는 AI 개발 도구를 처음 접하는 분들을 위한 실전 가이드입니다.