Claude Code 프롬프트 마스터 가이드

AI와 대화하는 기술: 평범한 프롬프트 vs 마스터급 프롬프트
20배 더 나은 코드를 얻는 실전 프롬프트 패턴 완전 정복

---

왜 프롬프트가 중요한가?

개발자 A와 개발자 B가 있습니다. 둘 다 Claude Code를 사용합니다. 똑같은 AI, 똑같은 모델, 똑같은 과제입니다. 하지만 결과는 천지 차이입니다. A는 10줄짜리 샘플 코드를 받습니다. 실전에서는 쓸 수 없습니다. B는 500줄의 프로덕션급 코드를 받습니다. 테스트까지 포함되어 있습니다. 무엇이 다를까요? 바로 프롬프트입니다.

많은 개발자들이 AI를 처음 접하면서 실망합니다. “별거 없네”, “기대만큼 안 나오네”라고 말합니다. 하지만 문제는 AI가 아닙니다. 프롬프트입니다. 마치 검색 엔진처럼, 어떻게 질문하느냐에 따라 결과가 완전히 달라집니다. 구글에 “밥”이라고 검색하는 것과 “서울 강남역 근처 점심 식사 맛집 추천”이라고 검색하는 것의 차이를 생각해보세요.

프롬프트 엔지니어링은 단순한 기술이 아닙니다. 사고방식입니다. 여러분이 원하는 것을 정확히 표현하고, AI가 이해할 수 있는 방식으로 전달하는 기술입니다. 이 가이드는 1년간 수천 개의 프롬프트를 작성하며 얻은 통찰을 담았습니다. 실패한 프롬프트, 성공한 프롬프트, 그리고 그 차이를 만드는 패턴들을 정리했습니다.

실제 사례를 봅시다. 평범한 개발자가 Claude에게 이렇게 요청합니다.

API 만들어줘

Claude는 성실하게 응답합니다. 하지만 결과물은 10줄짜리 샘플 코드입니다. Flask로 작성된 “Hello World” 수준입니다. 에러 핸들링도 없고, 인증도 없고, 테스트도 없습니다. 개발자는 실망합니다. “AI가 이것밖에 못 해?”

같은 과제를 받은 마스터급 개발자는 다르게 접근합니다.

FastAPI로 사용자 관리 API 만들어줘.

엔드포인트:
- POST /users (회원가입, bcrypt 비밀번호)
- POST /users/login (JWT 반환, 7일 만료)
- GET /users/me (본인 정보, 인증 필요)
- PUT /users/me (정보 수정)
- DELETE /users/me (탈퇴, soft delete)

기술 스택:
- SQLModel (PostgreSQL)
- Pydantic 검증
- JWT (python-jose)

보안:
- Rate limit 10/minute
- SQL Injection 방어
- CORS 설정

파일 구조:
app/
  models/user.py
  schemas/auth.py
  api/v1/users.py
  
테스트도 pytest로 작성해줘.

이번에는 Claude가 전혀 다른 결과물을 내놓습니다. 500줄의 완전한 시스템입니다. 모델, 스키마, API, 테스트가 모두 포함되어 있습니다. 에러 핸들링도 완벽하고, 보안도 고려되어 있습니다. 즉시 프로덕션에 투입할 수 있는 수준입니다.

두 프롬프트의 차이는 무엇일까요? 글자 수? 아닙니다. 첫 번째는 3단어, 두 번째는 100단어입니다. 하지만 중요한 것은 양이 아닙니다. 구조입니다. 두 번째 프롬프트는 무엇을(What), 어떻게(How), 왜(Why)를 모두 명확히 합니다. Claude는 추측할 필요가 없습니다. 정확히 무엇을 만들어야 하는지 알고 있습니다.

이것이 바로 프롬프트 엔지니어링의 핵심입니다. AI를 속이거나 조종하는 것이 아닙니다. 명확하게 소통하는 것입니다. 여러분이 원하는 것을 정확히 표현하고, AI가 최선의 결과를 낼 수 있도록 충분한 정보를 제공하는 것입니다. 이 가이드는 그 방법을 가르칩니다. 단순한 트릭이나 팁이 아닙니다. 체계적인 접근법입니다. 여러분의 프롬프트를 평범한 수준에서 마스터급으로 끌어올릴 것입니다.

---

Part 1: 기본 원칙

1. 5가지 황금 원칙

프롬프트 엔지니어링에는 다섯 가지 핵심 원칙이 있습니다. 구체성, 구조화, 컨텍스트, 예제, 제약사항입니다. 이 다섯 가지를 마스터하면 여러분의 프롬프트는 완전히 달라집니다. 하나씩 깊이 살펴봅시다.

원칙 1: 구체성 (Specificity)

“데이터베이스 만들어줘”라고 말하는 것은 식당에 가서 “음식 주세요”라고 말하는 것과 같습니다. 종업원은 당황합니다. 한식? 중식? 양식? 메인 요리? 디저트? 추측해야 합니다. AI도 마찬가지입니다. 모호한 요청을 받으면 추측합니다. 그리고 추측은 대부분 틀립니다.

구체성은 프롬프트 엔지니어링의 가장 기본적이면서도 가장 중요한 원칙입니다. 여러분이 원하는 것을 정확하게 표현할수록, AI가 정확한 결과를 낼 확률이 높아집니다. 이는 단순한 상관관계가 아닙니다. 인과관계입니다.

실제로 많은 개발자들이 프롬프트를 짧게 쓰려고 합니다. 시간을 절약하려는 의도입니다. 하지만 역설적이게도, 짧은 프롬프트는 더 많은 시간을 낭비하게 만듭니다. AI가 잘못 이해하고, 여러분이 원하지 않는 결과를 내놓고, 다시 설명해야 하고, 또 수정을 요청해야 합니다. 결국 처음부터 구체적으로 작성하는 것보다 3배의 시간이 걸립니다.

나쁜 예를 봅시다.

데이터베이스 만들어줘

이 프롬프트는 문제투성이입니다. Claude는 수십 가지를 추측해야 합니다. 어떤 데이터베이스 시스템인가? MySQL? PostgreSQL? MongoDB? Redis? 어떤 테이블을 만들어야 하나? 각 테이블에는 어떤 필드가 필요한가? 관계는 어떻게 설정하나? 인덱스는? 제약조건은?

Claude는 성실하게 일반적인 예제를 만들어줄 것입니다. 아마도 users 테이블 하나에 id, name, email 정도만 들어있을 것입니다. 여러분이 원하는 것과는 거리가 멉니다. 그리고 여러분은 “아니, 이게 아니라…“라며 다시 설명해야 합니다.

이제 좋은 예를 봅시다.

PostgreSQL 데이터베이스 스키마 만들어줘.

테이블:
1. users
   - id: SERIAL PRIMARY KEY
   - email: VARCHAR(255) UNIQUE NOT NULL
   - password_hash: VARCHAR(255) NOT NULL
   - created_at: TIMESTAMP DEFAULT NOW()

2. posts
   - id: SERIAL PRIMARY KEY
   - user_id: INTEGER REFERENCES users(id) ON DELETE CASCADE
   - title: VARCHAR(200) NOT NULL
   - content: TEXT
   - created_at: TIMESTAMP DEFAULT NOW()

인덱스:
- users.email
- posts.user_id
- posts.created_at

schema.sql 파일로 만들어줘.

