좋은 사양 작성하기

빈 페이지에서 사양을 작성하는 경우는 드뭅니다. 일반 언어로 변경 사항을 설명하면 /opsx:propose가 요구 사항과 시나리오 초안을 작성하고, 여러분은 이를 다듬습니다. 이 페이지에서는 마지막 단계, 즉 “좋은 사양”이란 무엇인지, AI가 그런 사양을 작성하도록 유도하는 방법을 설명합니다.

이 문서는 변경 사항 검토의 보충 안내서입니다. 검토는 초안의 약점을 찾아내는 일이고, 작성은 좋은 사양을 구성하는 요소를 이해하는 일입니다.

사양은 코드가 아니라 동작입니다

사양은 시스템이 무엇을 하는지 누구나 확인할 수 있는 방식으로 설명하며 구현 방법은 다루지 않습니다. 요구 사항(동작에 대한 진술)과 이를 입증하는 구체적인 예제인 시나리오로 구성됩니다.

### 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

큐, 라이브러리, 테이블 스키마와 같은 구현 방법은 design.md 또는 코드에 작성하세요. 동작과 구현 방식을 하나의 요구 사항에 섞으면 요구 사항을 테스트할 수 없게 되고 코드가 바뀌는 순간 오래된 내용이 됩니다.

좋은 요구 사항의 조건

좋은 요구 사항은 하나의 동작을 명시하며, 다른 사람에게 전달해도 바로 테스트할 수 있을 만큼 명확하게 작성됩니다.

• 진술 하나에 SHALL/MUST 하나를 사용합니다. 요구 사항에 “또한”이라는 절이 세 개 있다면 실제로는 요구 사항 세 개입니다. 분리하세요.

• 관찰 가능해야 합니다. 코드를 직접 보지 않는 사람도 요구 사항이 충족됐는지 알 수 있어야 합니다. “업로드 용량이 10MB를 초과하면 시스템은 오류 배너를 표시해야 한다(SHALL)“는 관찰 가능합니다. “시스템은 대용량 업로드를 원활하게 처리해야 한다(SHALL)“는 그렇지 않습니다.

• 적절한 강도를 사용합니다. OpenSpec은 RFC 2119 키워드를 사용하며, 각각 의미가 다릅니다.

  키워드	의미
  MUST / SHALL	반드시 지켜야 하는 요구 사항입니다. 예외가 없습니다.
  SHOULD	정당한 예외를 허용하는 강력한 권장 사항입니다.
  MAY	선택 사항입니다.

  기본적으로 MUST/SHALL을 사용하세요. “하지 않을 타당한 이유가 없다면 해야 한다”는 뜻일 때만 SHOULD를 사용하세요.

요구 사항 검증 기준은 다음과 같습니다. 코드를 한 번도 본 적 없는 테스터가 요구 사항 통과 여부를 판단할 수 있나요? 그렇지 않다면 더 명확하게 다듬어야 합니다.

좋은 시나리오의 조건

시나리오는 요구 사항이 실제로 유용한지 보여 줍니다. 각각은 자동화 테스트로 만들 수 있는 구체적인 GIVEN / WHEN / THEN입니다.

• 요구 사항을 실제로 시험해야 합니다. 요구 사항을 다른 말로 반복하는 시나리오는 아무것도 테스트하지 않습니다. 구체적인 상황과 결과를 작성하세요.
• 정상적인 흐름뿐 아니라 중요한 경우를 다룹니다. 정상 로그인은 쉽습니다. 빈 입력, 만료된 토큰, 두 번째 클릭, 오류 상황 등은 버그가 발생하기 쉬워 시나리오가 특히 유용한 영역입니다.
• 제목에 상황을 명시합니다. “시나리오: 만료된 토큰 거부”는 검토자가 무엇을 다루는지 바로 알려 주지만 “시나리오: 테스트 2”는 그렇지 않습니다.

유용한 습관은 승인 전에 *어떤 한 가지 경우가 제대로 작동하지 않으면 가장 속상할까?*라고 자문하고, 그 사례가 시나리오에 포함됐는지 확인하는 것입니다.

올바른 종류의 델타 선택하기

변경 사항은 세 가지 섹션 유형을 사용해 사양 수정 내용을 설명합니다. 올바른 유형을 사용하면 보관 후에도 사양의 정확성을 유지할 수 있습니다.

• ## ADDED Requirements — 이전에 없던 새로운 동작입니다.
• ## MODIFIED Requirements — 기존 동작이 변경됩니다. 변경된 전체 내용을 작성하세요. 변경 사항에 대한 짧은 설명을 덧붙이면 검토에 도움이 됩니다.
• ## REMOVED Requirements — 제거되는 동작과 제거 이유를 한 줄로 설명합니다.

