# 4. 프로젝트 구조
← [[openspec-03-core-concepts|3. 핵심 개념 이해]] | 다음 → [[openspec-05-core-workflows|5. 핵심 워크플로우]]
---
> [!info] 단일 진실 공급원
> 이 챕터가 OpenSpec 폴더 구조의 **단일 진실 공급원**이다. 다른 챕터에서 폴더 구조를 언급할 때는 이 챕터를 참조한다.
## 4.1 전체 디렉터리 구조
```
your-project/
├── openspec/
│ ├── config.yaml ← 프로젝트 설정 (필수)
│ ├── specs/ ← 현재 시스템 사양 (단일 진실 공급원)
│ │ ├── auth.md
│ │ ├── payments.md
│ │ └── notifications/
│ │ └── email.md
│ ├── changes/ ← 진행 중인 변경사항
│ │ ├── add-dark-mode/
│ │ │ ├── proposal.md
│ │ │ ├── design.md ← 선택
│ │ │ ├── tasks.md
│ │ │ ├── .openspec.yaml ← 메타데이터 (자동 생성, 선택)
│ │ │ └── specs/ ← 델타 스펙
│ │ │ └── ui-theme.md
│ │ └── archive/ ← 완료된 변경사항
│ │ └── 2026-05-01-add-login/
│ └── schemas/ ← 커스텀 스키마 (선택)
│ └── my-workflow/
│ ├── schema.yaml
│ └── templates/
│
├── .claude/ ← Claude Code 통합 파일
│ ├── skills/
│ │ ├── openspec-propose/SKILL.md
│ │ ├── openspec-apply/SKILL.md
│ │ └── ...
│ └── commands/opsx/
│ ├── propose.md
│ └── apply.md
│
├── .cursor/ ← Cursor 통합 파일 (도구 선택 시)
├── .github/ ← GitHub Copilot 통합 파일 (도구 선택 시)
└── ...
```
> [!tip] 스펙 파일 구성 권장 방식
> 도메인별로 분리하면 AI가 관련 스펙만 로드하여 컨텍스트 효율이 높아진다.
>
> ```
> openspec/specs/
> ├── auth/
> │ ├── login.md
> │ ├── registration.md
> │ └── permissions.md
> ├── payments/
> │ ├── checkout.md
> │ └── refunds.md
> └── notifications/
> └── email.md
> ```
## 4.2 config.yaml 완전 레퍼런스
`openspec/config.yaml`은 OpenSpec의 핵심 설정 파일이다.
### 전체 필드 구조
| 필드 | 타입 | 필수 | 기본값 | 설명 |
|------|------|------|--------|------|
| `schema` | string | 선택 | `spec-driven` | 사용할 워크플로우 스키마 |
| `context` | multiline string | 선택 | — | 모든 아티팩트 생성 시 AI에게 전달되는 프로젝트 정보 |
| `rules` | object | 선택 | — | 특정 아티팩트 생성 시 적용되는 규칙 목록 |
| `rules.proposal` | string[] | 선택 | — | proposal.md 생성 규칙 |
| `rules.specs` | string[] | 선택 | — | specs/*.md 생성 규칙 |
| `rules.design` | string[] | 선택 | — | design.md 생성 규칙 |
| `rules.tasks` | string[] | 선택 | — | tasks.md 생성 규칙 |
| `rules.apply` | string[] | 선택 | — | 코드 구현 시 적용 규칙 |
### 스키마 결정 우선순위
```
1. CLI 플래그: openspec validate --schema my-workflow
2. 변경 메타데이터: openspec/changes/{name}/.openspec.yaml
3. 프로젝트 설정: openspec/config.yaml
4. 기본값: spec-driven
```
### 완전한 config.yaml 예시
```yaml
# 사용할 워크플로우 스키마
schema: spec-driven
# AI에게 전달되는 프로젝트 컨텍스트
context: |
Tech stack: React 18 + TypeScript, FastAPI (Python 3.12)
Database: PostgreSQL 15, Redis 7
Testing: Vitest + React Testing Library, pytest
API style: RESTful with OpenAPI 3.1
Architecture: Monorepo with pnpm workspaces
절대 사용 금지: jQuery, class components
코드 스타일: Ruff (Python), ESLint + Prettier (TS)
Language: Korean (ko-KR)
All artifacts must be written in Korean.
Technical terms (API, REST, JWT, etc.) stay in English.
# 아티팩트별 생성 규칙
rules:
proposal:
- 데이터베이스 변경 시 롤백 계획 포함
- 영향받는 팀 및 서비스 식별
- 예상 작업 시간 명시
specs:
- Given/When/Then 형식으로 시나리오 작성
- 각 Requirement에 최소 2개 시나리오 포함
- 엣지 케이스 시나리오 반드시 포함
design:
- 성능 영향도 평가 포함
- 보안 고려사항 명시
- DB 변경 시 인덱스 전략 명시
tasks:
- 각 태스크는 독립적으로 완료 가능해야 함
- 단위 테스트 작성 태스크 반드시 포함
- DB 마이그레이션 태스크는 항상 마지막에 위치
```
> [!warning] context 필드에 넣지 말아야 할 것
> - AI가 이미 아는 일반적 모범 사례 ("항상 에러 처리를 하세요" 등)
> - 장황한 설명이나 배경 이야기
> - 코드 예시 (templates 디렉터리에 포함)
## 4.3 변경사항 폴더 내부 구조
각 변경사항 폴더(`openspec/changes/{name}/`)의 표준 구성:
| 파일 | 역할 | 생성 시점 |
|------|------|-----------|
| `proposal.md` | 의도, 범위, 접근 방식 (WHY) | `/opsx:propose` 또는 첫 `/opsx:continue` |
| `specs/` | Delta Specs — ADDED/MODIFIED/REMOVED (WHAT) | proposal 이후 |
| `design.md` | 기술적 구현 방법 (HOW) | specs 이후, 선택 |
| `tasks.md` | 구현 체크리스트 (STEPS) | specs + design 이후 |
| `.openspec.yaml` | 메타데이터 (스키마, 생성일 등) | 자동 생성, 선택 |
> [!note] design.md는 필수가 아니다
> 간단한 변경은 `proposal → specs → tasks` 3단계로도 충분하다. DAG 의존성은 강제가 아닌 가능성을 나타낸다.
커스터마이징 방법은 [[openspec-08-customization|8장 커스터마이징]]을 참고한다.
---
← [[openspec-03-core-concepts|3. 핵심 개념 이해]] | 다음 → [[openspec-05-core-workflows|5. 핵심 워크플로우]]