개요
OpenSpec은 AI 코딩 워크플로우에 경량 스펙 레이어를 추가하여 사람과 AI가 코드를 작성하기 전에 요구사항을 일치시키도록 보장합니다. 20개 이상의 AI 어시스턴트를 위한 슬래시 명령을 제공하고, 기능별로 변경 사항을 구성합니다.
README 미리보기
\n \n \n \n \n \n \n\n\n\n \n \n \n \n\n\n\nThe most loved spec framework.\n\n[](https://github.com/Fission-AI/OpenSpec/stargazers)\n[](https://www.npmjs.com/package/@fission-ai/openspec)\n[](https://github.com/Fission-AI/OpenSpec/graphs/contributors)\n\n\n\nOur philosophy:\n\n```text\n→ fluid not rigid\n→ iterative not waterfall\n→ easy not complex\n→ built for brownfield not just greenfield\n→ scalable from personal projects to enterprises\n```\n\n> [!TIP]\n> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.\n>\n> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)\n\n\n Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.\n\n\n\n\n## See it in action\n\n```text\nYou: /opsx:explore\nAI: What would you like to explore?\nYou: I want dark mode but I'm not sure how to do it cleanly.\nAI: Let me look at your styling setup...\n Cleanest path here: CSS variables + a small theme context,\n with system-preference detection. No new dependencies. Scope it?\nYou: Yes, let's do it.\n\nYou: /opsx:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n\nYou: /opsx:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n\nYou: /opsx:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n\nOpenSpec Dashboard\n\n\n \n\n\n\n\n## Quick Start\n\n**Requires Node.js 20.19.0 or higher.**\n\nInstall OpenSpec globally:\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\nThen navigate to
FAQ (5)
방법Node.js 없이 OpenSpec을 설치하는 방법 (독립 실행형 바이너리)
v1.15.0부터 OpenSpec은 Node.js가 필요 없는 독립 실행형 바이너리를 제공합니다. 다음 명령으로 설치하세요:
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex이전에 npm으로 설치한 경우 openspec install을 실행하여 독립 실행형 바이너리 버전으로 전환하세요. 자세한 내용은 저장소의 docs/installation.md에 있는 설치 가이드에서 확인할 수 있습니다.
문제 해결요구사항이 500자를 초과하는데도 `openspec validate --strict`가 통과하는 이유는 무엇이며, CI에서 이 제한을 어떻게 강제할 수 있나요?
OpenSpec **1.14.1 이상**으로 업그레이드하세요. 이전에는 overlong-requirement 발견 사항이 INFO로 보고되었기 때문에 openspec validate --all --strict가 상태 0으로 종료되었습니다. 1.14.1+에서는 **500자**를 초과하는 요구사항 설명으로 인해 strict 유효성 검사가 실패합니다. 다음 명령으로 품질 게이트를 실행하세요:
openspec validate --all --strict기존 발견 사항을 수정하려면 의미를 변경하지 않으면서 긴 요구사항을 여러 개의 작은 요구사항으로 분할하세요. 단순히 잘라내지 마세요. 에이전트 작성 지침에도 이제 500자 제한이 문서화되어 있어 새로운 overlong 요구사항이 발생하는 것을 방지합니다.
문제 해결활성 변경 사항이 계속 보이도록 `openspec view`에서 아카이브된 변경 사항을 숨기려면 어떻게 해야 하나요?
이 문제는 아카이브된 변경 사항을 openspec view 대시보드에 추가한 PR #399에서 발생한 회귀입니다. 이는 PR fix(view): keep archived changes off the dashboard(이슈 #2030 종료)에서 수정되었습니다. 해당 수정이 포함된 릴리스로 OpenSpec을 업그레이드한 후 openspec view를 다시 실행하세요. 그러면 아카이브된 변경 사항이 더 이상 진행 중인 작업을 화면 밖으로 밀어내지 않습니다. 임시 해결 방법으로는 openspec list를 사용하세요.
문제 해결allowedEditRoots가 declaring repo와 충돌하여 OpenSpec apply skill이 store-backed 변경 사항을 거부하는 문제를 해결하는 방법
OpenSpec 1.13.1에서는 openspec status --change <name> --json --store plans가 구현 편집이 선언 리포(예: /path/to/app)에서 이루어져야 함에도 불구하고 actionContext.allowedEditRoots를 스토어 루트(예: /path/to/plans)만으로 잘못 설정할 수 있습니다. 이 경우 생성된 apply 스킬은 리포 컨텍스트가 CLI가 제어하는 값과 충돌하는 것으로 처리하고 0/N 작업에서 중단됩니다.
해결 방법: PR fix(status): include the declaring repo in store-backed edit roots가 포함된 OpenSpec 릴리스로 업그레이드하세요(또는 커밋 0d814f39 이후에서 빌드하세요). 수정 후 다음 명령으로 확인하세요:
openspec status --change <name> --json --store plansactionContext.allowedEditRoots에는 두 루트가 모두 포함되어야 합니다:
["/path/to/app", "/path/to/plans"]스토어 루트는 계획 아티팩트를 보유하고, 선언 리포 루트는 구현 편집을 보유합니다. mode와 출력 계약은 변경되지 않습니다.
임시 해결 방법: 에이전트의 거부를 수동으로 재정의하고 선언 리포와 스토어 루트 모두에서의 편집을 명시적으로 승인하세요. 이때 버그가 있는 status 출력의 allowedEditRoots가 계획 아티팩트만으로 제한되는 것이 아님을 명확히 해야 합니다.
문제 해결'Archive the change' 및 'Verify archived result' 작업이 아카이빙을 차단할 때 OpenSpec 순환 종속성을 해결하는 방법은?
OpenSpec 1.14.1+로 업그레이드하세요. 이 버전에서는 openspec instructions apply가 변경 사항이 아카이브될 준비가 되었다고 선언하는 대신 추적된 작업의 완료만 보고합니다. tasks.md에서는 아카이브 전에 완료할 수 있는 작업만 - [ ] 체크박스로 유지하세요. 아카이브에 의존하는 단계는 일반 글머리 기호 섹션으로 옮겨 작업 수에 영향을 주지 않도록 하세요:
## 워크플로 후속 작업
- 프로젝트의 검토 요구 사항이 충족된 후 변경 사항을 아카이브하세요.
- 아카이브된 결과를 확인하세요.완료 메시지는 이제 다음과 같습니다: "All tracked tasks are complete. Review or verify the change as appropriate before archiving." state: "all_done", 작업 파싱, 유효성 검사, 아카이브 동작 및 플래그는 변경되지 않습니다. 이전 순정 OpenSpec에서는 경고를 확인하거나 --yes를 사용할 수 있습니다. 미완료 작업이 0개여야 하는 더 엄격한 사용자 지정 정책을 사용하는 경우 정책을 업데이트하거나 아카이브에 의존하는 작업을 추적 목록에서 옮겨야 합니다.