사양 우선 워크플로
코드를 작성하기 전에 요구사항을 정의합니다.
OpenSpecAI 어시스턴트를 위한 사양 기반 개발
AI 어시스턴트 프로젝트를 구축하고 관리하기 위한 경량 사양 도구입니다.
환영합니다. 여기는 OpenSpec 관련 모든 것의 집결지입니다.
OpenSpec는 여러분과 AI 코딩 어시스턴트가 코드를 작성하기 전에 무엇을 만들지 합의할 수 있도록 도와줍니다. 변경 사항을 설명하면 AI가 짧은 사양과 작업 목록을 초안으로 작성하고, 두 사람이 동일한 계획을 검토한 후 작업을 진행합니다. 더 이상 작업 중간에 AI가 잘못된 것을 만들었다는 사실을 발견하는 일이 없습니다.
다른 것을 읽지 않더라도 이 두 페이지만 읽어보세요:
/opsx:propose를 실제로 입력하는 위치 (힌트: 터미널이 아닌 AI 채팅에서). 거의 모든 사람이 한 번은 헷갈립니다.두 번째 항목은 보이는 것보다 훨씬 중요합니다. OpenSpec에는 두 가지 부분이 있습니다: 터미널에서 실행하는 명령줄 도구와 AI 어시스턴트에 전달하는 슬래시 명령어입니다. 어느 것이 어느 것인지 아는 것이 가장 흔한 혼란을 방지해 줍니다.
가장 먼저 만들어야 할 습관: 무엇을 만들지 확신이 없을 때
/opsx:explore로 시작하세요. 이는 무위험 사고 파트너로, 여러분의 코드를 읽고 옵션을 저울질하며, 어떤 산출물이나 코드가 존재하기 전에 모호한 아이디어를 구체적인 계획으로 다듬어 줍니다. Explore First 가이드에서 그 이유를 설명합니다.
완전 초보입니다. 시작하기에서 시작하고, 핵심 개념 한눈에 보기를 빠르게 훑어보세요. 뭔가 궁금할 때는 FAQ와 용어집이 바로 옆에 있습니다.
문제는 있지만 계획이 없습니다. 이 경우가 가장 흔하며, 전용 답변이 있습니다: Explore First. /opsx:explore를 사용해 어떤 것도 확정하기 전에 AI와 함께 생각해보세요.
큰 기존 코드베이스가 있습니다. 전부 문서화할 필요는 없습니다. 기존 프로젝트에서 OpenSpec 사용에서 실제 브라운필드 코드에서 어떻게 시작하는지 보여줍니다.
그냥 작동하게만 하고 싶습니다. 설치 후 openspec init를 실행하고, 명령어 작동 방식을 읽어 첫 번째 슬래시 명령어가 올바른 위치에 전달되도록 하세요. 또는 AI 지원 설치 프롬프트로 설정을 어시스턴트에게 맡기세요.
예제로 배우는 것을 좋아합니다. 예제 & 레시피 페이지에서 실제 변경 사항을 처음부터 끝까지 따라갑니다: 작은 기능, 버그 수정, 리팩토링, 탐색.
AI가 계획을 초안으로 작성했는데 — 이제 뭐를 해야 하나요? 읽어보세요. 변경 사항 검토에서 코드가 작성되기 전에 잘못된 방향으로 가고 있는지 잡아내는 2분 검수를 보여주고, 좋은 사양 작성하기에서 승인할 만한 계획의 구성 요소를 다룹니다.
팀에서 작업합니다. 팀에서 OpenSpec 사용에서 변경 사항이 브랜치와 풀 리퀘트에 어떻게 매핑되는지, 팀원들이 코드가 아닌 계획을 어떻게 검토하는지 보여줍니다.
기존 워크플로에서 넘어왔습니다. 마이그레이션 가이드에서 무엇이 변경되었고 왜 변경되었는지 설명하며, 기존 작업이 안전하다고 약속합니다.
팀 프로세스에 맞게 조정하고 싶습니다. 커스터마이징에서 프로젝트 설정, 사용자 정의 스키마, 공유 컨텍스트를 다룹니다.
무언가 깨졌습니다. 문제 해결에서 사람들이 실제로 겪는 실패 사례와 해결 방법을 모았습니다.
| 문서 | 제공 내용 |
|---|---|
| 시작하기 | 설치, 초기화, 그리고 첫 번째 변경 사항을 처음부터 끝까지 실행 |
| Explore First | /opsx:explore를 사용해 확정한 후 아이디어를 생각하기 |
| 명령어 작동 방식 | 슬래시 명령어가 실행되는 위치, "인터랙티브 모드"의 의미, 터미널 vs 채팅 |
| 핵심 개념 한눈에 보기 | 사양, 변경 사항, 델타, 아카이브 — 전체 멘탈 모델을 한 페이지에 |
| 설치 | npm, pnpm, yarn, bun, Nix, AI 어시스턴트에 설치를 맡기는 프롬프트, 그리고 작동 확인 방법 |
| 문서 | 제공 내용 |
|---|---|
| 워크플로 | 일반적인 패턴과 각 명령어를 언제 사용할지 |
| 예제 & 레시피 | 실제 변경 사항의 전체 워크스루, 복사-붙여넣기 가능 |
| 좋은 사양 작성하기 | 강력한 요구사항과 시나리오의 모습, 변경 사항의 적절한 규모 설정 |
| 변경 사항 검토 | 코드가 작성되기 전에 초안된 계획에 대한 2분 검수 |
| 팀에서 OpenSpec 사용 | 변경 사항이 브랜치, 풀 리퀘스트, 검토에 어떻게 맞물리는지 |
| 기존 프로젝트에서 OpenSpec 사용 | 대형 브라운필드 코드베이스에 OpenSpec 도입 |
| 변경 사항 편집 및 반복 | 산출물 업데이트, 되돌리기, 수동 편집 조정 |
| 명령어 | 모든 /opsx:* 슬래시 명령어 참조 |
| CLI | 모든 openspec 터미널 명령어 참조 |
| 문서 | 제공 내용 |
|---|---|
| 개념 | 사양, 변경 사항, 산출물, 스키마, 아카이브에 대한 장문 설명 |
| OPSX 워크플로 | 워크플로가 단계 고정형이 아닌 유동적인 이유, 아키텍처 심층 분석 |
| 용어집 | 모든 용어를 한 곳에서 정의 |
| 문서 | 제공 내용 |
|---|---|
| 커스터마이징 | 프로젝트 설정, 사용자 정의 스키마, 공유 컨텍스트 |
| 다국어 지원 | 영어 이외의 언어로 산출물 생성 |
| 지원 도구 | OpenSpec가 통합하는 30개 이상의 AI 도구 및 파일 저장 위치 |
| 커뮤니티 쇼케이스 | OpenSpec로 구축된 프로젝트 및 리소스 |
| 문서 | 제공 내용 |
|---|---|
| FAQ | 사람들이 가장 많이 묻는 질문에 대한 빠른 답변 |
| 문제 해결 | 구체적인 실패에 대한 구체적인 해결책 |
| 마이그레이션 가이드 | 레거시 워크플로에서 OPSX로 전환 |
| 문서 | 제공 내용 |
|---|---|
| 스토어: 사용자 가이드 | 작업이 리포지토리나 팀을 가로지를 때 전용 리포지토리에서 계획 |
| 에이전트 계약 | 에이전트가 구동하는 기계 가독성 CLI 인터페이스 |
1. Install npm install -g @fission-ai/openspec@latest
2. Initialize cd your-project && openspec init
3. Explore (in your AI chat) /opsx:explore ← optional, but a great habit
4. Propose (in your AI chat) /opsx:propose add-dark-mode
5. Build (in your AI chat) /opsx:apply
6. Archive (in your AI chat) /opsx:archive단계 1과 2는 터미널에서 수행합니다. 나머지는 AI 어시스턴트의 채팅에서 수행합니다. 이 구분이 기억할 가치가 있는 유일한 것이며, 명령어 작동 방식에서 그 이유를 정확히 설명합니다. 단계 3은 선택 사항이지만, 확신이 없을 때 /opsx:explore로 시작하는 습관은 가장 가치 있는 습관입니다.
openspec feedback "your message" 터미널에서 바로 피드백 전송 (GitHub 이슈를 엽니다).이 문서에서 잘못된 것, 오래된 것, 혼란스러운 것을 발견하셨나요? 그것은 버그입니다. 이슈나 PR을 열어주세요. 문서 개선은 여러분이 할 수 있는 가장 가치 있는 기여 중 하나입니다.