빠른 시작
새 프로젝트 또는 기존 프로젝트에서 아이디어부터 보관까지의 첫 번째 변경 사항.
시작하기 전에 컴퓨터에 CLI가 설치되어 있어야 하며(설치) 프로젝트에 OpenSpec이 초기화되어 있어야 합니다(프로젝트 설정).
빈 프로젝트에서 시작하기
선택한 스택이나 완성된 아키텍처 없이도 시작할 수 있습니다. 프로젝트 폴더에서 OpenSpec을 초기화한 다음, AI 채팅에서 에이전트에게 옵션을 함께 탐색하도록 요청하세요. AI 채팅에서:
Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.첫 번째 변경에 필요한 사항을 결정하고 나중의 아키텍처 선택은 열어두세요. 에이전트에게 그 한 가지 변경을 제안하도록 요청한 다음, 아래 단계를 따르세요. 프로젝트가 성장함에 따라 아키텍처를 다시 검토할 수 있습니다.
한눈에 보는 루프
모든 변경은 동일한 다섯 단계를 거칩니다: 에이전트와 함께 아이디어를 검토하고, 에이전트가 계획을 초안 작성하며, 코드가 만들어지기 전에 계획을 수정하고, 에이전트가 그것을 바탕으로 구현하며, 보관이 출시된 사항으로 스펙을 업데이트합니다.
flowchart LR
explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
propose --> review["3 · Review<br/>you correct the plan"]
review --> apply["4 · Apply<br/>agent builds, task by task"]
apply --> archive["5 · Archive<br/>specs absorb the change"]
archive -. "next change" .-> explore
아래의 모든 프롬프트는 코드를 요청하는 것과 같은 AI 채팅에 입력됩니다. 예제는 도구 전반에 걸쳐 작동하도록 일상적인 언어를 사용합니다. 스킬을 직접 호출할 수도 있습니다. 구문은 도구에 따라 다릅니다(지원 도구).
1단계: 탐색
계획을 요청하기 전에 에이전트와 함께 아이디어를 검토하세요. AI 채팅에서:
Help me explore how rate limiting should work in this app.탐색은 사고 모드입니다. 에이전트는 코드베이스를 조사하고, 중요한 질문을 하며, 옵션을 스케치하고, 가정에 이의를 제기합니다. 코드를 작성하지 않습니다. 결정한 사항을 기록하라는 요청을 하거나, 제안했을 때 동의하지 않는 한 다른 것도 작성하지 않습니다. 결과물은 더 날카로운 아이디어입니다.
문제에 필요한 만큼 여기 머무르세요. 형태가 적절해 보이면 이양하세요:
Propose the change we just discussed.이 줄은 합의한 모든 것을 전달하면서 제안 단계를 시작합니다. 2단계의 첫 번째 프롬프트는 건너뛰세요.
2단계: 제안
제안은 아이디어를 검토 가능한 계획으로 바꿉니다. 탐색에서 오면 이미 실행 중입니다. 변경 사항이 머릿속에 명확할 때 새로 시작하면 직접 요청하세요. AI 채팅에서:
Propose a change to add rate limiting.에이전트는 필요한 것을 묻고 변경 폴더를 작성합니다:
openspec/changes/add-rate-limiting/
├── proposal.md 이유, 그리고 무엇이 변경되는지
├── specs/ "완료"의 의미, 테스트 가능한 요구 사항으로
├── design.md 기술적 결정 (변경에 필요한 경우에만)
└── tasks.md 구현 체크리스트아직 코드는 없습니다. 제안은 계획에서 멈춥니다.
3단계: 계획 검토 및 수정
아직 코드가 만들어지기 전에, 단어만 있는 동안 계획을 수정하세요. 다음 순서로 읽으세요:
proposal.md: 이것이 올바른 문제이며 적절한 규모입니까?specs/: 가치가 가장 높은 읽기입니다. 이러한 요구 사항을 완료된 것으로 수용하시겠습니까?tasks.md: 작업이 스펙을 다루고 그 외에는 아무것도 다루지 않습니까?
무언가를 수정하려면 다음 중 하나가 작동합니다:
- 파일을 직접 편집하세요. 아티팩트는 일반 마크다운이며 파일이 계획입니다.
- 에이전트에게 무엇이 잘못되었는지 말하세요("스펙에 인증되지 않은 경우가 누락되었습니다"). 에이전트가 아티팩트를 수정합니다.
4단계: 적용
적용은 계획을 코드로 바꿉니다. 구현은 깨끗한 컨텍스트 창에서 더 잘 진행되므로 새 채팅 세션을 시작하세요. AI 채팅에서:
Apply the add-rate-limiting change.에이전트는 변경 폴더를 읽은 다음 tasks.md를 진행하며 각 작업이 완료될 때마다 체크합니다.
- 중단되거나 컨텍스트를 초과했나요? 새 세션을 열고 다시 적용하도록 요청하세요. 첫 번째 체크되지 않은 작업에서 재개합니다.
- 계획이 잘못된 것으로 밝혀졌나요? 아티팩트를 수정하고(3단계의 두 가지 방법 중 하나로) 적용을 계속하세요.
- 진행 상황은
tasks.md체크박스에 있습니다. 숨겨진 상태는 없습니다.
5단계: 보관
보관은 두 가지를 수행합니다: 변경의 요구 사항으로 기본 스펙을 업데이트하고, 변경 폴더를 보관 폴더로 이동합니다(/openspec/changes/archive/*에).
tasks.md의 모든 박스가 체크되면 AI 채팅에서:
Archive the add-rate-limiting change.보관이 수행하는 작업을 단계별로 살펴봅니다:
## 완료된 변경
> 구현이 완료되었습니다. 델타 스펙(이 변경이 추가하는 것)이 여전히 변경 폴더 안에 있습니다; specs/는 아직 rate limiting에 대해 알지 못합니다.
openspec/
├── specs/ (아직 rate-limiting 스펙 없음)
└── changes/
└── add-rate-limiting/
├── proposal.md
├── tasks.md 모든 박스 체크됨
└── specs/
└── rate-limiting/
└── spec.md 델타: ADDED requirements
## 요구 사항이 specs/에 적용됨
> 델타의 각 요구 사항이 기본 스펙에 적용됩니다: 추가된 것은 추가되고, 수정된 것은 이전 버전을 대체합니다. 새로운 기능은 새 스펙 파일을 가져옵니다.
openspec/
├── specs/
+ │ └── rate-limiting/
+ │ └── spec.md "Requirement: Rate limiting"을 획득
└── changes/
└── add-rate-limiting/
└── specs/
└── rate-limiting/
└── spec.md 델타, 병합의 원천
## 폴더가 archive/로 이동
> 델타를 포함한 전체 변경 폴더가 날짜 접두사 아래 보관소로 이동합니다. 아무것도 삭제되지 않습니다.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md
└── changes/
- └── add-rate-limiting/
+ └── archive/
+ └── 2026-08-08-add-rate-limiting/
+ ├── proposal.md
+ ├── tasks.md
+ └── specs/rate-limiting/spec.md
## 스펙이 구축된 시스템을 설명함
> changes/는 다음 변경을 위해 비워있습니다. specs/는 시스템이 수행하는 작업에 대한 진실의 원천입니다; archive/는 그곳에 도달한 방법의 역사입니다.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md 구축된 스펙
└── changes/
└── archive/
└── 2026-08-08-add-rate-limiting/Git는 별개의 문제입니다. 변경 폴더를 코드와 함께 커밋하고, 워크플로우에 대한 다른 것은 변경되지 않습니다.
보관된 변경 유지 또는 정리
openspec/changes/archive/는 각 완료된 변경에 대한 제안, 설계, 작업 및 델타를 유지합니다. 위의 보관 흐름에서 델타는 이미 openspec/specs/를 업데이트했습니다.
- 전체 변경 폴더를 유지하세요: 현재 체크아웃에서 자체 완비 기록을 원할 때.
- 보관된 변경의
specs/폴더를 제거하세요: Git이 스펙 역사일 때. 먼저 보관소를 커밋한 다음openspec/changes/archive/<change>/specs/를 삭제하세요. 제안, 설계 및 작업은 체크아웃에 남아 있습니다.openspec validate --archived는 적용된 델타가 아닌 작업 완료를 확인하기 때문에 여전히 작동합니다. - 전체 변경 폴더를 제거하세요: 더 이상 체크아웃에 제안, 설계 또는 작업 역사가 필요하지 않을 때만. 현재 스펙은 변경되지 않지만
openspec validate --archived와 체크아웃 검색에 더 이상 해당 변경이 포함되지 않습니다.
WARNING
Git이 삭제된 파일을 보존하길 원하면 보관 커밋을 저장소 역사에 유지하세요. 보관 및 정리 커밋을 함께 스쿼시하면 중간 스냅샷이 제거됩니다.
OpenSpec은 보관된 변경을 자동으로 정리하거나 보존 설정을 제공하지 않습니다.
더 나아가기
고급 가이드
아직 작성되지 않았습니다; 추가할 예정인 가이드:
- 프로토타입 먼저: 스펙 전에 코드를 스파이크하고, 프로토타입에서 배운 것으로 제안을 백필합니다.
- 반복적 구축: 하나의 큰 제안 대신 작은 변경의 순서.
- 구현된 변경 수정: 적용 후 계획이 다시 이동해야 하지만 변경이 아직 병합 또는 보관되지 않았습니다.