# config-schema

> vibe-commander.config.json 설정 파일의 스키마 설계 및 Zod 4 검증 패턴을 가이드합니다. 설정 파일 구조, 스키마 정의, 설정 검증, 새 설정 필드 추가 요청 시 사용합니다.

- Author: yachaboom
- Repository: viilab/vibe-commander
- Version: 20260207190114
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/viilab/vibe-commander
- Web: https://mule.run/skillshub/@@viilab/vibe-commander~config-schema:20260207190114

---

---
name: config-schema
description: vibe-commander.config.json 설정 파일의 스키마 설계 및 Zod 4 검증 패턴을 가이드합니다. 설정 파일 구조, 스키마 정의, 설정 검증, 새 설정 필드 추가 요청 시 사용합니다.
metadata:
  version: 1.0.0
  category: configuration
  tags: [zod, json-schema, config, validation]
---

# Config Schema Design Guide

`vibe-commander.config.json`은 도구의 범용성을 결정하는 핵심 파일입니다.
프로젝트별 변동 요소를 설정으로 흡수하여 코드 수정 없이 다양한 프로젝트에 적용합니다.

## Instructions

### Step 1: 설정 구조 이해

설정 파일은 7개 주요 섹션으로 구성됩니다.

```
vibe-commander.config.json
├── paths             # 파일/디렉토리 경로
├── unitTypes[]       # 유닛 유형 정의 (ID 패턴, 템플릿 등)
├── docDiscovery      # 문서 탐색 패턴
├── planParsing       # 계획서 파싱 규칙
├── backlogParsing    # 로드맵 파싱 규칙
├── commitSearch      # 커밋 탐색 전략
├── commandSections   # 커맨드 파일 섹션 구분
├── defaultSpecialRequests    # 기본 특별 요청사항
└── specialRequestsByType     # 유형별 추가 특별 요청사항
```

### Step 2: Zod 4 스키마 정의

모든 설정 필드는 Zod 4 스키마로 정의하여 런타임 검증합니다.

```typescript
import { z } from 'zod';

// 유닛 유형 스키마
const UnitTypeSchema = z.object({
  key: z.string(),
  displayName: z.string().optional(),
  idPattern: z.string(),            // RegExp 문자열
  planDir: z.string(),              // docRoots 키 참조
  commandSection: z.string(),       // 커맨드 파일 섹션 헤더
  collectDeps: z.boolean(),
  headerTemplate: z.string(),       // Mustache 스타일 템플릿
});

// 전체 설정 스키마
const ProjectConfigSchema = z.object({
  $schema: z.string().optional(),
  version: z.literal(1),
  paths: PathsSchema,
  unitTypes: z.array(UnitTypeSchema).min(1),
  docDiscovery: DocDiscoverySchema,
  planParsing: PlanParsingSchema,
  backlogParsing: BacklogParsingSchema.optional(),
  commitSearch: CommitSearchSchema.optional(),
  commandSections: CommandSectionsSchema.optional(),
  defaultSpecialRequests: z.array(z.string()).optional(),
  specialRequestsByType: z.record(z.string(), z.array(z.string())).optional(),
});
```

### Step 3: 설정 로드 및 검증

```typescript
export function loadConfig(projectRoot: string): ProjectConfig {
  const configPath = path.join(projectRoot, 'vibe-commander.config.json');
  const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
  const result = ProjectConfigSchema.safeParse(raw);

  if (!result.success) {
    return {
      success: false,
      error: {
        code: 'CONFIG_INVALID',
        message: '설정 파일 검증 실패',
        details: result.error.format(),
      },
    };
  }
  return { success: true, data: result.data };
}
```

## Rules

### 설정 필드 추가 시 필수 사항

새 설정 필드를 추가할 때는 반드시 다음 3가지를 함께 수행합니다.

**Do ✅**:
```typescript
// 1. Zod 스키마에 필드 추가 (optional로 시작, 기본값 제공)
const NewFieldSchema = z.object({
  newOption: z.string().default('default-value'),
});

// 2. 타입에 반영
type ProjectConfig = z.infer<typeof ProjectConfigSchema>;

// 3. JSON Schema 자동 생성 (IDE 자동완성용)
// zodToJsonSchema(ProjectConfigSchema)를 빌드 시 실행
```

