Spec Review 템플릿 2026 — requirements.md·design.md·tasks.md를 15분 안에 만드는 실전 프롬프트

Posted on by

Quick Answer

Spec Review가 필요한 팀이 제일 자주 막히는 건 개념이 아니라 첫 템플릿이다. 그래서 시작은 거창한 도구보다, requirements.md, design.md, tasks.md 세 장을 빠르게 만드는 기본 틀이 더 중요하다. 이 글은 그 세 장을 15분 안에 만들 수 있게 최소 템플릿과 바로 붙여넣을 프롬프트까지 정리한 실전판이다.

이 글이 필요한 사람

  • 방금 Spec Review가 필요하다는 말엔 동의했는데, 막상 문서 첫 줄을 못 쓰는 팀
  • Kiro 스타일 specs나 자체 markdown spec을 팀에 도입하고 싶은 사람
  • Codex, Claude Code, Copilot coding agent 앞단에 사람 검토용 문서를 먼저 세우고 싶은 사람
  • requirements, design, tasks가 서로 따로 놀지 않게 연결하고 싶은 사람

지금 결론

  1. 첫 도입은 requirements / design / tasks 세 장이면 충분하다.
  2. 좋은 Spec Review 문서는 길이보다 범위, 비목표, acceptance criteria, 실패 흐름이 선명해야 한다.
  3. 프롬프트는 멋있게 쓰는 것보다, 입력과 출력 형식을 고정하는 쪽이 훨씬 잘 먹힌다.

그래서 이 글의 목적은 “스펙 문화의 철학”이 아니라, 지금 당장 팀에서 복붙해서 돌릴 수 있는 템플릿을 주는 데 있다.

Spec Review 얘기를 꺼내면 팀 반응이 대충 둘로 갈린다.

  • “맞는 말이긴 한데, 문서 늘어나면 귀찮아지잖아”
  • “좋은데 그래서 뭘 어디에 쓰면 되는데?”

둘 다 맞는 말이다. 문서만 늘면 귀찮다. 그래서 더더욱 첫 템플릿은 짧고 실행 가능해야 한다.

Kiro의 Specs 문서가 requirements.md, design.md, tasks.md 세 장 구조를 잡는 이유도 여기에 있다. 너무 거창한 프로세스부터 넣으면 팀이 도망간다. 반대로 세 장만 있으면, 구현 전 사람 검토와 구현 후 리뷰의 기준점을 꽤 빠르게 만들 수 있다.

오늘 당장 써도 되는 최소 구조

내 추천은 이거다.

  1. requirements.md
  2. design.md
  3. tasks.md

여기까지만 먼저 만든다. 회의록, ADR, 회고, 리스크 레지스터 같은 건 나중 문제다. 처음부터 다 꺼내면 개발팀이 아니라 문서팀이 된다.

1. requirements.md 템플릿

가장 먼저 필요한 건 요구사항 문서다. 여기서는 구현 세부사항보다 무엇을 맞다고 볼지를 고정한다.

# Requirements

## 문제 정의
- 지금 무엇이 불편한가
- 누가 어떤 상황에서 막히는가

## 목표
- 이번 작업으로 해결할 핵심 1~3개

## 비목표
- 이번 v1에서 하지 않을 것 1~3개

## 사용자 시나리오
- 사용자 A는 ...
- 사용자 B는 ...

## Acceptance Criteria
- [ ] 사용자는 저장 후 새로고침해도 상태를 유지할 수 있어야 한다
- [ ] 관리자 권한 없는 사용자는 설정 API를 호출할 수 없어야 한다
- [ ] 에러 발생 시 재시도 방법이 화면에 보여야 한다

## 실패 흐름
- 인증 실패 시 어떻게 보이는가
- 네트워크 실패 시 어떻게 보이는가

requirements에서 제일 중요한 4줄

  • 목표
  • 비목표
  • acceptance criteria
  • 실패 흐름

이 네 개가 흐리면 아래 문서는 다 흔들린다.

2. design.md 템플릿

design은 예쁜 설계도가 아니라, 요구사항을 어떤 구조로 만족할지 보여주는 문서다.

# Design

## 개요
- 요구사항을 어떤 구조로 풀지 한 문단 요약

## 주요 컴포넌트
- API
- UI
- 저장소/DB
- 외부 연동

## 데이터 흐름
1. 사용자가 입력
2. 서버 검증
3. 저장
4. 응답 반환