이 프롬프트는 완전히 다릅니다. Claude는 추측할 필요가 없습니다. PostgreSQL을 사용해야 한다는 것을 알고 있습니다. 정확히 어떤 테이블이 필요한지, 각 필드의 타입과 제약조건이 무엇인지 알고 있습니다. 외래 키 관계도 명확합니다. CASCADE 삭제도 지정되어 있습니다. 인덱스까지 정의되어 있습니다. 심지어 출력 파일 이름까지 지정되어 있습니다.

결과는 어떨까요? Claude는 정확히 여러분이 원하는 스키마를 만들어줍니다. 한 번에, 수정 없이, 바로 사용할 수 있는 형태로 말입니다. 이것이 구체성의 힘입니다.

하지만 여기서 의문이 듭니다. “이렇게 자세히 쓰려면 이미 알아야 하는 거 아닌가? 그럼 AI가 무슨 소용인가?” 좋은 질문입니다. 핵심을 짚었습니다. 구체성은 완전한 지식을 요구하지 않습니다. 명확한 의도를 요구합니다. 여러분이 “무엇을” 원하는지 알면 됩니다. “어떻게” 구현할지는 AI가 채워줍니다.

예를 들어, 위 프롬프트에서 여러분은 PostgreSQL 문법을 완벽히 알 필요가 없습니다. “users 테이블에 이메일이 필요하고, 중복되면 안 되고, 비밀번호는 해시로 저장한다”는 것만 알면 됩니다. 그것을 PostgreSQL로 어떻게 표현하는지는 Claude가 압니다. 여러분은 요구사항을 명확히 하면 됩니다.

원칙 2: 구조화 (Structure)

인간의 뇌는 구조를 좋아합니다. AI도 마찬가지입니다. 정보가 구조화되어 있으면 이해하기 쉽습니다. 산만하게 흩어져 있으면 놓치기 쉽습니다. 프롬프트도 글쓰기입니다. 좋은 글은 구조가 있습니다. 서론, 본론, 결론이 있습니다. 단락이 나뉘어 있고, 문장이 논리적으로 연결됩니다.

많은 개발자들이 프롬프트를 하나의 긴 문장으로 씁니다. 생각나는 대로 줄줄이 늘어놓습니다. “사용자 인증 만들어줘. JWT 써야 하고 비밀번호는 bcrypt로 해시하고 이메일 중복 체크하고 로그인하면 토큰 주고 그걸로 인증하게 해줘.” 숨이 차지 않나요? 읽기도 어렵습니다. Claude도 마찬가지입니다.

나쁜 예를 봅시다.

사용자 인증 만들어줘. JWT 써야 하고 비밀번호는 bcrypt로 해시하고 
이메일 중복 체크하고 로그인하면 토큰 주고 그걸로 인증하게 해줘.

이 프롬프트의 문제는 가독성입니다. 정보는 다 있습니다. JWT, bcrypt, 이메일 중복 체크, 토큰 인증. 하지만 한 덩어리로 뭉쳐 있어서 놓치기 쉽습니다. Claude가 “비밀번호는 bcrypt로”라는 부분을 놓칠 수 있습니다. 모든 정보가 같은 우선순위로 보이기 때문입니다.

이제 구조화된 프롬프트를 봅시다.

사용자 인증 시스템 만들어줘.

요구사항:

회원가입:
- 이메일 중복 체크
- 비밀번호: bcrypt (12 rounds)
- 검증: 이메일 형식, 비밀번호 8자 이상

로그인:
- 이메일 + 비밀번호 확인
- 성공 시: JWT 발급 (7일 만료)
- 실패 시: 401 에러

인증:
- Bearer 토큰 검증
- 만료 체크
- 사용자 정보 반환

기술 스택:
- FastAPI
- SQLModel
- python-jose (JWT)
- passlib (bcrypt)

파일 구조:
app/
  models/user.py
  schemas/auth.py
  services/auth.py
  api/v1/auth.py

차이가 느껴지나요? 같은 정보지만 완전히 다른 느낌입니다. 첫째, 읽기 쉽습니다. 눈이 자연스럽게 흐릅니다. 둘째, 우선순위가 명확합니다. 회원가입, 로그인, 인증이 구분되어 있습니다. 셋째, 빠뜨릴 가능성이 줄어듭니다. 각 항목이 명확히 구분되어 있어서, Claude가 하나하나 체크하며 구현할 수 있습니다.

구조화의 힘은 단순히 보기 좋은 것을 넘어섭니다. Claude가 더 나은 코드를 생성하게 만듭니다. 구조화된 프롬프트를 받으면, Claude도 구조화된 사고를 합니다. “아, 회원가입 로직이 따로 있구나. 로그인 로직이 따로 있구나. 각각 별도 함수로 만들어야겠다.” 이런 식으로 코드도 더 잘 구조화됩니다.

완벽한 프롬프트 구조는 이런 흐름을 따릅니다. 목적에서 시작합니다. 무엇을 만들 것인가를 명확히 합니다. 그다음 요구사항을 상세히 나열합니다. 각 기능이 무엇을 해야 하는지 구체적으로 설명합니다. 이어서 기술 스택을 지정합니다. 어떤 도구와 라이브러리를 사용할지 명시합니다. 제약사항도 추가합니다. 지켜야 할 규칙과 한계를 정의합니다. 예제를 제공합니다. 입력과 출력의 샘플을 보여줍니다. 마지막으로 출력 형식을 지정합니다. 어떤 파일로, 어떤 구조로 결과물을 원하는지 명확히 합니다.

이 흐름을 따르면 Claude는 여러분의 의도를 완벽히 파악합니다. 각 단계가 다음 단계의 컨텍스트가 됩니다. 목적이 요구사항의 맥락이 되고, 요구사항이 기술 스택의 기준이 되고, 기술 스택이 제약사항의 범위가 됩니다. 이런 논리적 흐름이 있으면 Claude는 일관된 결과물을 만듭니다.

원칙 3: 컨텍스트 (Context)

여러분이 레스토랑에서 일하는 셰프라고 상상해보세요. 손님이 “스테이크 주세요”라고 주문합니다. 여러분은 어떻게 요리하나요? 미디엄? 웰던? 소스는? 사이드는? 손님이 “저는 다이어트 중이라 칼로리 낮게, 소스 빼고, 야채 많이 주세요”라고 추가로 말한다면 어떨까요? 완전히 다른 요리가 나올 것입니다.

컨텍스트는 바로 이런 것입니다. 단순히 무엇을(What) 원하는지뿐만 아니라, 왜(Why) 원하는지, 어떤 상황(Context)인지를 설명하는 것입니다. Claude는 컨텍스트를 이해하면 더 적절한 결정을 내립니다.

실제 사례를 봅시다. 에러가 발생했습니다. 고쳐야 합니다. 나쁜 프롬프트는 이렇습니다.

에러 고쳐줘

이것만으로는 Claude가 할 수 있는 게 없습니다. 무슨 에러인지, 어디서 발생하는지, 어떤 상황에서 일어나는지 아무것도 모릅니다. 추측할 수밖에 없습니다. 그리고 틀릴 것입니다.

이제 컨텍스트가 풍부한 프롬프트를 봅시다.

다음 에러를 고쳐줘:

에러 메시지:

Traceback (most recent call last):
  File "app/services/user.py", line 45, in create_user
    result = await session.execute(query)
sqlalchemy.exc.IntegrityError: duplicate key value violates 
unique constraint "users_email_key"

관련 코드:

# app/services/user.py
async def create_user(email: str, password: str):
    user = User(
        email=email, 
        password_hash=hash_password(password)
    )
    session.add(user)
    await session.commit()  # 여기서 에러!
    return user

