에이전트 주도 개발에서 발생하는 문제를 해결하고, 컨텍스트를 정밀하게 관리하는 방법

바이브 코딩이란?
Claude Code 5분 만에 시작하기
1. 바이브 코딩의 여정: 문제와 해결의 반복
- 시작: 프롬프트 한 줄의 마법
- 첫 번째 시도: "스펙 문서를 통째로 넣으면 되지 않을까?"
2. 왜 이런 문제가 발생하는가?
3. 해결책: LLM의 인지적 한계를 시스템으로 보완하기
4. 효과적인 프롬프트 작성
- 핵심 원칙: "누가 읽어도 같은 것을 상상할 수 있어야 한다"
- 실전 팁
  - 한 번에 하나만: 복합 요구사항은 쪼개기
  - 숫자로 명확하게: "적당히" 대신 구체적 수치
  - 결과 확인 후 다음 요청: 오류 누적 방지
  - 경계 조건 명시: 예외 상황을 미리 정의
  - 부정문보다 긍정문: 하지 말아야 할 것보다 해야 할 것을 명시
5. 정리: 바이브 코딩의 핵심 원칙
6. 자주 발생하는 문제와 해결
마무리: LLM의 한계를 시스템으로 보완한다

작성 환경: Claude Code 2.0.67, Claude Opus 4.5 (claude-opus-4-5-20251101)

Claude Code와 LLM은 빠르게 발전하고 있어 일부 성능, 기능, UI가 변경될 수 있습니다. 최신 정보는 공식 문서를 참고하세요.

바이브 코딩이란?

바이브 코딩(Vibe Coding)은 2025년 2월, Andrej Karpathy가 X(Twitter)에서 처음 사용한 용어다.

"나는 이것을 '바이브 코딩'이라고 부른다. 완전히 바이브에 몸을 맡기고, 지수적 성장을 받아들이며, 코드가 존재한다는 것조차 잊어버리는 방식이다. […] 나는 항상 'Accept All'을 누르고, 더 이상 diff를 읽지 않는다. […] 이건 진짜 코딩이 아니다—그냥 보고, 말하고, 실행하고, 복붙할 뿐인데, 대부분 잘 돌아간다." 원문

Karpathy의 원래 정의는 꽤 극단적이다. 코드를 읽지도 않고, diff도 확인하지 않고, 그냥 분위기(vibe)에 맡기는 방식이다.

하지만 실무에서는 더 넓은 의미로 사용된다. 이 가이드에서는 "코드를 읽되, LLM이 생성을 주도하는" 방식을 다룬다:

자연어로 의도를 전달하면
에이전트가 코드를 생성하고, 파일을 수정하고, 명령을 실행하며
개발자는 결과를 확인하고 방향을 조정한다

용어 정리: 이 글에서 "에이전트"는 Claude Code 등의 프로그램을 의미한다. "LLM"은 일반적인 대규모 언어 모델의 특성을 설명할 때 사용한다.

Karpathy의 정의처럼 "코드를 읽지 않는" 진정한 바이브 코딩에 도달하려면, 에이전트의 결과를 신뢰할 수 있어야 한다. 이 가이드는 그 신뢰를 구축하기 위한 징검다리를 제공한다.

Claude Code 5분 만에 시작하기

$ # https://www.claude.com/product/claude-code
$ curl -fsSL https://claude.ai/install.sh | bash

$ # 프로젝트 디렉토리에서 Claude Code 실행
$ cd your-project
$ claude

$ # 원하는 것을 요청
$ claude> 할일 앱 만들어줘

이게 전부다. Claude Code가 알아서 계획을 짜고 코드를 작성한다. (물론 파일 수정 권한은 허용해줘야 한다.)

1. 바이브 코딩의 여정: 문제와 해결의 반복

시작: 프롬프트 한 줄의 마법

바이브 코딩은 단순하게 시작했다.

Claude Code가 코드를 뚝딱 만들어낸다. 신기하다. 하지만 곧 문제를 발견한다.

> 아, 비밀번호 검증이 빠졌네. 추가해줘.
> 에러 메시지도 보여줘야지.
> 로그인 성공하면 리다이렉트 해줘.
> 세션 관리는?
...

매번 빠진 부분을 발견하고, 프롬프트를 작성하고, 결과를 확인하고, 다시 수정을 요청한다.

첫 번째 시도: "스펙 문서를 통째로 넣으면 되지 않을까?"

개발자들은 자연스럽게 생각했다. PRD나 스펙 문서를 한 번에 넣어주면, 에이전트가 알아서 전체를 구현해주지 않을까?

> 다음 스펙에 따라 인증 시스템을 구현해줘:

