"이거 해줘"가 실패하는 이유 — 클코스터디 2주차, AI에게 일을 넘기는 법
2026.10.12

소개
지피터스 24기 「프로토타입을 넘어서, Claude Code로 남이 실제로 쓰는 서비스 만들기」 스터디를 진행하고 있습니다. 1주차에는 코드를 한 줄도 쓰지 않고 인터뷰로 설계문서를 만들었고, 2주차부터 드디어 코드를 짭니다. 다만 내가 짜는 게 아니라 AI에게 위임합니다.
바이브코딩을 해 보신 분이라면 이 흐름이 익숙하실 거예요.
Day 1: "와, 된다!"
Day 10: "얘 왜 이걸 이렇게 만들었지?"
Day 30: "이거 고치면 저게 왜 깨지지?"
2주차의 논지는 한 줄입니다.
위임이 실패하는 건 AI가 멍청해서가 아니라, 태스크가 자기완결이 아니어서다.
"이거 해줘"에는 배경도, 범위도, 완료 기준도 없습니다. 그러니 AI는 빈칸을 그럴듯하게 상상해서 채우고, 그 상상이 쌓여 Day 30이 됩니다. 그래서 이번 주에는 세 가지를 해 봤습니다.
만들기 전에 클릭되는 프로토타입으로 눈으로 확인하기
일을 자기완결 태스크로 쪼개고, 태스크마다 건드릴 파일을 미리 못 박기
그 태스크를 AI에게 넘겨 동작하는 first cut 받기
수업 전에 제가 먼저 같은 흐름을 처음부터 끝까지 돌려 보며 시간을 쟀고, 이 글은 그 실측 기록입니다. 아래 화면과 터미널 캡처는 모두 그 실측에서 나온 실제 결과입니다.
진행 방법
사용한 도구
Claude Code (Pro 플랜 이상)
gatekit — 제가 만든 오픈소스 Claude Code 플러그인입니다. CLAUDE.md에 산문으로 적어 두던 지침("스펙 먼저", "테스트 통과해야 완료")을 훅(hook)으로 바꿔서, 지켜질 때도 있고 안 지켜질 때도 있는 게 아니라 매번 실행되게 만듭니다. GitHub: https://github.com/loganmakes/gatekit (MIT)
설치 (macOS / Linux, 터미널에서):
curl -fsSL https://claude.ai/install.sh | bash
claude plugin marketplace add loganmakes/gatekit
claude plugin install gatekit@gatekitWindows는 PowerShell 한 줄입니다 (WSL 필요 없음):
irm https://raw.githubusercontent.com/loganmakes/gatekit/v0.16.20/install/install.ps1 | iex설치 후 프로젝트 폴더에서 claude를 실행하고 /gatekit:doctor로 점검합니다.
실측 대상
만든 것: 팀 장비 대여 웹앱 — 카메라·노트북 같은 팀 장비를 누가 언제 빌려 갔는지 관리
시작점: "엑셀엔 비어 있다고 돼 있었는데 실제로는 다른 팀원이 이틀 전에 들고 나가서, 채팅방에 물어보며 30분 넘게 찾았다. 한 달에 두세 번 있다."
규모: 기능 16개 — 로그인, 팀원 관리, 장비 등록, 대여·반납, 연체 표시, 겹치는 예약 막기, 댓글, CSV 내보내기 등
스택: Node.js + SQLite, 팀장 노트북에서 띄우고 같은 와이파이의 휴대폰으로 접속
1단계 — 만들기 전에 눈으로 보기: /gatekit:mockup
프롬프트:
/gatekit:mockup디자인 소스(Figma 등)가 있는지 묻는데, 저는 "디자인은 기본 프리셋으로 해 주세요"라고 답했습니다. 그러면 1주차 설계문서(01-prd.md)의 기능을 바탕으로 화면 목록과 화면 사이의 이동, 화면마다 정상·빈 상태·오류·로딩 네 가지 상태를 설계하고, 실제로 클릭되는 HTML 프로토타입을 만들어 줍니다. 이번엔 화면 9개, 상태 36개가 나왔습니다.


위쪽 검은 막대에서 보는 사람(팀원/관리자)과 화면 상태를 바꿔 가며 직접 눌러 볼 수 있습니다. 정상 화면만 그리는 게 아니라 "목록을 못 불러오면 뭐라고 보여 줄지"까지 이 단계에서 정해집니다.
확정하려고 하면 한 번 더 묻습니다. 기능 목록으로만 볼 때는 안 보이던 빠진 기능이 화면을 눌러 보면 보이기 때문입니다.

