# 3. 핵심 개념 이해 ← [[openspec-02-installation-and-setup|2. 설치 및 초기 설정]] | 다음 → [[openspec-04-project-structure|4. 프로젝트 구조]] --- ## 3.1 Specs (사양) `openspec/specs/`는 **현재 시스템 동작의 단일 진실 공급원(Single Source of Truth)** 이다. > [!info] 스펙은 구현 계획이 아닌 행동 계약이다 > "A spec is a behavior contract, not an implementation plan" — 외부적으로 관찰 가능한 동작만 기술하며, 구현 세부사항은 포함하지 않는다. 사양 파일의 구조: ```markdown # 인증 사양 ## 목적 사용자 인증 및 세션 관리를 정의한다. ## Requirements ### Requirement: 이메일 로그인 사용자는 이메일과 비밀번호로 로그인할 수 있어야 한다. #### Scenario: 유효한 자격증명으로 로그인 - GIVEN: 가입된 사용자가 있고 - WHEN: 올바른 이메일과 비밀번호를 입력하면 - THEN: JWT 토큰을 반환하고 대시보드로 이동한다 ``` > [!info] RFC 2119 키워드 > | 키워드 | 의미 | > |--------|------| > | MUST / SHALL | 절대 필수 요구사항 | > | SHOULD | 권장사항 (예외 허용) | > | MAY | 선택사항 | ## 3.2 Changes (변경사항) `openspec/changes/`는 **진행 중인 개발 작업** 을 담는다. 각 변경사항은 독립적인 폴더로 관리된다. 변경 폴더 구조 (공식 기준): ``` openspec/changes/add-dark-mode/ ├── proposal.md ← 의도와 범위 (WHY) ├── design.md ← 기술적 접근법 (HOW) [선택] ├── tasks.md ← 구현 체크리스트 (STEPS) ├── .openspec.yaml ← 메타데이터 (자동 생성, 선택) └── specs/ ← 델타 스펙 (WHAT changes) └── ui-theme.md ``` > [!tip] 독립 폴더의 장점 > 각 변경사항이 자체 폴더에 격리되므로 **병렬 작업**이 가능하고, PR 리뷰 시 변경 범위가 명확하다. ## 3.3 Delta Specs (델타 사양) — 핵심 혁신 > [!note] Delta Specs란? > 기존 사양을 **전체 재작성하지 않고 변경사항만 명세** 하는 방식이다. `ADDED / MODIFIED / REMOVED` 세 섹션으로 구성된다. 공식 Delta Specs 형식: ```markdown # Delta Spec: UI 테마 시스템 ## ADDED Requirements ### Requirement: 다크모드 토글 사용자는 헤더의 토글 버튼으로 다크/라이트 모드를 전환할 수 있어야 한다. #### Scenario: 다크모드 활성화 - GIVEN: 사용자가 라이트 모드로 앱을 사용 중이고 - WHEN: 헤더의 토글 버튼을 클릭하면 - THEN: 전체 UI가 다크 테마로 전환되고 설정이 localStorage에 저장된다 ## MODIFIED Requirements ### Requirement: 사이드바 배경색 기존 동작: 사이드바는 항상 흰색(#FFFFFF) 배경이다 변경 동작: 사이드바는 현재 테마(라이트/다크)에 따라 배경색을 동적으로 적용한다 #### Scenario: 테마 전환 시 사이드바 갱신 - GIVEN: 사용자가 다크모드로 전환하면 - WHEN: 페이지가 리렌더링되면 - THEN: 사이드바 배경색이 #1A1A1A로 변경된다 ## REMOVED Requirements ### Requirement: 수동 색상 입력 사용자가 hex 값으로 직접 색상을 입력하는 기능을 제거한다. 이유: 테마 시스템과 중복되며 사용률이 낮음. ``` 아카이빙 시 이 델타 스펙이 `openspec/specs/`의 해당 파일에 자동 병합된다. > [!success] 왜 Delta Specs인가? > - AI에게 정확한 목표 제시 → 출력 품질 향상 > - 전체 재작성 없이 brownfield 프로젝트에 점진적 적용 > - 여러 변경사항이 같은 스펙 파일을 수정해도 충돌 없이 병합 > - 변경 이력 자동 추적 ## 3.4 아티팩트 의존성 그래프 (DAG) 아티팩트는 DAG 구조로 의존성이 관리된다: ```mermaid graph TD A[proposal.md] --> B["specs/*.md (Delta Specs)"] A --> C[design.md] B --> D[tasks.md] C --> D D --> E[구현 - 코드 작성] E --> F[아카이브] style A fill:#4A90D9,color:#fff style F fill:#27AE60,color:#fff ``` > [!important] 핵심 원칙 > 의존성은 "다음에 **반드시** 해야 할 것"이 아닌 "**가능한 것**"을 나타낸다. 단계를 건너뛰거나 역방향으로 수정할 수 있다. `/opsx:continue`는 이 DAG를 읽어 다음 생성 가능한 아티팩트를 자동으로 판단한다. ## 3.4.1 스펙의 단계적 엄밀함 (Progressive Rigor) > [!tip] 관료주의를 피하라 > 모든 변경에 완전한 스펙이 필요하지 않다. 변경을 검증 가능하게 만드는 **최소한의 수준**만 사용한다. | 수준 | 내용 | 적합한 상황 | |------|------|------------| | **Lite (기본)** | 간단한 행동 요구사항, 명확한 범위, 몇 가지 인수 조건 | 대부분의 변경 | | **Full** | 완전한 시나리오 커버리지, 엣지 케이스, 성능/보안 제약 | 크로스팀 변경, API 계약 변경, 보안·마이그레이션 | > [!info] 스펙에 포함할 내용 vs 제외할 내용 > **포함:** 외부에서 관찰 가능한 동작, 입출력, 오류 조건, 보안·호환성 제약 > **제외:** 내부 클래스/함수명, 라이브러리 선택, 상세 구현 절차 (이것들은 `design.md`나 `tasks.md`에) ## 3.5 Archive (아카이브) 프로세스 변경사항 완료 후 아카이빙 절차: 1. 델타 스펙 → `openspec/specs/` 해당 파일에 병합 (ADDED는 추가, MODIFIED는 갱신, REMOVED는 제거) 2. 변경 폴더 → `openspec/changes/archive/YYYY-MM-DD-변경명/` 으로 이동 3. proposal.md, design.md, tasks.md 등 모든 아티팩트 보존 (감사 추적 목적) > [!note] sync와 archive의 관계 > `/opsx:sync`는 스펙 병합만 수행하며 변경 폴더는 그대로 둔다. `/opsx:archive`는 sync 여부를 자동 확인 후 폴더를 이동한다. 직접 sync를 호출하는 것은 선택사항이다. 자세한 워크플로우는 [[openspec-05-core-workflows|5장]]을 참고한다. --- ## 용어집 (Glossary) | 용어 | 정의 | |------|------| | **Artifact** | 변경 폴더 내 문서 (proposal, design, tasks, delta specs) | | **Archive** | 변경을 완료 처리하고 델타를 메인 스펙에 병합하는 과정 | | **Change** | 폴더 형태로 패키징된 제안 변경사항. 아티팩트와 델타 스펙 포함 | | **Delta Spec** | 현재 스펙 대비 변경사항만 기술하는 스펙 (ADDED/MODIFIED/REMOVED) | | **Domain** | 스펙의 논리적 그룹 (예: `auth/`, `payments/`) | | **Requirement** | 시스템이 갖춰야 할 구체적 동작 | | **Scenario** | 요구사항의 구체적 예시 (주로 Given/When/Then 형식) | | **Schema** | 아티팩트 유형과 의존성을 정의하는 워크플로우 정의 파일 | | **Spec** | 시스템 동작을 기술하는 사양. 요구사항과 시나리오 포함 | | **Source of Truth** | `openspec/specs/` 디렉터리. 현재 합의된 시스템 동작의 기준 | --- ← [[openspec-02-installation-and-setup|2. 설치 및 초기 설정]] | 다음 → [[openspec-04-project-structure|4. 프로젝트 구조]]