변경 사항 검토하기

OpenSpec의 핵심 약속은 여러분과 AI가 코드를 작성하기 전에 무엇을 만들 것인지 합의하는 것입니다. 이 합의는 AI가 작성한 초안을 실제로 읽지 않으면 아무런 의미가 없습니다. 이 페이지는 그 두 분의 검토 시간에 대한 것입니다 — 무엇을 열고, 어떤 순서로 읽고, 무엇을 확인해야 하는지 설명합니다.

이 내기는 간단합니다: 한 단락의 계획에서 잘못된 방향 전환을 미리 잡아내는 것은 거의 비용이 들지 않지만, 300줄의 코드에서 같은 잘못된 방향 전환을 잡아내는 것은 그렇지 않습니다. 검토가 바로 그 내기의 성과를 거두는 순간입니다.

검토해야 하는 두 가지 시점

정확히 두 가지가 있습니다:

/opsx:propose ──► **계획 검토** ──► /opsx:apply ──► **코드 검토** ──► /opsx:archive
                  (코드 작성 전)                    (/opsx:verify)

1. /opsx:propose(또는 /opsx:ff) 실행 후, /opsx:apply 실행 전 — 계획이 아직 글로만 적혀있을 때 읽으세요.
2. 빌드 완료 후, /opsx:verify로 — 코드가 실제로 계획한 내용대로 구현되었는지 확인하세요.

첫 번째 검토가 가장 많은 시간을 절약해주지만, 대부분의 사람들이 건너뛰는 부분입니다. 이 페이지는 대부분 이 첫 번째 검토에 대해 설명합니다.

이 순서대로 읽으세요

변경 사항은 openspec/changes/<name>/ 경로에 있는 일반 마크다운 파일이 모인 폴더입니다. 문제가 있을 경우 가장 빨리 검토를 중단할 수 있는 순서대로 파일을 읽으세요:

openspec/changes/add-dark-mode/
├── proposal.md      1. 의도와 범위 ← 여기가 잘못되었다면 여기서 중단하세요
├── specs/…/spec.md  2. 요구사항 ← 검토의 핵심 부분입니다
├── design.md        (대규모 변경의 경우에만) 기술적 접근 방식
└── tasks.md         3. 작업 계획

모든 줄을 읽을 필요는 없습니다. 각 파일마다 하나씩, 총 세 가지 질문에 답하면 됩니다.

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

먼저 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 시나리오가 최소 하나 이상 포함되어 있습니다.

경고 신호:

• 모호한 요구사항. "The system SHALL be fast"는 구축하거나 테스트할 수 없습니다. 무엇이 빠르다는 의미인가요?
• 시나리오가 없는 요구사항, 또는 해당 요구사항을 검증하지 않는 시나리오입니다.
• 가장 중요한 포인트: 누락된 내용을 찾아내는 것입니다. AI는 여러분이 말한 내용을 충실히 기록합니다. 여러분의 역할은 잊고 말한 내용을 찾아내는 것입니다. 만약 OS 설정 존중 기능이 가장 중요하다고 생각했는데 관련 시나리오가 없다면, 그것이 바로 검토가 본전을 찾는 순간입니다.

델타 명세를 읽을 때 시스템이 오직 이 내용만 정확히 동작한다면 만족할 수 있을까? 라고 질문하세요. 아직 코드와 관련된 내용이 없으므로 수정 비용이 매우 적습니다.

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

마지막으로 tasks.md를 여세요. 이 파일은 AI가 따라 진행할 구현 체크리스트입니다.

올바른 작업 목록의 특징: 단계가 순서대로 정리되어 있고, 각 작업이 특정 요구사항과 대응되며, 불분명한 내용이 없습니다.

경고 신호:

• 이에 대응하는 요구사항이 없는 작업입니다 (어디서 나온 작업인가요?).
• 모든 실제 결정을 숨기는 하나의 거대한 "기능 구현" 작업입니다.
• 방금 승인한 범위에 속하지 않는 내용을 다루는 작업입니다.

여기서는 작업 소요 시간을 추정하거나 세부적으로 간섭할 필요가 없습니다 — 계획이 여러분이 이미 승인한 요구사항과 일치하는지만 확인하면 됩니다.

이의를 제기하는 것은 비용이 적게 듭니다

만약 세 가지 질문 중 어느 하나라도 부정적인 답이 나왔다면, 그렇게 말하세요. 단계가 고정되어 있지도 않고 잠긴 내용도 없습니다 — 수정한 후 바로 다음 단계로 넘어가면 됩니다. 수정 방법은 변경 사항 편집하기에 나와있는 것과 정확히 두 가지가 있습니다:

• 직접 파일을 편집하세요. 일반 마크다운 파일이므로 범위 줄을 수정하거나, 요구사항을 구체화하거나, 작업을 삭제할 수 있습니다.
• 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를 실행하세요. 어느 하나라도 통과하지 못했다면 그것은 실패가 아니라, 2분 검토가 제 역할을 하는 것입니다.

추가로 확인할 내용

• 좋은 명세 작성하기 — 검토할 가치가 있는 요구사항과 시나리오를 작성하는 방법을 설명합니다.
• 변경 사항 편집 및 반복하기 — 작업을 시작한 후 계획을 수정하는 방법을 설명합니다.
• 워크플로우 — 검토가 전체 워크플로우에서 차지하는 위치를 설명합니다.