Getting Started (업데이트: 2026. 6. 7.)

Claude Code에 첫 작업을 맡길 때 사고 안 나는 요청서 쓰는 법

Claude Code에 첫 작업을 맡길 때 사고를 막는 요청서 작성법. 목적·건드려도 되는 범위·검증·되돌리는 법을 한 장에 정리하는 틀을 복붙 예시와 함께 소개합니다.

Claude Code에 첫 작업을 맡길 때 사고 안 나는 요청서 쓰는 법

“이 저장소, README 쪽 좀 알아서 깔끔하게 정리해 줘.”

설치하고 30분, 제가 Claude Code에 처음 던진 요청이 바로 이거였습니다. 돌아온 건 README만 손볼 줄 알았는데 package.json의 스크립트 이름까지 바뀐 diff였어요. 돌아가긴 하는데, 정작 고치고 싶었던 절차와는 전혀 다른 곳이 3개 파일이나 바뀌어 있었습니다. “이거… 그냥 올려도 되나?” 하고 화면 앞에서 그대로 굳어버렸죠.

똑똑하다는 Claude Code가 왜 시키지도 않은 곳까지 건드릴까요. 능력 문제가 아닙니다. 제가 “어디까지 해도 되는지”를 한마디도 정해주지 않았을 뿐입니다. 신입에게 “가게, 알아서 잘 봐 둬” 하고 외출했더니 진열대를 통째로 재배치해 놨더라, 그런 이야기입니다.

이 글은 그 “어디까지”를 종이 한 장에 적는 이야기입니다. 저는 이걸 요청서(첫 작업 요청서)라고 부릅니다.

핵심 요약

  • 첫 요청에서 사고가 나는 건, 목적·허용 범위·검증·되돌리는 법을 안 정한 채 “알아서 잘”이라고 던지기 때문입니다.
  • 요청서에는 9개 항목(목적 / 독자 상태 / 읽어도 됨 / 편집해도 됨 / 실행해도 됨 / 건드리지 마 / 검증 / 되돌리는 법 / 다음 한 걸음)을 적습니다.
  • Claude Code에 맡기는 건 “읽기·고치기·검증 명령 실행”까지입니다. 삭제·배포 반영·과금은 사람이 판단합니다.
  • 복붙해서 쓰는 요청서 템플릿과, 요청서의 빠진 항목을 자동으로 점검하는 JavaScript를 넣어 뒀습니다.
  • 우선 “실패해도 git으로 되돌릴 수 있는 작은 작업 1개”만 고르는 것이, 가장 빠른 성공 경험입니다.

왜 첫 작업에서 사고가 나는가

Claude Code를 깔자마자 많은 사람이 하는 게 “넓은 요청”입니다. “저장소 정리해 줘”, “README 고쳐 줘”. 마음은 압니다. 뭘 할 수 있는지 시험해 보고 싶은 거죠.

하지만 넓은 요청을 던지면 처음 10분은 탐색으로 사라집니다. Claude Code는 파일을 여기저기 읽고, 관련 있어 보이는 곳을 멋대로 고치고, 마지막엔 “아마 잘 돌아갈 겁니다” 같은 모호한 보고로 끝납니다. 당신은 diff를 전부 다시 읽어야 하고, 결국 “차라리 내가 하는 게 빨랐겠다”가 됩니다.

원인은 모델이 멍청해서가 아닙니다. 목표와 경계를 건네주지 않은 것입니다. 사람 신입도 첫날에 “자유롭게 해” 소리를 들으면 손이 멈추거나 폭주하거나 둘 중 하나입니다. 경계를 먼저 정하는 것만으로 이 사고는 거의 사라집니다.

조작 자체가 아직 불안한 분은 먼저 Claude Code 시작하기 가이드를 한 번 훑고 돌아오면, 이 요청서 이야기가 훨씬 매끄럽게 들어옵니다.

요청서에 적는 9가지 항목

제가 매번 한 장에 적는 건 다음 9개 항목입니다. 어려운 말은 필요 없어요. 각 줄에 답을 하나씩 채우면 됩니다.