상황:
사용자 회원가입 기능을 구현했습니다. 새로운 사용자가 가입할 때는 
문제없이 작동합니다. 하지만 이미 존재하는 이메일로 다시 가입을 
시도하면 위 에러가 발생합니다. 현재는 에러 처리가 전혀 되어 있지 
않아서 서버가 500 에러를 반환합니다.

원하는 것:
중복된 이메일로 가입을 시도하면 명확한 에러 메시지를 반환하고 
싶습니다. HTTP 400 Bad Request를 반환하고, 사용자에게 
"이미 가입된 이메일입니다"라는 메시지를 보여주면 좋겠습니다.

이제 Claude는 완벽히 이해합니다. 에러의 정확한 위치, 원인, 현재 코드, 발생 상황, 원하는 동작을 모두 알고 있습니다. 추측할 필요가 없습니다. 즉시 정확한 해결책을 제시할 수 있습니다. try-except 블록을 추가하고, IntegrityError를 캐치하고, 적절한 HTTP 에러를 반환하는 코드를 생성할 것입니다.

컨텍스트의 힘은 정확성뿐만 아닙니다. 배려입니다. Claude에게 충분한 정보를 주는 것은, Claude가 여러분을 더 잘 도울 수 있게 하는 것입니다. 마치 의사에게 증상을 자세히 설명하는 것처럼, AI에게도 상황을 자세히 설명해야 합니다.

좋은 컨텍스트는 세 가지 질문에 답합니다. 첫째, 무슨 일이 일어났는가? 현상을 객관적으로 설명합니다. 둘째, 왜 문제인가? 어떤 영향을 미치는지, 왜 고쳐야 하는지 설명합니다. 셋째, 무엇을 원하는가? 이상적인 결과를 구체적으로 설명합니다.

이 세 가지를 명확히 하면, Claude는 단순히 기술적 해결책만 제시하는 것이 아니라, 여러분의 비즈니스 요구사항에 맞는 솔루션을 제안합니다. 예를 들어, “사용자 경험을 해치지 않으면서 보안을 강화하고 싶다”는 컨텍스트를 주면, Claude는 과도하게 엄격하지 않으면서도 안전한 중간 지점을 찾아줍니다.

원칙 4: 예제 (Examples)

“말로 설명하는 것보다 보여주는 게 낫다”는 말이 있습니다. 프롬프트에서도 마찬가지입니다. 추상적인 설명보다 구체적인 예제가 훨씬 명확합니다. 특히 복잡한 데이터 구조나 특정 형식을 원할 때, 예제는 필수입니다.

개발자들이 자주 하는 실수가 있습니다. “Pydantic 스키마 만들어줘”라고만 말하는 것입니다. 하지만 Pydantic 스키마는 수천 가지 형태가 가능합니다. Claude는 어떤 걸 원하는지 알 수 없습니다. 간단한 검증? 복잡한 nested 구조? 커스텀 validator?

나쁜 예를 봅시다.

JSON 검증해줘

이것은 거의 의미가 없습니다. 어떤 JSON을 검증하나요? 어떤 규칙으로? 이제 예제가 포함된 프롬프트를 봅시다.

다음 JSON을 검증하는 Pydantic 스키마 만들어줘:

입력 예제:

{
  "user": {
    "name": "John Doe",
    "age": 30,
    "email": "john@example.com",
    "tags": ["developer", "python"]
  },
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}


검증 규칙:
user.name은 2자에서 50자 사이여야 하며 필수 항목입니다. 
user.age는 18세에서 120세 사이여야 하고 역시 필수입니다. 
user.email은 유효한 이메일 형식이어야 하며 필수입니다. 
user.tags는 최대 5개까지 가능하고, 각 태그는 1자에서 20자 
사이여야 합니다. preferences.theme은 "light" 또는 "dark"만 
가능합니다. preferences.notifications는 불린 값이며 
기본값은 true입니다.

에러 메시지도 한글로 작성해주세요.

이제 Claude는 정확히 압니다. JSON의 구조, 각 필드의 타입, 검증 규칙, 심지어 에러 메시지 언어까지. 예제가 모든 것을 명확하게 만들었습니다. 결과물은 정확히 여러분이 원하는 Pydantic 스키마가 될 것입니다. 한 번에, 수정 없이.

예제의 힘은 여기서 끝나지 않습니다. 예제는 엣지 케이스도 보여줄 수 있습니다. 정상 케이스 예제와 에러 케이스 예제를 모두 제공하면, Claude는 두 경우를 모두 처리하는 코드를 만듭니다.

더 나아가, 예제는 before와 after를 보여줄 수도 있습니다. “이 데이터가 이렇게 변환되어야 한다”는 식으로 입력과 출력을 모두 보여주면, Claude는 정확히 그 변환 로직을 구현합니다. 말로 설명하면 10문장 걸릴 것을 예제 하나로 해결할 수 있습니다.

원칙 5: 제약사항 (Constraints)

자유는 때로 저주입니다. 선택지가 너무 많으면 결정하기 어렵습니다. Claude도 마찬가지입니다. 제약이 없으면 무엇을 만들어야 할지 고민합니다. 여러 가능성을 모두 탐색하느라 시간을 낭비합니다. 하지만 명확한 제약이 있으면 집중합니다. 빠르게, 정확하게 결과를 냅니다.

제약사항은 단순히 금지가 아닙니다. 방향 제시입니다. “이렇게 만들어야 한다”는 가이드라인입니다. 실제 프로젝트에는 항상 제약이 있습니다. 사용할 수 있는 라이브러리, 코드 길이 제한, 성능 요구사항, 스타일 가이드. 이런 제약을 명확히 하면, Claude는 현실적이고 즉시 사용 가능한 코드를 만듭니다.

나쁜 예를 봅시다.

함수 만들어줘

이것은 너무 열려 있습니다. 어떤 언어로? 어떤 라이브러리를 써도 되나? 얼마나 복잡해도 되나? Claude는 자신이 아는 가장 화려한 방법을 동원할 수도 있습니다. 외부 라이브러리 10개를 import하고, 클래스 계층을 만들고, 디자인 패턴을 적용한 200줄짜리 코드를 만들 수도 있습니다. 여러분이 원한 건 간단한 10줄짜리 함수였는데 말입니다.

이제 제약이 명확한 프롬프트를 봅시다.

사용자 검색 함수를 만들어주세요.

제약사항:
외부 라이브러리는 사용하지 마세요. Python 표준 라이브러리만 
사용해주세요. 함수는 1개만 만들고, 클래스는 만들지 마세요. 
전체 코드는 50줄 이하로 작성해주세요. 타입 힌트는 반드시 
포함해주세요. Docstring은 Google 스타일로 작성해주세요.

함수 시그니처:

def search_users(
    users: List[User],
    query: str,
    fields: List[str]
) -> List[User]:
    """
    사용자를 검색합니다.
    
    Args:
        users: 검색할 사용자 목록
        query: 검색어
        fields: 검색할 필드 (예: ["name", "email"])
    
    Returns:
        검색된 사용자 목록
    """


검색 로직:
대소문자는 무시하고 검색해주세요. 부분 일치로 검색하며, 
여러 필드 중 하나라도 매칭되면 결과에 포함해주세요. 
즉, OR 검색입니다.

이제 Claude는 정확히 경계를 압니다. 외부 라이브러리는 안 됩니다. 간단한 함수여야 합니다. 50줄 안에 끝내야 합니다. 타입 힌트와 Docstring은 필수입니다. 이런 제약 안에서 Claude는 최적의 솔루션을 찾습니다. 과도하게 복잡하지도, 과도하게 단순하지도 않은, 딱 적절한 코드를 만듭니다.

