서론

Claude Code를 설치하고 몇 개의 프롬프트(Prompt)를 보내보셨을 겁니다. 하지만 "로그인 시스템을 작성해줘"와 같이 실질적인 요청을 할 때, 결과물이 너무 일반적이거나, 불완전하거나, 혹은 핵심을 완전히 놓치는 것처럼 느껴질 때가 있습니다.

문제는 거의 항상 프롬프트에 있습니다. 이는 해결 가능합니다.

이 장에서는 모호한 요청을 프로덕션 환경에 바로 적용 가능한 코드(Production-ready code)로 바꿔주는 정확한 구조와 습관을 다룹니다. Claude가 코드를 작성하기 전에 알아야 할 것, 패턴 매칭(Pattern-matching) 대신 추론(Reasoning)을 유도하는 방법, 컨텍스트(Context)를 잃지 않고 여러 파일을 제공하는 방법, 그리고 CLAUDE.md를 통해 프로젝트 전반의 표준을 고정하는 방법을 알아봅니다.

Claude가 코드를 작성하기 전에 필요한 것

Claude가 단 한 줄의 코드를 생성하기 전에, 사용자의 프롬프트로부터 세 가지 사항을 해결합니다.

1. 무엇을 만들 것인가. "로그인 시스템"은 단순한 비밀번호 확인일 수도 있고, 전체 OAuth 흐름일 수도 있으며, JWT 기반의 API 엔드포인트(Endpoint)일 수도 있습니다. Claude는 그중 하나를 선택합니다. 만약 명시하지 않았다면, Claude는 추측한 것입니다.

2. 어떻게 동작해야 하는가. 에러 발생 시 차단해야 할까요, 아니면 구조화된 에러 응답(Structured error responses)을 반환해야 할까요? 실패를 로그(Log)로 남겨야 할까요? 입력을 검증(Validate)해야 할까요? 비밀번호를 해싱(Hash)해야 할까요? 이에 대해 침묵한다면 Claude는 기본값(Defaults)을 선택하며, 이는 종종 가장 단순한 방식이 됩니다.

3. 결과물이 어떤 형태여야 하는가. 단일 함수인가요? 모듈인가요? 독스트링(Docstrings)이 포함된 클래스인가요? 가공되지 않은 코드인가요, 아니면 설명이 포함된 코드인가요?

이 중 어느 하나라도 답하지 않은 채로 두면 Claude가 그 공백을 채웁니다. 출력물이 정확히 틀린 것은 아니겠지만, 당신이 의도했던 결과물은 아닐 것입니다.

전송 전 유용한 사고 점검법: 무엇을(What), 어떻게(How), 형식(Format). 이 세 가지 질문에 답하는 데 걸리는 3초가 돌아오는 결과물을 일관되게 개선해 줄 것입니다.

효과적인 프롬프트 작성하기

약한 프롬프트 vs 강한 프롬프트

약한 프롬프트:

"사용자 인증을 처리하는 함수를 작성해줘."

Claude는 기본적인 사용자 이름/비밀번호 확인 기능만 생성합니다. 에러 처리도, 해싱도, 구조도 없습니다. 기술적으로는 작동하지만, 배포할 수 있는 수준은 아닙니다.

강한 프롬프트:

"FastAPI를 사용하여 JWT 토큰으로 사용자 인증을 처리하는 Python 함수를 작성하세요. 데이터베이스를 통해 자격 증명을 확인하고, 15분 후에 만료되는 토큰을 발행하며, 구조화된 JSON 응답을 반환해야 합니다. Docstring(독스트링)과 각 단계를 설명하는 주석을 포함하세요."

네 가지 추가 사항: 프레임워크 (FastAPI), 언어 (Python), 기대 동작 (JWT, 만료 시간, JSON 응답), 출력 형식 (Docstring, 주석). 이제 Claude는 무엇이 "완료"된 상태인지 알게 되었습니다.

Chain-of-Thought Prompting (사고의 사슬 프롬프팅)

Claude에게 코드를 작성하기 전에 추론하도록 요청하면 더 신중하게 추론합니다. 이것이 Chain-of-Thought (CoT, 사고의 사슬) 프롬프팅이며, Claude의 최신 기능들과 함께 어떻게 조화를 이루는지 알아둘 가치가 있습니다.

사용하지 않았을 때:

"팩토리얼을 계산하는 FastAPI 엔드포인트를 작성하세요."

Claude는 종종 입력값 검증이 없는 재귀 함수를 생성합니다. 양의 정수에는 작동하지만, 음수나 매우 큰 값에서는 오류가 발생합니다.

사용했을 때:

"코드를 작성하기 전에, 숫자를 입력받아 팩토리얼을 반환하는 FastAPI 엔드포인트에 대한 접근 방식을 개요로 작성하세요. 그런 다음 입력값 검증, 에러 처리(Error handling), 주석을 포함한 전체 구현 코드를 작성하세요."

Claude는 먼저 자신의 계획 — 입력 스키마 (Input schema), 재귀 vs 반복 (Recursion vs iteration), 예외 케이스 (음수, 0, 큰 값), JSON 출력 — 을 나열한 다음, 그 계획에 부합하는 코드를 작성합니다. 그 결과물은 더 안전하며 디버깅하기에도 훨씬 수월합니다.

한 가지 중요한 뉘앙스: Chain-of-thought prompting은 Claude의 extended thinking 기능이 도입되기 전까지 표준 접근 방식이었습니다. Extended thinking (Sonnet 4.6 및 Opus 4.6/4.7에서 사용 가능)은 출력을 생성하기 전에 Claude에게 별도로 할당된 추론 과정을 제공합니다. 이 추론 흔적(reasoning trace)을 API 응답에서 검사할 수 있습니다. 복잡한 코딩 작업의 경우, extended thinking이 수동적인 chain-of-thought prompting보다 일반적으로 더 나은 결과를 산출합니다. 만약 이를 지원하는 플랜을 사용하고 있다면, 아키텍처 결정, 복잡한 디버깅, 다단계 리팩터링 시 이 기능을 활성화하세요. Extended thinking을 사용할 수 없거나 Claude의 응답 내에 추론 과정이 인라인으로 나타나야 할 때만 수동적인 chain-of-thought가 유용합니다.

어떤 접근 방식을 사용하든, Anthropic의 문서는 한 가지 일관된 발견 사항을 지적합니다. 바로 항상 Claude에게 생각 과정을 출력하도록 요청해야 한다는 것입니다. 만약 추론 과정이 응답에 나타나지 않는다면, 어떤 추론 단계도 실행되지 않았다는 의미입니다.

다중 파일 프롬프트 (Multi-File Prompts)

실제 프로젝트는 여러 파일을 아우릅니다. Claude는 입력 구조만 명확하게 구성해 준다면 이를 잘 처리합니다.

나쁜 접근 방식: 레이블 없이 다섯 개의 파일을 프롬프트에 쏟아붓습니다. Claude는 어떤 코드가 어느 파일에 속하는지, 그리고 그들 사이의 관계가 무엇인지 추적하지 못합니다.

좋은 접근 방식: 각 파일에 명확한 헤더를 붙이고 목표를 미리 제시합니다.

Claude, FastAPI 파일 두 개를 공유할게요. 이 두 파일 전반에 걸쳐 유효성 검사(validation)가 어떻게 처리되는지 분석하고 중복을 제거하도록 리팩터링해 주세요.

...

Claude는 구조를 읽고 모듈 간의 관계를 이해하며, 한 번의 작업으로 두 파일을 모두 리팩터링합니다. Sonnet 4.6 및 Opus 4.6/4.7의 1M 토큰 컨텍스트 창 덕분에 이 방식으로 대규모 코드베이스(많은 파일, 전체 문서화, 테스트 스위트)를 입력할 수 있습니다.

CLAUDE.md: 프로젝트 전반의 표준 (Project-Wide Standards)

블로그에서 '시스템 프롬프트(system prompts)'라고 설명한 방식은 API 사용에는 정확하지만, Claude Code에서는 표준 메커니즘이 CLAUDE.md입니다. 이는 프로젝트 루트에 배치하는 파일(또는 로컬 규칙을 위한 하위 디렉터리)입니다. Claude는 세션 시작 시 이를 자동으로 읽습니다.

CLAUDE.md에는 다음과 같은 내용이 포함될 수 있습니다:

프로젝트 표준 (Project Standards)

• 언어: Python 3.12, FastAPI 0.115
  ...

Claude는 디렉터리 구조를 기반으로 여러 개의 CLAUDE.md 파일을 자동으로 병합합니다. 즉, 루트(root) 디렉터리의 전역 규칙(global rules)과 하위 디렉터리의 로컬 재정의(local overrides)가 적용됩니다. 이는 시니어 엔지니어의 사고 방식, 즉 프로젝트 전반에 걸친 컨벤션(conventions)과 파일별 제약 사항을 결합하는 방식과 유사합니다.

API 사용 시에도 시스템 프롬프트(system prompts)는 동일한 방식으로 작동합니다. 한 번 설정하면 세션 내의 모든 요청이 해당 표준을 상속받습니다.

특히 보안 가드레일(security guardrails)에 대하여: 프롬프트를 로그(logs)처럼 취급하십시오. 프롬프트는 언제든 검사될 수 있다고 가정해야 합니다. 프롬프트에 비밀번호나 자격 증명(credentials)을 넣지 마십시오. 도구 권한(tool permissions)은 Claude가 작업을 수행하는 데 필요한 범위로 제한하십시오. 인증(authentication) 또는 액세스 제어(access control)와 관련된 모든 사항에 대해서는 반드시 사람이 검토 과정(review loop)에 참여하도록 하십시오.

