변경 사항 검토

OpenSpec이 약속하는 핵심은 코드 작성 전에 사용자와 AI가 무엇을 만들지 합의하는 것입니다. AI가 작성한 초안을 실제로 읽어야 그 합의가 의미를 가집니다. 이 페이지에서는 2분 동안 무엇을 어떤 순서로 열어 보고 무엇을 살펴야 하는지 설명합니다.

원리는 간단합니다. 한 문단짜리 계획에서 잘못된 방향을 발견하는 데는 거의 비용이 들지 않지만, 코드 300줄을 작성한 뒤 같은 문제를 찾는 데는 그렇지 않습니다. 검토를 통해 이 원칙의 효과를 얻을 수 있습니다.

검토 시점 두 가지

검토는 정확히 두 번 진행합니다.

/opsx:propose ──► REVIEW THE PLAN ──► /opsx:apply ──► REVIEW THE CODE ──► /opsx:archive
                  (before any code)                    (/opsx:verify)

1. /opsx:propose(또는 /opsx:ff) 실행 후, /opsx:apply 전에 — 아직 글로만 작성된 계획을 읽습니다.
2. 구현 후 /opsx:verify로 — 코드가 계획에 적힌 내용을 실제로 구현했는지 확인합니다.

첫 번째 검토가 가장 큰 비용을 절약해 주지만 많은 사람이 건너뜁니다. 이 페이지에서는 첫 번째 검토를 주로 다룹니다.

다음 순서로 읽기

변경 사항은 openspec/changes/<name>/ 아래의 일반 Markdown 파일로 구성된 폴더입니다. 문제가 있을 때 가장 빨리 멈출 수 있도록 다음 순서로 읽으세요.

openspec/changes/add-dark-mode/
├── proposal.md      1. the intent and scope   ← if this is wrong, stop here
├── specs/…/spec.md  2. the requirements       ← the heart of the review
├── design.md        (only for bigger changes) — the technical approach
└── tasks.md         3. the plan of work

모든 줄을 읽을 필요는 없습니다. 각 파일에 대해 세 가지 질문에 답하면 됩니다.

제안: 올바른 문제를 다루나요?

먼저 proposal.md를 여세요. 한두 문단으로 “이유”와 “내용”, 즉 의도와 범위 및 접근 방식을 설명합니다.

좋은 제안의 조건: 명확한 의도 하나, 익숙한 범위, 지금 이 작업을 해야 하는 이유가 드러나야 합니다.

주의 신호:

• 요청한 것과 약간 다른 문제를 해결합니다.
• 범위가 커졌습니다. 테마 전환을 요청했는데 제안이 “이왕 하는 김에” 인증까지 다룹니다.
• 내용이 모호합니다. “설정 페이지 개선”은 범위가 아닙니다. “OS 설정을 따르는 다크 모드 전환 추가”처럼 작성해야 합니다.

답해야 할 질문: 실제로 요청한 내용과 일치하며, 몰래 추가된 범위는 없나요? 아니라면 여기서 멈추세요. 더 읽지 말고 제안을 수정하세요(수정 요청은 간단합니다 참조).

사양 델타: “완료”가 올바르게 정의되어 있나요?

검토의 핵심입니다. specs/ 아래의 델타 사양은 변경 사항을 배포했을 때 실제로 이루어질 내용을 요구 사항과 이를 입증하는 시나리오로 설명합니다.

## ADDED Requirements

### Requirement: Dark Mode Toggle
The system SHALL let a user switch between light and dark themes.

#### Scenario: Respects the OS preference on first load
- GIVEN a user who has never set a theme
- WHEN they open the app on a device set to dark mode
- THEN the app renders in dark mode

좋은 요구 사항의 조건: 테스터에게 전달할 수 있는 명확한 SHALL/MUST 진술 하나와, 해당 진술을 실제로 검증하는 GIVEN/WHEN/THEN 시나리오가 하나 이상 있어야 합니다.

주의 신호:

• 모호한 요구 사항. “시스템은 빨라야 한다(SHALL)“는 구현하거나 테스트할 수 없습니다. 어느 정도로 빨라야 하나요?
• 시나리오가 없는 요구 사항 또는 해당 요구 사항을 검증하지 않는 시나리오
• 가장 중요한 발견: 빠진 내용. AI는 사용자가 말한 내용을 그대로 기록합니다. 사용자의 역할은 말하지 않은 내용을 발견하는 것입니다. OS 설정 사례가 가장 중요하다고 생각했는데 이를 다루는 시나리오가 없다면, 검토가 제 역할을 한 것입니다.