제약사항의 진정한 가치는 커뮤니케이션입니다. 제약을 명확히 하는 것은, 여러분의 프로젝트 컨텍스트를 Claude와 공유하는 것입니다. “우리 팀은 간단함을 선호한다”, “성능이 중요하다”, “유지보수성을 우선한다” 같은 가치를 전달하는 것입니다. 그리고 Claude는 그 가치에 맞는 코드를 만듭니다.

제약사항을 정의할 때는 긍정적 표현을 사용하는 것이 좋습니다. “이걸 하지 마세요”보다는 “이렇게 해주세요”가 더 명확합니다. “async/await 쓰지 마세요”보다는 “동기 함수로 작성해주세요”가 더 직접적입니다. Claude가 무엇을 피해야 하는지가 아니라, 무엇을 해야 하는지를 알게 됩니다.

---

2. 프롬프트 해부학

완벽한 프롬프트는 단순히 정보를 나열한 것이 아닙니다. 논리적 흐름이 있습니다. 각 부분이 다음 부분의 맥락이 되고, 전체가 하나의 이야기를 만듭니다. 이 흐름을 이해하면, 어떤 요청이든 효과적인 프롬프트로 만들 수 있습니다.

완벽한 프롬프트는 여섯 단계로 구성됩니다. 목적, 요구사항, 기술 스택, 제약사항, 예제, 출력 형식입니다. 각 단계는 특정한 역할을 합니다.

목적 단계에서는 무엇을 만들 것인지 명확히 합니다. 한 문장으로 핵심을 표현합니다. “사용자 대시보드 API를 만들어주세요.” 이것이 전체 프롬프트의 북극성이 됩니다. 모든 후속 내용은 이 목적을 달성하기 위한 것입니다.

요구사항 단계에서는 상세 명세를 작성합니다. 각 기능이 무엇을 해야 하는지, 어떤 엔드포인트가 필요한지, 응답 형식은 어떤지를 구체적으로 설명합니다. 이 단계가 가장 중요하고 가장 길어질 수 있습니다. 충분히 자세하게 작성하세요.

기술 스택 단계에서는 사용할 도구를 지정합니다. 프레임워크, 라이브러리, 데이터베이스를 명시합니다. 버전까지 지정하면 더욱 좋습니다. “FastAPI 0.100+”, “SQLModel with PostgreSQL 15”, “python-jose for JWT” 같은 식으로요.

제약사항 단계에서는 지켜야 할 규칙을 정의합니다. 성능 요구사항, 보안 요구사항, 코딩 스타일을 명시합니다. “N+1 쿼리 방지”, “Redis 캐싱 (5분 TTL)”, “본인 데이터만 조회 가능” 같은 제약을 추가합니다.

예제 단계에서는 입출력 샘플을 보여줍니다. 정상 케이스와 에러 케이스를 모두 포함하면 좋습니다. 요청 예제, 성공 응답 예제, 실패 응답 예제를 작성합니다. 이를 통해 Claude는 정확한 형식을 이해합니다.

출력 형식 단계에서는 결과물의 형태를 지정합니다. 어떤 파일로 만들어야 하는지, 디렉토리 구조는 어떤지, 테스트 포함 여부는 어떤지를 명시합니다. “app/api/v1/dashboard.py 파일로 만들고, pytest 테스트도 포함해주세요” 같은 식으로요.

실제 예시를 봅시다.

목적:
사용자 대시보드 API를 만들어주세요.

요구사항:
GET /dashboard/stats 엔드포인트를 구현해주세요. 이 엔드포인트는 
로그인한 사용자의 활동 통계를 반환합니다. 총 게시글 수, 총 댓글 수, 
그리고 최근 7일간의 일별 활동 데이터를 포함해야 합니다.

응답 형식은 다음과 같습니다:
{
  "total_posts": 123,
  "total_comments": 456,
  "activity": [
    {"date": "2026-01-01", "posts": 10, "comments": 25},
    {"date": "2026-01-02", "posts": 15, "comments": 30}
  ]
}

activity 배열은 최근 7일치 데이터를 포함하며, 날짜는 YYYY-MM-DD 
형식입니다.

기술 스택:
FastAPI를 사용해주세요. 데이터베이스는 SQLModel로 PostgreSQL에 
연결합니다. 인증은 JWT를 사용하며, 모든 요청에 유효한 토큰이 
필요합니다.

제약사항:
쿼리는 최적화해주세요. N+1 쿼리 문제가 발생하지 않도록 join이나 
eager loading을 사용해주세요. Redis로 결과를 캐싱하며, TTL은 
5분입니다. 사용자는 자신의 데이터만 조회할 수 있어야 합니다.

예제:
요청 예제:
GET /dashboard/stats
Authorization: Bearer eyJhbGc...

성공 응답 (200):
{
  "total_posts": 123,
  "total_comments": 456,
  "activity": [...]
}

실패 응답 (401):
{
  "error": "Unauthorized",
  "detail": "Invalid or expired token"
}

출력 형식:
app/api/v1/dashboard.py 파일로 만들어주세요. pytest로 작성된 
테스트도 함께 포함해주세요. 테스트는 성공 케이스와 인증 실패 
케이스를 모두 커버해야 합니다.

이 프롬프트는 완벽한 흐름을 따릅니다. 각 단계가 이전 단계를 바탕으로 더 구체적인 정보를 제공합니다. Claude는 이 흐름을 따라 사고하며, 일관되고 완성도 높은 코드를 만들어냅니다.

이 구조를 템플릿처럼 사용할 수 있습니다. 새로운 요청이 있을 때마다, 이 여섯 단계를 채워나가세요. 처음에는 어색할 수 있지만, 몇 번 하다 보면 자연스러워집니다. 그리고 결과물의 품질이 눈에 띄게 향상되는 것을 느낄 것입니다.

---

Part 2: 패턴 라이브러리

이론을 배웠으니 이제 실전입니다. 실제 개발에서 자주 마주치는 상황들과, 각 상황에 최적화된 프롬프트 패턴을 살펴봅시다. 이 패턴들은 수백 번의 시행착오를 거쳐 검증된 것들입니다. 그대로 사용해도 좋고, 여러분의 상황에 맞게 변형해도 좋습니다.

3. 프로젝트 생성 패턴

새 프로젝트를 시작할 때, 처음부터 올바른 구조로 시작하는 것이 중요합니다. 나중에 리팩토링하는 것보다 처음부터 잘 만드는 것이 훨씬 쉽습니다. 여기 두 가지 프로젝트 생성 패턴이 있습니다.

패턴 3.1: 빈 프로젝트에서 시작

완전히 새로운 프로젝트를 시작할 때 사용하는 패턴입니다.

FastAPI 프로젝트를 처음부터 만들어주세요.

프로젝트 구조:
표준적인 FastAPI 프로젝트 레이아웃을 사용해주세요. app 디렉토리 
안에 api, models, schemas, services, core로 분리된 구조입니다. 
각 디렉토리에는 적절한 __init__.py 파일이 있어야 합니다.

설정:
pyproject.toml로 의존성을 관리합니다. 개발 환경과 프로덕션 환경을 
구분한 설정 파일을 만들어주세요. 환경 변수는 .env 파일로 관리하고, 
pydantic-settings로 로드합니다.

Docker:
Dockerfile과 docker-compose.yml을 포함해주세요. PostgreSQL과 
Redis 컨테이너도 compose 파일에 정의해주세요. 개발 환경에서 
바로 실행할 수 있어야 합니다.