항목무엇을 적나나쁜 예 → 좋은 예
목적끝났을 때 어떤 상태면 성공인가”README를 고친다” → “README 절차를 package.json에 맞춘다”
독자 상태누구를 위한 작업인가(공란) → “초보자, 한 번만 확실히 성공하고 싶다”
읽어도 됨참조를 허용하는 파일(전부) → “README.md와 package.json만”
편집해도 됨수정을 허용하는 파일(전부) → “README.md만”
실행해도 됨돌려도 되는 명령(아무거나) → “npm run build만”
건드리지 마절대 못 바꾸게 하는 곳(미지정) → “package-lock, 배포 설정, 가격”
검증성공의 증거가 되는 것”돌아가면 OK” → “build가 통과 / diff가 README만”
되돌리는 법실패 시 어떻게 원래대로 돌리나(없음) → “README를 git에서 되돌린다”
다음 한 걸음독자가 다음에 갈 곳 하나(3개 나열) → “우선 무료 입문 자료만”

핵심은 “건드리지 마”, “검증”, “되돌리는 법” 세 가지입니다. 여기를 적는 순간, 요청이 “부탁”에서 “안심하고 맡길 수 있는 일”로 바뀝니다.

복붙해서 쓰는 요청서 템플릿

그대로 쓸 수 있는 틀입니다. 코드 블록으로 둔 건, Claude Code에 그대로 붙여 넣어 건네줄 수 있게 하기 위해서입니다. 자기 저장소 이름과 고치고 싶은 위치로 바꿔 주세요.

# 첫 작업 요청서

목적: README의 셋업 절차를 package.json 내용에 맞춘다.
독자 상태: 초보자. 한 번만 확실히 성공하고 싶다.
읽어도 됨:
- README.md
- package.json
편집해도 됨:
- README.md 만
실행해도 됨:
- npm run build
건드리지 마:
- package-lock.json
- 배포 설정(환경 변수·공개 설정)
- 가격이나 신청 링크
검증:
- npm run build 가 통과한다
- git diff 가 README.md 만 바뀐 상태다
되돌리는 법:
- 검증에 실패하면 README.md 를 git에서 원래대로 되돌린다
다음 한 걸음:
- 우선 무료 입문 자료만 안내한다

실제 요청 예로 말하면, README 절차를 package.json에 맞추기만 하는 거라면, 읽는 건 README와 package.json, 편집은 README만, 증거는 npm run build입니다. 이 정도 입자라면 실패해도 git checkout -- README.md 한 방으로 되돌릴 수 있습니다. 첫 한 번은 이만큼 좁아도 됩니다. 오히려 좁을수록 성공했는지 아닌지를 당신 스스로 판단할 수 있습니다.

Claude Code에 맡기는 범위와, 사람이 판단하는 범위

요청서를 쓸 때 저는 머릿속으로 이 선을 긋습니다. 경계가 모호하면 Claude Code는 “친절을 베푼다는 마음”으로 선을 넘어옵니다.

Claude Code에 맡겨도 됨사람이 판단(자동화하지 않음)
지정한 파일을 읽기어떤 파일을 건드리게 할지 결정
지정한 파일만 고치기파일 삭제
npm run build 등 검증 명령 실행운영 환경 반영·배포
diff 요약을 돌려주기과금이 발생하는 작업
실패 원인을 보고하기git push --force 등 되돌릴 수 없는 작업

왼쪽은 맡깁니다. 오른쪽은 처음엔 전부 “실행 전에 사람에게 확인”으로 둡니다. 안전하다고 확인된 작업만 나중에 조금씩 자동 쪽으로 옮깁니다. 이 순서를 지키는 것만으로 한밤중에 간 떨어지는 횟수가 확 줄어듭니다.

요청을 건넬 때는 이런 한마디를 덧붙입니다.

이 요청서 범위 안에서만, 작은 작업 1개를 실행해 주세요.
범위 밖이라고 판단한 건 실행하지 말고 제안만 해 주세요.

먼저 다음 5가지를 돌려주세요.
1. 앞으로 읽을 파일
2. 앞으로 편집할 파일
3. 작업 전후로 돌릴 검증 명령
4. 변경 diff의 요약
5. 실패했을 때 되돌리는 법

“구현 전에 계획과 검증을 먼저 돌려줘”라고 부탁하는 게 핵심입니다. 돌아온 계획이 요청서 범위를 넘었다면 그 자리에서 멈출 수 있습니다. 손을 대기 전에 멈추면 뒷정리가 필요 없습니다.

요청서의 빠진 항목을 자동으로 점검하는 코드

