지시 잘하기 — 일을 맡기는 6가지 원리
좋은 결과는 좋은 지시에서 나옵니다. 클로드는 의도를 어느 정도 짐작하지만, 사장님 머릿속을 읽지는 못합니다. 원리보다 당장 붙여 넣어 쓸 문장이 급하시면 역할별로 추린 오늘 시켜 볼 지시문을 먼저 보셔도 됩니다. AI에게는 자기가 한 일을 스스로 판단하지 못하는 약점이 있습니다. 그래서 아래에서 검증 방법까지 함께 건네라고 거듭 당부합니다. 이 약점이 왜 생기는지는 「AI는 자기가 한 일을 스스로 판단하지 못합니다」 페이지에서 설명합니다.
원리는 하나입니다 — 신입 직원에게 맡기듯
일 잘 맡기는 법은 사람에게나 AI에게나 같습니다. 신입 직원에게 일을 줄 때 원하는 결과, 잘됐는지 판단할 기준, 참고할 재료를 함께 건네듯, 클로드에게도 이 세 가지를 함께 줍니다. 이렇게 건네는 질문이나 지시를 프롬프트(prompt)라고 부릅니다. 업무 지시서라고 생각하면 됩니다.
출발점은 구체적으로 말하는 것입니다. 두루뭉술한 지시보다 상황을 콕 집은 지시가 훨씬 정확한 결과를 냅니다.
# 막연한 지시 버그 고쳐 줘 # 구체적인 지시 로그인 버그를 고쳐 주세요. 잘못된 비밀번호를 넣으면 빈 화면만 나옵니다.
좋은 지시를 만드는 6가지 원리
공식 안내의 프롬프트 모음이 잘 통하는 이유는 공통점 여섯 가지에 있습니다. 이 여섯 가지를 알면 어떤 지시든 자기 일에 맞게 바꿔 쓸 수 있습니다. 예시는 공식 안내의 문장을 그대로 옮겼습니다.
1. 단계가 아니라 결과를 말합니다. 어떤 파일을 어떻게 고치라고 지시하지 않습니다. 무엇을 원하는지만 말하고, 파일 찾기는 클로드에게 맡깁니다.
공개 API에 요청 한도(rate limit)를 추가하고, 기존 테스트가 그대로 통과하는지 확인해 줘.
2. 스스로 확인할 방법을 함께 줍니다. 실행·테스트·비교·검증을 같은 지시에 넣으면, 클로드가 한 번 시도하고 멈추는 대신 스스로 반복하며 고칩니다.
마이그레이션을 작성하고, 개발용 데이터베이스에 실행한 다음, 스키마가 일치하는지 확인해 줘.
3. 참고할 대상을 가리킵니다. 이미 마음에 드는 파일이나 패턴을 알려 주면 클로드가 우리 방식에 맞춰 만듭니다.
프로필 페이지와 같은 레이아웃을 따르는 설정 페이지를 추가해 줘.
4. 숫자로 잴 수 있는 목표를 줍니다. 숫자로 판가름 나는 일은 목표 숫자를 정해 주면 다 됐는지가 분명해집니다.
번들 크기를 200KB 아래로 줄이고, 무엇을 제거했는지 보여 줘.
5. 자료(원본)를 직접 건넵니다. 오류 메시지·실행 기록·화면 캡처를 붙여 넣거나 @로 파일을 불러옵니다. 설명을 옮겨 적는 것보다 원본을 그대로 읽게 하는 편이 정확합니다.
빌드가 왜 실패해? @build.log
6. 원하는 답의 형태를 말합니다. 형식·분량·대상 독자를 지정하면 쓰기 좋은 형태로 답이 나옵니다.
결제 재시도 로직이 어떻게 동작하는지 다이어그램이 있는 HTML 페이지로 설명한 다음, 브라우저로 열어 줘.
아쉬운 지시 vs 좋은 지시
공식 안내의 사례를 아쉬운 지시와 좋은 지시로 나눠 정리했습니다.
예시에 개발 용어가 나와도 지시하는 방식은 그대로 옮겨 쓸 수 있습니다. “홈페이지 소개 문구 고쳐 줘” 대신 “소개 문구가 딱딱하다는 의견이 있었어. 뉴스레터의 인사말 톤을 참고해서 첫 문단을 다시 써 줘”라고 하는 식입니다.
| 요령 | 아쉬운 지시 | 좋은 지시 |
|---|---|---|
| 증상까지 설명한다 | 아쉬운 지시“로그인 버그 고쳐” | 좋은 지시“세션이 만료된 뒤 로그인이 실패한다는 제보가 있어. src/auth/의 인증 흐름, 특히 토큰 갱신 쪽을 봐. 문제를 재현하는 실패 테스트를 먼저 쓰고 고쳐” |
| 통째로 맡기지 않고 단계로 쪼갠다 | 아쉬운 지시“회원 정보 기능을 한 번에 다 만들어 줘” | 좋은 지시“1. 사용자 프로필을 저장할 새 데이터베이스 표를 만들어 주세요. 2. 프로필을 조회하고 수정하는 통로(API)를 만들어 주세요. 3. 사용자가 자기 정보를 보고 고칠 수 있는 웹 페이지를 만들어 주세요.” |
| 먼저 살펴보게 한다 | 아쉬운 지시곧장 “고쳐 줘”부터 시작 | 좋은 지시“데이터베이스 구조를 분석해 주세요”처럼 먼저 훑어보게 한 뒤 본 작업을 시킨다 |
| 기존 방식을 참고하게 한다 | 아쉬운 지시“달력 위젯 추가해” | 좋은 지시“홈 화면의 기존 위젯들이 어떻게 만들어졌는지 봐. HotDogWidget.php가 좋은 예야. 그 방식대로 달력 위젯을 새로 만들어” |
재료를 직접 건네는 법
말로 설명하는 대신 자료를 곧장 건네면 답이 훨씬 정확해집니다. 네 가지 방법이 있습니다.
- @로 파일을 불러옵니다. 위치를 설명하는 대신 @ 뒤에 파일 이름을 적으면 클로드가 그 파일을 읽고 답합니다. 예를 들어 “
@meeting-notes.md를 읽고 실행 항목을 정리해 줘”처럼 씁니다. - 이미지를 붙여 넣습니다. 화면 캡처를 복사한 뒤 Ctrl+V로 붙여 넣습니다(맥에서 쓰는 터미널 프로그램 iTerm2에서는 Cmd+V도 됩니다). 창에 이미지를 끌어다 놓아도 됩니다. 제대로 붙었으면 입력창에 [Image #N] 표시가 나타납니다.
- 문서 주소(URL)를 줍니다. 참고할 문서나 설명 페이지의 주소를 그대로 붙여 넣습니다. 그러면 클로드가 그 페이지를 가져와 읽고 답합니다.
- 필요한 것을 직접 가져오게 합니다. “필요한 정보는 직접 찾아봐”라고 시키면 클로드가 스스로 파일을 읽어 맥락을 챙깁니다.
# 화면 캡처를 붙여 넣은 뒤
이건 오류가 난 화면 캡처야. 원인이 뭐야?우리 회사도 오류가 나면 증상을 말로 옮겨 적는 대신 화면 캡처를 그대로 붙여 넣습니다. 옮겨 적는 사이에 중요한 정보가 빠지기 때문입니다.
큰일은 면담부터
규모가 큰 일은 지시를 처음부터 완벽하게 쓰려 애쓰지 말고, 클로드가 먼저 사장님을 면담하게 합니다. 하고 싶은 일을 짧게 말한 뒤 이렇게 덧붙입니다.
질문을 던져 가며 나를 면담해 줘
그러면 만드는 방법·화면·예외 상황·장단점처럼 미처 생각 못 한 지점을 클로드가 하나씩 물어봐 줍니다. 대화가 끝나면 정리된 설계 문서를 만들게 합니다. 그다음 새 대화를 열어 그 문서를 보며 실제 작업에 들어가는 순서가 좋습니다. 공식 안내의 예시는 이렇습니다.
워크스페이스별 요청 한도(rate limit) 기능을 만들고 싶어. 구현·UX·예외 상황·트레이드오프를 하나씩 물어봐서 빠짐없이 정리한 다음, 명세를 SPEC.md에 써 줘.
같은 이유로, 무언가 고치기 전에 살펴보기 → 계획 → 실행 순서를 권합니다. 계획 단계에서는 파일을 읽고 답만 하는 계획 모드(plan mode)를 쓰면 안전합니다. 자세한 것은 권한 모드 바꾸기 페이지에 있습니다.
“됐다”는 말 대신 증거
확인할 방법이 없으면 클로드는 겉보기만 보고 “다 됐다”고 판단하고 멈춥니다. 그래서 정말 맞는지 따지는 일이 사장님 몫으로 남습니다. 반대로 성공인지 실패인지 스스로 판정할 방법을 주면, 클로드가 일하고 검사하고 통과할 때까지 알아서 고칩니다. 지켜보는 작업이 지켜보지 않아도 되는 작업으로 바뀝니다.
validateEmail 함수를 만들어. 예시: [email protected]은 참, invalid는 거짓, [email protected]은 거짓. 만든 뒤 테스트를 돌려
일이 끝나면 “됐다”는 말 대신 증거를 보여 달라고 합니다. 테스트 출력, 실제로 실행한 명령어와 그 결과, 화면 캡처 같은 것입니다. 증거를 읽는 편이 직접 다시 확인하는 것보다 빠릅니다.
같은 문제로 클로드가 두 번 넘게 고쳐 봤다면, 그 대화에는 실패한 시도가 지저분하게 쌓여 있습니다. 이럴 때는 /clear로 대화에 쌓인 기록(맥락)을 비우고, 배운 것을 반영한 더 나은 지시로 새로 시작하는 편이 거의 항상 낫습니다. 맥락이 왜 중요한지는 맥락 관리 페이지에서 다룹니다.
파일을 잔뜩 읽어야 하는 조사는 서브에이전트(별도 방에서 일하고 요약만 가져오는 직원)에게 맡기면, 지금 대화의 맥락을 깨끗하게 유지할 수 있습니다.