품질 도구:
pre-commit 훅을 설정해주세요. black, isort, flake8, mypy를 
포함합니다. .gitignore도 Python 프로젝트에 맞게 작성해주세요.

기본 엔드포인트:
GET /health (헬스 체크)
GET /docs (Swagger UI)

이 모든 것을 포함해서, 바로 개발을 시작할 수 있는 완전한 
프로젝트 스켈레톤을 만들어주세요.

이 프롬프트는 프로젝트의 전체 기반을 한 번에 만듭니다. Claude는 디렉토리를 생성하고, 설정 파일을 작성하고, Docker 구성을 만들고, 품질 도구를 설정합니다. 여러분은 바로 비즈니스 로직을 작성할 수 있습니다.

핵심은 “바로 사용 가능한” 상태로 만들어달라는 것입니다. 단순히 파일을 나열하는 것이 아니라, 실제로 실행되고 작동하는 프로젝트를 요청합니다. Claude는 이를 이해하고, 모든 의존성을 올바르게 설정하고, 파일 간 연결을 제대로 만듭니다.

패턴 3.2: 기존 패턴 복제

이미 잘 작동하는 코드가 있고, 비슷한 기능을 더 만들고 싶을 때 사용합니다.

기존 인증 패턴을 따라서 상품 관리 기능을 만들어주세요.

참고할 기존 코드:
app/api/v1/auth.py에 인증 엔드포인트가 있습니다. 이 파일의 
구조와 스타일을 똑같이 따라주세요. 에러 핸들링 방식, 응답 형식, 
Pydantic 스키마 사용 방법 등 모든 패턴을 일관되게 유지해주세요.

새로운 기능:
상품 CRUD API를 만들어주세요. POST /products (상품 생성), 
GET /products (목록 조회), GET /products/{id} (상세 조회), 
PUT /products/{id} (수정), DELETE /products/{id} (삭제)입니다.

상품 모델:
id, name, description, price, stock, created_at, updated_at 
필드를 포함합니다. price는 Decimal 타입이고, stock은 
음수가 될 수 없습니다.

인증:
모든 엔드포인트는 JWT 인증이 필요합니다. 인증 로직은 기존 
auth.py와 똑같이 구현해주세요.

파일 구조:
app/api/v1/products.py (엔드포인트)
app/models/product.py (데이터 모델)
app/schemas/product.py (Pydantic 스키마)
app/services/product.py (비즈니스 로직)

기존 코드와 100% 일관된 스타일로 작성해주세요.

이 패턴의 힘은 일관성입니다. Claude에게 기존 코드를 참고하라고 명시적으로 말하면, Claude는 그 코드의 스타일, 패턴, 컨벤션을 학습합니다. 결과물은 기존 코드와 구분이 안 될 정도로 일관됩니다. 마치 같은 사람이 작성한 것처럼 보입니다.

4. 기능 구현 패턴

기능을 구현할 때는 크게 두 가지 패턴이 있습니다. CRUD를 자동 생성하는 패턴과, 복잡한 비즈니스 로직을 구현하는 패턴입니다.

패턴 4.1: CRUD 자동 생성

반복적인 CRUD 작업을 빠르게 만드는 패턴입니다.

댓글 기능을 위한 완전한 CRUD API를 만들어주세요.

데이터 모델:
Comment 모델을 만들어주세요. id (Primary Key), post_id 
(Foreign Key to posts), user_id (Foreign Key to users), 
content (TEXT), created_at, updated_at 필드를 포함합니다.

엔드포인트:
POST /posts/{post_id}/comments - 댓글 작성
GET /posts/{post_id}/comments - 댓글 목록 (페이지네이션)
GET /comments/{id} - 댓글 상세
PUT /comments/{id} - 댓글 수정 (작성자만)
DELETE /comments/{id} - 댓글 삭제 (작성자만)

비즈니스 규칙:
댓글은 로그인한 사용자만 작성할 수 있습니다. 수정과 삭제는 
작성자 본인만 가능합니다. 내용은 1자에서 1000자 사이여야 합니다. 
삭제는 soft delete로 구현해주세요 (deleted_at 필드).

페이지네이션:
목록 조회는 페이지네이션을 지원합니다. page와 size 쿼리 
파라미터를 받으며, 기본값은 page=1, size=20입니다. 응답에는 
items, total, page, size를 포함합니다.

테스트:
각 엔드포인트마다 성공 케이스와 실패 케이스를 테스트하는 
pytest 코드를 작성해주세요.

완전히 작동하는 CRUD 시스템을 한 번에 만들어주세요.

이 프롬프트는 CRUD의 모든 부분을 명시합니다. Claude는 Create, Read, Update, Delete를 모두 구현하고, 각각에 대한 검증, 권한 체크, 테스트를 추가합니다. 결과물은 즉시 사용 가능한 완전한 기능입니다.

패턴 4.2: 복잡한 비즈니스 로직

단순 CRUD를 넘어서는 복잡한 로직을 구현할 때 사용합니다.

주문 처리 시스템을 구현해주세요.

비즈니스 플로우:
사용자가 장바구니에서 주문을 생성하면, 다음 단계를 거칩니다:

1. 재고 확인: 모든 상품의 재고가 충분한지 확인합니다. 
   하나라도 부족하면 전체 주문이 실패합니다.

2. 재고 예약: 재고를 임시로 예약합니다 (10분 타임아웃). 
   이 시간 안에 결제하지 않으면 예약이 자동 해제됩니다.

3. 결제 처리: Stripe API를 호출해서 결제를 진행합니다. 
   결제가 실패하면 예약을 즉시 해제합니다.

4. 주문 확정: 결제 성공 시 주문 상태를 'confirmed'로 변경하고, 
   예약된 재고를 실제로 차감합니다.

5. 알림: 사용자에게 주문 확인 이메일을 보냅니다.

트랜잭션:
이 전체 과정은 하나의 데이터베이스 트랜잭션으로 처리되어야 
합니다. 중간에 실패하면 모든 변경사항이 롤백됩니다.

에러 처리:
각 단계에서 발생할 수 있는 에러를 명확히 정의하고 처리해주세요. 
재고 부족, 결제 실패, 네트워크 오류 등 모든 케이스를 다뤄주세요.

멱등성:
같은 주문을 여러 번 제출해도 한 번만 처리되어야 합니다. 
idempotency key를 사용해서 중복 처리를 방지해주세요.

테스트:
각 단계의 성공과 실패를 시뮬레이션하는 테스트를 작성해주세요. 
특히 롤백 로직이 제대로 작동하는지 검증해주세요.

이 프롬프트는 복잡한 비즈니스 로직을 단계별로 설명합니다. Claude는 각 단계를 이해하고, 단계 간 연결을 만들고, 에러 시나리오를 처리하고, 트랜잭션을 보장하는 코드를 작성합니다. 단순히 코드를 생성하는 것이 아니라, 비즈니스 요구사항을 정확히 구현합니다.

5. 리팩토링 패턴

기존 코드를 개선하는 것도 중요한 작업입니다. 리팩토링 패턴은 크게 두 가지입니다. God Class를 분리하는 패턴과, 성능을 최적화하는 패턴입니다.

패턴 5.1: God Class 분리

하나의 클래스에 너무 많은 책임이 있을 때 사용합니다.

UserService 클래스를 리팩토링해주세요.

현재 문제:
app/services/user.py에 있는 UserService 클래스가 500줄이 
넘습니다. 인증, 권한, 프로필 관리, 알림, 통계 등 너무 많은 
기능이 한 클래스에 몰려 있습니다. 테스트하기도 어렵고 
유지보수도 힘듭니다.

