# 8. 커스터마이징
← [[openspec-07-cli-commands-reference|7. CLI 명령어 레퍼런스]] | 다음 → [[openspec-09-supported-tools-and-integration|9. 지원 AI 도구 및 통합]]
---
## 커스터마이징 3단계
| 레벨 | 방법 | 대상 |
|------|------|------|
| **1. 프로젝트 설정** | `config.yaml`에 context/rules 작성 | 대부분의 팀 |
| **2. 커스텀 스키마** | 고유한 워크플로우 아티팩트 정의 | 특별한 프로세스가 필요한 팀 |
| **3. 글로벌 오버라이드** | 전역 설정으로 모든 프로젝트에 스키마 공유 | 파워 사용자 |
## 8.1 프로젝트 설정 (config.yaml)
`openspec/config.yaml`로 팀 컨벤션을 AI에게 주입한다. 전체 필드 구조는 [[openspec-04-project-structure|4장 프로젝트 구조]]를 참고한다.
### context 필드 작성 가이드
> [!success] 포함할 내용
> ```yaml
> context: |
> # 기술 스택
> Backend: FastAPI (Python 3.12), SQLAlchemy
> Frontend: React 18 + TypeScript
> Database: PostgreSQL 15, Redis 7
>
> # 아키텍처 패턴
> API style: RESTful with OpenAPI 3.1
> Auth: JWT with refresh tokens
>
> # 프로젝트 제약
> 절대 사용 금지: jQuery, class components
> 코드 스타일: Ruff (Python), ESLint + Prettier (TS)
> ```
> [!warning] 포함하지 않을 내용
> - AI가 이미 아는 일반적 모범 사례 ("항상 에러 처리를 하세요" 등)
> - 장황한 설명이나 배경 이야기
> - 코드 예시 (templates 디렉터리에 포함)
### rules 필드 작성 가이드
```yaml
rules:
proposal:
- 데이터베이스 마이그레이션이 포함된 경우 롤백 계획 필수
- API 변경 시 하위 호환성 계획 포함
specs:
- Given/When/Then 형식 준수
- 각 Requirement에 최소 2개 시나리오
design:
- 인덱스 전략 명시 (DB 변경 시)
- 예상 응답 시간 명시 (API 변경 시)
tasks:
- 단위 테스트 작성 태스크 반드시 포함
- 마이그레이션 태스크는 항상 마지막에 위치
```
> [!tip] context vs rules 우선순위
> `context`와 `rules` 모두 AI 프롬프트에 주입되며, `context`는 배경 정보로, `rules`는 해당 아티팩트 생성 시점에 적용되는 구체적 지침으로 동작한다.
## 8.2 다국어 지원
`config.yaml`의 `context`에 언어를 지정하면 모든 아티팩트가 해당 언어로 생성된다.
```yaml
context: |
Language: Korean (ko-KR)
All artifacts must be written in Korean.
Technical terms (API, REST, JWT, etc.) and code/file paths stay in English.
```
### 지원 언어 예시
| 언어 | context 설정값 |
|------|----------------|
| 한국어 | `Language: Korean (ko-KR)` |
| 일본어 | `Language: Japanese (ja-JP)` |
| 중국어(간체) | `Language: Chinese Simplified (zh-CN)` |
| 중국어(번체) | `Language: Chinese Traditional (zh-TW)` |
| 포르투갈어(브라질) | `Language: Portuguese (pt-BR)` |
| 스페인어 | `Language: Spanish (es)` |
| 프랑스어 | `Language: French (fr)` |
| 독일어 | `Language: German (de)` |
**설정 확인:**
```bash
openspec instructions --change my-change # 생성될 내용 미리 확인
```
## 8.3 커스텀 스키마
기본 `spec-driven` 스키마를 팀 필요에 맞게 수정하거나 새로 만든다.
### 기존 스키마 복제 (권장)
```bash
openspec schema fork spec-driven research-first
```
### 처음부터 생성
```bash
openspec schema init research-first \
--description "연구 단계가 포함된 워크플로우" \
--artifacts proposal,research,design,tasks \
--default
```
### 스키마 구조
```
openspec/schemas/research-first/
├── schema.yaml ← 아티팩트 정의 및 의존성
└── templates/
├── proposal.md ← 제안서 Markdown 템플릿
├── research.md ← 연구 문서 템플릿 (추가)
├── design.md ← 설계 템플릿
└── tasks.md ← 작업 목록 템플릿
```
`schema.yaml` 예시:
```yaml
artifacts:
- id: proposal
generates: proposal.md
requires: []
template: templates/proposal.md
instruction: |
Create a proposal document describing the intent and scope of this change.
- id: research
generates: research.md
requires: [proposal]
template: templates/research.md
instruction: |
Research existing solutions and document findings.
- id: design
generates: design.md
requires: [research]
template: templates/design.md
instruction: |
Design the technical approach based on research findings.
- id: tasks
generates: tasks.md
requires: [design]
template: templates/tasks.md
instruction: |
Create an implementation checklist based on the design.
```
> [!note] `instruction` 필드
> 각 아티팩트를 생성할 때 AI 프롬프트에 주입되는 지시사항이다. `config.yaml`의 rules와 함께 동작한다.
### 적용 및 검증
```bash
openspec schema validate research-first # 스키마 구조 검증
openspec config set schema research-first # 프로젝트 기본 스키마로 설정
openspec schema which # 현재 사용 중인 스키마 확인
```
특정 변경에만 스키마를 적용하려면:
```bash
/opsx:new my-change --schema research-first
```
---
← [[openspec-07-cli-commands-reference|7. CLI 명령어 레퍼런스]] | 다음 → [[openspec-09-supported-tools-and-integration|9. 지원 AI 도구 및 통합]]