AI 에이전트에게 지시서 쓰는 법 — build-plan 포맷으로 B1부터 B17까지

“B2 해줘”가 왜 실패하는가 — 에이전트에게 맥락이 통째로 전달되어야 하는 이유

마이위키를 만들면서 딱 한 가지 습관이 생겼습니다. 에이전트한테 작업을 시킬 때 “B2 해줘” 대신 @docs/guide/build-plan.md B2 진행하자라고 하는 거요. 처음엔 그냥 문서 경로 하나 더 붙인 거라고 생각했는데, 해보니 완전히 달랐습니다.

줄만 복사하면 메타가 날아간다

build-plan.md에는 각 항목마다 모드가 박혀 있어요. plan 모드는 계획을 먼저 보여주고 사람이 승인해야 진행하는 거고, auto 모드는 에이전트가 설계 문서를 울타리 삼아 자율로 결정하고 바로 실행합니다. 게이트(✓)가 붙은 항목은 계약 레이어라 틀어지면 가지 전체로 전파되니까 반드시 사람 리뷰가 필요하고요.

근데 “B2 해줘”라고 줄만 복사해서 넘기면, 이 모드 정보와 게이트 표시, 의존 관계가 전부 날아갑니다. 에이전트는 그냥 자기 판단으로 처리해버려요. 제가 @build-plan.md를 통째로 참조했을 때 B2(영속성 베이스)가 plan 모드로 진입한 게 처음엔 의외였는데 — 알고 보니 B2 옆의 plan 태그와 게이트 ✓를 에이전트가 읽은 거였어요. 오작동이 아니라 지시서가 의도대로 작동한 거였습니다.

build-plan의 구조: 줄기에서 가지로

B1B17은 레이어별로 성격이 다릅니다. 줄기(B1B5)는 계약 레이어입니다. 여기서 틀어지면 그 위에 쌓는 가지 6개가 전부 그 오류를 상속해요. 그래서 전부 plan 모드에 게이트가 달려 있고, 저도 매 항목마다 계획서를 확인하고 승인한 다음 착수했습니다.

가지(B6B11)는 수직 슬라이스입니다. 각 슬라이스가 자기 파일만 건드리고, worktree-b{N}-{이름} 워크트리에서 격리 구현한 뒤 타입체크와 린트 통과 후 --no-ff 머지합니다. 이 구간이 auto 모드의 수혜를 제일 크게 받아요. B6B10까지 완료되는 동안 에이전트가 의존 격리 결정까지 스스로 처리했습니다 — B6 Space가 미완일 때 B7 Document가 spaceId를 스칼라 uuid로 두고 머지 시 ManyToOne으로 정식화하는 결정이 문서에 박혀 있었고, 에이전트가 그걸 읽고 알아서 처리한 거예요. 제가 따로 설명하지 않아도 됐습니다.

plan vs auto: 에이전트가 결정을 “언제” 보여주냐의 차이

여기서 오해하기 쉬운 게 하나 있어요. plan 모드와 auto 모드 모두 에이전트가 결정을 내립니다. 차이는 그 결정을 사람한테 “먼저 보여주냐, 실행 후에 보여주냐”예요.

auto 모드로 돌리는데도 에이전트가 중요한 걸 물어올 때가 있습니다. 실제로 B2 진행 중에 MikroORM v6로 설계했는데 세팅이 v7이라 골격이 통째로 바뀐다며 확인을 요청했어요. 이건 두 개의 축이 따로 움직이기 때문입니다. 모드 축(계획을 먼저 보여주냐)과 에스컬레이션 축(이 결정이 사람 몫이냐)은 별개예요. auto 모드여도 계약 드리프트처럼 비가역적이거나 폭발 반경이 큰 결정은 에이전트가 모드를 뚫고 올라옵니다. 이게 살아있는 안전망이에요.

통합과 배포: 사람 게이트가 남는 이유

통합 구간(B12~B15)은 레이어가 얽히기 시작합니다. 특히 B13 Organize 파이프라인은 triage → apply 핸들러, 잠금 가드, Revision 적립이 엮여 있는 핵심 지능 부분이라 에이전트가 초안을 만들어도 사람이 검증하는 반자동으로 갑니다.

배포(B17)는 hong-server 시크릿과 Caddyfile이 걸려 있어서 아예 사람 게이트예요. 서버 시크릿과 라우팅은 에이전트한테 줄 수 있는 결정이 아닙니다.

지시서를 쓴다는 것

결국 build-plan.md는 체크리스트가 아니라 에이전트한테 주는 지시서입니다. 각 항목의 모드, 게이트, 의존 메타가 지시의 일부예요. 그걸 문서 통째로 참조하게 해야 에이전트가 맥락을 안고 움직입니다. 줄 하나만 떼어 넘기면 에이전트는 맥락 없이 자기 판단으로 채우고, 그 판단이 맞을 수도 틀릴 수도 있어요.

AI에게 작업을 맡길 때, 지시 한 줄이 아니라 그 지시가 담긴 문서 전체를 참조하게 해보세요. 맥락이 살아있으면 에이전트가 덜 엉뚱해집니다. 4레버 방법론에서 다루는 맥락 관리 레버가 바로 이 원리와 맞닿아 있어요.

<- 이전 편: build-plan 스킬로 개발 시간 단축하기 · 다음 편 ->: Claude의 설계 제안을 세 번 뒤집었다 배경: 스킬의 비밀 — 자연어가 로직이 되는 순간 · 함께 보기: 마이위키 탄생 스토리