원하는 구조:
단일 책임 원칙에 따라 다음과 같이 분리해주세요:

- AuthService: 로그인, 로그아웃, 토큰 관리
- UserProfileService: 프로필 조회, 수정
- UserNotificationService: 알림 설정, 알림 발송
- UserStatsService: 사용자 통계 계산

각 서비스는 명확한 책임을 가지며, 다른 서비스에 의존할 수 
있습니다. 예를 들어 AuthService는 UserProfileService를 
사용할 수 있습니다.

마이그레이션:
기존 코드를 새 구조로 옮기되, 동작은 완전히 똑같아야 합니다. 
기존 API는 하나도 깨지면 안 됩니다. 내부 구조만 바뀌어야 합니다.

테스트:
각 새로운 서비스마다 유닛 테스트를 작성해주세요. 기존 통합 
테스트도 모두 통과해야 합니다.

이 프롬프트는 리팩토링의 목표와 제약을 명확히 합니다. Claude는 코드를 분석하고, 적절히 분리하고, 의존성을 관리하고, 테스트를 작성합니다. 중요한 것은 “동작은 똑같아야 한다”는 제약입니다. Claude는 이를 이해하고 보수적으로 리팩토링합니다.

패턴 5.2: 성능 최적화

느린 코드를 빠르게 만들 때 사용합니다.

상품 목록 API의 성능을 최적화해주세요.

현재 상황:
GET /products 엔드포인트가 너무 느립니다. 1000개 상품을 
조회하는 데 5초가 걸립니다. 응답 시간을 500ms 이하로 줄여야 
합니다.

문제 분석:
프로파일링 결과, N+1 쿼리 문제가 있습니다. 각 상품마다 
카테고리, 리뷰, 재고를 별도로 조회하고 있습니다. 또한 결과를 
캐싱하지 않아서 같은 요청도 매번 DB를 조회합니다.

최적화 방안:
1. N+1 쿼리 해결: join이나 eager loading으로 한 번에 조회
2. 인덱스 추가: 자주 사용하는 필터 컬럼에 인덱스
3. Redis 캐싱: 결과를 5분간 캐싱 (TTL 5분)
4. 페이지네이션: 한 번에 모든 데이터를 보내지 않기

구현:
위 최적화를 모두 적용해주세요. 쿼리를 분석해서 최적의 join 
전략을 사용하고, 필요한 인덱스를 마이그레이션 파일로 만들고, 
Redis 캐싱을 추가하세요.

벤치마크:
before/after 성능을 측정하는 벤치마크 테스트를 작성해주세요.

이 프롬프트는 성능 문제의 원인과 해결 방향을 모두 제시합니다. Claude는 제시된 방안을 구체적으로 구현하고, 측정 가능한 개선을 만들어냅니다.

---

Part 3: 고급 테크닉

기본 패턴을 넘어서, 더 복잡하고 정교한 작업을 위한 고급 테크닉을 살펴봅시다. 이것들은 경험이 쌓이면서 자연스럽게 익히게 되는 기법들입니다.

11. 다단계 프롬프트

복잡한 작업은 한 번에 하기 어렵습니다. 여러 단계로 나누는 것이 효과적입니다.

1단계: 설계만 해주세요
---
사용자 알림 시스템을 설계해주세요. 구현하지 말고 설계만 해주세요.

요구사항:
- 이메일, SMS, 푸시 알림 지원
- 템플릿 기반 알림
- 사용자별 알림 설정
- 알림 이력 추적

다음을 포함한 설계 문서를 작성해주세요:
- 데이터 모델
- API 엔드포인트
- 시스템 아키텍처
- 기술 스택 추천

[Claude의 설계를 검토한 후]

2단계: 승인된 설계로 구현
---
위에서 제안한 설계를 승인합니다. 이제 실제로 구현해주세요.

우선순위 1: 이메일 알림만 먼저 구현
- Notification 모델
- EmailTemplate 모델
- POST /notifications/email 엔드포인트
- 실제 이메일 발송 (SMTP)

테스트까지 포함해서 완전히 작동하는 버전을 만들어주세요.

[1차 구현을 확인한 후]

3단계: 기능 확장
---
이메일이 잘 작동합니다. 이제 SMS를 추가해주세요.

기존 이메일 패턴을 그대로 따라주세요:
- SMSTemplate 모델
- POST /notifications/sms 엔드포인트
- Twilio API 통합

코드 스타일과 구조를 이메일과 100% 일관되게 유지해주세요.

이 방식의 장점은 통제력입니다. 각 단계를 검토하고 승인한 후 다음으로 진행합니다. 잘못된 방향으로 가면 바로 수정할 수 있습니다. 처음부터 모든 것을 한 번에 요청했다면, 중간에 방향을 바꾸기 어려웠을 것입니다.

12. 컨텍스트 관리

Claude는 대화 기록을 기억합니다. 이를 활용하면 더 효율적으로 작업할 수 있습니다.

테크닉 12.1: 대화 히스토리 활용

[이전 대화에서 인증 시스템을 구현했다면]

앞에서 만든 인증 시스템을 사용해서 권한 관리를 추가해주세요.

기존 시스템과 통합:
우리가 만든 JWT 토큰에 role 필드를 추가하세요. admin, user, 
guest 세 가지 역할을 지원합니다.

권한 체크:
데코레이터를 만들어주세요. @require_role("admin") 같은 식으로 
엔드포인트에 붙이면 해당 역할만 접근할 수 있게 하는 거죠.

기존 코드 수정 최소화:
우리가 만든 코드를 최대한 유지하면서 권한 기능만 추가해주세요.

“앞에서 만든”, “우리가 만든” 같은 표현을 사용하면 Claude는 대화 기록에서 해당 코드를 찾습니다. 다시 설명할 필요가 없습니다.

테크닉 12.2: 파일 첨부 전략

큰 프로젝트에서는 모든 파일을 첨부할 수 없습니다. 관련 파일만 선택적으로 첨부하세요.

상품 검색 기능을 추가하려고 합니다.

첨부 파일:
app/models/product.py - 상품 모델 구조 파악용
app/api/v1/products.py - 기존 API 스타일 참고용
app/core/search.py - 우리가 사용하는 검색 유틸

이 세 파일을 참고해서 Elasticsearch 기반 검색을 추가해주세요.

50개 파일을 다 첨부하면 Claude가 혼란스러워합니다. 핵심적인 3-4개만 첨부하고, 그 파일들이 왜 중요한지 설명하세요.

13. 프롬프트 체이닝

여러 프롬프트를 연결해서 복잡한 작업을 수행하는 기법입니다.

체인 1: 분석
---
이 레거시 코드를 분석해주세요.

[코드 첨부]

다음을 파악해주세요:
- 주요 기능
- 외부 의존성
- 잠재적 버그
- 개선 필요 부분

JSON 형식으로 결과를 정리해주세요.

[분석 결과를 받은 후]

체인 2: 계획
---
분석 결과를 바탕으로 리팩토링 계획을 세워주세요.

우선순위:
1. 긴급 (보안 이슈)
2. 중요 (성능 문제)  
3. 선택 (코드 품질)

각 항목마다 예상 시간과 리스크를 평가해주세요.

[계획을 검토한 후]

체인 3: 실행
---
계획의 1번 항목부터 실행해주세요.

[보안 이슈를 제시한 것]을 수정하되, 기존 API는 절대 깨지면 
안 됩니다. 하위 호환성을 100% 유지하면서 보안만 강화해주세요.

[수정 완료 후]