[30페이지 분량의 상세 스펙 문서]
- 1. 사용자 인증
  - 1.1 이메일/비밀번호 로그인
  - 1.2 소셜 로그인 (Google, Kakao)
  - 1.3 2FA 옵션
- 2. 인증 관리
  - 2.1 JWT 토큰 발급
  - 2.2 리프레시 토큰
  ...

결과는 실망스러웠다. 뭔가 만들어지긴 하는데, 이상하다. 스펙에 분명히 있던 내용이 빠져있고, 요청하지 않은 기능이 들어가 있고, 전체적으로 방향이 이상하다.

2. 왜 이런 문제가 발생하는가?

Lost in the Middle - 긴 문서에서 중간 정보가 사라진다

에이전트는 긴 컨텍스트를 처리할 때 중간에 위치한 정보를 놓치는 경향이 있다. 이 현상은 "Lost in the Middle" 논문에서 다루고 있다.

[30페이지 스펙 문서]
├── 1~5페이지: 잘 반영됨 ✓
├── 6~25페이지: 일부 누락 가능 ⚠️  ← 여기에 중요한 요구사항이 있었다면?
└── 26~30페이지: 잘 반영됨 ✓

이 패턴은 심리학의 서열 위치 효과와 유사하다.

효과	설명
초두 효과 (Primacy)	처음 정보가 장기기억에 저장되어 잘 기억됨
최신 효과 (Recency)	최근 정보가 단기기억에 남아 잘 기억됨
중간 정보	반복 기회도 적고, 단기기억에서도 밀려나 누락됨

LLM은 사람이 생성한 데이터로 학습되었기 때문에, 인간 인지의 편향이 학습 데이터에 반영되어 있을 가능성이 있다.

학습 데이터의 시점 편향 - 과거 패턴으로 회귀한다

에이전트는 학습 시점에 더 많이 존재했던 패턴을 우선시하는 경향이 있다.

재미있는 썰이 있다. AI에게 "웹사이트 만들어줘"라고 하면 높은 확률로 보라색 그라데이션이 나온다는 것이다. Tailwind CSS 창시자가 5년 전 기본 버튼 색상을 bg-indigo-500으로 설정했고, 이 색상이 수많은 튜토리얼에 퍼졌다. AI는 그 "중앙값"을 학습했고, 결과적으로 AI가 생성한 UI는 전부 비슷한 보라색이 되었다는 이야기다.

코드에서도 비슷한 현상이 나타날 수 있다.

턴	요청	결과
1턴	"Zustand 사용해. Redux 금지"	✅ Zustand로 작성
5턴	"새로운 상태 추가해줘"	✅ Zustand 유지
10턴	"장바구니 기능 만들어줘"	⚠️ Redux 패턴 섞임
15턴	"결제 기능 추가해줘"	❌ Redux로 회귀

Zustand는 2019년에 등장했지만, 학습 데이터에는 Redux 예제가 압도적으로 많다. 컨텍스트의 명시적 지시와 학습된 prior가 경쟁하면서, 대화가 길어질수록 학습된 패턴이 우세해질 수 있다.

스펙 자체의 모호성 - 해석의 여지가 존재한다

완벽한 스펙 문서를 작성하는 것은 본질적으로 어렵다.

모순되는 요구사항

스펙 문서 7페이지: "모든 요청과 응답을 로그에 기록한다"
스펙 문서 12페이지: "개인정보는 어떤 경우에도 로그에 남기면 안 된다"

→ 에이전트: 개인정보가 포함된 요청은 어떻게 로깅할까?

비슷한 사례로 GDPR의 "삭제권"과 "감사 의무" 충돌이 있다. 이 경우는 예외 조항으로 해결 가능하지만, 스펙 문서에서 이런 충돌은 흔하게 발생하고 예외 조항은 놓치기 쉽다.

엔트로피가 높은 표현

정보 엔트로피 관점에서, 여러 의미로 해석될 수 있는 표현은 불확실성이 높다.

"보안을 고려한 인증 시스템"

→ 해석 A: 비밀번호 암호화만 적용
→ 해석 B: 2FA 도입
→ 해석 C: OAuth 2.0 + JWT + 세션 관리 전체 구현

동일한 문장도 읽는 사람의 배경지식에 따라 전혀 다르게 해석될 수 있으며, 에이전트도 마찬가지다.

오류 중첩 - 작은 오해가 눈덩이가 된다

에이전트는 자기회귀(autoregressive) 방식으로 작동한다. 앞에서 생성한 내용을 기반으로 다음 내용을 생성하기 때문에, 초반의 작은 오해가 이후 모든 코드에 영향을 미친다.