델타를 읽으며 *시스템이 정확히 이것만 수행한다면 만족할까?*라고 자문하세요. 아직 코드가 없으므로 내용을 바꾸는 비용이 적습니다.

작업 목록: 작업 계획이 합리적인가요?

마지막으로 tasks.md를 여세요. AI가 따라갈 구현 체크리스트입니다.

좋은 작업 목록의 조건: 순서가 있고 각 단계가 요구 사항과 연결되며 불분명한 작업이 없어야 합니다.

주의 신호:

• 관련 요구 사항이 없는 작업(이 작업은 어디서 나온 건가요?)
• 실제 결정을 모두 감추는 하나의 거대한 “기능 구현” 작업
• 방금 승인한 범위 밖의 내용을 다루는 작업

이 단계에서 일정을 추정하거나 세세하게 관리할 필요는 없습니다. 계획이 이미 승인한 요구 사항과 일치하는지만 확인하세요.

수정 요청은 간단합니다

세 질문 중 어느 하나라도 답이 만족스럽지 않다면 의견을 말하세요. 단계가 고정되어 있지 않으므로 수정하고 계속 진행하면 됩니다. 변경 사항 편집에서 설명한 것처럼 두 가지 방법이 있습니다.

• 직접 파일을 편집합니다. 일반 Markdown 파일이므로 범위 문장을 바꾸고 요구 사항을 구체화하거나 작업을 삭제하면 됩니다.
• AI에게 문제를 알려 수정하게 합니다. “인증 변경은 범위 밖이니 삭제해 줘”, “사용자가 이미 테마를 선택한 경우의 시나리오를 추가해 줘”, *“작업 3을 스키마와 UI로 나눠 줘”*라고 요청하세요.

그런 다음 수정한 부분을 다시 읽으세요. 직접 이름을 걸고 승인할 수 있는 계획이 될 때까지 초안을 다듬습니다. 이런 반복 과정이 바로 제품이 작동하는 방식입니다.

코드 작성 후 검증하기

구현이 끝나면 /opsx:verify로 두 번째 검토를 진행합니다. 산출물과 코드를 다시 읽고 다음 세 가지 측면에서 불일치를 보고합니다.

측면	확인하는 내용
완전성	모든 작업 완료, 모든 요구 사항 구현, 시나리오 적용
정확성	구현이 사양의 의도와 일치하고 경계 사례를 처리하는지 여부
일관성	설계 결정이 실제 코드에 반영되었는지 여부

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Respects the OS preference on first load" has no test coverage

문제를 CRITICAL, WARNING 또는 SUGGESTION으로 표시하며 보관을 차단하지는 않습니다. 격차를 알려 주고 판단은 사용자에게 맡깁니다. 이를 통해 “AI가 코드를 작성했나?“와 “합의한 내용을 구현했나?“를 구분할 수 있습니다.

/opsx:verify는 확장 프로필에 포함되어 있습니다. 사용할 수 없다면 openspec config profile로 활성화한 뒤 openspec update를 실행하거나 변경 사항과 diff를 직접 다시 확인하세요.

검토 규모 조정하기

모든 변경 사항에 전체 검토를 진행할 필요는 없습니다. 파일 하나의 오타 수정은 20초 동안 훑어보면 됩니다. 인증, 결제 또는 복구할 수 없는 데이터를 건드리는 변경 사항에는 위 질문을 모두 확인해야 합니다. 절차를 위한 절차가 아니라 실수가 큰 비용을 초래하는 곳에 주의를 기울이고 그렇지 않은 곳은 빠르게 훑는 것이 목적입니다.

2분 체크리스트

• 제안의 의도가 요청한 내용과 일치합니다.
• 범위에 불필요한 내용이 추가되지 않았습니다.
• 모든 요구 사항이 테스트하기에 충분히 구체적입니다.
• 모든 요구 사항에 해당 내용을 실제로 검증하는 시나리오가 있습니다.
• 가장 중요하게 생각하는 사례가 다뤄집니다.
• 작업이 요구 사항과 연결되며 불분명하거나 범위 밖인 항목이 없습니다.
• AI가 정확히 이 내용만 구현해도 괜찮습니다.

일곱 항목을 모두 통과하면 안심하고 /opsx:apply를 실행하세요. 통과하지 못한 항목이 있어도 실패가 아닙니다. 검토가 제 역할을 한 것입니다.

다음 단계

• 좋은 사양 작성하기 — 승인할 만한 요구 사항과 시나리오 작성 방법
• 변경 사항 편집 및 반복 개선 — 시작 후 계획을 수정하는 방법
• 워크플로 — 전체 흐름에서 검토가 들어가는 위치