요청서를 다 썼다고 생각해도 항목이 빠지는 일은 흔합니다. 저는 항목이 있는지 없는지를 기계로 점검합니다. 복붙하면 돌아가는 JavaScript입니다. Node.js에서 node check-brief.mjs처럼 돌릴 수 있습니다.

// 요청서에 필요한 항목이 다 들어 있는지 기계적으로 확인한다
const requiredFields = [
  "목적",
  "읽어도 됨",
  "편집해도 됨",
  "실행해도 됨",
  "건드리지 마",
  "검증",
  "되돌리는 법",
  "다음 한 걸음",
];

export function validateFirstTaskBrief(markdown) {
  // 들어 있지 않은 항목을 추려낸다
  const missing = requiredFields.filter((field) => !markdown.includes(field));

  // 검증 명령(여기서는 npm run build)까지 적혀 있는지도 본다
  const hasProofCommand = markdown.includes("npm run build");

  return {
    ok: missing.length === 0,
    missing,
    readyForClaudeCode: missing.length === 0 && hasProofCommand,
  };
}

// 동작 확인 예시
const sample = `
목적: README를 package.json에 맞춘다
읽어도 됨: README.md
편집해도 됨: README.md
실행해도 됨: npm run build
건드리지 마: package-lock.json
검증: npm run build 가 통과한다
되돌리는 법: git에서 README.md를 되돌린다
다음 한 걸음: 무료 입문 자료
`;

const result = validateFirstTaskBrief(sample);
console.log(result);
// → { ok: true, missing: [], readyForClaudeCode: true }

이 점검을 통과시킨 다음 요청서를 건네면 “건드리지 마”와 “되돌리는 법”을 빠뜨리는 일이 사라집니다. 사람 눈에만 기대면 바쁜 날엔 반드시 어딘가 빠집니다. 기계가 알 수 있는 건 기계에 맡기는 게 편합니다.

이런 상황에서 효과를 본다 (3가지)

1. README나 절차 문서 수정 “문서를 최신화해 줘”라면 범위가 무한입니다. “README의 셋업 장만, package.json의 스크립트 이름에 맞춰 줘”라고 좁히면 diff가 1개 파일에 들어가고 npm run build로 확인할 수 있습니다. 첫 작업으로 가장 잘 맞습니다.

2. 풀 리퀘스트 1차 리뷰 “이 PR 좀 봐 줘”가 아니라, “변경 파일 중 src/ 아래만 읽고, 테스트가 깨질 것 같은 곳을 짚어 줘. 코드는 고치지 말고 지적만.” 읽는 건 맡기고, 고칠지 말지는 사람이 남깁니다. 이걸로 “멋대로 고치다가 다른 버그를 만드는” 사고를 막습니다.

3. CTA(독자의 다음 한 걸음으로 가는 동선) 교체 인기 글 아래 버튼 하나만 바꾸는 작업이라도, “관련 컴포넌트를 찾아서 고쳐 줘”는 너무 넓습니다. 먼저 “건드려도 되는 파일”, “확인할 공개 URL”, “교체할 링크”를 요청서로 정합니다. 작업 후 확인이 “왠지 괜찮아 보임”에서 “이 증거라면 내보낼 수 있음”으로 바뀝니다.

제가 저질렀던 실패 3가지

솔직히 적습니다. 요청서를 쓰기 시작하기 전, 저는 같은 실패를 반복했습니다.

첫 번째는 “건드리지 마”를 안 적었던 것. README만 고쳐 줬으면 했는데 Claude Code가 친절하게 package.json까지 손봐 주는 바람에 build가 안 통과했습니다. 건드리지 마: package-lock.json, 배포 설정 이 3줄을 더한 것만으로 이건 두 번 다시 안 일어났습니다.

두 번째는 검증을 “돌아가면 OK”로 때운 것. 무엇을 두고 “돌아간다”인지 안 정해 놨으니 매번 diff를 눈으로 전부 쫓았습니다. 검증: npm run build 가 통과 / diff가 README만처럼 구체적인 명령으로 바꿨더니 확인이 10초 만에 끝나게 됐습니다.

세 번째는 다음 한 걸음을 3개 나열한 것. 글 끝에 자료도 교재도 상담도 전부 붙였더니 독자 반응이 흐릿해졌습니다. 독자 상태에 맞춰 1개로 좁히는 편이, 결국 그 1개가 제대로 클릭됩니다. 무엇을 적을지는 CLAUDE.md 작성 모범 사례에 프로젝트 규약으로 남겨 두면 매번 흔들리지 않습니다.