스펙: "보안을 고려한 인증 시스템"

에이전트의 처리 과정:
1. "보안을 고려" → 2FA가 필요하겠군 (자의적 해석)
2. 2FA를 전제로 세션 관리 설계 (오해 기반 구현)
3. 2FA를 전제로 에러 처리 구현 (오류 누적)
4. 2FA를 전제로 UI 컴포넌트 생성 (오류 확산)
5. 2FA를 전제로 테스트 코드 작성 (오류 고착화)

결과: 요청하지 않은 2FA가 시스템 전체에 녹아있음

문제는 이 오류를 나중에 발견할수록 수습 비용이 기하급수적으로 증가한다는 것이다.

작업 기억의 한계 - 저장은 되지만 조작이 어렵다

앞서 살펴본 Lost in the Middle은 내용이 길어질 때 중간 정보가 희석되는 현상이다. 여기서는 다른 문제를 살펴보자: 지시가 길지 않음에도 별개의 항목이 많아지면 일부가 누락되는 현상이다.

> 다음 규칙을 모두 지켜서 코드를 작성해줘:
> 1. 에러는 명시적으로 처리
> 2. 모든 API 호출에 타임아웃 설정
> 3. 환경변수로 설정값 관리
> 4. 로그는 JSON 형식으로
> 5. 테스트 코드도 함께 작성

→ 1, 2번은 잘 지키는데 4, 5번이 빠져있음

인간도 작업 기억 용량에 한계가 있다. Miller(1956)의 고전적 연구는 7±2개의 청크를 제시했지만, 현대 연구(Cowan, 2001)는 새로운 정보의 순수한 작업 기억 용량을 4±1개 항목으로 추정한다. 흥미롭게도 LLM도 유사한 한계를 보인다. Zhang et al.(2024, EMNLP)의 n-back 테스트에서 GPT-4조차 3개 이상의 항목을 동시에 추적할 때 성능이 급격히 저하되었다. 다만 LLM의 메커니즘은 인간의 작업 기억과는 다르다.

인간의 작업 기억 vs LLM의 컨텍스트

인간은 작업 기억(working memory)이라는 별도의 계산 영역이 있다. 복잡한 계산을 할 때 중간 결과를 임시로 저장하고, 필요한 정보만 로드해서 처리하고, 불필요한 정보는 내려놓을 수 있다.

인간이 "15 × 7 + 23"을 계산할 때:
1. 15 × 7 = ? → 작업 기억에서 계산
2. 105를 임시 저장 (원래 숫자들은 내려놓음)
3. 105 + 23 = 128

LLM은 이런 별도의 작업 영역이 없다. 어텐션 메커니즘이 "더 주목/덜 주목"을 모방하지만, 컨텍스트 내 모든 토큰에 항상 접근 가능하다. 인간처럼 특정 정보를 명시적으로 "내려놓고" 작업 기억을 비우는 것은 불가능하다.

LLM이 여러 규칙을 적용할 때:
- 모든 규칙이 컨텍스트에 존재함
- 하지만 "지금 이 규칙에 집중"하는 메커니즘이 약함
- 결과: 일부 규칙이 출력에 반영되지 않음

작업	인간	LLM
정보 저장	✅	✅ (컨텍스트에 존재)
특정 정보에 집중	✅ (작업 기억에 로드)	⚠️ (어텐션으로 간접 참조)
중간 결과 보관	✅ (임시 저장)	❌ (출력하지 않으면 사라짐)
불필요한 정보 무시	✅ (내려놓음)	❌ (컨텍스트에 계속 남음)

이 한계를 극복하기 위한 시도들

이 구조적 한계를 극복하기 위해 여러 방법이 도입되었다:

1. Chain of Thought (2022)

중간 추론 단계를 외부로 출력하게 해서, 출력된 텍스트 자체가 "외부 메모지" 역할을 한다.

일반: "답은 128입니다"
CoT: "먼저 15 × 7 = 105, 그 다음 105 + 23 = 128입니다"

2. Extended Thinking / Reasoning Tokens (2024~)

최신 모델의 Extended Thinking 등은 "thinking tokens"를 도입해서 답변 전에 추론 단계를 거친다. 하지만 이것도 본질적으로는 외부 메모지를 추가한 것이다.

3. 에이전트 루프

Plan → Act → Verify를 반복하면서, 파일 시스템이나 Todo 같은 외부 도구를 작업 공간으로 활용한다.

결국 현재까지의 해결책들은 LLM 내부에 작업 기억을 만든 게 아니라, 외부에서 작업 공간을 제공하는 방식이다. Claude Code의 도구들도 이 맥락에서 이해할 수 있다.

