| name | spec-first-ship |
| description | spec.md에 적어 둔 요구사항 체크리스트를 따라, 매 반복마다 미체크 항목 하나를 검증까지 끝내고 [x]로 마킹하는 기획(Planning) 루프입니다. 사용자가 "spec.md 체크리스트대로 하나씩 구현해줘", "명세 따라 요구사항 하나씩 검증하면서 ship", "스펙 먼저 적고 그 순서대로 만들어줘", "체크리스트 다 체크될 때까지 구현", "spec-first ship", "implement from spec.md one requirement at a time", "spec-driven implementation loop"처럼 미리 적어 둔 명세/체크리스트를 기준으로 한 항목씩 완성해 나가고 싶을 때 사용하세요. (구분: prd.json 스토리를 fresh-context로 하나씩 구현·커밋하는 건 looping:ralph-story-executor, 실패 테스트 먼저 쓰고 최소 구현하는 TDD 루프는 looping:autoloop-tdd, 브랜치에서 구현해 PR 올리고 CI green까지 가는 건 looping:ship-pr-until-green, 명세 없이 깨진 테스트만 전부 통과시키는 건 looping:test-until-green) |
명세 우선 출시 (Spec-First Ship)
spec.md 체크리스트를 따라, 매 반복마다 미체크 요구사항 하나를 검증까지 끝내고 [x]로 마킹합니다.
| 항목 | 값 |
|---|
| 카테고리 | 기획(Planning) |
| 트리거 | 수동(manual) — 사람이 직접 시작 |
| 종료 조건(Exit) | spec.md에 미체크 요구사항이 하나도 남지 않을 때 |
| 반복 한도(Max iterations) | 15 |
| 매 반복 체크 명령 | npm test |
| 설치 파일 | 있음 — spec.md 스캐폴드 제공 |
| 가드레일 | 강화됨(Hardened) |
| 지원 에이전트 | Claude Code · Cursor · Codex |
이 루프는 언제 쓰나
"무엇을 만들지"는 이미 정리돼 있는데, 에이전트가 한 번에 여러 요구사항을 헤집어 놓아 어디까지 됐는지 추적이 안 될 때 씁니다. 먼저 spec.md에 요구사항을 체크리스트로 적어 두면, 에이전트가 첫 번째 미체크 항목 하나만 골라 테스트와 함께 구현하고, 검증이 통과해야 비로소 [x]로 마킹합니다. 한 반복 = 한 요구사항이라 진행 상황이 체크박스로 그대로 보이고, 큰 변경으로 여러 기능을 동시에 깨뜨리는 일을 막습니다. 명세가 곧 진행 현황판이자 종료 조건이 됩니다.
루프 흐름
수동 시작 → 명세 읽기 → 요구사항 구현 → 검증 →〔피드백 게이트〕spec.md 전부 체크됨?
↑ │ 아니오 (미체크 남음)
└──────────────────────────────────────────────┘
│ 예
종료
매 반복(pass)마다 하는 일
- 명세 읽기 —
spec.md를 읽고 첫 번째 미체크 요구사항을 고릅니다. 한 반복에서 여러 요구사항을 동시에 시작하지 않습니다.
- 요구사항 구현 — 그 단일 요구사항을 테스트와 함께 구현합니다. 검증을 통과한 뒤에만
spec.md에서 [x]로 마킹합니다.
- 검증 — 그 요구사항에 대해 명세에 적힌 테스트와 수동 체크를 실행합니다.
npm test
가드레일 (점수 조작 방지 규칙)
종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.
- 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
- 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
- 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.
Claude Code에서 실행하기
이 루프는 수동(manual) 트리거입니다. 가장 간단합니다 — 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.
"명세 우선 출시(Spec-First Ship)" 루프를 시작합니다.
목표: spec.md의 모든 요구사항이 구현되고 체크 완료됨
최대 반복: 15
매 반복 사이 실행: npm test
종료 조건: spec.md에 미체크 요구사항이 하나도 없을 때
1단계: spec.md를 읽고, 첫 번째 미체크 항목을 구현한 뒤 검증하고, [x]로 마킹한 다음 이번 반복을 멈춘다.
이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.
설치 파일: 원본 사이트의 Install files는 프로젝트 루트에 spec.md 스캐폴드를 깔아 줍니다. zip을 받아 레포 루트에 풀면 spec.md 경로가 디스크에 생깁니다. 직접 만들어도 무방합니다 — 요구사항을 - [ ] ... 체크리스트로 적어 두기만 하면 됩니다. 시작 전에 spec.md가 실제로 존재하는지 확인하세요.
팁 / 변형
- 체크 명령 교체:
npm test는 예시입니다. 프로젝트에 맞게 pytest, go test ./..., cargo test, pnpm test, bun test 등으로 바꾸세요. 요구사항별로 다른 검증이 필요하면 spec.md의 해당 항목 옆에 검증 명령을 적어 두고 에이전트가 그걸 쓰게 하세요.
- 좋은 spec.md 쓰기: 한 항목은 한 반복에 끝낼 수 있을 만큼 잘게 쪼개고, 각 항목에 "어떻게 검증하는지"(테스트 파일·수동 확인 절차)를 같이 적으면 수렴이 빨라집니다.
- 막힐 때: 같은 요구사항에서 두 번 이상 실패하면 가드레일대로 멈추고, 그 항목은
[ ]로 남겨 둔 채 블로커를 사람에게 보고하게 하세요.
- 연관 루프: prd.json 스토리를 fresh-context로 하나씩 구현·커밋하는
looping:ralph-story-executor, 실패 테스트부터 쓰는 looping:autoloop-tdd, 다 끝낸 뒤 PR로 ship하는 looping:ship-pr-until-green.
원본 영어 kickoff (loops.elorm.xyz 원문)
Start the "Spec-First Ship" loop.
Goal: every requirement in spec.md is implemented and checked off
Max iterations: 15
Between iterations run: npm test
Exit when: spec.md has no unchecked requirements
Step 1: Read spec.md, implement the first unchecked item, verify it, mark [x], and stop this iteration.
Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.
출처: https://loops.elorm.xyz/loops/spec-first-ship
