사양 우선 워크플로우
코드 작성 전에 요구사항을 정의하세요.
OpenSpecAI 어시스턴트를 위한 사양 기반 개발
AI 어시스턴트 프로젝트를 구축하고 관리하기 위한 경량 사양입니다.
환영합니다. 이것이 OpenSpec의 모든 문서 홈입니다.
OpenSpec는 코드가 작성되기 전에 여러분과 AI 코딩 어시스턴트가 무엇을 구축할지 합의하는 것을 도와줍니다. 변경 사항을 설명하면 AI가 짧은 사양과 작업 목록을 초안으로 작성하고, 여러분 모두가 같은 계획을 검토한 후 작업이 진행됩니다. 이제 작업이 절반 진행된 후에 AI가 잘못된 것을 구축했다는 것을 발견하는 일은 없습니다.
다른 내용을 읽지 않더라도 이 두 페이지만 읽으세요:
/opsx:propose를 입력하는 위치(힌트: 터미널이 아닌 AI 채팅입니다). 이 부분은 거의 모든 사람이 한 번씩 혼동하는 부분입니다.두 번째 항목이 생각보다 중요합니다. OpenSpec는 두 부분으로 나뉘어 있습니다: 터미널에서 실행하는 명령줄 도구와 AI 어시스턴트에 제공하는 슬래시 명령어. 어느 것이 어느 것인지 알면 가장 흔한 혼란을 피할 수 있습니다.
가장 먼저 길러야 할 습관: 구축할 것이 확실하지 않을 때는
/opsx:explore로 시작하세요. 코드가 존재하기 전에 코드를 읽고, 옵션을 평가하며, 모호한 아이디어를 구체적인 계획으로 다듬는 부담 없는 사고 파트너입니다. 먼저 탐색하기 가이드에서 그 이유를 설명합니다.
완전히 새로 시작하는 경우. 시작하기부터 시작한 다음 핵심 개념 한눈에 보기를 훑어보세요. 어떤 부분이 낯설게 느껴지면 자주 묻는 질문과 용어 사전이 가까이 있습니다.
계획은 없지만 문제가 있는 경우. 이는 흔한 경우이며 전용 답변이 있습니다: 먼저 탐색하기. /opsx:explore를 사용하여 무언가에 커밋하기 전에 AI와 함께 생각을 정리하세요.
기존 대규모 코드베이스가 있는 경우. 전체를 문서화할 필요는 없습니다. 기존 프로젝트에서 OpenSpec 사용하기에서 바다를 끓이지 않고 실제 레거시 코드에서 시작하는 방법을 보여줍니다.
그냥 작동하게 만들고 싶은 경우. 설치를 실행하고, openspec init를 실행한 다음 명령어 작동 방식을 읽어 첫 번째 슬래시 명령어가 올바른 위치에 전달되도록 하세요.
예시로 배우는 것을 좋아하는 경우. 예시 & 레시피 페이지에서 실제 변경 사항을 처음부터 끝까지 살펴봅니다: 작은 기능, 버그 수정, 리팩토링, 탐색.
AI가 방금 계획을 초안으로 작성했습니다 — 이제 뭘 하죠? 읽으세요. 변경 사항 검토에서 코드가 작성되기 전에 잘못된 방향을 잡을 수 있는 2분 검토 방법을 설명하고, 좋은 사양 작성하기에서 승인할 만한 계획이 어떻게 구성되는지 다룹니다.
팀에서 작업하는 경우. 팀에서 OpenSpec 사용하기에서 변경 사항이 브랜치와 풀 리퀘스트에 매핑되는 방법과 팀원들이 코드 전에 계획을 검토하는 방법을 보여줍니다.
기존 워크플로우에서 넘어온 경우. 마이그레이션 가이드에서 변경된 내용과 이유를 설명하며 기존 작업이 안전하다고 보장합니다.
팀의 프로세스에 맞게 조정하고 싶은 경우. 커스터마이징에서 프로젝트 설정, 커스텀 스키마, 공유 컨텍스트를 다룹니다.
무언가가 작동하지 않는 경우. 문제 해결에서 사람들이 실제로 겪는 오류와 해결 방법을 모았습니다.
| 문서 | 제공하는 내용 |
|---|---|
| 시작하기 | 설치, 초기화, 첫 번째 변경 사항을 엔드 투 엔드로 실행 |
| 먼저 탐색하기 | /opsx:explore를 사용하여 커밋하기 전에 아이디어를 생각 정리 |
| 명령어 작동 방식 | 슬래시 명령어가 실행되는 위치, "대화형 모드"의 의미, 터미널 vs 채팅 |
| 핵심 개념 한눈에 보기 | 한 페이지에 담은 전체 정신 모델: 사양, 변경 사항, 델타, 아카이브 |
| 설치 | npm, pnpm, yarn, bun, Nix, 작동 확인 방법 |
| 문서 | 제공하는 내용 |
|---|---|
| 워크플로우 | 일반적인 패턴과 각 명령어를 사용해야 하는 시점 |
| 예시 & 레시피 | 실제 변경 사항의 전체 워크스루, 복사-붙여넣기 가능 |
| 좋은 사양 작성하기 | 강력한 요구사항과 시나리오의 모습, 변경 사항 크기 조정 방법 |
| 변경 사항 검토 | 코드가 작성되기 전 초안 계획에 대한 2분 검토 |
| 팀에서 OpenSpec 사용하기 | 변경 사항이 브랜치, 풀 리퀘스트, 검토에 맞는 방식 |
| 기존 프로젝트에서 OpenSpec 사용하기 | 대규모 레거시 코드베이스에 OpenSpec 채택 방법 |
| 변경 사항 편집 & 반복 | 아티팩트 업데이트, 돌아가기, 수동 편집 조정 |
| 명령어 | 모든 /opsx:* 슬래시 명령어 참조 |
| CLI | 모든 openspec 터미널 명령어 참조 |
| 문서 | 제공하는 내용 |
|---|---|
| 개념 | 사양, 변경 사항, 아티팩트, 스키마, 아카이브에 대한 장문 설명 |
| OPSX 워크플로우 | 워크플로우가 유동적인 이유와 단계 고정이 아닌 이유, 아키텍처 심층 분석 |
| 용어 사전 | 모든 용어가 한 곳에 정의되어 있습니다 |
| 문서 | 제공하는 내용 |
|---|---|
| 커스터마이징 | 프로젝트 설정, 커스텀 스키마, 공유 컨텍스트 |
| 다국어 지원 | 영어 외 언어로 아티팩트 생성 |
| 지원 도구 | OpenSpec가 통합하는 25개 이상의 AI 도구와 파일 저장 위치 |
| 문서 | 제공하는 내용 |
|---|---|
| 자주 묻는 질문 | 가장 많이 묻는 질문에 대한 빠른 답변 |
| 문제 해결 | 실제 발생하는 오류에 대한 구체적인 해결 방법 |
| 마이그레이션 가이드 | 기존 워크플로우에서 OPSX로 이동하는 방법 |
| 문서 | 제공하는 내용 |
|---|---|
| 스토어: 사용자 가이드 | 작업이 여러 리포지토리나 팀에 걸쳐 있을 때 자체 리포지토리에 계획 |
| 에이전트 계약 | 에이전트가 구동하는 기계 판독 가능한 CLI 표면 |
1. 설치 npm install -g @fission-ai/openspec@latest
2. 초기화 cd your-project && openspec init
3. 탐색 (AI 채팅에서) /opsx:explore ← 선택 사항이지만 좋은 습관입니다
4. 제안 (AI 채팅에서) /opsx:propose add-dark-mode
5. 구축 (AI 채팅에서) /opsx:apply
6. 아카이브 (AI 채팅에서) /opsx:archive1단계와 2단계는 터미널에서 실행합니다. 나머지는 AI 어시스턴트의 채팅에서 실행합니다. 이 구분은 기억할 가치가 있는 유일한 것이며 명령어 작동 방식에서 정확한 이유를 설명합니다. 3단계는 선택 사항이지만, 확실하지 않을 때 /opsx:explore로 시작하는 습관이 가장 가치 있습니다.
openspec feedback "your message" 터미널에서 직접 피드백을 보냅니다(GitHub 이슈를 엽니다).이 문서에 잘못된 내용, 오래된 내용, 혼동되는 내용이 있나요? 그것은 버그입니다. 이슈나 PR을 열어주세요. 문서 개선은 여러분이 할 수 있는 가장 가치 있는 기여 중 하나입니다.