3. 해결책: LLM의 인지적 한계를 시스템으로 보완하기

LLM의 작업 기억 한계는 근본적으로 해결되지 않았다. 대신 우리는 시스템 수준에서 이를 우회한다. 인간이 인지 한계를 극복하는 전략을 참고해서, Claude Code가 이를 LLM에게 외부에서 적용해주는 것이다.

인간의 전략	LLM의 한계	Claude Code 도구
메모지에 적고 수정	작업 공간 부재 (중간 결과 임시 저장 불가)	파일 시스템으로 외부화
체크리스트로 진행 관리	여러 항목 동시 추적 실패	Todo
작게 쪼개서 처리	Lost in the Middle (긴 컨텍스트에서 중간 정보 누락)	멀티턴 대화
역할 분담	단일 컨텍스트 처리 한계	서브에이전트
실행 전 계획 점검	자기회귀로 인한 오류 중첩	Plan 모드, Extended Thinking
중요사항 주기적 확인	긴 대화에서 초기 정보 희석	CLAUDE.md
불필요한 정보 정리	컨텍스트 선택적 비활성화 불가	Compact + 파일로 백업

인간은 작업 기억에서 불필요한 정보를 내려놓으면서도 필요할 때 장기 기억에서 다시 불러올 수 있다. Claude Code의 Compact는 컨텍스트를 요약해서 집중력을 유지하고, 파일 시스템에 기록을 남겨서 필요시 복구할 수 있게 한다.

핵심 원리: 인간이 인지 한계를 극복하는 방식—정보를 쪼개고, 중요한 건 반복하고, 중간중간 점검하고, 불필요한 건 정리하는 것—을 LLM에게도 적용하는 것이다.

방법 1: 작은 요청의 멀티턴 대화

가장 기본적인 해결책은 요청을 작게 나누는 것이다.

1턴: "로그인 화면 만들어줘. 이메일과 비밀번호로 로그인하는 기본 형태야."
     → 결과 확인 ✓

2턴: "좋아. 로그인 성공하면 /dashboard로 이동하게 해줘."
     → 결과 확인 ✓

3턴: "비밀번호 3회 틀리면 계정 30분 잠금해줘."
     → 결과 확인 ✓

각 턴이 짧아서 정보 누락이 없고, 명확해서 오해가 없으며, 매번 확인하므로 오류가 누적되지 않는다.

방법 2: Plan 모드 - 실행 전 방향 검증

Plan 모드는 Claude Code의 파일 수정 권한을 제한하고, 먼저 계획을 수립하도록 강제한다.

Plan 모드 없이 바로 실행하면?

> "인증 시스템 리팩토링해줘"

Claude가 "보안 강화"를 자의적으로 해석
→ 2FA가 필요하다고 판단
→ 바로 코드 수정 시작
→ 세션 관리, 에러 처리, UI 모두 2FA 전제로 변경
→ 10개 파일이 수정된 후에야 사용자가 결과 확인
→ "어? 나 2FA 원한 적 없는데..."
→ 이미 늦음. 10개 파일을 다시 되돌려야 함

Plan 모드를 사용하면?

> "인증 시스템 리팩토링해줘"

Claude가 먼저 계획서 작성:
"다음과 같이 리팩토링을 진행하겠습니다:
1. 2FA 도입으로 보안 강화
2. 세션 관리 로직 분리
..."

사용자: "잠깐, 2FA는 필요 없어. 세션 관리만 개선해줘."

→ 방향 수정 후 실행
→ 오류 중첩 사전 차단

Plan 모드의 핵심은 오해가 코드에 반영되기 전에 잡아내는 것이다.

Mode 설정

Shift+Tab 또는 --permission-mode 플래그로 Mode를 설정한다.

Mode	설명	용도
Default	매번 권한 요청	신중한 작업
Auto-accept	파일 수정 자동 승인	반복 작업
Plan	계획 수립 후 승인	복잡한 작업, 방향 검증

방법 3: Todo - 빠짐없이 체크리스트로 관리

여러 파일을 수정하거나 참고해야 하는 작업에서는 Todo로 명시적으로 관리하면 누락을 방지할 수 있다.

> 모든 API 엔드포인트에 rate limiting을 추가해줘. 먼저 수정이 필요한 파일 목록을 Todo로 만들어줘.

Todos
□ routes/auth.js - 로그인/회원가입 엔드포인트
□ routes/users.js - 사용자 CRUD 엔드포인트
□ routes/products.js - 상품 조회/검색 엔드포인트
□ routes/orders.js - 주문 생성/조회 엔드포인트
□ routes/payments.js - 결제 처리 엔드포인트
□ middleware/rateLimit.js - 공통 rate limit 미들웨어 생성

