# 11. 베스트 프랙티스 ← [[openspec-10-advanced-usage-patterns|10. 고급 사용 패턴]] | 다음 → [[openspec-12-migration-guide|12. 마이그레이션 가이드]] --- ## 11.1 효과적인 사용을 위한 핵심 원칙 > [!tip] 1. 고성능 추론 모델 사용 > OpenSpec은 계획 단계에서 AI의 추론 능력에 크게 의존한다. Claude Sonnet/Opus 4 계열, GPT-4o 또는 그 후속 모델처럼 추론 능력이 강한 모델을 사용할 때 아티팩트 품질이 크게 향상된다. > [!tip] 2. 컨텍스트 위생 (Context Hygiene) 유지 > 구현(`/opsx:apply`) 시작 전 AI 컨텍스트 창을 정리한다. 긴 탐색 대화가 구현 단계에서 혼선을 줄 수 있다. **apply 전 새 대화창을 여는 것을 습관화한다.** > [!tip] 3. 아티팩트를 직접 편집하라 > AI가 생성한 proposal.md, specs, design.md, tasks.md를 그대로 사용하지 말고, 팀의 실제 요구사항에 맞게 편집한다. 이 파일들은 AI의 초안이며 최종 확정은 인간이 한다. > [!tip] 4. Delta Specs는 작게 유지하라 > 하나의 변경에 너무 많은 요구사항을 담지 않는다. "다크모드 + 알림 설정 + 결제 방법 변경"을 한 변경에 담으면 구현이 복잡해지고 검토가 어려워진다. 각각 독립적인 변경으로 분리한다. > [!tip] 5. Tasks.md를 스코프 크리프 방어선으로 활용하라 > AI에게 `/opsx:apply`를 실행할 때 "tasks.md에 없는 작업은 하지 말 것"을 명시한다. tasks.md가 구현 경계가 된다. > [!tip] 6. 대규모 변경 전 반드시 Propose 먼저 > 새 기능, 대규모 리팩터링, 아키텍처 변경은 코드를 한 줄도 작성하기 전에 반드시 `/opsx:propose`를 실행한다. > [!tip] 7. 스펙을 버전 관리에 포함하라 > `openspec/` 전체를 git에 커밋한다. `openspec/specs/`가 팀의 살아있는 문서이자 신규 팀원 온보딩 자료가 된다. > [!tip] 8. CI에서 스펙 검증을 자동화하라 > PR마다 `openspec validate --all --strict`를 실행하면 스펙과 코드의 동기화를 강제할 수 있다. [[openspec-10-advanced-usage-patterns#10.2 CI/CD 파이프라인 통합|10.2 CI/CD 통합]] 참고. ## 11.2 변경사항 명명 규칙 > [!success] 권장: 동사-명사 kebab-case > ``` > add-dark-mode > fix-auth-token-expiry > refactor-payment-service > update-user-api-v2 > remove-legacy-import > ``` > [!failure] 피해야 할 이름 > ``` > fix ← 너무 모호 > update ← 너무 모호 > feature-1 ← 의미 없음 > wip ← 작업 상태를 이름에 포함하지 않음 > 2026-05-08-fix ← 날짜는 자동 추가됨 > ``` ## 11.3 코드 작성 중 요구사항 변경 시 > [!failure] 잘못된 방법 > 코드 먼저 수정 → 나중에 스펙 업데이트 > [!success] 올바른 방법 > 스펙 먼저 수정 (`specs/*.md` 또는 `tasks.md`) → 코드 수정 이를 통해 스펙과 코드가 항상 동기화된 상태를 유지할 수 있다. ## 11.4 팀 도입 전략 ``` Week 1: 소규모 파일럿 - 팀 1~2명이 새 기능에 OpenSpec 적용 - /opsx:onboard로 전체 워크플로우 체험 Week 2: 피드백 반영 - config.yaml에 팀 컨벤션 반영 - 커스텀 rules 추가 - CI에 openspec validate 추가 Week 3~: 팀 전체 도입 - 모든 새 기능에 OpenSpec 워크플로우 의무화 - 레거시 코드 스펙 문서화 시작 ``` **도입 성공 지표 (KPI):** | 지표 | 목표 | |------|------| | 변경당 평균 PR 리뷰 시간 | 감소 (스펙이 맥락 제공) | | 구현 후 요구사항 변경 빈도 | 감소 | | `openspec validate --strict` 통과율 | 90% 이상 | | 아카이브 비율 (완료/시작) | 80% 이상 | > [!note] 커스터마이징 참고 > 팀 컨벤션을 config.yaml에 반영하는 방법은 [[openspec-08-customization|8장 커스터마이징]]을 참고한다. ## 11.5 안티패턴 — 흔한 실패 모드 > [!failure] 안티패턴 1: Tasks.md 무시 후 즉흥 코딩 > AI에게 `/opsx:apply`를 주고도 tasks.md를 사전에 검토·수정하지 않으면, AI가 잘못된 방향으로 구현하거나 불필요한 코드를 추가할 수 있다. > > **해결:** apply 전 반드시 tasks.md를 읽고 순서와 범위를 확인한다. > [!failure] 안티패턴 2: 델타 스펙 비대화 (Spec Bloat) > 하나의 변경에 여러 기능을 몰아넣으면 Delta Specs가 비대해지고, 아카이빙 시 스펙 충돌 위험이 높아진다. > > **해결:** 변경 하나 = 논리적 작업 단위 하나. 관련 없는 기능은 별도 변경으로 분리한다. > [!failure] 안티패턴 3: 스펙과 코드 동기화 실패 > 구현 중 요구사항이 바뀌었는데 스펙을 업데이트하지 않으면, 시간이 지날수록 스펙이 현실과 멀어진다. > > **해결:** 요구사항 변경 시 코드보다 스펙을 먼저 수정한다. `/opsx:verify`로 주기적으로 동기화 상태를 확인한다. > [!failure] 안티패턴 4: context 필드 남용 > config.yaml의 context에 "항상 에러 처리를 하세요", "코드 품질을 유지하세요" 같은 일반적인 내용을 채워 넣으면 AI 프롬프트가 오염되어 실제 프로젝트 정보가 희석된다. > > **해결:** context에는 이 프로젝트에만 해당하는 구체적 정보만 포함한다. > [!failure] 안티패턴 5: 아카이브 없이 변경 방치 > 구현이 완료됐는데 `/opsx:archive`를 실행하지 않으면, `openspec/changes/`에 완료된 변경이 쌓여 목록이 혼잡해지고 스펙도 업데이트되지 않는다. > > **해결:** 구현 완료 → `/opsx:verify` → `/opsx:archive`를 워크플로우의 마지막 단계로 습관화한다. > [!failure] 안티패턴 6: propose 없이 대규모 구현 > 아키텍처 변경이나 새 기능을 바로 코드로 작성하면, 나중에 스펙 문서화가 어렵고 AI 지원도 받기 어렵다. > > **해결:** 코드를 한 줄도 쓰기 전에 `/opsx:propose`로 계획을 수립한다. explore → propose → review → apply 순서를 지킨다. --- ← [[openspec-10-advanced-usage-patterns|10. 고급 사용 패턴]] | 다음 → [[openspec-12-migration-guide|12. 마이그레이션 가이드]]