데일리 밥

Agent Skills /spec 쓰는 법 — 코드보다 먼저 「무엇을 만들지」를 문서로 [2/6]

Daily BaapIT/전자기기

Claude Code 에 「가족 여행 경비 정산 앱 만들어 줘」라고 하면 곧바로 파일을 만들기 시작하잖아요. 그 전에 무엇을 만들지 먼저 합의하는 단계를 넣을 수 있나요?

넣을 수 있어요. Agent Skills 의 /spec 명령이 그 자리예요. 이 명령은 코드를 한 줄도 쓰지 않고, 만들 것·쓸 명령·폴더 구조·코드 스타일·테스트 방법·하지 말 것을 SPEC.md 한 파일에 적어 사람에게 확인을 받아요. 그리고 뒤에 올 /plan·/build auto 는 이 파일이 없으면 시작하지 않게 만들어져 있어서, 순서를 건너뛰기가 어려워요.

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

/spec 이 하는 일 — 「가정」을 먼저 꺼낸다

/spec 은 spec-driven-development 스킬을 부르는 명령이에요. 저장소의 스킬 원문은 이 일을 네 단계 관문으로 그려요.

사양 쓰기 ──→ 계획 ──→ 작업 나누기 ──→ 구현
   │           │           │            │
 사람 확인    사람 확인    사람 확인     사람 확인

앞 단계를 사람이 확인하기 전에는 다음으로 넘어가지 않는 게 규칙이에요.

가장 특징적인 부분은 사양을 쓰기 전에 가정을 먼저 적으라는 거예요. 스킬 원문의 예시는 이래요.

ASSUMPTIONS I'M MAKING:
1. 웹 앱이다 (네이티브 모바일 아님)
2. 인증은 세션 쿠키다 (JWT 아님)
3. DB 는 PostgreSQL (기존 Prisma 스키마 기준)
→ 틀렸으면 지금 고쳐 주세요. 아니면 이대로 갑니다.

「사양의 존재 이유는 코드를 쓰기 전에 오해를 드러내는 것이고, 가정은 가장 위험한 형태의 오해다」라고 적혀 있어요. 애매한 요구를 조용히 채워 넣는 것을 이 스킬은 실패로 봐요.

또 하나는 뭉뚱그린 요구를 측정할 수 있는 기준으로 바꾸라는 거예요. 「대시보드를 더 빠르게」라는 요구를 「4G 에서 LCP 2.5초 미만, 첫 데이터 로드 500ms 미만, 로딩 중 레이아웃 이동 없음」처럼 고쳐 적고 「이 목표가 맞나요?」라고 되묻는 식이에요. 그래야 「빠르게」가 무슨 뜻인지 추측하지 않고, 되는지 안 되는지를 재서 알 수 있다는 논리예요.

SPEC.md 에 들어가는 여섯 항목

스킬이 요구하는 사양의 뼈대는 여섯 개예요.

항목 무엇을 적나
Objective 무엇을 왜 만드나, 누가 쓰나, 성공이 무엇인가
Commands 빌드·테스트·린트·개발 서버 실행 명령 전체 (도구 이름만 적지 않는다)
Project Structure 소스·테스트·문서가 어디 가나
Code Style 설명 세 문단보다 잘 쓴 코드 한 조각
Testing Strategy 프레임워크, 테스트 위치, 커버리지 기대치
Boundaries 항상 한다 / 먼저 묻는다 / 절대 안 한다 세 단계

여기에 성공 기준(Success Criteria)과 아직 못 정한 것(Open Questions)이 따라와요. 「Boundaries」의 세 단계가 실제로 가장 쓸모 있어요. 「커밋 전에 테스트를 돈다」는 항상, 「의존성 추가·DB 스키마 변경」은 먼저 묻기, 「시크릿 커밋·실패하는 테스트 지우기」는 절대 금지 — 이렇게 적어 두면 뒤의 /build 가 여기를 보고 멈추거나 물어요.