10개 파일을 한 번에 수정해달라고 하면 중간에 빠지는 파일이 생길 수 있다. Todo로 목록을 먼저 만들고 하나씩 처리하면, 어떤 파일이 남았는지 명확히 보이고 누락 없이 작업을 완료할 수 있다. 이는 Lost in the Middle 문제를 우회하는 효과적인 방법이다.

방법 4: 서브에이전트 - 컨텍스트 분리

서브에이전트는 각각 독립된 컨텍스트를 가진다. 하나의 거대한 요청을 여러 서브에이전트가 나눠서 처리하면, 각 에이전트는 자신의 작업에만 집중할 수 있다.

> 각 도메인별로 Explore를 사용해서 병렬로 탐색하고 컨벤션을 파악해줘

Running 4 Explore agents...
├─ Explore 인증 도메인 · 9 tool uses · 26.0k tokens
├─ Explore 결제 도메인 · 6 tool uses · 14.7k tokens
├─ Explore 알림 도메인 · 4 tool uses · 15.9k tokens
└─ Explore 검색 도메인 · 7 tool uses · 14.8k tokens

전체 코드베이스를 한 번에 분석하면 Lost in the Middle 문제가 발생하지만, 도메인별로 분리하면 각 에이전트가 작은 컨텍스트에서 정밀하게 작업할 수 있다.

다양한 퍼소나로 검증도 가능하다:

> 여러 전문가 퍼소나를 사용해서 아키텍처를 평가해줘.

Running 5 agents...
├─ Architect evaluation · 8 tool uses · 28.3k tokens
├─ Senior engineer evaluation · 31 tool uses · 52.5k tokens
├─ DevOps/SRE evaluation · 28 tool uses · 43.5k tokens
├─ Security expert evaluation · 33 tool uses · 51.1k tokens
└─ QA engineer evaluation · 16 tool uses · 25.4k tokens

방법 5: Extended Thinking - 깊이 있는 추론

LLM은 기본적으로 바로 답변을 생성한다. Extended Thinking은 답변 전에 명시적인 추론 단계를 추가한다.

일반 모드:     질문 → 바로 답변 생성

Extended Thinking:
질문 → [생각: 여러 접근 방식 탐색 → 각 방식 결과 예측
        → 자기 검증 → 최적 경로 선택] → 답변

앞서 설명한 것처럼 이것도 본질적으로는 외부 메모지다. 하지만 추론 시간이 늘어날수록 복잡한 문제의 정확도가 향상된다.

복잡한 아키텍처 결정이나 디버깅 시에는 Tab으로 Extended Thinking을 활성화한다.

> 이 아키텍처 문제를 ultrathink해서 진행해줘

thinking budget 순서: "think" < "think hard" < "think harder" < "ultrathink"

언제 효과적인가?

Extended Thinking은 모든 작업에 효과적인 것은 아니다. 단순 코드 작성에는 오버헤드만 추가될 수 있고, 특정 유형의 작업에서 큰 차이를 만든다.

효과적인 경우:

> 이 에러 왜 발생하는지 think harder해서 분석해줘
> TypeError: Cannot read property 'map' of undefined
> [스택 트레이스 + 관련 코드]

→ 여러 가능성을 순차적으로 검토
→ 비동기 타이밍 이슈 발견
→ 데이터 로딩 전 렌더링 시도가 원인임을 파악

디버깅: 에러 원인을 추적하고 여러 가설을 검증해야 할 때
레거시 코드 분석: 복잡한 의존성과 부작용을 파악해야 할 때
아키텍처 결정: 여러 접근 방식의 트레이드오프를 비교해야 할 때
엣지 케이스 탐색: "이 코드에서 발생할 수 있는 문제점을 찾아줘"

효과가 적은 경우:

단순 CRUD 코드 생성
보일러플레이트 작성
명확한 스펙의 UI 컴포넌트 구현
패턴이 정해진 반복 작업

💡 경험적 팁: "왜?"라는 질문이 필요한 작업에는 Extended Thinking이 효과적이고, "무엇을"만 명확한 작업에는 기본 모드가 더 효율적이다.

방법 6: CLAUDE.md - 컨텍스트를 계층적으로 관리

root/CLAUDE.md - 프로젝트 온보딩용

root의 CLAUDE.md에 금지 사항이나 세부 규칙을 넣으면 대화가 길어질수록 잊혀진다. 대신 프로젝트를 처음 접하는 사람이 알아야 할 내용을 작성한다.