체인 4: 검증
---
변경사항을 검증하는 테스트를 작성해주세요.

보안 취약점이 실제로 수정되었는지 확인하는 테스트와, 
기존 기능이 여전히 작동하는지 확인하는 회귀 테스트를 
모두 포함해주세요.

이 방식은 대규모 작업에 매우 효과적입니다. 각 체인이 다음 체인의 입력이 됩니다. 분석 → 계획 → 실행 → 검증의 흐름을 따르면 실수가 줄어듭니다.

---

Part 4: 실전 시나리오

이론과 패턴을 배웠으니, 이제 실전 시나리오를 봅시다. 실제 프로젝트에서 마주치는 복잡한 상황들과, 그것을 해결하는 구체적인 프롬프트를 살펴봅니다.

Prompting best practices

14. 제로에서 배포까지

완전히 새로운 프로젝트를 만들어서 배포하기까지의 4시간 타임라인입니다.

Hour 1: 설계와 구조

새로운 블로그 플랫폼을 만들 겁니다. 4시간 안에 배포 가능한 
MVP를 만들어야 합니다.

지금 1시간 동안 할 일:
설계만 하고 구현하지 마세요. 다음을 정리해주세요.

기능 정의:
- 사용자: 회원가입, 로그인
- 글: 작성, 수정, 삭제, 목록, 상세
- 최소 기능만 (댓글 X, 좋아요 X)

기술 스택 결정:
- 백엔드: FastAPI or Django?
- DB: PostgreSQL or MongoDB?
- 인증: JWT or Session?

각 선택의 pros/cons를 설명하고 추천해주세요.

데이터 모델 설계:
필요한 모델과 필드를 정의해주세요.

API 엔드포인트 설계:
모든 엔드포인트 목록을 만들어주세요.

이 모든 걸 마크다운 문서로 정리해서, 다음 시간에 
바로 구현할 수 있게 해주세요.

Hours 2-3: 구현

Hour 1에서 승인한 설계대로 구현해주세요.

5개 프롬프트로 나눠서 진행하겠습니다:

프롬프트 1: 프로젝트 구조
FastAPI 프로젝트를 생성하고 기본 구조를 만들어주세요. 
Docker Compose로 PostgreSQL도 포함해주세요.

[완료 후]

프롬프트 2: 인증
User 모델과 JWT 인증을 구현해주세요. 회원가입, 로그인 
엔드포인트를 만들어주세요.

[완료 후]

프롬프트 3: 글 작성
Post 모델과 CRUD API를 만들어주세요. 작성자 본인만 
수정/삭제할 수 있게 해주세요.

[완료 후]

프롬프트 4: 목록과 상세
글 목록 조회 (페이지네이션)와 상세 조회를 구현해주세요.

[완료 후]

프롬프트 5: 테스트
핵심 기능의 통합 테스트를 작성해주세요. 실제로 동작하는지 
확인할 수 있어야 합니다.

Hour 4: 배포 준비

프로덕션 배포를 준비해주세요.

환경 변수 관리:
개발/프로덕션 환경을 분리해주세요. .env.example 파일을 
만들어서 필요한 환경 변수를 문서화해주세요.

Dockerfile 최적화:
멀티 스테이지 빌드로 이미지 크기를 줄여주세요. 프로덕션용 
Dockerfile을 만들어주세요.

헬스 체크:
/health 엔드포인트를 추가해서 컨테이너가 정상인지 체크할 수 
있게 해주세요.

README:
로컬에서 실행하는 방법, 배포하는 방법, API 문서를 포함한 
README.md를 작성해주세요.

배포 스크립트:
한 명령으로 배포할 수 있는 deploy.sh 스크립트를 만들어주세요.

이 타임라인을 따르면, 4시간 만에 실제로 작동하는 서비스를 만들고 배포할 수 있습니다. 핵심은 범위를 명확히 제한하는 것입니다. “최소 기능만”이라는 제약이 프로젝트를 시간 내에 완료 가능하게 만듭니다.

15. 레거시 개선

오래된 코드를 현대적으로 개선하는 시나리오입니다.

단계 1: 진단 (30분)
---
이 레거시 코드베이스를 분석해주세요.

[프로젝트 디렉토리 구조 첨부]

파악해야 할 것:
- 사용 중인 기술 스택과 버전
- 코드 복잡도 (라인 수, 순환 복잡도)
- 의존성 그래프
- 테스트 커버리지
- 명백한 보안 취약점
- 성능 병목 지점

우선순위 기준:
1. 보안 위험 (즉시 해결)
2. 성능 문제 (사용자 영향)
3. 유지보수성 (개발자 생산성)

진단 리포트를 작성해주세요.

[리포트를 받은 후]

단계 2: 로드맵 (30분)
---
진단 결과를 바탕으로 개선 로드맵을 만들어주세요.

3개 페이즈로 나눠주세요:

Phase 1 (1주): 긴급 (보안, 크리티컬 버그)
Phase 2 (2주): 중요 (성능, 안정성)
Phase 3 (1주): 선택 (코드 품질, 문서)

각 페이즈마다:
- 구체적인 작업 목록
- 예상 시간
- 필요한 리소스
- 리스크 평가

[로드맵을 승인한 후]

단계 3: 실행 (주별)
---
Week 1: Phase 1 실행

[긴급 항목 목록]을 하나씩 수정해주세요.

작업 1: SQL Injection 취약점 수정
app/api/search.py의 파라미터 바인딩을 추가해주세요.
기존 API는 절대 깨지면 안 됩니다.

[완료 후]

작업 2: 인증 강화
비밀번호 해싱을 MD5에서 bcrypt로 변경해주세요.
마이그레이션 스크립트도 만들어주세요.

[계속...]

레거시 개선의 핵심은 점진적 접근입니다. 한 번에 모든 걸 바꾸려 하지 마세요. 작은 부분을 고치고, 테스트하고, 배포하고, 다음으로 넘어갑니다. Strangler Fig 패턴을 따릅니다.

16. 긴급 버그 수정

프로덕션에서 버그가 발생했을 때의 5분 해결 템플릿입니다.

🚨 긴급 버그

증상:
사용자가 결제하면 500 에러가 발생합니다. 5분 전부터 
시작되었고, 결제는 실제로 처리되지만 에러 응답을 받습니다.

에러 로그:
[로그 첨부]

관련 코드:
[payment.py 첨부]

최근 변경:
30분 전에 배포한 코드에서 payment timeout을 5초에서 
10초로 변경했습니다.

긴급 조치 (1분 내):
즉시 서비스를 복구할 방법을 알려주세요. 롤백? 임시 패치?

[임시 조치 적용 후]

근본 원인 (5분):
정확한 원인을 파악하고 설명해주세요. 로그를 분석해서 
무엇이 문제인지 찾아주세요.

[원인 파악 후]

영구 수정 (10분):
근본 원인을 해결하는 패치를 만들어주세요. 테스트 코드도 
포함해서 같은 문제가 재발하지 않게 해주세요.

[수정 완료 후]

사후 분석:
이 버그가 왜 발생했는지, 어떻게 방지할 수 있었는지, 
향후 어떻게 대응할지 문서화해주세요.

긴급 상황에서는 명확성이 생명입니다. 증상, 로그, 최근 변경사항을 모두 제공하면 Claude는 빠르게 문제를 파악하고 해결책을 제시합니다.

---

Part 5: Claude 4 시대의 고급 프롬프팅

17. Claude 4의 새로운 특성 이해하기