## 인터페이스 계약
- 엔드포인트
- 입력 필드
- 출력 필드
- 실패 시 응답

## 리스크
- 성능
- 권한
- 롤백

design에서 길게 쓰지 말아야 할 것

  • 모든 클래스 설명
  • 미래에 할 수도 있는 확장안
  • 구현 전에 꼭 필요하지 않은 최적화

design은 구현을 시작하게 만드는 문서지, 건축 잡지 화보가 아니다.

3. tasks.md 템플릿

tasks는 TODO 목록이 아니라, acceptance criteria를 누가 어떤 순서로 닫을지 적는 문서다.

# Tasks

## 순서
1. API 기본 경로 추가
2. 권한 검증 구현
3. 저장 로직 연결
4. UI 에러 메시지 추가
5. 테스트 작성

## 각 태스크 완료 기준
- Task 1: 기본 요청/응답이 동작해야 한다
- Task 2: 권한 없는 사용자는 403을 받아야 한다
- Task 3: 저장 후 새로고침 시 데이터가 유지돼야 한다
- Task 4: 실패 시 사용자에게 재시도 문구가 보여야 한다
- Task 5: 핵심 플로우 테스트가 통과해야 한다

## 테스트 포인트
- 정상 저장
- 권한 오류
- 네트워크 실패

tasks에서 꼭 해야 하는 연결

이건 진짜 중요하다.

  • requirements의 acceptance criteria
  • design의 구조
  • tasks의 완료 기준

이 셋이 연결돼야 한다. 안 그러면 tasks는 그냥 “열심히 할 일 목록”이 되어버린다.

15분 안에 만드는 실전 프롬프트

이제 진짜 실전이다. 아래 프롬프트는 Claude Code, Codex, Copilot 계열 앞단에서 다 비슷하게 쓸 수 있는 구조다.

프롬프트 1: requirements.md 초안 만들기

아래 기능 아이디어를 requirements.md로 정리해줘.

반드시 포함:
1. 문제 정의
2. 목표 3개 이하
3. 비목표 3개 이하
4. 사용자 시나리오 2개
5. acceptance criteria 5개 이하
6. 실패 흐름 2개

조건:
- 추상적인 문장 대신 테스트 가능한 문장으로 쓸 것
- "좋아야 한다", "개선돼야 한다" 같은 표현 금지
- 지금 당장 구현에 필요한 범위만 적을 것

기능 아이디어:
{여기에 기능 설명}

프롬프트 2: design.md 만들기

아래 requirements.md를 바탕으로 design.md를 작성해줘.

반드시 포함:
1. 개요
2. 주요 컴포넌트
3. 데이터 흐름
4. 인터페이스 계약
5. 리스크

조건:
- 새로운 범위를 발명하지 말 것
- acceptance criteria를 충족하는 데 직접 필요한 구조만 설명할 것
- 700자 안팎으로 압축할 것

requirements:
{여기에 requirements.md}

프롬프트 3: tasks.md 만들기

아래 requirements.md와 design.md를 바탕으로 tasks.md를 작성해줘.

반드시 포함:
1. 구현 순서
2. 각 태스크 완료 기준
3. 테스트 포인트

조건:
- 각 태스크는 acceptance criteria와 직접 연결할 것
- 완료 기준은 한 줄로 쓸 것
- 불필요한 보조 파일 추가는 피할 것

requirements:
{requirements.md}

design:
{design.md}

사람 리뷰어가 보는 순서도 같이 정하자

Spec Review를 도입해놓고도 리뷰 순서가 없으면 다시 흐려진다. 나는 아래 순서가 제일 실전적이라고 본다.

  1. 비목표가 선명한가
  2. acceptance criteria가 테스트 가능한가
  3. 실패 흐름이 빠져 있지 않은가
  4. design이 requirements 범위를 넘기지 않는가
  5. tasks가 acceptance criteria를 직접 닫는가

이 순서로 보면 리뷰어가 덜 헤맨다. 이게 없으면 또 코멘트가 취향싸움으로 내려간다.

바로 복붙 가능한 리뷰 체크리스트

# Spec Review Checklist