자주 묻는 질문

Q. 매번 이 9개 항목을 전부 적는 건 번거롭지 않나요? 처음 몇 번뿐입니다. 템플릿을 하나 만들어 first-task-brief.md로 둬 두면, 다음부턴 내용을 3~4줄만 갈아 끼우면 됩니다. 적는 시간보다, 폭주한 diff를 다시 읽는 시간이 훨씬 깁니다.

Q. 간단한 작업에도 요청서가 필요한가요? “1개 파일 오타 수정” 수준이면 말로 하는 요청으로 충분합니다. 요청서가 효과를 보는 건, 여러 파일을 건드릴 가능성이 있는 작업이나, 운영·과금·삭제가 스칠 수 있는 작업입니다. 헷갈리면 쓴다, 로 손해는 없습니다.

Q. 영어 키 이름(Goal, May edit 등)으로 적어야 하나요? 팀에서 로그를 나란히 놓고 비교한다면 영어 키가 맞춰져서 편하지만, 혼자 쓴다면 한국어로 충분합니다. Claude Code는 어느 쪽이든 이해합니다. 중요한 건 언어가 아니라 항목이 빠지지 않았는지입니다.

Q. 프로그래밍을 안 하는 사람도 쓸 수 있나요? 쓸 수 있습니다. 글쓰기나 자료 정리에서도 “읽어도 됨·편집해도 됨·건드리지 마”의 사고방식은 똑같습니다. 비개발자용 입구는 개발자가 아닌 사람을 위한 Claude Code에 정리해 뒀습니다.

Q. Claude Code가 요청서를 무시하고 범위 밖을 건드리면요? 먼저 “처음에 계획과 검증을 돌려줘”라고 부탁해서, 손을 대기 전에 멈추는 게 기본입니다. 그래도 넘는다면 요청서의 “건드리지 마”가 구체적이지 않을 가능성이 높습니다. 폴더 이름이나 파일 이름까지 명시하면 효과가 있습니다.

실제로 해 본 결과

이 요청서를, README를 package.json에 맞추는 작은 작업으로 시험한 게 가장 이해하기 쉬웠습니다. 편집해도 됨: README.md 만이라고 먼저 적어 두니, Claude Code가 package-lock이나 설정 파일로 손을 뻗는 흐름이 실행 전 계획 단계에서 멈췄습니다. diff를 다시 읽는 수고가 그대로 사라진 게 컸습니다.

검증에 npm run build와 git diff 두 개를 넣은 것도 효과적이었습니다. 작업 후 판단이 “분위기상 괜찮아 보임”이 아니라 “build가 초록, diff는 README만, 그러니 내보낼 수 있음”이라는 단언으로 바뀌었습니다. 반대로 다음 한 걸음을 공란으로 둔 날은, 저조차 “다음에 뭘 안내하더라” 하고 헤맸고 글 끝 동선이 흐릿해졌습니다.

결국 알게 된 건, Claude Code에 큰 자유를 건네는 게 가치가 아니라는 것입니다. 첫 작업을 작게 잘라, 성공·실패·다음 행동을 내 눈으로 볼 수 있는 상태로 만든다. 이게 가장 빠릅니다. 경계를 한 장 적는 번거로움은, 폭주한 diff를 나중에 다시 읽는 번거로움에 비하면 없는 거나 마찬가지였습니다.

바깥쪽 구조를 더 다지고 싶은 분은 Anthropic의 Claude Code 공식 문서에서 권한 설정 동작을 확인해 두면, 요청서와 설정의 역할 분담이 또렷해집니다. 회사 업무에 Claude Code를 도입해 운영 규칙까지 정비하고 싶다면, 교육·상담에서 실제 작업에 맞춘 요청서 틀 만들기부터 함께 진행할 수 있습니다.

#claude-code #초보자 #요청서 #프롬프트 #셋업 #첫 작업
무료

무료 PDF: Claude Code 치트시트

이메일을 입력하면 명령, 리뷰 습관, 안전한 워크플로를 정리한 PDF를 받을 수 있습니다.

개인정보를 안전하게 관리하며 스팸을 보내지 않습니다.

Masa

작성자 소개

Masa

Claude Code 실무 워크플로와 팀 도입을 검증하는 엔지니어입니다.

관련 글