시작하기 전에

  • 1편대로 플러그인이 설치돼 있어야 해요.
  • 프로젝트 폴더에서 claude 를 켜요. 빈 폴더여도 돼요. 아래 실행 예는 README 한 줄만 있는 폴더에서 돌린 거예요.
  • 명령 이름은 /agent-skills:spec 이에요. README 에는 /spec 으로 적혀 있지만 플러그인으로 설치하면 앞에 이름이 붙어요.

절차

  1. 대화창에 명령과 만들고 싶은 것을 한 문장으로 적어요.
/agent-skills:spec 가족 여행 경비를 나누는 웹앱을 만들고 싶어요. 누가 얼마를 냈는지 적으면 끝날 때 정산 금액을 계산해 주면 됩니다.
  1. 질문에 답해요. 명령 정의(commands/spec.toml)에 따르면 네 가지를 물어요 — 목표와 대상 사용자, 핵심 기능과 수용 기준, 기술 스택 선호와 제약, 경계(항상·묻기·금지).
  2. 프로젝트 루트에 생긴 SPEC.md 를 읽어요. 가정 목록부터 봐요. 틀린 가정이 있으면 파일을 고치거나 대화로 고쳐 달라고 하면 돼요.
  3. 「이대로 가자」고 답하면 사양 단계가 끝나요. 다음은 /plan 이에요.

실제로 돌려 본 결과 — 1분 35초, 가정 8개

이 글을 쓰면서 설치된 환경에서 실제로 돌렸어요. 조건은 이래요.

  • 폴더에는 「아직 코드는 없다」는 README 한 줄만
  • 모델은 Sonnet, 사람이 답할 수 없는 환경이어서 프롬프트 끝에 **「물어보지 말고 가정을 적어 두고 진행하세요」**를 덧붙임
  • 걸린 시간 1분 35초, SPEC.md 약 7.5KB

결과 파일은 정말로 가정 8개를 맨 위에 적고 시작했어요. 일부를 옮기면 이래요.

## 가정 (ASSUMPTIONS)

질문할 수 없는 환경이라 아래 가정을 세우고 진행한다. 틀렸다면 이 섹션을 고치고 다시 시작할 것.

1. 사용자/인증: 가족 소규모(2~10명) 내부용. 로그인 없음. 한 사람(총무)이 한 기기에서 입력…
2. 데이터 저장: 서버·DB 없이 브라우저 localStorage 에 저장…
4. 분담 방식: 기본은 전원 균등 분담. …최초 버전은 단순화한다. (Open Questions 참조)
5. 정산 목표: "누가 누구에게 얼마" 목록만 계산. 실제 송금·결제 기능은 없다

「Boundaries」는 이렇게 나왔어요.

- Always: 정산 계산 로직 변경 시 관련 단위 테스트를 먼저 통과시킨 뒤 커밋 / 금액은 정수(원 단위)로만 처리
- Ask first: 백엔드·DB·인증 도입 / 상태관리 라이브러리·CSS 프레임워크 추가 / "부분 분담" 기능
- Never: 실제 송금·결제 API 연동 / 계좌번호 등 금융 개인정보 저장 / 실패하는 테스트를 승인 없이 삭제

그리고 「Open Questions」 넷 — 부분 분담이 필요한가, 여러 기기에서 동시에 입력하나, 배포처가 정해져 있나, 원화 외 통화가 필요한가 — 를 「답을 가정해 진행했고 실제로는 확인이 필요한 항목」이라고 남겼어요. 사람이 있었다면 이 넷을 물었을 거예요.

기억해 두실 점 하나. 이 사양은 기술 스택으로 React 18·Vite 5 를 골랐어요. 그게 2026년 9월 시점에 최신 버전인지는 /spec 이 확인해 주지 않아요. 버전을 공식 문서로 확인하는 일은 다른 스킬(source-driven-development, 6편)의 몫이에요. 사양에 적힌 버전은 한 번 직접 보셔야 해요.