- [ ] 문제 정의가 한 문장으로 설명된다
- [ ] 목표보다 비목표가 더 모호하지 않다
- [ ] acceptance criteria가 테스트 가능한 문장이다
- [ ] 실패 흐름이 최소 1개 이상 있다
- [ ] design이 새 범위를 발명하지 않는다
- [ ] tasks 완료 기준이 acceptance criteria와 연결된다
- [ ] 구현 전 사람이 승인할 지점이 있다

이 정도만 있어도 리뷰의 질이 꽤 달라진다.

언제는 이 템플릿을 안 써도 된다

모든 작업에 스펙 3장을 붙일 필요는 없다. 괜히 그랬다간 팀이 문서 늪에 빠진다.

아래는 그냥 코드 리뷰 중심으로 가도 된다.

  • CSS 한 줄 수정
  • 로그 문구 변경
  • 범위가 너무 명확한 단순 버그 수정
  • 이미 같은 패턴으로 여러 번 반복한 작업

반대로 이 템플릿이 빛나는 건 이런 경우다.

  • 여러 파일이 한 번에 바뀌는 기능
  • PM/디자인/개발 해석이 갈릴 수 있는 작업
  • 실패 흐름이 중요한 기능
  • “이번에 안 할 것”을 꼭 박아야 하는 작업

한마디로 구현 난이도보다 해석 난이도가 높으면 템플릿 가치가 커진다.

우리 로컬 규칙에 붙이면 더 잘 맞는 이유

이건 그냥 바깥 얘기만 하는 게 아니다. 우리 로컬 에이전트 문서에도 이미 같은 감각이 들어가 있다.

prototype-architect.md는 from-sdd 모드에서 acceptance criteria를 완료 기준, 테스트 포인트, 실패 흐름에 직접 연결하라고 적어둔다.

prototype-reviewer.md는 설계-구현 정합성, 인터페이스, 보안, 실행 가능성을 순서대로 보게 만든다.

즉 바깥 제품 문서와 우리 로컬 운영 감각이 이미 같은 방향을 보고 있다. 그래서 이 템플릿은 뜬구름이 아니라 바로 우리 작업 방식에 붙일 수 있다.

실수 TOP 5

1. 템플릿부터 거창하게 만드는 실수

처음엔 세 장이면 충분하다. ADR, 리스크 레지스터, 회고 양식까지 한 번에 꺼내면 다 도망간다.

2. acceptance criteria를 추상적으로 쓰는 실수

“좋아야 한다”, “안정적이어야 한다”는 감상이지 기준이 아니다.

3. design에서 새 범위를 발명하는 실수

설계 문서가 갑자기 기획 문서가 되면 안 된다.

4. tasks를 그냥 할 일 목록으로 쓰는 실수

acceptance criteria와 연결되지 않으면 진짜 쉽게 흐려진다.

5. 사람 승인 지점을 안 넣는 실수

Spec Review의 핵심은 문서가 아니라 human gate다.

FAQ

Q1. 이 템플릿은 Kiro 전용인가요?

아니다. Kiro docs의 구조에서 힌트를 받았지만, markdown 세 장 구조 자체는 Claude Code, Codex, Copilot 앞단 어디에 붙여도 쓸 수 있다.

Q2. requirements, design, tasks를 꼭 따로 나눠야 하나요?

초기엔 한 파일로 시작해도 된다. 다만 팀이 여러 명이거나 작업이 커지면 분리하는 쪽이 훨씬 덜 꼬인다.

Q3. 15분 안에 진짜 가능한가요?

가능하다. 단 완성 문서를 만들겠다는 욕심을 버리고, 사람 검토 가능한 초안을 만든다는 목표로 접근해야 한다.

Q4. 이 템플릿만 있으면 코드 리뷰는 줄어드나요?

코드 리뷰가 사라지진 않는다. 대신 어디를 먼저 볼지가 훨씬 선명해진다.

Q5. 한 줄 결론은 뭔가요?

Spec Review는 철학보다 템플릿이 먼저다. 세 장만 제대로 만들면 팀 리뷰 위치가 진짜로 올라간다.

다음에 읽을 글

출처

결국 이 글의 포인트는 “스펙 문화 멋있다”가 아니다. 팀이 덜 싸우고, 덜 헤매고, AI가 만든 코드 위에서 덜 피곤해지려면 사람이 먼저 볼 문서를 얇고 선명하게 만들어야 한다는 거다. 세 장이면 된다. 너무 많이 꺼내면 멋은 있는데 아무도 안 쓴다. 그건 템플릿이 아니라 박물관이다.