가이드

좋은 스펙 작성

거의 빈 페이지에서 스펙을 작성하지 않습니다. 변경 사항을 일반 언어로 설명하고, /rasen:propose가 요구사항과 시나리오를 작성하고, 그 다음 그것을 좋게 만듭니다. 이 페이지는 마지막 부분에 관한 것입니다 — "좋음"이 무엇인지, 그리고 AI를 그쪽으로 어떻게 조종하는지.

이것은 Reviewing a Change의 동반자입니다: 검토는 초안의 약점을 포착하는 것이고, 작성은 강한 것이 무엇으로 만들어지는지를 아는 것입니다.

스펙은 코드가 아닌 동작

스펙은 시스템이 수행하는 것을 누구나 확인할 수 있는 조건으로 나타냅니다 — 어떻게 빌드되는지가 아니라. 요구사항(동작의 진술)과 시나리오(그들을 증명하는 구체적인 예)로 만들어집니다.

### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticate

how — 큐, 라이브러리, 테이블 스키마 — 는 design.md 또는 코드에 유지합니다. 동작과 구현이 하나의 요구사항으로 섞이면 요구사항은 테스트 가능하지 않게 되고 코드가 변경되는 순간 부실해지기 시작합니다.

좋은 요구사항이 되는 것

좋은 요구사항은 다른 누군가에게 테스트를 위해 건네줄 수 있을 정도로 명확하게 나타낸 하나의 동작입니다.

하나의 진술, 하나의 SHALL/MUST. 요구사항에 세 개의 "그리고 또한" 절이 있으면 실제로 세 개의 요구사항입니다. 나눕니다.
관찰 가능. 코드 외부의 누군가가 그것을 유지하는지 여부를 알 수 있어야 합니다. "시스템은 업로드가 10 MB를 초과할 때 오류 배너를 표시합니다"는 관찰 가능합니다. "시스템은 큰 업로드를 우아하게 처리합니다"는 아닙니다.
올바른 강도. Rasen은 RFC 2119 키워드를 사용하며 다른 의미를 나타냅니다:

키워드 의미

MUST / SHALL 어렵지 않은 요구사항입니다.

SHOULD 정당한 예외의 여지가 있는 강한 권장사항입니다.

MAY 진정으로 선택 사항입니다.

기본적으로 MUST/SHALL을 도달합니다. "정말로 그렇지 않을 이유가 있으면"을 의미할 때만 SHOULD를 사용합니다.

키워드	의미
`MUST` / `SHALL`	어렵지 않은 요구사항입니다.
`SHOULD`	정당한 예외의 여지가 있는 강한 권장사항입니다.
`MAY`	진정으로 선택 사항입니다.

요구사항의 테스트: 코드를 본 적이 없는 테스터가 합격했는지 여부를 알 수 있을까? 아니면 더 선명하게 필요합니다.

좋은 시나리오가 되는 것

시나리오는 요구사항이 가치를 얻는 곳입니다. 각각은 자동화된 테스트가 될 수 있는 구체적인 GIVEN / WHEN / THEN입니다.

요구사항을 실행합니다. 단순히 다른 말로 요구사항을 다시 진술하는 시나리오는 아무것도 테스트하지 않습니다. 구체적인 상황과 구체적인 결과를 만듭니다.
행복한 경로뿐 아니라 중요한 사례를 다룹니다. 유효한 로그인은 쉽습니다. 빈 입력, 만료된 토큰, 두 번째 클릭, 잘못된 것 — 그것들은 버그가 사는 곳이고 시나리오가 가장 가치 있는 곳입니다.
제목에 사례의 이름을 지정합니다. "시나리오: 만료된 토큰 거부"는 검토자에게 한눈에 다루는 내용을 알려줍니다; "시나리오: 테스트 2"는 아닙니다.

유용한 습관: 승인하기 전에 깨지는 것을 싫어하는 하나의 사례는 무엇입니까? — 그리고 시나리오가 그것을 명시하는지 확인합니다.

올바른 종류의 델타 선택

변경 사항은 세 가지 섹션 유형으로 스펙에 대한 편집을 설명합니다. 올바른 것을 사용하면 보관된 스펙이 정직해집니다:

