핵심 개념 한눈에 보기

OpenSpec은 사용자와 AI 사이의 가벼운 합의 계층입니다. 변경 사항의 동작을 기록하고 AI가 세부 내용을 작성하면, 두 사람이 같은 계획을 확인한 다음에야 코드 작성을 시작합니다. 이 페이지에서 전체 개념을 한눈에 볼 수 있습니다. 자세한 설명은 개념을 참조하세요.

핵심을 다섯 단어로 요약하면 다음과 같습니다. 먼저 합의하고, 확신을 갖고 구현하기.

다섯 가지 핵심 개념

OpenSpec의 모든 기능은 다섯 가지 개념을 바탕으로 합니다. 이를 이해하면 나머지는 세부 사항입니다.

1. 사양이 기준 정보입니다. 사양은 시스템이 현재 어떻게 동작하는지 설명합니다. openspec/specs/에 도메인(auth/, payments/, ui/)별로 구성됩니다. 요구 사항(“시스템은 30분 후 세션을 만료해야 한다(SHALL)”)과 구체적인 Given/When/Then 예제인 시나리오로 이루어집니다. 사양을 “이 소프트웨어는 무엇을 하나요?“에 대한 하나의 합의된 답이라고 생각하세요.

2. 변경 사항은 하나의 작업 단위입니다. 동작을 추가, 수정 또는 삭제하려면 변경 사항을 만듭니다. openspec/changes/ 아래의 폴더 하나에 제안, 설계, 작업 목록, 사양 수정 등 해당 작업에 필요한 모든 내용을 담습니다. 변경 사항 하나, 폴더 하나, 기능 하나입니다.

3. 델타 사양은 전체가 아니라 바뀌는 내용을 설명합니다. 변경 사항 안에서 전체 사양을 다시 쓰지 않고 작은 델타를 작성합니다. 이 요구 사항은 ADDED, 저 요구 사항은 MODIFIED, 다른 요구 사항은 REMOVED로 표시합니다. 덕분에 OpenSpec은 새 프로젝트뿐 아니라 기존 시스템을 수정하는 데도 효과적입니다. 최종 상태가 아니라 차이를 설명합니다.

4. 산출물은 서로를 바탕으로 작성됩니다. 변경 사항에는 자연스러운 순서에 따라 작성되고 다음 단계의 입력이 되는 몇 가지 문서가 포함됩니다.

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

언제든 각 문서로 돌아가 수정할 수 있습니다. 이들은 관문이 아니라 다음 작업을 가능하게 하는 요소입니다. (자세한 내용은 아래에서 설명합니다.)

5. 보관하면 변경 사항이 기준 정보에 반영됩니다. 작업이 끝나면 변경 사항을 보관합니다. 델타 사양이 기본 사양에 병합되고 변경 사항 폴더는 날짜가 포함된 changes/archive/로 이동합니다. 이제 사양은 새로운 상태를 설명하며 다음 변경 사항을 시작할 수 있습니다. 주기가 완료됩니다.

구조 한눈에 보기

┌─────────────────────────────────────────────────────────────────┐
│                          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                   →  (optional) think it through with the AI first
/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
        (you read and adjust the plan)
/opsx:apply                     →  AI builds it, checking off tasks
/opsx:archive                   →  specs updated, change archived

확신이 서지 않을 때는 탐색부터 시작하세요. /opsx:explore는 코드를 읽고 선택지를 제시하며, 코드를 작성하기 전에 모호한 아이디어를 구체적인 계획으로 바꾸는 부담 없는 사고 파트너입니다. 막연한 요청만으로도 무언가를 만들어 버리는 AI에 대한 최고의 해결책입니다. 원하는 바를 정확히 알고 있나요? 바로 /opsx:propose로 넘어가세요. 탐색은 기본 프로필에 포함되어 있어 언제든 사용할 수 있습니다. 탐색 안내서를 참조하세요.

