핵심 개념 요약

OpenSpec은 사용자와 AI 사이의 경량화된 합의 계층입니다. 사용자는 변경 사항이 무엇을 해야 하는지 기술하고, AI가 세부 사항을 초안 작성합니다. 두 분 모두 동일한 계획을 검토한 후에야 코드가 작성됩니다. 이 페이지는 모든 정신 모델을 한 화면에 담고 있습니다. 더 긴 버전이 필요하다면 Concepts를 참조하십시오.

핵심 아이디어는 다섯 단어로 요약할 수 있습니다: 먼저 합의하고, 확신을 가지고 구축합니다.

다섯 가지 아이디어

OpenSpec의 모든 것은 다섯 가지 개념에서 파생됩니다. 이들을 이해하면 나머지는 세부 사항일 뿐입니다.

1. 명세(Specs)가 진실입니다. 명세는 시스템이 현재 어떻게 작동하는지를 설명합니다. 이는 openspec/specs/에 존재하며, 도메인(auth/, payments/, ui/)별로 구성됩니다. 명세는 요구 사항("시스템은 30분 후에 세션을 만료시켜야 한다")과 시나리오(구체적인 given/when/then 예시)로 이루어집니다. 명세를 "이 소프트웨어가 무엇을 하는가?"에 대한 단일 합의된 답변으로 생각하십시오.

2. 변경 사항은 하나의 작업 단위입니다. 동작을 추가, 수정 또는 제거하고자 할 때, 사용자는 변경 사항을 생성합니다. 이는 openspec/changes/ 내부에 해당 작업을 담는 폴더이며, 그 작업과 관련된 모든 것을 한곳에 모아둡니다. 제안서(proposal), 설계(design), 작업 목록, 그리고 명세 편집본이 포함됩니다. 하나의 변경 사항, 하나의 폴더, 하나의 기능입니다.

3. 델타 명세(Delta specs)는 전체 세계가 아니라 변화하는 부분을 설명합니다. 변경 사항 내부에서 전체 명세를 다시 작성할 필요는 없습니다. 작은 델타를 작성합니다: 이 요구 사항을 ADDED(추가), 저것을 MODIFIED(수정), 저것을 REMOVED(제거). 이것이 OpenSpec이 그린필드(green-field) 프로젝트뿐만 아니라 기존 시스템을 편집하는 데 능숙한 이유입니다. 목적지지가 아닌 차이점(diff)을 설명합니다.

4. 아티팩트(Artifacts)는 서로를 기반으로 구축됩니다. 하나의 변경 사항에는 몇 가지 문서가 포함되며, 이들은 자연스러운 순서로 생성되고 각자가 다음 단계에 영향을 줍니다:

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

언제든지 이들 중 어느 것을 다시 살펴볼 수 있습니다. 이들은 통과해야 할 관문(gate)이 아니라 가능하게 하는 요소(enabler)입니다. (아래에서 더 자세히 설명합니다.)

5. 아카이브(Archiving)는 변경 사항을 진실 속으로 되돌립니다. 작업이 완료되면, 사용자는 해당 변경 사항을 아카이브합니다. 그 델타 명세가 메인 명세에 병합되고, 변경 폴더는 날짜 스탬프와 함께 changes/archive/로 이동합니다. 이제 명세는 새로운 현실을 설명하며, 다음 변경 사항을 준비할 수 있습니다. 순환이 완료됩니다.

개요 (The picture)

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

두 개의 폴더. specs/는 진실입니다. changes/는 제안 중인 내용입니다. 아카이브를 통해 제안이 진실 속으로 이동합니다.

실제로 실행하게 될 루프

기본 설정에서 하루의 흐름은 다음과 같습니다. 선택적으로 먼저 생각해보십시오. 그런 다음 한 명령어가 계획을 초안 작성하고, 사용자가 읽고 조정하며, 다음 단계가 구축하고, 마지막 단계가 파일을 정리합니다.

/opsx:explore                   →  (선택 사항) AI와 함께 먼저 생각해보기
/opsx:propose add-dark-mode     →  AI가 제안서, 명세, 설계를 초안 작성함
        (사용자가 계획을 읽고 조정)
/opsx:apply                     →  AI가 작업을 구축하고, 태스크를 체크함
/opsx:archive                   →  명세 업데이트, 변경 사항 아카이브