베스트 프랙티스 (Best Practices)

초보자를 위한 팁

• 모든 프롬프트를 작성하기 전에 무엇을(What), 어떻게(How), 어떤 형식으로(Format) 체크리스트를 실행하십시오.
• 디버깅 시에는 실제 에러 메시지를 그대로 붙여넣으십시오. Claude는 에러를 의역한 내용이 아니라 전체 스택 트레이스(stack trace)를 볼 때 에러를 더 잘 진단합니다.
• Claude에게 추론 과정(reasoning)을 설명해 달라고 요청하십시오: "왜 재귀(recursion) 대신 반복적 접근 방식(iterative approach)을 선택했나요?"라는 질문을 던지면, Claude의 답변을 통해 모델이 문제를 어떻게 모델링하고 있는지 배울 수 있습니다.

숙련된 개발자를 위한 팁

• 모든 프로젝트에 CLAUDE.md를 커밋(commit)하십시오. 짧고 명확하게 유지하십시오. 구체적인 규칙이 긴 문서보다 더 효과적입니다.
• 여러 파일이 포함된 프롬프트에서는 파일에 명확한 라벨을 붙이십시오. 상단에 목표를 명시한 다음 파일들을 붙여넣으십시오.
• 복잡한 작업에는 확장된 사고(extended thinking)를 사용하십시오. 코딩 및 에이전트(agentic) 작업 시 노력 수준(effort)을 xhigh로 설정하십시오. Anthropic의 공식 문서에서도 대부분의 개발 유스케이스(use cases)에 대해 이를 기본값으로 권장합니다.
• 매우 긴 자율 실행(autonomous runs)이 필요한 경우, 하위 에이전트(sub-agents)를 사용하십시오: "방금 결제 프로세서를 작성했습니다. 이제 하위 에이전트를 사용하여 해당 코드에 대한 보안 검토(security review)를 수행하세요." 이렇게 하면 검토가 별도의 컨텍스트(context)에서 실행되는 동안 메인 대화의 집중도를 유지할 수 있습니다.

흔한 프롬프팅 오류

문제 (Problem)	예상 원인 (Likely Cause)	해결책 (Fix)
일반적인 출력 (Generic output)	프롬프트에 프레임워크(framework), 형식(format), 또는 동작 제약 조건(behavior constraints)이 누락됨	구체적인 언어, 라이브러리 및 출력 요구 사항을 추가
...

대화로서의 프롬프트 (Prompts as Dialogue)

Claude를 가장 잘 활용하는 개발자들은 프롬프팅을 단발성 명령(one-shot command)이 아닌 대화(conversation)로 취급합니다. 먼저 Claude가 문제를 어떻게 해석하는지 테스트할 수 있도록 충분히 넓은 범위에서 시작하세요. 돌아온 결과에 따라 내용을 다듬어 나가십시오. Claude에게 자신의 선택을 방어(defend)해 달라고 요청해 보세요.

각 반복(iteration)은 출력을 개선합니다. 시간이 지나면 언제 구체적이어야 하는지, 그리고 언제 Claude가 해석할 여지를 남겨두어야 하는지에 대한 감각을 익히게 됩니다. 즉, 엄격한 사양(tight spec)이 더 나은 코드를 생성하는 시점과, 느슨한 프레이밍(looser framing)이 더 나은 아키텍처(architecture)를 끌어내는 시점을 알게 됩니다. Anthropic의 자체 베스트 프랙티스(best practices) 가이드에서는 이를 명확히 설명합니다. 때로는 모호한 프롬프트가 정확히 정답일 수 있는데, 이는 제약을 가하기 전에 Claude가 문제를 어떻게 해석하는지 확인하고 싶기 때문입니다.

결론 (Conclusion)

프롬프팅은 학습 곡선(learning curve)은 짧지만 한계치(ceiling)는 높은 기술입니다. 기초 원칙은 다음과 같습니다. 무엇을(What), 어떻게(How), 어떤 형식으로(Format) 할 것인지 전송하기 전에 답변하십시오. 추론(reasoning)이 필요한 작업에는 생각의 사슬(chain-of-thought) 또는 확장된 사고(extended thinking)를 사용하십시오. 여러 파일로 구성된 입력값은 명확하게 라벨을 붙이십시오. 매 세션마다 같은 말을 반복하지 않도록 프로젝트 표준을 CLAUDE.md에 저장하십시오.

직접 해보세요: 최근에 작성한 코드 한 조각을 가져오십시오.