슬래시 명령은 AI 어시스턴트 채팅에 입력합니다. 설정(openspec init)은 터미널에서 진행합니다. 이 차이가 익숙하지 않다면 가장 흔한 혼동 지점을 설명하는 명령 작동 방식을 먼저 읽어 보세요.

“관문이 아니라 촉진 요소”

OpenSpec에서 자주 사용하는 표현입니다. 쉽게 설명하면 다음과 같습니다.

전통적인 사양 프로세스는 폭포수 방식입니다. 계획을 마쳐야만 구현할 수 있고, 되돌아가기 어렵습니다. OpenSpec은 이런 방식을 따르지 않습니다. proposal → specs → design → tasks 순서는 다음에 가능해지는 작업을 보여 줄 뿐, 반드시 다음에 해야 하는 작업을 강제하지 않습니다.

구현 중 설계가 잘못됐다는 사실을 알게 됐나요? design.md를 수정하고 계속 진행하세요. 범위를 줄여야 한다는 것을 깨달았나요? 제안을 업데이트하세요. 잠기는 것은 없습니다. 의존성이 있는 이유는 AI에 필요한 맥락을 제공하기 위해서일 뿐(기반이 되는 사양 없이 좋은 작업 목록을 만들 수는 없습니다), 사용자를 제한하기 위해서가 아닙니다.

이 방식의 장점은 실제 작업이 복잡하고 반복적이라는 사실을 인정한다는 점이며, OpenSpec은 그런 방식으로 일할 수 있게 합니다. 대신 규율이 필요합니다. 무엇도 다음 단계로 진행하도록 강제하지 않으므로 변경 사항의 범위가 커지지 않도록 직접 관리해야 합니다. 워크플로 안내서에서 유용한 습관을 확인하세요.

약간의 추가 작업이 가치 있는 이유

솔직히 말해 OpenSpec은 단계를 하나 더 추가합니다. 구현 전에 짧은 계획을 작성합니다. 그 대가로 무엇을 얻을까요?

• 비용이 들기 전에 잘못된 방향을 발견합니다. 한 문단짜리 제안의 오해를 수정하는 데는 비용이 들지 않습니다. AI가 400줄을 작성한 뒤 고치는 일은 그렇지 않습니다.
• 계획과 코드가 같은 저장소에 있습니다. 6개월 뒤 사양을 보면 여러분과 다음 AI 세션 모두 시스템이 현재 방식으로 동작하는 이유를 알 수 있습니다.
• 변경 사항을 검토할 수 있습니다. 변경 사항 폴더는 잘 정리된 묶음입니다. 제안을 읽고 델타를 훑어본 다음 작업을 확인하면 됩니다. 채팅 기록을 뒤질 필요가 없습니다.
• 기존 코드베이스에 잘 맞습니다. 델타를 사용하면 5만 줄짜리 앱 전체를 문서화하지 않고도 변경 사항을 사양화할 수 있습니다.

솔직한 단점도 있습니다. 정말 사소한 한 줄 수정에는 절차가 번거로울 수 있으며, 그래도 괜찮습니다. OpenSpec은 가볍게 설계됐지만 비용이 전혀 들지 않는 것은 아닙니다. 합의가 중요한 곳에서 사용하세요. 막연히 요청한 내용을 자신 있게 구현하는 AI와 일하다 보면 대부분의 작업에 합의가 필요하다는 것을 알게 됩니다.

다음 단계

• 처음 사용하나요? 시작하기에서 첫 변경 사항을 처음부터 끝까지 안내합니다.
• 무엇을 만들지 아직 확신이 없나요? 먼저 탐색하기부터 시작하세요.
• 명령을 어디서 실행하는지 혼동되나요? 명령 작동 방식을 참조하세요.
• 위 내용을 자세히 알고 싶나요? 개념을 읽어 보세요.
• 예제로 배우고 싶나요? 예제 및 레시피를 참조하세요.
• 용어의 뜻이 궁금한가요? 용어집을 확인하세요.