의문이 들 때, 탐색(/opsx:explore)부터 시작하십시오. /opsx:explore는 위험 부담 없는 사고 파트너입니다. 이는 사용자의 코드를 읽고 옵션을 제시하며, 어떤 아티팩트가 존재하기 전에 모호한 아이디어를 구체적인 계획으로 바꿉니다. 이는 그렇지 않으면 AI가 모호한 프롬프트로부터 무언가를 구축할 것이라는 점에 대한 최고의 해독제입니다. 원하는 것을 정확히 알고 있습니까? /opsx:propose로 바로 이동하십시오. 어느 쪽이든, 탐색은 기본 프로필드에 포함되어 있으므로 항상 존재합니다. Explore guide를 참조하십시오.

이들은 AI 어시스턴트의 채팅창에 입력하는 슬래시 명령어입니다. 설정(openspec init)은 터미널에서 수행됩니다. 이 분할(split)이 낯설다면, 먼저 How Commands Work를 읽으십시오. 이것이 가장 흔한 혼란 지점입니다.

"가능하게 하는 요소이지, 강제하는 관문이 아니다"

이 문구는 OpenSpec의 모든 곳에 나타나므로, 이를 평범한 용어로 설명합니다.

전통적인 명세 프로세스는 폭포수와 같습니다: 계획을 완료하고 그 후에야 구현할 수 있으며, 되돌아가기는 고통스럽습니다. OpenSpec은 이를 거부합니다. proposal → specs → design → tasks 순서는 다음에 무엇이 가능해지는지를 보여줄 뿐, 다음에 무엇을 강제해야 하는지를 보여주지 않습니다.

구현 과정에서 설계가 잘못되었다는 것을 발견했습니까? design.md를 편집하고 계속 진행하십시오. 범위가 축소되어야 한다고 깨달았습니까? 제안서를 업데이트하십시오. 아무것도 잠기지 않습니다. 의존성은 AI가 필요한 맥락을 갖도록 존재할 뿐입니다 (명세를 기반으로 하지 않으면 좋은 태스크를 작성할 수 없습니다). 사용자를 가두기 위함이 아닙니다.

여기서의 강점은 정직함에 있습니다: 실제 작업은 지저분하고 반복적이며, OpenSpec은 이를 허용합니다. 트레이드오프는 규율입니다: 아무것도 당신을 앞으로 나아가도록 강제하지 않기 때문에, 변경 사항이 산만해지게 두기보다는 집중 상태를 유지하는 것은 사용자에게 달려 있습니다. Workflows 가이드에는 이를 위한 좋은 습관리가 담겨 있습니다.

이 작은 오버헤드가 가치 있는 이유

솔직히 말해서: OpenSpec은 단계를 추가합니다. 구축하기 전에 짧은 계획을 작성해야 합니다. 그렇다면 무엇을 얻게 됩니까?

• 비용이 발생하기 전에 잘못된 방향을 잡아냅니다. 한 문단짜리 제안서에서 오해를 수정하는 것은 무료입니다. AI가 400줄을 작성한 후에 이를 수정하는 것은 그렇지 않습니다.
• 계획과 코드는 같은 레포지토리(repo)에 있습니다. 반년 후에도 명세는 시스템이 왜 그렇게 작동하는지를 (그리고 다음 AI 세션에게) 알려줍니다.
• 변경 사항은 검토할 수 있습니다. 변경 폴더는 깔끔한 패키지입니다: 제안서를 읽고, 델타를 훑어보고, 태스크를 확인하십시오. 채팅 기록을 통해 고고학적 발굴을 할 필요가 없습니다.
• 기존 코드베이스에 맞습니다. 델타 덕분에 전체를 문서화하지 않고도 50,000줄짜리 앱의 변경 사항을 지정할 수 있습니다.

그리고 솔직한 트레이드오프: 정말 사소한 한 줄 수정에 대해서는 이 의식(ceremony)이 가치가 없을 수도 있으며, 그것은 괜찮습니다. OpenSpec은 경량화되도록 설계되었지만, 공짜가 아닙니다. 합의가 중요한 곳에 사용하십시오. AI와 함께 작업할 때 대부분의 경우에 그렇다는 것을 알게 될 것입니다. 그 AI는 당신이 모호하게 요청한 모든 것을 확신을 가지고 구축해낼 것이기 때문입니다.

다음으로 나아갈 길

• 처음인가요? Getting Started에서 첫 번째 변경 사항을 완전히 다룹니다.
• 무엇을 만들어야 할지 모르겠습니까? Explore First가 시작할 곳입니다.
• 명령어가 어디서 실행되는지에 대해 혼란스럽습니까? How Commands Work.
• 위 내용의 심층적인 버전을 원하십니까? Concepts.
• 예시를 통해 배우고 싶으십니까? Examples & Recipes.
• 용어 정의가 필요합니까? Glossary.