델타 명세서의 변경 사항을 메인 명세서에 동기화합니다.
이는 에이전트 주도 작업입니다. 델타 명세서를 읽고 메인 명세서를 직접 편집하여 변경 사항을 적용합니다. 이를 통해 전체 요구사항을 복사하지 않고 시나리오를 추가하는 등 지능적인 병합이 가능합니다.
저장소 선택: 사용자가 저장소(이 머신에 등록된 독립형 OpenSpec 저장소) 이름을 지정하거나 작업이 저장소 내에 있는 경우 openspec store list --json을 실행하여 등록된 저장소 ID를 확인한 후, 명세서와 변경 사항을 읽거나 쓰는 명령어(new change, status, instructions, list, show, validate, archive, doctor, context)에 --store <id> 플래그를 전달하세요. 다른 명령어는 이 플래그를 받지 않습니다. 명령어에서 출력하는 힌트에는 이미 플래그가 포함되어 있으므로 후속 작업에도 유지하세요. 저장소가 없으면 명령어는 가장 가까운 로컬 openspec/ 루트에서 작동합니다.
입력: 선택적으로 변경 이름을 지정합니다. 생략하면 대화 맥락에서 추론할 수 있는지 확인합니다. 모호하거나 명확하지 않은 경우 사용 가능한 변경 사항을 반드시 질문해야 합니다.
단계
-
변경 이름이 제공되지 않은 경우 선택 요청
openspec list --json을 실행하여 사용 가능한 변경 사항을 가져옵니다. AskUserQuestion 도구를 사용하여 사용자가 선택하도록 합니다.델타 명세서(
specs/디렉토리 아래)가 있는 변경 사항을 표시합니다.중요: 변경 사항을 추측하거나 자동 선택하지 마세요. 항상 사용자가 선택하도록 하세요.
-
변경 컨텍스트 확인
실행:
openspec status --change "<name>" --json -
델타 명세서 찾기
상태 JSON의
artifactPaths.specs.existingOutputPaths를 델타 명세서 파일 목록으로 사용합니다.각 델타 명세서 파일에는 다음과 같은 섹션이 있습니다:
## ADDED Requirements- 추가할 새 요구사항## MODIFIED Requirements- 기존 요구사항 변경## REMOVED Requirements- 제거할 요구사항## RENAMED Requirements- 이름을 변경할 요구사항 (FROM:/TO: 형식)
델타 명세서가 없으면 사용자에게 알리고 중지합니다.
-
각 델타 명세서에 대해 메인 명세서에 변경 사항 적용
CLI가 반환한 각 저장소-로컬 기능 델타 명세서 경로에 대해:
a. 델타 명세서를 읽어 의도된 변경 사항을 이해합니다.
b.
openspec/specs/<capability>/spec.md에 있는 메인 명세서를 읽습니다 (아직 없을 수 있음).c. 변경 사항을 지능적으로 적용합니다:
ADDED Requirements:
- 요구사항이 메인 명세서에 없으면 → 추가합니다.
- 요구사항이 이미 존재하면 → 일치하도록 업데이트합니다 (암시적 MODIFIED로 처리).
MODIFIED Requirements:
- 메인 명세서에서 요구사항을 찾습니다.
- 변경 사항을 적용합니다. 여기에는 다음이 포함될 수 있습니다:
- 새 시나리오 추가 (기존 시나리오를 복사할 필요 없음)
- 기존 시나리오 수정
- 요구사항 설명 변경
- 델타에 언급되지 않은 시나리오/내용은 그대로 보존합니다.
REMOVED Requirements:
- 메인 명세서에서 전체 요구사항 블록을 제거합니다.
RENAMED Requirements:
- FROM 요구사항을 찾아 TO로 이름을 변경합니다.
d. 메인 명세서가 없으면 새로 만듭니다:
openspec/specs/<capability>/spec.md를 생성합니다.- Purpose 섹션을 추가합니다 (간략히 작성하고 TBD로 표시).
- ADDED 요구사항으로 Requirements 섹션을 추가합니다.
-
요약 표시
모든 변경 사항을 적용한 후 다음을 요약합니다:
- 업데이트된 기능
- 수행된 변경 사항 (요구사항 추가/수정/제거/이름 변경)
델타 명세서 형식 참조
## ADDED Requirements
### Requirement: 새 기능
시스템은 새로운 작업을 수행해야 한다.
#### Scenario: 기본 사례
- **WHEN** 사용자가 X를 수행하면
- **THEN** 시스템이 Y를 수행한다.
## MODIFIED Requirements
### Requirement: 기존 기능
#### Scenario: 추가할 새 시나리오
- **WHEN** 사용자가 A를 수행하면
- **THEN** 시스템이 B를 수행한다.
## REMOVED Requirements
### Requirement: 더 이상 사용하지 않는 기능
## RENAMED Requirements
- FROM: `### Requirement: 이전 이름`
- TO: `### Requirement: 새 이름`
핵심 원칙: 지능적 병합
프로그램적 병합과 달리 부분 업데이트를 적용할 수 있습니다:
- 시나리오를 추가하려면 MODIFIED 아래에 해당 시나리오만 포함하세요. 기존 시나리오를 복사하지 마세요.
- 델타는 의도를 나타내며, 전체를 대체하는 것이 아닙니다.
- 변경 사항을 합리적으로 병합하려면 판단을 사용하세요.
성공 시 출력
## Specs Synced: <change-name>
업데이트된 메인 명세서:
**<capability-1>**:
- 요구사항 추가: "새 기능"
- 요구사항 수정: "기존 기능" (시나리오 1개 추가)
**<capability-2>**:
- 새 명세서 파일 생성
- 요구사항 추가: "또 다른 기능"
메인 명세서가 업데이트되었습니다. 변경 사항은 여전히 활성 상태입니다. 구현이 완료되면 보관하세요.
가드레일
- 변경하기 전에 델타 명세서와 메인 명세서를 모두 읽으세요.
- 델타에 언급되지 않은 기존 내용은 그대로 보존하세요.
- 명확하지 않은 사항이 있으면 설명을 요청하세요.
- 작업하면서 변경 사항을 표시하세요.
- 작업은 멱등성을 가져야 합니다. 두 번 실행해도 동일한 결과가 나와야 합니다.