중요한 점은 프로토타입을 확정하기 전에는 다음 단계(태스크 분해)가 아예 실행되지 않는다는 것입니다. 말로 막는 게 아니라 검사 스크립트가 막습니다. 프로토타입 단계에서 빠진 화면을 고치는 비용은 문서 한 줄이지만, 다 만든 뒤에 발견하면 다시 만들어야 하니까요.
2단계 — 자기완결 태스크로 쪼개기: /gatekit:tasks
프롬프트:
/gatekit:tasks여기서 지키는 규칙은 세 가지입니다.
수직 슬라이스 — "DB 모델 다 만들기" 같은 수평 작업은 금지. 화면·로직·데이터가 함께 도는 단위로 자릅니다. "팀원을 등록하면 목록에 보인다"처럼 끝까지 눌러 볼 수 있는 단위입니다.
쓰기 범위(write_scope) — 태스크마다 건드려도 되는 파일을 미리 선언합니다. AI가 범위 밖 파일을 쓰려고 하면 훅이 막습니다.
자기완결 지시 — 작업자(AI)는 그 태스크 지시문 하나만 읽고 일합니다. 다른 문서를 찾아보지 않아도 끝낼 수 있어야 합니다.

마지막 두 줄이 중요합니다. 코드가 없는 상태에서 각 태스크의 통과 조건을 미리 돌려 보고 전부 실패하는 것을 확인합니다. 처음부터 통과하는 검사는 아무것도 검사하지 않는 검사이기 때문입니다.
실제로 나온 태스크 하나를 줄여서 보여 드리면 이런 모양입니다.
{"id": "admin-members",
"title": "팀원 등록·임시 비밀번호·비밀번호 초기화·비활성화 (F3 / S7)",
"write_scope": ["src/routes/admin-users.js", "src/views/admin-users/**",
"public/css/admin-users.css",
"tests/admin-users.test.js", "e2e/admin-users.spec.js"],
"instruction": "팀 장비 대여 앱에 관리자용 팀원 관리 화면 S7을 추가한다. … (테이블 구조, 화면 문구, 오류 문구, 테스트할 내용까지 한 문단) … 두 테스트가 통과하면 끝.",
"gates": [{"name": "test", "argv": ["node", "--test", "tests/admin-users.test.js"]},
{"name": "e2e", "argv": ["npx", "--no-install", "playwright", "test", "e2e/admin-users.spec.js", "--project", "mobile"]}],
"depends_on": ["auth-foundation"],
"round": 2}눈여겨볼 곳은 두 군데입니다.
instruction의 마지막 문장 "두 테스트가 통과하면 끝." — 완료가 말이 아니라 명령으로 정의돼 있습니다.gates— 그 "두 테스트"를 실제로 실행하는 명령입니다. AI가 "다 했습니다"라고 말해도 이 명령이 통과하지 않으면 완료가 아닙니다.
round는 동시에 돌릴 수 있는 묶음입니다. 같은 라운드의 태스크끼리 쓰기 범위가 겹치면 검사에서 fail이 납니다. depends_on은 앞 태스크가 만든 파일이 실제로 필요할 때만 겁니다. "기능 목록에서 먼저 나왔으니까"는 의존이 아닙니다. 의존을 함부로 걸면 라운드 수가 늘고, 그만큼 시간이 늘어납니다.
3단계 — 위임하고 first cut 받기: /gatekit:gate → /gatekit:build
/gatekit:gate
/gatekit:build/gatekit:gate에서 "무엇이 되면 완료인가"를 명령 목록으로 정리하고 승인하면, 그 승인에 문서의 해시(SHA-256)가 박힙니다. 승인 전에는 소스 코드 쓰기 자체가 막혀 있고, 승인 후 문서를 고치면 승인이 자동으로 무효가 됩니다. 완료 기준은 3주차 검수에서 본격적으로 다룹니다.
그다음 /gatekit:build가 승인을 확인하고 태스크 10개를 줄 세웁니다.

