05. 프롬프트로 작업 지시하기

두 가지 엔지니어링

AI 코딩에서 결과 품질을 가르는 두 축이 있습니다.

비유하자면, 프롬프트 엔지니어링은 주문을 정확히 하는 일이고, 컨텍스트 엔지니어링은 요리사에게 어떤 재료와 레시피를 건넬지 고르는 일입니다. 둘 다 필요합니다. 이 장은 주로 전자를, 컨텍스트 엔지니어링의 도구들(CLAUDE.md·메모리·세션 관리)은 4장·9장·22장에서 다룹니다.

핵심 원칙: 모호한 지시 → 모호한 결과

가장 흔한 실수는 너무 추상적인 지시입니다. "앱을 더 빠르게 해줘", "로그인 로직 좀 봐줘" 같은 말은 Claude가 의도를 추측하게 만듭니다.

flowchart LR
    A["'앱을 빠르게 해줘'"]:::danger --> B[추측·탐색 남발]:::agent --> C[엉뚱한 방향·시간 낭비]:::danger
    D["'상품 목록 페이지 첫 로딩이 느림.<br/>N+1 쿼리 의심. src/api/products.ts부터 확인'"]:::user --> E[정확한 탐색]:::agent --> F[원하는 결과]:::result

    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000
    classDef user fill:#FFE082,stroke:#F9A825,color:#000

📌 핵심: Claude는 의도를 추론할 수는 있어도 독심술은 못 합니다. 원하는 결과·제약·참고할 기존 패턴을 명시할수록 결과가 좋아집니다.

나쁜 예 vs 좋은 예

❌  사용자 설정 페이지 만들어줘

✅  /settings 경로에 사용자 설정 페이지를 만들어줘.
    - 프로필 섹션: 이름, 이메일, 아바타 업로드
    - 알림 설정: 이메일/푸시 체크박스
    - 기존 UserProfile 컴포넌트 패턴을 따를 것
    - 폼 유효성 검사 테스트를 추가할 것

좋은 예는 (1) 무엇을, (2) 어떤 구성으로, (3) 어떤 기존 패턴을 따라, (4) 검증은 어떻게 까지 담고 있습니다.

스펙(spec): 큰 작업의 설계도

작은 작업은 한 문장으로 충분하지만, 여러 파일에 걸친 기능은 스펙 문서를 먼저 만드는 게 효과적입니다. 스펙은 "무엇을 만들지"를 적은 짧은 설계 문서이고, Claude와 함께 다듬을 수 있습니다.

전형적인 흐름:

flowchart TB
    A[고수준 설명 + 기존 코드 위치 제시]:::user --> B[Claude가 탐색·접근법 제안]:::agent
    B --> C{검토}:::danger
    C -->|오해 발견| D[왜 틀렸는지 알려주고 재제안 요청]:::user
    D --> B
    C -->|좋음| E[스펙 확정 → 구현 지시]:::result

    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

이 "탐색 → 계획 → 검토 → 구현" 흐름은 Claude Code의 Plan Mode로 체계화되어 있습니다(→ 7장).

맥락을 효율적으로 전달하는 법

Claude에게 정보를 주는 방법은 여러 가지입니다. 공식 베스트 프랙티스에서 권장하는 것들:

⚠️ 흔한 실수 — "주방 싱크대" 세션: 한 작업을 하다가 무관한 걸 묻고, 다시 원래 작업으로 돌아오는 패턴. 컨텍스트가 잡동사니로 가득 차 품질이 떨어집니다. 무관한 작업 사이에는 /clear 로 비우세요.

⚠️ 흔한 실수 — 반복 교정의 늪: Claude가 틀려서 고쳐주는데 또 틀리고, 또 고치고… 실패한 시도들이 컨텍스트를 오염시킵니다. 두 번 고쳐도 안 되면, /clear 후 배운 것을 반영한 더 나은 초기 프롬프트를 새로 쓰세요.

좋은 프롬프트 체크리스트

□ 목표가 구체적인가? (무엇을, 어디에, 어떤 형태로)
□ 따라야 할 기존 패턴·파일을 짚어줬는가?
□ 제약·금지사항이 있다면 명시했는가?
□ 검증 방법(테스트·빌드)을 알려줬는가?
□ 큰 작업이면 스펙/계획을 먼저 세웠는가?
□ 무관한 이전 맥락이 섞여 있지 않은가? (필요시 /clear)

💡 한 사례에서는 약 500단어 분량의 잘 짜인 지시가, 500MB짜리 고장난 코드를 30KB의 동작하는 코드로 바꿨다고 합니다. 지시의 질이 곧 결과의 질입니다.

이 장에서 배운 것

• 결과 품질은 프롬프트 엔지니어링(무엇을 어떻게 말할지)과 컨텍스트 엔지니어링(무엇을 보게 할지)의 두 축으로 결정된다.
• 모호한 지시는 모호한 결과를 낳는다. 목표·구성·기존 패턴·검증 방법을 구체적으로 적는다.
• 큰 작업은 스펙을 먼저 만들고 탐색→계획→검토→구현 흐름을 따른다.
• 맥락은 이미지·URL·파이프·경로 지정 등으로 효율적으로 전달한다.
• 무관한 작업 사이엔 /clear, 두 번 실패하면 /clear 후 더 나은 프롬프트로 재시작한다.

✍️ 확인 문제

1. "앱을 빠르게 해줘" 같은 지시가 비효율적인 이유와, 이를 좋은 프롬프트로 바꾸는 방법을 설명해 보세요.
2. 제안된 구현이 마음에 들지 않을 때, 스펙을 직접 고치는 것보다 권장되는 접근은 무엇인가요?
3. "반복 교정의 늪"에 빠졌을 때의 권장 대응은 무엇인가요?

다음 장: 06. 코드베이스 탐색과 파일 작업 — Claude가 파일을 다루는 도구들을 들여다봅니다.