# OpenSpec 사용자 상세 가이드 ## Table of Contents - [OpenSpec 사용자 상세 가이드](#table-of-contents) - [목차](./openspec-00-toc.md) - [1. OpenSpec이란?](./openspec-01-what-is-openspec.md) - [1.1 문제 배경](./openspec-01-what-is-openspec.md#11-문제-배경) - [1.2 OpenSpec의 해법](./openspec-01-what-is-openspec.md#12-openspec의-해법) - [1.3 핵심 철학](./openspec-01-what-is-openspec.md#13-핵심-철학) - [1.4 경쟁 도구와의 차이](./openspec-01-what-is-openspec.md#14-경쟁-도구와의-차이) - [2. 설치 및 초기 설정](./openspec-02-installation-and-setup.md) - [2.1 사전 요구사항](./openspec-02-installation-and-setup.md#21-사전-요구사항) - [2.2 패키지 매니저별 설치](./openspec-02-installation-and-setup.md#22-패키지-매니저별-설치) — npm/pnpm/yarn/bun/Nix/flake.nix - [2.3 설치 확인](./openspec-02-installation-and-setup.md#23-설치-확인) - [2.4 프로젝트 초기화](./openspec-02-installation-and-setup.md#24-프로젝트-초기화) - [2.5 첫 번째 변경 제안 (빠른 시작)](./openspec-02-installation-and-setup.md#25-첫-번째-변경-제안-빠른-시작) - [3. 핵심 개념 이해](./openspec-03-core-concepts.md) - [3.1 Specs (사양)](./openspec-03-core-concepts.md#31-specs-사양) - [3.2 Changes (변경사항)](./openspec-03-core-concepts.md#32-changes-변경사항) - [3.3 Delta Specs (델타 사양) — 핵심 혁신](./openspec-03-core-concepts.md#33-delta-specs-델타-사양--핵심-혁신) - [3.4 아티팩트 의존성 그래프 (DAG)](./openspec-03-core-concepts.md#34-아티팩트-의존성-그래프-dag) - [3.4.1 스펙의 단계적 엄밀함 (Progressive Rigor)](./openspec-03-core-concepts.md#341-스펙의-단계적-엄밀함-progressive-rigor) - [3.5 Archive (아카이브) 프로세스](./openspec-03-core-concepts.md#35-archive-아카이브-프로세스) - [용어집 (Glossary)](./openspec-03-core-concepts.md#용어집-glossary) - [4. 프로젝트 구조](./openspec-04-project-structure.md) - [4.1 전체 디렉터리 구조](./openspec-04-project-structure.md#41-전체-디렉터리-구조) - [4.2 config.yaml 완전 레퍼런스](./openspec-04-project-structure.md#42-configyaml-완전-레퍼런스) - [4.3 변경사항 폴더 내부 구조](./openspec-04-project-structure.md#43-변경사항-폴더-내부-구조) - [5. 핵심 워크플로우](./openspec-05-core-workflows.md) - [5.1 Core 프로필 워크플로우 (권장 시작점)](./openspec-05-core-workflows.md#51-core-프로필-워크플로우-권장-시작점) - [1단계: Propose (제안)](./openspec-05-core-workflows.md#1단계-propose-제안) - [2단계: Apply (구현)](./openspec-05-core-workflows.md#2단계-apply-구현) - [3단계: Sync (동기화)](./openspec-05-core-workflows.md#3단계-sync-동기화) - [4단계: Archive (완료)](./openspec-05-core-workflows.md#4단계-archive-완료) - [5.2 슬래시 명령어 ↔ CLI 명령어 매핑](./openspec-05-core-workflows.md#52-슬래시-명령어--cli-명령어-매핑) - [5.3 확장 워크플로우 패턴](./openspec-05-core-workflows.md#53-확장-워크플로우-패턴) - [패턴 A: 빠른 기능 개발 (요구사항 명확 시)](./openspec-05-core-workflows.md#패턴-a-빠른-기능-개발-요구사항-명확-시) - [패턴 B: 탐색 기반 개발 (요구사항 불명확 시)](./openspec-05-core-workflows.md#패턴-b-탐색-기반-개발-요구사항-불명확-시) - [패턴 C: 병렬 개발](./openspec-05-core-workflows.md#패턴-c-병렬-개발) - [패턴 D: 완료 흐름 (검증 포함)](./openspec-05-core-workflows.md#패턴-d-완료-흐름-검증-포함) - [6. 슬래시 명령어 레퍼런스](./openspec-06-slash-commands-reference.md) - [도구별 명령어 문법](./openspec-06-slash-commands-reference.md#도구별-명령어-문법) - [6.1 Core 프로필 명령어](./openspec-06-slash-commands-reference.md#61-core-프로필-명령어) - [`/opsx:propose`](./openspec-06-slash-commands-reference.md#opsxpropose) - [`/opsx:explore`](./openspec-06-slash-commands-reference.md#opsxexplore) - [`/opsx:apply`](./openspec-06-slash-commands-reference.md#opsxapply) - [`/opsx:sync`](./openspec-06-slash-commands-reference.md#opsxsync) — 수동 사용 시기 표 - [`/opsx:archive`](./openspec-06-slash-commands-reference.md#opsxarchive) - [6.2 확장 프로필 명령어](./openspec-06-slash-commands-reference.md#62-확장-프로필-명령어) - [`/opsx:new`](./openspec-06-slash-commands-reference.md#opsxnew) - [`/opsx:continue`](./openspec-06-slash-commands-reference.md#opsxcontinue) - [`/opsx:ff`](./openspec-06-slash-commands-reference.md#opsxff) - [`/opsx:verify`](./openspec-06-slash-commands-reference.md#opsxverify) — 3차원 검증 + 출력 예시 - [`/opsx:bulk-archive`](./openspec-06-slash-commands-reference.md#opsxbulk-archive) - [`/opsx:onboard`](./openspec-06-slash-commands-reference.md#opsxonboard) — 11단계 진행 목록 - [6.3 레거시 명령어 호환성](./openspec-06-slash-commands-reference.md#63-레거시-명령어-호환성) - [7. CLI 명령어 레퍼런스](./openspec-07-cli-commands-reference.md) - [7.1 설정 명령어](./openspec-07-cli-commands-reference.md#71-설정-명령어) - [7.2 탐색 명령어](./openspec-07-cli-commands-reference.md#72-탐색-명령어) - [7.3 검증 명령어](./openspec-07-cli-commands-reference.md#73-검증-명령어) - [7.4 라이프사이클 명령어](./openspec-07-cli-commands-reference.md#74-라이프사이클-명령어) - [7.5 워크플로우 명령어](./openspec-07-cli-commands-reference.md#75-워크플로우-명령어) - [7.6 설정 명령어](./openspec-07-cli-commands-reference.md#76-설정-명령어) - [7.7 스키마 명령어](./openspec-07-cli-commands-reference.md#77-스키마-명령어) - [7.8 워크스페이스 명령어](./openspec-07-cli-commands-reference.md#78-워크스페이스-명령어) - [7.9 유틸리티 명령어](./openspec-07-cli-commands-reference.md#79-유틸리티-명령어) - [7.10 환경 변수](./openspec-07-cli-commands-reference.md#710-환경-변수) - [7.11 종료 코드](./openspec-07-cli-commands-reference.md#711-종료-코드) - [8. 커스터마이징](./openspec-08-customization.md) - [커스터마이징 3단계](./openspec-08-customization.md#커스터마이징-3단계) - [8.1 프로젝트 설정 (config.yaml)](./openspec-08-customization.md#81-프로젝트-설정-configyaml) - [context 필드 작성 가이드](./openspec-08-customization.md#context-필드-작성-가이드) - [rules 필드 작성 가이드](./openspec-08-customization.md#rules-필드-작성-가이드) - [8.2 다국어 지원](./openspec-08-customization.md#82-다국어-지원) - [8.3 커스텀 스키마](./openspec-08-customization.md#83-커스텀-스키마) - [기존 스키마 복제 (권장)](./openspec-08-customization.md#기존-스키마-복제-권장) - [처음부터 생성](./openspec-08-customization.md#처음부터-생성) - [스키마 구조](./openspec-08-customization.md#스키마-구조) - [적용 및 검증](./openspec-08-customization.md#적용-및-검증) - [9. 지원 AI 도구 및 통합](./openspec-09-supported-tools-and-integration.md) - [9.1 전체 지원 도구 목록](./openspec-09-supported-tools-and-integration.md#91-전체-지원-도구-목록) — 30종+ (init ID 포함) - [9.2 도구별 명령어 문법 비교](./openspec-09-supported-tools-and-integration.md#92-도구별-명령어-문법-비교) - [9.3 도구별 설치 파일 위치](./openspec-09-supported-tools-and-integration.md#93-도구별-설치-파일-위치) — Amazon Q/Gemini/RooCode/Kiro 등 전체 - [9.4 Claude Code 통합 상세](./openspec-09-supported-tools-and-integration.md#94-claude-code-통합-상세) - [9.5 도구 추가 / 변경](./openspec-09-supported-tools-and-integration.md#95-도구-추가--변경) - [10. 고급 사용 패턴](./openspec-10-advanced-usage-patterns.md) - [10.1 아키텍처 결정 기록 (ADR) 통합](./openspec-10-advanced-usage-patterns.md#101-아키텍처-결정-기록-adr-통합) - [10.2 CI/CD 파이프라인 통합](./openspec-10-advanced-usage-patterns.md#102-cicd-파이프라인-통합) - [10.3 멀티 저장소 워크스페이스](./openspec-10-advanced-usage-patterns.md#103-멀티-저장소-워크스페이스) - [10.4 Git WorkTrees와 병렬 개발](./openspec-10-advanced-usage-patterns.md#104-git-worktrees와-병렬-개발) - [10.5 기존 프로젝트 점진적 마이그레이션](./openspec-10-advanced-usage-patterns.md#105-기존-프로젝트-점진적-마이그레이션) - [11. 베스트 프랙티스](./openspec-11-best-practices.md) - [11.1 효과적인 사용을 위한 핵심 원칙](./openspec-11-best-practices.md#111-효과적인-사용을-위한-핵심-원칙) - [11.2 변경사항 명명 규칙](./openspec-11-best-practices.md#112-변경사항-명명-규칙) - [11.3 코드 작성 중 요구사항 변경 시](./openspec-11-best-practices.md#113-코드-작성-중-요구사항-변경-시) - [11.4 팀 도입 전략](./openspec-11-best-practices.md#114-팀-도입-전략) - [11.5 안티패턴 — 흔한 실패 모드](./openspec-11-best-practices.md#115-안티패턴--흔한-실패-모드) - [12. 마이그레이션 가이드](./openspec-12-migration-guide.md) - [12.1 구버전(레거시) → 최신 OPSX](./openspec-12-migration-guide.md#121-구버전레거시--최신-opsx) - [변경사항 요약](./openspec-12-migration-guide.md#변경사항-요약) - [마이그레이션 절차](./openspec-12-migration-guide.md#마이그레이션-절차) - [project.md → config.yaml 변환](./openspec-12-migration-guide.md#projectmd--configyaml-변환) — Before/After 예시, 포함/제외 기준 - [파일 보존/제거 목록](./openspec-12-migration-guide.md#파일-보존제거-목록) — 마이그레이션 후 구조도 - [기존 변경사항 재개](./openspec-12-migration-guide.md#기존-변경사항-재개) - [13. 트러블슈팅](./openspec-13-troubleshooting.md) - [13.1 일반 문제](./openspec-13-troubleshooting.md#131-일반-문제) — 8가지 케이스 (명령어 미인식, 아티팩트 미생성 등) - [13.2 CI/CD 환경 문제](./openspec-13-troubleshooting.md#132-cicd-환경-문제) - [13.3 워크스페이스 문제](./openspec-13-troubleshooting.md#133-워크스페이스-문제) - [14. 참고 자료](./openspec-14-references.md) - [공식 문서](./openspec-14-references.md#공식-문서) - [커뮤니티 자료](./openspec-14-references.md#커뮤니티-자료)