수동 요구사항을 Spec 문서로 자동화하기 | Spec 작성

Overview

시나리오, 성공 기준, 범위를 수동으로 챙기는 방식은 기능이 커질수록 놓치는 것이 생깁니다. /writing-spec 스킬은 이 수동 과정을 4단계로 자동화합니다.

이번 레슨에서는 칸반 보드 예시로 각 단계를 확인합니다.

학습 목표

• /writing-spec 스킬의 4단계 워크플로우를 이해합니다
• 수동 요구사항에 없던 구성요소(전제 조건, 미결정 사항)의 역할을 설명할 수 있습니다
• Spec 검토 기준을 적용하여 생성된 문서를 평가할 수 있습니다

Step 1: 질문으로 빈칸 채우기

artifacts/example/requirements.md의 5줄짜리 요구사항을 /writing-spec의 입력으로 사용합니다.

/writing-spec @artifacts/example/requirements.md

AI는 한 번에 문서를 생성하지 않습니다. 사용자 흐름을 시뮬레이션하고, 변경 비용이 높은 결정부터 질문합니다.

"컬럼은 3개(Todo, In Progress, Done)로 고정하시나요, 아니면 사용자가 컬럼을 추가/삭제할 수 있게 하시나요?"

"카드에 표시할 정보는 제목만인가요? 설명, 라벨, 마감일도 포함하나요?"

나중에 바꾸기 어려운 결정(데이터 구조, 핵심 기능 범위)은 질문하고, 비용이 낮은 결정(버튼 위치, 색상)은 기본값을 제안합니다. 충분히 대화한 뒤 "됐어"라고 하면 다음 단계로 넘어갑니다.

Step 2: Spec 문서 생성

AI가 대화 내용을 바탕으로 구조화된 Spec 문서를 생성합니다. 시나리오, 성공 기준, 범위는 자동으로 구성됩니다. 완성된 문서는 artifacts/kanban/spec.md에 저장됩니다.

수동 요구사항에는 없던 두 가지 구성요소가 추가됩니다.

전제 조건은 확정된 가정입니다. "데이터는 localStorage에 저장한다"처럼, 이 기능이 동작하기 위해 참이어야 하는 조건입니다.

미결정 사항은 아직 결정하지 못한 항목입니다. "컬럼 개수를 3개로 고정할지 사용자가 추가할 수 있게 할지 미정"처럼, 답이 필요하지만 아직 정하지 못한 것입니다.

확정된 것과 미정인 것이 분리되면, AI가 미정인 것을 확정된 것으로 착각하고 추측하는 일이 줄어듭니다. 수동으로 작성할 때는 둘 다 "그냥 안 적는" 것으로 처리됩니다.

Spec 문서의 두 가지 원칙

제외 항목에는 반드시 제외 이유를 적습니다. 이유가 없으면 의도적인 결정인지 깜빡한 것인지 구분할 수 없습니다.

• 제외: 다중 보드 -- 1차에서는 단일 보드만 지원. 다중 보드는 2차에서 추가 예정

구현 방법은 Spec에 쓰지 않습니다. "어떤 라이브러리로", "어떤 아키텍처로" 같은 결정은 Plan 단계에서 합니다. Spec에 넣으면 요구사항이 특정 기술에 묶입니다.

Step 3: spec.yaml 추출

AI가 Spec 문서의 성공 기준을 기계가 읽을 수 있는 spec.yaml로 변환합니다. 이 파일이 나중에 테스트 코드(Spec Test)의 입력이 됩니다.

성공 기준 "'Todo' 컬럼의 카드를 'In Progress'로 드래그하면 카드가 이동한다"는 다음 테스트가 됩니다.

test("카드를 다른 컬럼으로 드래그하면 이동한다", async () => {
  await dragCard("Buy groceries", "Todo", "In Progress");
  expect(getColumnCards("In Progress")).toContain("Buy groceries");
});

성공 기준이 구체적일수록, AI가 생성하는 테스트도 정확해집니다. /writing-plan 스킬은 spec.yaml을 읽고 Spec Test를 첫 번째 Task로 자동 배치합니다. Spec Test의 상세(불변 계약, 구현 테스트와의 차이)는 Lesson 05에서 다룹니다.

Step 4: 독립 리뷰

AI가 생성한 Spec을 spec-reviewer 에이전트가 독립적으로 검토합니다. 누락된 시나리오가 있으면 사용자에게 보여주고, 사용자가 포함 여부를 결정합니다.

에이전트 리뷰와 별개로, 사용자도 세 가지 기준으로 검토합니다.

1. 모든 시나리오가 [상황]/[동작] 구조인가? "칸반 보드를 지원해야 한다"처럼 구조가 빠진 항목이 있으면 다듬습니다
2. 성공 기준에 구체적 입력과 출력이 있는가? "드래그 앤 드롭이 잘 동작해야 한다"는 AI가 테스트로 변환할 수 없습니다
3. 미결정 사항에 결정이 필요한 항목이 나열되어 있는가? AI가 추측으로 채운 부분이 미결정 사항 대신 전제 조건에 들어가 있을 수 있습니다

핵심 포인트 정리

1. 4단계 자동화: 질문 -> 문서 생성 -> spec.yaml 추출 -> 독립 리뷰. 각 단계의 산출물이 다음 단계의 입력이 됩니다
2. 확정과 미정의 분리: 전제 조건과 미결정 사항을 명시적으로 나누어, AI가 미정인 것을 추측으로 채우는 일을 방지합니다

이어서 배울 내용

요구사항을 Spec 문서로 정리했습니다. 다음 레슨에서는 Spec만으로는 결정할 수 없는 화면 구조를 Wireframe으로 정의합니다.