데일리 밥

Agent Skills /plan 쓰는 법 — 일을 한 번에 끝낼 크기로 자르기 [3/6]

Daily BaapIT/전자기기

사양까지는 만들었는데, 「이제 만들어」라고 하면 Claude Code 가 DB 손대다가 화면 만들다가 다시 DB 로 돌아오는 식으로 뒤섞이지 않나요?

Agent Skills 의 /plan 은 코드를 한 줄도 쓰지 않고 사양을 「한 번에 끝낼 수 있는 작업」 목록으로 자르는 명령이에요. 결과는 tasks/plan.md 와 tasks/todo.md 두 파일이고, 작업마다 「다 됐다」의 조건과 확인 방법, 다른 작업과의 의존이 붙어요. 뒤의 /build 는 이 파일에서 다음 작업을 골라요. 이 글은 그 자르는 규칙과, 실제로 돌려 본 결과를 다뤄요.

이 시리즈 — ① 설치와 첫 확인 · ② /spec — 만들 것을 먼저 문서로 · ③ /plan — 일을 한 번에 끝낼 크기로(이 글) · ④ /build 와 /test · ⑤ /review 와 /ship · ⑥ 알아서 켜지는 스킬과 한계

/plan 이 하는 일 — 다섯 단계

/plan 은 planning-and-task-breakdown 스킬을 불러요. 스킬 원문의 순서는 이래요.

  1. 읽기만 하는 모드로 들어간다. 사양과 관련 코드를 읽고, 기존 패턴과 위험을 적어요. 여기서 코드를 쓰면 안 돼요.
  2. 무엇이 무엇에 기대는지 그린다. DB 스키마 → 타입 → API → 화면처럼 의존 그래프를 만들고, 바닥부터 위로 올라가는 순서를 잡아요.
  3. 세로로 자른다. 「DB 전부 → API 전부 → 화면 전부」가 아니라 「회원가입 한 줄을 DB·API·화면까지」, 다음 「로그인 한 줄을 끝까지」 식이에요. 작업 하나가 끝나면 실제로 되는 기능이 하나 생겨요.
  4. 작업을 정해진 틀로 쓴다. 설명 한 문단, 수용 기준(검사할 수 있는 조건), 검증 방법(테스트·빌드·수동 확인 명령), 의존하는 작업, 건드릴 파일, 크기.
  5. 순서를 잡고 검문소를 둔다. 위험한 작업은 앞에(빨리 실패하려고), 작업 2~3개마다 「전체 테스트 통과·빌드 성공·사람 확인」 검문소를 넣어요.

크기표가 따로 있어요.

크기 파일 수 예
XS 1 검증 규칙 하나 추가
S 1~2 엔드포인트 하나
M 3~5 회원가입 흐름 하나
L 5~8 필터·페이지네이션 있는 검색
XL 8+ 너무 크다 — 더 쪼갠다

「에이전트는 S 와 M 에서 가장 잘한다」고 적혀 있어요. 더 쪼갤 신호도 셋이에요. 한 번에 두 시간 넘게 걸릴 것 같을 때, 수용 기준을 세 줄 안에 못 쓸 때, 인증과 결제처럼 독립된 두 하위 시스템을 함께 건드릴 때예요.

시작하기 전에

  • 2편에서 만든 SPEC.md 가 저장소 루트에 있어야 해요. 명령 정의(commands/planning.toml)가 「기존 사양(SPEC.md 또는 그에 준하는 것)을 읽어라」로 시작해요.
  • 결과 파일 위치는 tasks/plan.md 와 tasks/todo.md 로 정해져 있어요. 뒤의 /build 가 이 경로를 봐요.

절차

  1. 사양이 있는 폴더에서 명령을 쳐요.
/agent-skills:plan
  1. 계획이 나오면 사람이 읽어요. 이 단계가 이 명령의 존재 이유예요. 특히 「Architecture Decisions」 절과 「Open Questions」 절을 봐요. 사양이 정하지 않은 것을 계획이 대신 정한 자리가 거기예요.
  2. 고칠 것이 있으면 대화로 고쳐 달라고 하거나 파일을 직접 고쳐요.
  3. 승인하면 /build 로 넘어가요.

실제로 돌려 본 결과 — 6분 26초, 두 파일 25KB

2편에서 만든 여행 경비 정산 앱 사양 위에 그대로 돌렸어요. 조건은 같아요. Sonnet, 사람이 답할 수 없는 환경이라 「묻지 말고 진행하라」를 덧붙임.

  • 걸린 시간 6분 26초. /spec 의 네 배예요
  • tasks/plan.md 약 12KB, tasks/todo.md 약 13KB
  • 실행이 「최대 턴 12회 도달」로 끝났어요. 파일 두 개는 다 만들어진 뒤였지만, 마무리 정리를 할 턴이 남지 않았어요. 이게 뒤에서 이야기할 어긋남의 원인으로 보여요

plan.md 의 구성은 이랬어요. 개요 → 구조 결정 → 의존 그래프(문자 그림) → 5단계로 나눈 작업 목록과 단계마다 검문소 → 병렬로 할 수 있는 것 → 위험과 대응(표) → 미해결 질문 4개.

「구조 결정」 절에는 사양이 정하지 않은 것을 계획이 정하면서 「⚠️ 인간 리뷰 필요」 표시를 두 군데 달아 놓았어요. 하나를 옮기면 이래요.