라운드 2는 하위 에이전트 4개가 동시에 만들었고, 태스크마다 gates 명령을 실제로 돌려서 통과해야 다음으로 넘어갔습니다. 아래는 마지막 라운드에서 휴대폰 화면 점검 게이트가 실패를 잡아낸 장면입니다. AI는 "다 됐다"고 생각했지만, 내 대여 화면의 반납 버튼이 손가락으로 누르기엔 작은 36px이었습니다.

빌드가 끝나면 이렇게 정리해 줍니다. 빌드 중 검사가 잡아내서 고친 문제 목록이 함께 나옵니다.

완성된 first cut — 실제 앱 화면
아래는 완료 기준이 자동으로 찍어 남긴 실제 앱 화면입니다(휴대폰 크기 390px). 앞의 프로토타입과 비교해 보세요.





마지막 댓글 화면을 보시면 댓글 앞에 브라우저 기본 글머리표(•)가 그대로 남아 있습니다. 이건 테스트로는 안 잡히고, 다음 단계에서 코드를 짜지 않은 별도 평가자가 화면을 보고 잡아냈습니다.

결과와 배운 점
실측 결과
단계 | 걸린 시간 |
|---|---|
설치·준비 | 21초 |
discover (뭘 만들지 찾기, 질문 11개) | 4분 |
interview (설계문서, 질문 10개 + 리서치) | 6분 |
mockup (프로토타입) | 6분 |
tasks (태스크 분해) | 6분 |
gate (완료 기준 승인) | 3분 |
build (태스크 10개, 5라운드) | 23분 |
verify (독립 검증) | 4분 |
합계 | 53분 |
기획 26분 + 구현 23분 + 검증 4분. 최종 판정은
ok(화면 경고 1건).서버 테스트 74개, 휴대폰 화면 E2E 11개 통과. 빌드 중 게이트가 실제 결함 7개를 잡았습니다. 알림 문구 깨짐, 새벽 반납일 날짜 오류, 로그인 확인 누락, 권한 거부가 리다이렉트에 묻히던 문제, 예약 거부 뒤 404, 작은 버튼 등 AI가 "됐다"고 한 것 중 명령을 돌려 보니 안 된 것들입니다.
비용은 API 환산 약 $18 수준이었습니다.
단, 이 시간은 질문에 바로바로 답했을 때의 기계 시간입니다. 실제 수업에서는 21개 질문에 생각하는 시간이 15~20분 더 들기 때문에, 2시간 안에 전체를 돌리려면 여유가 전혀 없습니다. 수업에서는 discover를 건너뛰고 기능을 8개 정도로 줄이는 것을 권장합니다.
배운 점 ① — 위임의 품질은 지시문의 품질이다
위 태스크 예시의 지시문은 실제로는 한 문단이 넘게 깁니다. 테이블 컬럼 이름, 화면 문구, 오류 메시지, 무엇을 테스트할지까지 전부 들어 있습니다. 처음엔 "이렇게까지 써야 하나" 싶지만, 이게 바로 AI가 상상으로 채울 빈칸을 없애는 작업입니다. 그리고 이 지시문은 사람이 직접 쓰는 게 아니라 1주차 설계문서와 2주차 프로토타입에서 AI가 뽑아냅니다. 그래서 앞 단계가 탄탄해야 합니다.
배운 점 ② — 단위 테스트로는 영원히 안 잡히는 것들
이전 시범 빌드들에서 실제로 있었던 일입니다.
부품은 만들고 조립을 안 했다 — 스와이프 단위 테스트 15개가 전부 통과했는데, 그 모듈을 화면에 연결하는 작업이 없어서 실제로는 동작하지 않았습니다.
작업자가 테스트를 바꿔서 통과시켰다 — 시나리오를 쪼개고, 일부를 "기능이 아직 없음"을 확인하는 테스트로 바꿔 놨습니다.
기능 3개가 각자 테스트는 통과했는데 화면엔 없었다.
그래서 이번 태스크마다 단위 테스트(node --test) 옆에 휴대폰 화면에서 실제로 눌러 보는 E2E 테스트(playwright)가 같이 붙어 있습니다. 그래도 댓글 글머리표처럼 "보기에 이상한 것"은 결국 만든 세션이 아닌 다른 눈이 봐야 잡힙니다. 이게 3주차 검수의 주제입니다.
시행착오 — 도구 자체도 거짓말을 했다
이번 실측에서 결함은 앱에서만 나온 게 아니었습니다. gatekit 자체의 버그도 7개 나왔습니다. 몇 개만 소개하면:
디자인 프리셋의 색 값 형식을 색 검사기가 읽지 못해서, 태스크에서 색 검사가 빠졌습니다.
끝난 하위 에이전트의 쓰기 범위가 계속 잠겨 있어서, 3라운드부터 병렬 위임을 못 하고 한 세션이 직접 일했습니다.
종료 검사와 독립 검증이 같은 테스트 포트(3100)를 동시에 써서, 멀쩡한 기능이 "판정 불가(unverified)"로 나왔습니다.
진행 상황 안내가 중간에 영어로 바뀌었습니다.
7개 모두 다음 날까지 고쳐서 0.16.18~0.16.20으로 배포했습니다. 위임 도구도 결국 실제로 돌려 봐야 문제가 드러난다는 걸 제 도구로 다시 확인한 셈입니다.
나만의 꿀팁
"이것도 있으면 좋겠는데"가 나오면 설계문서를 펴 보세요. 거기 없으면 만들지 않습니다. 좋은 아이디어는 제안만 하고 목록에 적어 둡니다.
프로토타입에서 빠진 게 보이면 인터뷰로 돌아가세요. 그 시점의 수정 비용은 문서 한 줄입니다.
의존은 "그 파일이 있어야 하는 경우"에만. 라운드 수가 곧 시간입니다.
통과 조건은 코드 없을 때 한 번 돌려서 실패하는지 확인. 처음부터 통과하는 검사는 가짜 증거를 만듭니다.
동작하는 지점마다 커밋. 위임한 결과가 이상하면 되돌릴 수 있어야 합니다.
첫 화면은 못생기게 나옵니다. 정상입니다. 2주차 목표는 예쁜 화면이 아니라 끝까지 눌러지는 first cut입니다.
도움이 필요한 부분
Windows에서 설치하거나 실행하다 막힌 분들의 사례를 더 모으고 싶습니다. 오류 화면을 댓글로 남겨 주시면 반영하겠습니다.
"자기완결 태스크"를 다른 방식으로 쓰고 계신 분이 있다면 어떻게 쓰시는지 궁금합니다.
앞으로의 계획
3주차 — 검수: "만든 놈이 검사하면 안 된다." 구현한 세션이 아닌 별도 평가자가 완료 기준을 하나씩 직접 실행하고, 화면을 캡처해서 확인하는 구조를 다룹니다. 이 스터디의 심장인 주차입니다.
4주차 — 전달: 배포가 아니라 실사용자 1명에게 실제로 전달하기.
gatekit은 스터디가 끝나면 gatebound(https://gatebound.dev)라는 이름으로 이어 갑니다. 스터디 동안은 위의 gatekit 설치 명령을 그대로 쓰시면 됩니다.
도움 받은 글 (옵션)
gatekit 저장소와 매뉴얼: https://github.com/loganmakes/gatekit
Claude Code 훅(hooks) 공식 문서: https://docs.claude.com/en/docs/claude-code/hooks
로그인하고 댓글을 남겨 주세요


로미오님, "위임이 실패하는 건 AI가 멍청해서가 아니라 태스크가 자기완결이 아니어서다"라는 한 줄이 글 전체를 잘 잡아 줘요. "이거 해줘"에는 배경·범위·완료 기준이 없어서 AI가 빈칸을 상상으로 채운다는 설명이 Day 1, Day 10, Day 30 흐름과 정확히 이어졌어요.
코드가 없는 상태에서 통과 조건을 먼저 돌려 전부 실패하는지 확인한다는 팁이 특히 좋았어요. "처음부터 통과하는 검사는 아무것도 검사하지 않는 검사"라는 문장은 오래 기억에 남을 것 같아요. 휴대폰 화면 게이트가 AI는 "됐다"고 한 반납 버튼(36px)을 잡아낸 장면, 그리고 도구 자체의 버그 7개를 숨기지 않고 공개한 점도 신뢰가 갔고요.
53분 기계 시간에 질문 21개의 생각 시간 15~20분이 더 든다는 실측 덕분에, 수업에서 discover를 건너뛰고 기능을 8개로 줄이라는 권고도 설득력이 있어요. 도움을 구하신 Windows 설치 사례는 같은 스터디 분들의 오류 화면 댓글이 모이면 좋겠네요.
3주차 검수 편도 살금살금 기다리고 있을게요 🐾