보관할 때 ADDED 내용은 기본 사양에 추가되고, MODIFIED 내용은 이전 내용을 대체하며, REMOVED 내용은 삭제됩니다. 기능의 마지막 요구 사항을 제거하면 해당 기능을 폐기하는 것입니다. 내용이 없는 사양을 남기는 대신 보관 과정에서 openspec/specs/<capability>/spec.md를 삭제합니다. 파일을 삭제하는 유일한 보관 단계이므로 명시적 승인이 필요합니다. 해당 파일에 필요한 schema:와 함께 변경 사항의 .openspec.yaml에 retire_capabilities: true를 추가하세요. 이 설정이 없으면 보관이 중단되고 안내가 표시됩니다. 폐기 시 파일 전체가 삭제되므로 사양에 제목, ## Purpose, 요구 사항 블록 이외의 내용(예: ## Notes 섹션이나 요구 사항 아래 주석)이 있으면 진행하지 않습니다. 중단 안내에 해당 줄이 표시됩니다. 이를 ## Purpose나 요구 사항에 넣거나 사양을 직접 삭제하세요. 호출자의 체크아웃에 있는 사양이라면 커밋된 파일을 복원하는 git checkout 명령도 출력됩니다. 선택된 store에서는 체크아웃 범위를 지정한 복구 안내를 제공합니다. 실제 변경을 ADDED로 표시하면 서로 경쟁하는 요구 사항이 두 개 생기고, 새로운 동작을 MODIFIED로 설명하면 대체할 항목이 없습니다. 확실하지 않다면 현재 사양을 열어 요구 사항이 이미 있는지 확인하세요.

알아둘 섹션이 하나 더 있습니다. 델타에서 아직 없는 기능을 만들 때는 ## Purpose로 시작해 해당 기능의 목적을 한두 문장으로 설명하세요. 보관 과정에서 이를 새 기본 사양의 Purpose로 사용합니다. 생략하면 직접 작성해야 하는 TBD 자리 표시자가 들어갑니다. 기존 사양에는 이미 Purpose가 있으므로 델타에 작성된 내용은 무시됩니다. 수정하려면 openspec/specs/<capability-path>/spec.md를 직접 편집하세요. 여기서 <capability-path>는 specs/ 기준 상대 디렉터리로, 단순한 프로젝트의 user-auth나 도메인별로 구성된 프로젝트의 identity/user-auth 등이 해당합니다.

변경 사항 규모 조정하기

가장 흔한 작성 실수는 요구 사항을 잘못 표현하는 것이 아니라, 변경 사항 하나에 세 가지 작업을 넣으려는 것입니다.

좋은 변경 사항은 한 문장으로 말할 수 있는 의도 하나를 가집니다. “다크 모드 전환을 추가한다.” “로그인 엔드포인트에 속도 제한을 적용한다.” “쿠키에서 세션을 마이그레이션한다.” 변경 사항을 설명할 때 “그리고 …도”가 많이 필요하다면 분리해야 한다는 신호입니다.

변경 사항의 규모가 너무 크다는 신호:

• 제안의 범위가 서로 관련 없는 기능의 목록처럼 보입니다.
• 검토에 반나절이 걸릴 것 같아 아무도 검토하지 않을 것입니다.
• 두 사람이 충돌 없이 함께 작업할 수 없습니다.
• 작업의 절반을 별도로 배포할 수 있습니다.

규모가 작은 변경 사항은 검토하기 쉽고 한 번에 집중해 구현하기 좋으며, 6개월 뒤 보관 기록만 남았을 때도 이해하기 쉽습니다. 언제든 여러 변경 사항을 병렬로 진행할 수 있습니다. 변경 사항 편집 및 반복 개선과 워크플로를 참조하세요.

반대의 경우도 있습니다. 한 줄짜리 오타 수정에는 요구 사항 세 개와 설계 문서가 필요하지 않습니다. 작업의 중요도에 맞춰 절차를 조정하세요.

AI가 좋은 초안을 작성하도록 유도하기

첫 초안은 /opsx:propose가 작성하므로 결과물의 품질은 입력 내용의 품질에 따라 달라집니다. 요구 사항을 직접 작성할 필요는 없지만 AI가 올바른 방향으로 작성하도록 해야 합니다.

• 의도와 경계를 분명히 설명합니다. “첫 로드 시 OS 설정을 따르는 다크 모드 전환을 추가하되 기존 테마 API는 수정하지 마.” 범위 안의 내용만큼 범위 밖의 내용도 중요합니다.
• 중요하게 생각하는 경우를 지정합니다. “사용자가 이미 테마를 직접 선택한 상황의 시나리오를 넣어 줘.” AI는 지정한 내용을 다룹니다.
• 그다음 편집합니다. 일반 Markdown이므로 모호한 SHALL을 명확하게 하거나, 아무것도 테스트하지 않는 시나리오를 삭제하거나, 빠진 사례를 추가하세요. 또는 AI에게 *“타임아웃 요구 사항이 모호하니 30분으로 명확히 해 줘”*라고 요청할 수도 있습니다.

초안을 작성하고 다듬기를 반복하세요. 몇 차례 수정하면 신뢰할 수 있는 사양이 완성됩니다. 이것이 핵심입니다.

간단한 체크리스트

• 각 요구 사항은 하나의 관찰 가능한 동작을 SHALL/MUST로 표현합니다.
• 요구 사항에 구현 세부 정보가 포함되지 않았습니다.
• 모든 요구 사항에는 해당 내용을 실제로 검증하는 시나리오가 하나 이상 있습니다.
• 정상 흐름뿐 아니라 중요한 경계 및 오류 상황도 시나리오로 다룹니다.
• 현재 사양에 맞춰 ADDED / MODIFIED / REMOVED 델타를 올바르게 사용합니다.
• 전체 변경 사항의 의도를 한 문장으로 설명할 수 있습니다.

다음 단계

• 변경 사항 검토 — 놓친 내용을 찾는 2분 점검
• 개념 — 사양, 변경 사항, 델타의 기본 개념
• 예제 및 레시피 — 실제 변경 사항의 처음부터 끝까지