# 프로젝트 개요

온라인 쇼핑몰 백엔드 서비스

## 주요 명령어
- `npm run dev` - 개발 서버 실행
- `npm test` - 테스트 실행
- `npm run build` - 프로덕션 빌드

## 디렉토리 구조
src/
├── auth/       # 인증 (로그인, 세션, 토큰)
├── payment/    # 결제 (PG 연동, 환불)
├── notification/ # 알림 (이메일, 푸시)
└── search/     # 검색 (상품, 사용자)

## 데이터 흐름
요청 → 미들웨어(인증) → 핸들러 → 서비스 → 저장소 → 응답

디렉토리별 CLAUDE.md - 해당 영역 특화 컨벤션

디렉토리별 CLAUDE.md는 해당 디렉토리에 접근할 때 자동으로 주입된다. 그 디렉토리에서만 적용되는 컨벤션을 작성한다.

<!-- src/payment/CLAUDE.md -->
# 결제 도메인 컨벤션

## 필수 원칙
- 모든 금액 계산은 정수(원 단위)로 처리
- 결제 상태 변경 시 반드시 로그 기록
- PG사 API 호출은 반드시 재시도 로직 포함

## 참고
- PG 연동 문서: docs/pg-integration.md
- 환불 정책: docs/refund-policy.md

요약: 어디에 무엇을 쓸까?

위치	용도	로드 시점
root/CLAUDE.md	프로젝트 온보딩 (구조, 명령어, 흐름)	항상
src/xxx/CLAUDE.md	해당 디렉토리 특화 컨벤션	디렉토리 접근 시

방법 7: Agent Skills - 검사와 워크플로우를 자동화

Skill은 룰을 나열하는 게 아니라, 검사를 수행한다

root/CLAUDE.md에 금지 사항을 넣으면 대화가 길어질수록 잊혀진다. Skill은 단순히 룰을 나열하는 게 아니라, 실제로 검사하고 검증하는 로직을 포함해야 한다.

예시: 프로젝트 룰 검사 Skill

<!-- .claude/skills/rule-checker/SKILL.md -->
---
name: rule-checker
description: "프로젝트 규칙 위반 검사. 코드 수정 전후에 사용"
---

# 프로젝트 룰 검사

## 검사 항목
1. 에러 무시 없이 명시적 처리 여부
2. 외부 API 호출 타임아웃 설정 여부
3. 민감 정보 환경변수 관리 여부
4. TODO 주석 존재 여부
5. 비즈니스 로직 테스트 존재 여부

## 실행 방법
1. Explore로 변경된 파일 탐색
2. 각 검사 항목별 위반 사항 수집
3. 위반 목록과 수정 제안 리포트 생성

## 출력 형식
| 파일 | 위반 항목 | 심각도 | 수정 제안 |
|------|----------|--------|----------|

> 방금 수정한 파일들 룰 검사해줘

Running rule-checker skill...
├─ Explore 변경 파일 탐색 · 3 files found
├─ 검사 항목 1-5 수행
└─ 리포트 생성

위반 사항 2건 발견:
| 파일 | 위반 항목 | 심각도 | 수정 제안 |
|------|----------|--------|----------|
| services/payment.js | 타임아웃 미설정 | 높음 | fetch에 timeout 옵션 추가 |
| utils/api.js | 에러 무시 | 중간 | catch 블록에 로깅 추가 |

예시: 멀티 퍼소나 코드 리뷰 Skill

<!-- .claude/skills/multi-review/SKILL.md -->
---
name: multi-review
description: "여러 전문가 관점에서 코드 리뷰. PR 생성 전 사용"
---

# 멀티 퍼소나 코드 리뷰

## 리뷰 관점
- **Security**: 보안 취약점 (인젝션, 인증 우회 등)
- **Performance**: 성능 이슈 (N+1, 메모리 누수 등)
- **Maintainability**: 유지보수성 (복잡도, 결합도 등)
- **Testing**: 테스트 커버리지와 품질

## 실행 방법
Task를 사용해서 각 관점별로 병렬 리뷰 수행.
각 Task 결과를 종합하여 우선순위별 리포트 생성.

## 출력 형식
### 🔴 Critical
### 🟠 Major
### 🟡 Minor
### 💡 Suggestions

> PR 올리기 전에 멀티 리뷰 해줘

Running multi-review skill...
Running 4 Task agents...
├─ Security review · 12 tool uses
├─ Performance review · 8 tool uses
├─ Maintainability review · 15 tool uses
└─ Testing review · 6 tool uses

### 🔴 Critical (1건)
- [Security] services/auth.js:45 - SQL 인젝션 취약점