**Don't ❌**:
```typescript
// 스키마 없이 런타임에서 직접 접근 — 타입 안전성 없음
const config = JSON.parse(raw);
const value = config.newField; // ❌ 검증 없음, 타입 불명
```

### 프로젝트별 변동 요소 모델링

변동 요소는 반드시 설정으로 추출합니다.

**Do ✅**:
```jsonc
// 유닛 ID 패턴을 설정으로 정의
"unitTypes": [
  {
    "key": "implement",
    "idPattern": "^(U-\\d+|CP-).*",  // 프로젝트별 패턴
    "planDir": "plan"                  // docRoots 키 참조
  }
]
```

**Don't ❌**:
```typescript
// 코드에 프로젝트별 패턴 하드코딩
if (unitId.startsWith('U-')) { /* snapmit 전용 */ }
if (unitId.startsWith('FEAT-')) { /* 다른 프로젝트 전용 */ }
```

### Optional 필드와 Graceful Degradation

모든 선택 필드는 기본값을 가지고, 없어도 나머지 기능이 동작해야 합니다.

**Do ✅**:
```typescript
// 로드맵이 없어도 set-unit은 동작
const backlogParsing = config.backlogParsing;
if (!backlogParsing || !config.paths.roadmap) {
  return { success: false, error: { code: 'ROADMAP_NOT_CONFIGURED', message: '로드맵 미설정' } };
}
```

**Don't ❌**:
```typescript
// 로드맵 없으면 전체 실패
const roadmap = config.paths.roadmap!; // ❌ non-null assertion
```

### 템플릿 변수 시스템

`headerTemplate`에서 사용 가능한 변수를 명확히 정의합니다.

| 변수 | 설명 | 예시 |
|------|------|------|
| `{{unitId}}` | 원본 유닛 ID | `U-118[Mmp]` |
| `{{shortId}}` | phase 제거 | `U-118` |
| `{{bareId}}` | 숫자만 | `118` |
| `{{title}}` | 전체 제목 (ID 포함) | `U-118[Mmp]: 마크다운 이미지 링크 삽입` |
| `{{titleOnly}}` | 제목만 (ID 제외) | `마크다운 이미지 링크 삽입` |
| `{{planPath}}` | 계획서 상대 경로 | `vibe/unit-plans/U-118[Mmp].md` |
| `{{phase}}` | phase 문자열 | `Mmp` |
| `{{slug}}` | kebab-case 변환 | `u-118-mmp` |

## Examples

### Example 1: 새 유닛 유형 추가

User says: "bugfix 유닛 유형을 설정에 추가해줘"

Actions:
1. `unitTypes` 배열에 새 항목 추가
2. `idPattern`으로 기존 유형과 충돌하지 않는 정규식 정의
3. Zod 스키마에서 자동 검증됨을 확인
4. 필요시 `specialRequestsByType`에 bugfix 전용 요청사항 추가
Result: 코드 수정 없이 설정만으로 새 유닛 유형 지원

### Example 2: 다른 프로젝트에 설정 적용

User says: "Next.js 프로젝트에 맞는 설정 만들어줘"

Actions:
1. 프로젝트 파일 구조 스캔
2. ID 패턴 감지 (FEAT-*, BUG-* 등)
3. 문서 디렉토리 매핑 (docs/specs, docs/results 등)
4. 커맨드 파일 경로 설정
5. `planParsing` 규칙 조정 (frontmatter vs section)
Result: 프로젝트 맞춤형 config 생성

## Troubleshooting

### Error: CONFIG_INVALID
Cause: 설정 파일이 Zod 스키마를 통과하지 못함
Solution: `result.error.format()`의 상세 메시지 확인 후 해당 필드 수정

### Error: ID 패턴 충돌
Cause: 여러 `unitTypes`의 `idPattern`이 동일 ID에 매칭
Solution: `unitTypes` 배열 순서가 우선순위 (먼저 매칭되는 게 승). 더 구체적인 패턴을 앞에 배치

## References

설정 파일 전체 예시:
- snapmit 프로젝트: [references/config-snapmit.md](references/config-snapmit.md)