아직 아이디어가 흐릿하다면 — interview-me 와 idea-refine

/spec 은 「만들 것이 대체로 정해진」 상태를 전제해요. 그 앞 단계용 스킬이 둘 있어요. 둘 다 명령이 아니라 대화 중에 부르는 스킬이에요.

  • interview-me — 한 번에 질문 하나씩, 자기 추측을 붙여서 물어요. 「Q: 이 대시보드는 누가 보나요? / GUESS: 아침 스탠드업에서 팀장이 볼 것 같은데요」 식이에요. 답을 예측할 수 있을 만큼 확신(약 95%)이 서면 멈춰요. 「interview me」·「grill me」라고 말하면 켜져요. 스킬 원문
  • idea-refine — 아이디어 하나를 「어떻게 하면 …할 수 있을까」 문장으로 고쳐 쓰고, 58개 변형(뒤집기·제약 제거·10배 단순화…)을 만든 뒤 23방향으로 모아 docs/ideas/ 에 한 장짜리 문서로 남겨요. 스킬 원문

둘 다 사람이 실시간으로 답해야 돌아가요. interview-me 는 원문에 「CI·예약 실행·/loop 같은 비대화형에서는 부르지 말라」고 못 박혀 있어요.

안 되는 경우

  • 사람이 답할 수 없으면 질문 단계가 통째로 빠져요. 위 실행처럼 「가정을 적고 진행하라」고 하면 돌아가긴 하지만, 그 가정을 아무도 확인하지 않은 채 다음 단계로 넘어가요. 자동화 파이프라인에서 쓸 때는 SPEC.md 를 사람이 한 번 읽는 단계를 밖에서 만들어 두셔야 해요.
  • 사양에 적힌 버전이 최신이라는 보장이 없어요. 위에서 본 대로예요.
  • SPEC.md 위치가 정해져 있어요. /build auto 는 저장소 루트의 SPEC.md, docs/SPEC.md, spec/ 폴더 아래만 사양으로 인정해요. README 나 다른 문서는 인정하지 않아요. /spec 이 루트에 만들어 주니 옮기지만 않으면 돼요.
  • 사양이 길어지면 그 자체가 부담이에요. 매번 전체를 대화에 넣으면 토큰이 들고 집중이 흐려져요. context-engineering 스킬이 「5,000단어 사양 전체가 아니라 지금 기능에 해당하는 절만 넣어라」고 하는 이유예요.

이럴 땐 쓰지 마세요

한 줄 고치기, 오타, 요구가 분명하고 파일 하나로 끝나는 변경에는 /spec 이 낭비예요. 스킬 원문도 「30분 넘게 걸릴 일, 여러 파일을 건드리는 일, 구조를 정하는 일」에만 쓰라고 해요. 그리고 이미 사양 문서가 있다면 /spec 을 다시 돌리지 말고 그 파일을 SPEC.md 자리에 두고 /plan 으로 가면 돼요.

✔ 요약

  • /agent-skills:spec <한 문장> → 질문 답하기 → SPEC.md 확인 → 승인
  • 사양보다 먼저 「내가 가정하는 것」을 번호로 드러낸다
  • 여섯 항목: 목표·명령·구조·스타일·테스트·경계(항상/묻기/금지)
  • 실측: 빈 폴더, Sonnet, 1분 35초, 가정 8개 + 미해결 질문 4개
  • 사양에 적힌 라이브러리 버전은 직접 확인해야 한다
  • 사람이 없으면 질문이 빠지고, 뒤 명령은 SPEC.md 위치를 가린다
  • 2026년 9월 기준, 플러그인 버전 0.6.6

확인할 곳: spec-driven-development 스킬 원문 · /spec 명령 정의 · interview-me · idea-refine · Claude Code — Skills

← 목록으로