### 🟠 Major (2건)
- [Performance] repositories/user.js:23 - N+1 쿼리 발생
- [Testing] services/payment.js - 핵심 로직 테스트 없음

### 🟡 Minor (3건)
...

MCP vs Skill

	MCP	Skill
기반	웹/API 기반 도구	파일 시스템 기반 도구
연결 대상	외부 서비스 (Slack, GitHub, DB 등)	로컬 워크플로우, 검사 로직
설정	서버 구성 필요	SKILL.md 파일 작성
용도	외부 시스템과 통합	반복 검증, 워크플로우 자동화

MCP가 "외부 세계와 연결하는 도구"라면, Skill은 "내부 작업 방식을 정의하고 검증하는 도구"다.

Skill 구조

.claude/skills/my-skill/
├── SKILL.md (필수) - 설명과 지침
├── scripts/ (선택) - 검증 스크립트
├── reference.md (선택) - 참고 문서
└── examples.md (선택) - 예시

방법 8: Compact - 컨텍스트 정리로 집중력 유지

대화가 길어지면 컨텍스트에 불필요한 정보가 쌓인다. 인간이 작업 기억을 비우듯, Claude Code의 Compact는 대화를 요약해서 핵심만 남긴다.

> /compact

═══════════ Conversation compacted · ctrl+o for history ═══════════
  ⎿  Referenced file src/payment/PaymentService.ts
  ⎿  Todo list read (4 items)
  ⎿  Key decisions: Zustand 사용, 금액 정수 처리

언제 사용하는가?

대화가 10턴 이상 지속되었을 때: 초기 지시가 희석되기 전에
새로운 작업으로 전환할 때: 이전 작업의 세부사항이 불필요해졌을 때
응답 속도가 느려졌을 때: 컨텍스트가 너무 커졌다는 신호

중요한 정보는 파일로 백업

Compact 전에 중요한 결정사항이나 컨벤션은 파일로 저장해두면 나중에 다시 참조할 수 있다.

> 지금까지 논의한 아키텍처 결정사항을 docs/decisions.md에 정리해줘
> /compact

지금까지 살펴본 도구들은 LLM의 구조적 한계를 시스템 수준에서 보완한다. 하지만 이 도구들의 효과는 입력의 품질에 달려있다. 아무리 Todo로 관리해도 요구사항 자체가 모호하면 누락이 발생하고, Plan 모드를 사용해도 해석의 여지가 있으면 오해가 생긴다.

다음 섹션에서는 도구 활용과 함께 프롬프트 자체를 어떻게 작성해야 하는지 살펴본다.

4. 효과적인 프롬프트 작성

핵심 원칙: "누가 읽어도 같은 것을 상상할 수 있어야 한다"

나쁜 예	좋은 예
"사용자 친화적인 검색 기능"	"검색창에 2글자 이상 입력하면 추천 검색어 5개를 보여줘"
"적절한 에러 처리"	"API 호출 실패하면 '서버 연결 실패' 메시지를 빨간색으로 3초간 보여줘"
"빠르게 응답해야 해"	"API 응답이 3초 넘으면 타임아웃 처리해줘"

실전 팁

한 번에 하나만: 복합 요구사항은 쪼개기

❌ "검색 기능 만들되, 빠르고 정확하게"

✅
1턴: "제목으로 게시글 검색하는 기능 만들어줘"
2턴: "검색 결과가 100개 넘으면 20개씩 페이지로 나눠줘"
3턴: "검색 결과가 없으면 '검색 결과가 없습니다' 보여줘"

숫자로 명확하게: "적당히" 대신 구체적 수치

❌ "너무 많으면 안 돼"
✅ "파일 업로드는 한 번에 최대 5개까지만"

결과 확인 후 다음 요청: 오류 누적 방지

1턴: "로그인 폼 만들어줘"
     → 실행하고 결과 확인 ✓

2턴: "비밀번호 입력할 때 눈 아이콘 누르면 보이게 해줘"
     → 실행하고 결과 확인 ✓

경계 조건 명시: 예외 상황을 미리 정의

❌ "장바구니에 상품 추가해줘"
✅ "장바구니에 상품 추가해줘. 같은 상품이면 수량만 +1, 최대 99개까지만"

부정문보다 긍정문: 하지 말아야 할 것보다 해야 할 것을 명시

❌ "Redux 패턴 쓰지 마"
✅ "상태 관리는 Zustand로 해줘"

5. 정리: 바이브 코딩의 핵심 원칙

컨텍스트를 작게 나누고 정밀하게 관리하라.