- 나머지(원 단위 반올림) 처리 규칙 — SPEC.md 에 방법이 명시되어 있지 않아 아래로 결정:
  총 지출을 참가자 수로 나눈 몫(내림)을 기본 분담액으로 하고, 나머지는 참가자 ID 를
  정렬한 순서에서 앞에서부터 1원씩 추가로 부담시킨다. …
  ⚠️ 인간 리뷰 필요: 이 배분 규칙은 자의적 선택이다.

사양에 없는 것을 조용히 정하지 않고 「내가 정했고 확인이 필요하다」고 표시한 거예요. 2편에서 본 「가정을 드러낸다」 규칙이 여기까지 이어져요.

todo.md 는 작업마다 정해진 틀을 지켰어요. 정산 계산 함수 작업의 수용 기준은 이랬어요.

**Acceptance criteria:**
- [ ] 참가자 1명: 송금 목록 없음(빈 배열)
- [ ] 지출 0건: 송금 목록 없음
- [ ] 총액이 인원수로 나누어떨어지지 않는 경우: 나머지가 정확히 규칙대로 배분되고
      sum(각자 순잔액) === 0
- [ ] 한 사람이 전액 부담: 나머지 인원 전원이 그 사람에게 송금
- [ ] 이미 낸 돈이 정확히 같은 경우: 송금 목록 0건

이 다섯 줄이 뒤의 /build 에서 그대로 「먼저 쓸 실패하는 테스트」가 돼요. 계획을 잘 쓰면 테스트가 이미 반은 써진 셈이에요.

실측에서 드러난 어긋남 — 그래서 사람이 읽어야 한다

두 파일을 나란히 읽으니 서로 안 맞는 곳이 셋 있었어요.

  • plan.md 는 작업이 9개인데 todo.md 는 10개예요. 정산 함수가 한쪽에서는 Task 6, 다른 쪽에서는 Task 7 이에요.
  • plan.md 는 「저장 모듈에 지출 필드까지 처음부터 넣으니 별도의 확장 작업은 두지 않는다」고 결정했는데, todo.md 에는 그 확장 작업(Task 5)이 들어 있어요.
  • 참가자 삭제 규칙이 정반대예요. plan.md 는 「그 사람이 낸 지출도 함께 지운다(확인창 포함)」로 정했고, todo.md 의 Task 4 는 「이미 지출의 결제자로 등록된 참가자는 삭제를 막는다」로 적혀 있어요.

턴 한도에 걸려 두 파일을 맞춰 볼 여유가 없었던 것으로 보여요. 사람이 있었다면 계획을 보여 주는 단계에서 물었을 것이고, 사람이 없어도 턴을 더 줬으면 맞췄을 수 있어요. 어느 쪽이든 결론은 같아요. 계획은 나온 그대로 /build 에 넘기는 것이 아니라 읽고 고치는 문서예요. 이 어긋남을 안 고치고 /build auto 를 돌리면 Task 4 와 Task 5 가 서로 다른 규칙으로 만들어져요.

안 되는 경우

  • 사양이 없으면 계획도 없어요. 명령이 SPEC.md 를 읽는 것으로 시작해요. 없으면 「무엇을 계획하나」부터 되물어요.
  • 비대화형으로 돌리면 턴이 모자랄 수 있어요. 위 실측처럼 claude -p 로 돌릴 때 --max-turns 를 12 로 두면 마무리를 못 해요. 사람이 있는 대화에서는 이 제한이 없어요.
  • 계획 파일이 커요. 두 파일 합쳐 25KB 면 매 작업마다 전부 읽히면 토큰이 들어요. 6편에서 볼 context-engineering 스킬이 「필요한 절만 넣어라」고 하는 이유예요. 다행히 /build 는 「다음 대기 작업 하나」만 골라 읽는 구조예요.
  • 경로가 고정이에요. tasks/ 가 아닌 곳에 계획을 두면 /build 가 못 찾아요.

이럴 땐 쓰지 마세요

파일 하나짜리 변경, 범위가 뻔한 일에는 계획이 낭비예요. 스킬 원문도 「사양에 이미 작업이 잘 나뉘어 있으면 쓰지 마라」고 적어요. 그런 경우는 사양의 작업 목록을 tasks/todo.md 로 옮겨 두고 바로 /build 로 가면 돼요.

✔ 요약

  • /agent-skills:plan → tasks/plan.md + tasks/todo.md, 코드는 안 쓴다
  • 의존 그래프 → 세로 자르기 → 작업 틀(수용 기준·검증·의존·파일·크기) → 검문소
  • 크기는 S·M 이 적당, XL 은 더 쪼갠다
  • 실측: Sonnet, 6분 26초, 25KB, 턴 한도에 걸림
  • 사양이 안 정한 것을 계획이 정하고 「인간 리뷰 필요」로 표시한다
  • 두 파일이 서로 어긋날 수 있다 — 읽고 고친 뒤에 /build 로
  • 2026년 9월 기준, 플러그인 버전 0.6.6

확인할 곳: planning-and-task-breakdown 스킬 원문 · /plan 명령 정의 · /build 명령 정의 · Definition of Done 참고 문서 · Claude Code — Skills

← 목록으로