Claude 4 모델군(Sonnet 4.5, Haiku 4.5, Opus 4.5)은 이전 세대와 근본적으로 다른 특성을 가지고 있습니다. 이들은 더 정확한 지시 수행을 위해 훈련되었으며, 이는 프롬프트 작성 방식에도 영향을 미칩니다.

과거 Claude 3 시대에는 모델이 “알아서” 좋은 결과를 내주는 경우가 많았습니다. 개발자가 대략적인 방향만 제시해도 Claude가 맥락을 파악하고 기대 이상의 결과를 만들어냈습니다. 하지만 Claude 4는 다릅니다. 더욱 정확한 지시 수행에 최적화되어 있어, 여러분이 원하는 것을 명시적으로 표현해야 합니다.

이것이 후퇴일까요? 아닙니다. 오히려 더 예측 가능하고 제어 가능한 결과를 얻을 수 있게 되었다는 의미입니다. 명시적으로 요청하면 Claude 4는 이전보다 훨씬 정확하게 그것을 수행합니다. 핵심은 프롬프트를 더 구체적이고 명확하게 작성하는 것입니다.

18. 명시성: 생각보다 훨씬 중요하다

Claude 4를 사용할 때 가장 중요한 원칙은 “명시성”입니다. 과거처럼 “알아서 잘 해줄 거야”라는 기대는 버려야 합니다. 원하는 행동을 정확히 표현해야 합니다.

예를 들어, 분석 대시보드를 만들고 싶다면 “분석 대시보드 만들어줘”만으로는 부족합니다. Claude 4는 이 요청을 문자 그대로 해석하여 기본적인 대시보드만 만들 수 있습니다. 하지만 여러분이 원하는 것은 아마도 그 이상일 것입니다.

더 나은 접근은 이렇습니다.

분석 대시보드를 만들어줘. 가능한 한 많은 관련 기능과 상호작용을 포함해줘. 
기본을 넘어서서 완전히 기능하는 구현을 만들어줘.

“가능한 한 많이”, “완전히 기능하는”, “기본을 넘어서” 같은 수식어를 추가하면 Claude 4가 더 풍부한 결과를 만들어냅니다.

이전 모델에서는 이런 수식어가 불필요했을 수 있습니다. 하지만 Claude 4는 정확한 지시 수행에 최적화되어 있기 때문에, 여러분이 명시적으로 요청하지 않으면 “충분하다”고 판단하고 멈출 수 있습니다. 따라서 원하는 수준의 완성도, 디테일, 기능을 명시적으로 표현하는 것이 중요합니다.

19. 맥락의 힘: 왜 이것이 중요한지 설명하라

Claude 4는 단순히 무엇을 할지뿐만 아니라, 왜 그것을 해야 하는지도 이해하려 합니다. 지시 뒤에 숨겨진 동기나 맥락을 제공하면 Claude는 여러분의 목표를 더 잘 이해하고 더 적절한 응답을 만들어냅니다.

예를 들어, 응답 형식에 대한 선호를 표현할 때를 생각해봅시다.

보고서를 작성할 때는 자연스럽게 흐르는 산문체 단락으로 써줘. 
마크다운은 코드 블록과 간단한 제목에만 사용해. 그래야 읽기 편하거든.

흥미롭게도 Claude는 이런 설명으로부터 일반화할 수 있습니다. 한 번 이유를 설명하면, 유사한 상황에서 같은 원칙을 적용합니다. 이는 매번 구체적인 지시를 반복할 필요 없이, 한 번의 설명으로 일관된 행동을 이끌어낼 수 있다는 의미입니다.

20. 프론트엔드 디자인에서 창의성 발휘하기

Claude 4.x 모델, 특히 Opus 4.5는 복잡한 실제 웹 애플리케이션을 강력한 프론트엔드 디자인으로 구축하는 데 탁월합니다. 하지만 가이드 없이는 사용자들이 “AI 슬롭(AI slop)” 미학이라 부르는 일반적 패턴으로 수렴할 수 있습니다. 독특하고 창의적이며 놀라움과 기쁨을 주는 프론트엔드를 만들려면 명시적인 지침이 필요합니다.

타이포그래피에 집중하세요. 아름답고 독특하고 흥미로운 폰트를 선택하게 하세요. Arial이나 Inter 같은 일반적 폰트를 피하고 프론트엔드 미학을 높이는 독특한 선택을 하게 하세요.

색상과 테마에서 일관된 미학을 추구하게 하세요. CSS 변수로 일관성을 유지하세요. 고르게 분산된 조심스러운 팔레트보다 날카로운 강조색이 있는 지배적인 색상이 더 잘 작동합니다.

모션을 사용하세요. 효과와 마이크로 인터랙션을 위해 애니메이션을 사용하게 하세요. HTML에는 CSS 전용 솔루션을 우선하세요. 영향력 큰 순간에 집중하세요. 잘 조율된 한 번의 페이지 로드와 시차를 둔 나타남이 흩어진 마이크로 인터랙션보다 더 큰 기쁨을 만듭니다.

배경을 단색 기본값이 아니라 분위기와 깊이를 만들게 하세요. CSS 그라디언트를 레이어하고, 기하학적 패턴을 사용하거나, 전체 미학과 맞는 맥락적 효과를 추가하세요.

일반적인 AI 생성 미학을 피하게 하세요. 과도하게 사용되는 폰트 패밀리, 진부한 색 구성, 예측 가능한 레이아웃과 컴포넌트 패턴, 맥락 특화 성격이 부족한 획일적 디자인을 피하게 하세요.

---

결론

프롬프트 엔지니어링은 기술이지만, 동시에 예술입니다. 명확하게 소통하는 기술, 복잡한 요구사항을 구조화하는 기술, AI의 강점을 최대한 활용하는 기술입니다.

이 가이드에서 배운 패턴들을 마스터하면, 여러분의 개발 속도는 10배 빨라질 것입니다. 코드 품질은 20배 향상될 것입니다. 그리고 AI와 협업하는 즐거움을 느낄 것입니다.

핵심 원칙을 기억하세요. 구체적으로, 구조화해서, 컨텍스트와 함께, 예제를 포함하고, 제약사항을 명확히. 이 다섯 가지만 지켜도 여러분의 프롬프트는 평범한 수준을 벗어납니다.

Claude 4 시대의 추가 원칙도 잊지 마세요. 명시적으로 표현하고, 원하는 것을 정확히 요청하고, 맥락과 이유를 제공하세요. “가능한 한 많이”, “완전히 기능하는”, “프로덕션 준비된” 같은 수식어를 활용하세요. Claude 4는 여러분이 요청한 것을 정확히 수행합니다.

시작은 작게 하세요. 다음 작업부터 이 가이드의 패턴 하나를 적용해보세요. 익숙해지면 두 개, 세 개로 늘려가세요. 몇 주 후면 자연스럽게 마스터급 프롬프트를 작성하게 될 것입니다.

그리고 기억하세요. 완벽한 프롬프트는 없습니다. 상황에 맞게, 프로젝트에 맞게, 여러분의 스타일에 맞게 조정하세요. 이 가이드는 시작점입니다. 여러분만의 패턴을 만들어가세요.

행운을 빕니다. 그리고 즐거운 코딩 되세요!

---

작성일: 2026-01-03
버전: 3.0 (완전 서술형 버전) 저자: AI 시대의 개발자

감사의 말: 이 가이드의 모든 예제는 실전에서 검증되었습니다. 수천 시간의 개발 경험과 수백 번의 시행착오가 녹아 있습니다. Claude 4 베스트 프랙티스는 Anthropic 공식 문서를 기반으로 실전 경험을 더했습니다.