## ADDED Requirements — 이전에 존재하지 않았던 진정한 새로운 동작.
## MODIFIED Requirements — 이미 존재했고 변경 중인 동작입니다. 전체 새 버전을 포함합니다; 변경된 내용에 대한 짧은 참고는 검토자를 도웁니다.
## REMOVED Requirements — 동작이 사라지고 이유에 대한 라인.

보관 시 ADDED는 메인 스펙에 추가되고, MODIFIED는 이전 버전을 바꾸고, REMOVED는 삭제됩니다. 실제 변경을 ADDED로 표시하면 두 개의 경쟁 요구사항으로 끝나게 됩니다; 새로운 동작을 MODIFIED로 설명하면 바꾸는 것이 없습니다. 확실하지 않으면 현재 스펙을 열고 요구사항이 이미 있는지 확인합니다.

변경 크기 조정

가장 일반적인 저작 실수는 잘못 표현된 요구사항이 아닙니다 — 세 개의 변경을 시도하는 변경입니다.

좋은 변경은 문장에서 말할 수 있는 하나의 의도를 가집니다. "어두운 모드 토글을 추가합니다." "로그인 끝점에 속도 제한을 적용합니다." "세션을 쿠키에서 마이그레이션합니다." 변경 사항을 설명하려면 많은 "그리고 또한"이 필요하다는 것이 분할 신호입니다.

변경이 너무 큰 신호:

제안서의 범위는 관련 없는 기능의 목록처럼 읽힙니다.
리뷰하는 데 오후가 걸릴 것이므로 아무도 그렇지 않습니다.
두 사람이 충돌하지 않고 그것을 할 수 없습니다.
절반의 작업은 자체적으로 배포할 수 있습니다.

더 작은 변경은 검토하기 더 쉽고, 한 번의 집중 세션에서 빌드하기 더 쉽고, 6개월 후 보관이 모든 것인 경우에 더 쉽게 추론할 수 있습니다. 항상 여러 변경을 병렬로 실행할 수 있습니다 — Editing & iterating 및 Workflows를 참고합니다.

반대도 발생합니다: 한 줄의 오타 수정은 세 개의 요구사항과 설계 문서가 필요하지 않습니다. 의식을 이해관계와 일치시킵니다.

AI를 좋은 초안으로 조종하는 방법

/rasen:propose가 초안을 작성하므로 다시 얻은 품질은 준 품질을 추적합니다. 요구사항을 직접 작성할 필요는 없습니다 — AI를 잘 조종해야 합니다:

의도와 경계를 나타냅니다. "OS 설정을 첫 로드에서 따르는 어두운 모드 토글을 추가합니다 — 기존 테마 API를 건드리지 마세요." 범위 외의 절반은 범위 내의 절반만큼 중요합니다.
신경 쓰는 사례의 이름을 지정합니다. "이미 수동으로 테마를 선택한 사용자의 시나리오가 있는지 확인합니다." AI는 당신이 지적한 내용을 다룹니다.
그 다음 편집합니다. 그것은 일반 마크다운입니다. 모호한 SHALL을 조입니다, 아무것도 테스트하지 않는 시나리오를 삭제합니다, 누락된 경우를 추가합니다 — 또는 AI에 물어봅니다: "타임아웃 요구사항이 모호하고 30분으로 고정합니다."

초안, 선명, 반복. 몇 번의 라운드가 신뢰할 수 있는 스펙을 생성하는데 그것이 전부입니다.

빠른 체크리스트

각 요구사항은 하나의 관찰 가능한 동작입니다 SHALL/MUST.
구현 세부 사항은 요구사항에 구워지지 않습니다.
모든 요구사항은 실제로 실행하는 최소 하나의 시나리오를 가집니다.
중요한 엣지 및 오류 사례는 시나리오를 가집니다, 행복한 경로뿐이 아닙니다.
델타는 현재 스펙에 대해 ADDED / MODIFIED / REMOVED를 올바르게 사용합니다.
전체 변경은 문장에서 명시할 수 있는 하나의 의도를 가집니다.

다음에 갈 곳

Reviewing a Change — 미끄러진 것을 포착하는 2분 통과.
Concepts — 스펙, 변경, 델타 뒤의 더 깊은 모델.
Examples & Recipes — 처음부터 끝까지의 실제 변경.