문제	원인	해결책
요구사항 누락	Lost in the Middle	Todo로 명시적 관리, 서브에이전트로 분리
오류 중첩	초반 오해가 눈덩이처럼 커짐	Plan 모드로 사전 검증, 작은 단위로 요청
컨벤션 망각	긴 대화에서 정보 희석	디렉토리별 컨벤션 적용 및 CLAUDE.md 작성
구버전 패턴	학습 데이터 편향	사용할 패턴을 명시적으로 지정
반복 검증 필요	수동 확인의 한계	Agent Skills로 검사 자동화

한 줄 요약: 작게 나누고, 자주 확인하고, 반복은 스킬로 만들어라.

6. 자주 발생하는 문제와 해결

"분명히 말했는데 빠져있어요"

증상: 스펙에 명시한 내용이 구현에서 누락됨

원인: Lost in the Middle - 긴 컨텍스트에서 중간 정보가 무시됨 → 원인 분석 참조

해결:

Todo로 요구사항을 명시적으로 나열 → 방법 3 참조
서브에이전트로 작업을 분리 → 방법 4 참조
한 번에 하나씩 요청 → 방법 1 참조

"계속 옛날 방식으로 코드를 짜요"

증상: 최신 문법/패턴 대신 구버전 스타일로 작성

원인: 학습 데이터 편향 - 구버전이 더 많이 학습됨 → 원인 분석 참조

해결:

디렉토리별 CLAUDE.md에 버전과 패턴을 명시 → 방법 6 참조
서브에이전트나 Skill로 컨벤션 검사 자동화 → 방법 4, 방법 7 참조
"이 패턴으로 작성해줘"라고 명시적 요청

"대화가 길어지니까 처음에 정한 규칙을 안 지켜요"

증상: 초반에 정한 컨벤션이 10턴 이후부터 무시됨

원인: 긴 대화에서 초기 정보가 희석됨 → 원인 분석 참조

해결:

디렉토리별 CLAUDE.md로 컨벤션 관리 → 방법 6 참조
서브에이전트나 Skill로 컨벤션 검사 자동화 → 방법 4, 방법 7 참조
중요한 규칙은 해당 작업 시 다시 언급
새 대화 시작 고려 (컨텍스트 리셋)

"엉뚱한 방향으로 10개 파일을 수정했어요"

증상: 의도와 다른 해석으로 대규모 수정 발생

원인: 모호한 요청 + 자동 실행 → 원인 분석 참조

해결:

Plan 모드로 계획 먼저 확인 → 방법 2 참조
복잡한 작업은 단계별로 분리
"먼저 계획만 보여줘"로 시작

"같은 실수를 반복해요"

증상: 수정해도 다음 작업에서 같은 패턴의 실수 반복

원인: 일회성 피드백은 학습되지 않음

해결:

Agent Skill로 검사 로직 작성 → 방법 7 참조
커밋 전 자동 검사 실행
CLAUDE.md에 스킬을 사용한 검증 방법 명시

"서브에이전트 결과가 일관성이 없어요"

증상: 여러 서브에이전트의 결과가 서로 충돌

원인: 각 에이전트가 독립된 컨텍스트에서 작업

해결:

공통 컨텍스트를 각 서브에이전트에 전달
결과를 종합하는 최종 단계 추가
충돌 시 "이 두 결과를 통합해줘"로 요청

마무리: LLM의 한계를 시스템으로 보완한다

LLM의 작업 기억 한계는 근본적으로 해결되지 않았다. 대신 우리는 시스템 수준에서 이를 우회하고 있다. 섹션 3에서 살펴본 것처럼, Claude Code의 도구들—Todo, Plan 모드, 서브에이전트, CLAUDE.md, Compact—은 각각 LLM의 특정 인지적 한계를 보완한다.

결국 바이브 코딩의 핵심은 이 균형을 이해하는 것이다:

LLM이 잘하는 것: 패턴 인식, 코드 생성, 자연어 이해
LLM이 못하는 것: 긴 정보 추적, 능동적 상태 관리, 자기 검증
우리가 할 일: 못하는 것을 시스템으로 보완

LLM은 인간이 만든 데이터로 학습했기 때문에 인간 인지의 편향을 일부 물려받았다. 하지만 인간이 한계를 극복하는 전략—쪼개고, 반복하고, 점검하는 것—은 스스로 실행하지 못한다. Claude Code의 도구들은 이 전략을 외부에서 적용해주는 것이다.

이 관점을 갖추면 Karpathy가 말한 "Accept All, diff 안 읽기" 미래에 더 빨리, 더 안전하게 도달할 수 있다.

Claude Code를 활용한 예측 가능한 바이브 코딩 전략

댓글