용어집

OpenSpec 용어를 한곳에 모아 쉬운 말로 정의했습니다. 한 번 훑어보면 나머지 문서를 더 빠르게 읽을 수 있습니다.

용어는 주제별로 묶었으며 각 그룹 안에서는 알파벳순으로 정렬했습니다.

핵심 용어

사양(Spec). 시스템의 일부가 어떻게 동작하는지 설명하는 문서입니다. 사양은 openspec/specs/에 저장되고 도메인별로 구성되며 요구 사항과 시나리오로 이루어집니다. “이 소프트웨어는 무엇을 하나요?“에 대해 합의한 답이 사양입니다. 개념을 참조하세요.

기준 정보(Source of truth). openspec/specs/ 디렉터리 전체를 의미합니다. 시스템의 현재 동작 중 합의된 내용을 담고 있습니다. 변경 사항에서 수정 사항을 제안하고, 보관 시 이를 반영합니다.

변경 사항(Change). openspec/changes/<name>/ 아래의 폴더에 담기는 하나의 작업 단위입니다. 제안, 설계, 작업 목록, 변경 사항이 도입하는 사양 수정 등 해당 작업에 필요한 모든 내용이 포함됩니다. 변경 사항 하나에는 기능 또는 수정 하나가 들어갑니다.

산출물(Artifact). 변경 사항 안에 있는 문서입니다. 표준 산출물에는 제안, 델타 사양, 설계, 작업 목록이 있습니다. 의존성 순서에 따라 생성되며 서로의 입력으로 사용됩니다.

델타 사양(Delta spec). 전체 사양을 다시 작성하는 대신 ADDED, MODIFIED, REMOVED 섹션을 사용해 변경되는 부분만 설명하는 변경 사항 내의 사양입니다. 이를 통해 OpenSpec은 기존 시스템을 깔끔하게 수정할 수 있습니다. 개념을 참조하세요.

도메인(Domain). auth/, payments/, ui/처럼 사양을 논리적으로 묶는 단위입니다. 시스템을 이해하는 방식에 맞춰 도메인을 선택합니다.

사양의 구성 요소

요구 사항(Requirement). 시스템이 갖춰야 할 하나의 동작입니다. 보통 RFC 2119 키워드를 사용해 작성합니다. 예: “시스템은 세션을 30분 후에 만료시켜야 한다(SHALL).” 요구 사항은 무엇을 해야 하는지를 명시하며 어떻게 구현할지는 다루지 않습니다.

시나리오(Scenario). 요구 사항이 실제로 적용되는 구체적이고 테스트 가능한 예제로, 보통 Given/When/Then 형식으로 작성됩니다. 시나리오를 통해 요구 사항을 검증할 수 있으며, 이를 바탕으로 자동화 테스트를 작성할 수도 있습니다.

RFC 2119 키워드. 요구 사항의 강제 수준을 표준화된 의미로 나타내는 MUST, SHALL, SHOULD, MAY 등의 단어입니다. MUST와 SHALL은 반드시 따라야 합니다. SHOULD는 예외를 허용하지만 권장됩니다. MAY는 선택 사항입니다. 이 이름은 해당 키워드를 정의한 인터넷 표준 문서에서 유래했습니다.

산출물

제안(proposal.md). 변경 사항의 이유와 내용을 설명합니다. 의도, 범위, 상위 수준의 접근 방식을 다루며 가장 먼저 만드는 산출물입니다.

설계(design.md). 방법을 설명합니다. 기술적 접근 방식, 아키텍처 결정, 수정할 것으로 예상되는 파일을 다룹니다. 단순한 변경 사항에서는 선택 사항입니다.

작업 목록(tasks.md). 체크박스로 구성된 구현 체크리스트입니다. AI는 /opsx:apply를 실행하며 목록을 따라 작업을 진행하고 완료한 항목을 표시합니다.

생명 주기

보관(Archive). 변경 사항을 완료하는 과정입니다. 델타 사양이 기본 사양에 병합되고 변경 사항 폴더가 openspec/changes/archive/YYYY-MM-DD-<name>/으로 이동합니다. 보관 후 사양은 새로운 실제 동작을 설명합니다. 개념을 참조하세요.

동기화(Sync). 변경 사항을 보관하지 않고 델타 사양만 기본 사양에 병합하는 작업입니다. 보통 자동으로 진행되지만(보관 시 실행 여부를 묻습니다), 장기 실행되는 변경 사항에서는 /opsx:sync를 단독으로 사용할 수 있습니다. 명령을 참조하세요.

워크플로 및 명령

OPSX. 경직된 단계 대신 유연한 동작을 중심으로 구성된 현재 OpenSpec 표준 워크플로입니다. 슬래시 명령은 모두 /opsx:로 시작합니다. OPSX 워크플로를 참조하세요.

슬래시 명령(Slash command). /opsx:propose처럼 AI 어시스턴트 채팅에 입력하는 명령입니다. 슬래시 명령으로 워크플로를 진행하며 터미널 명령은 아닙니다. 명령 작동 방식을 참조하세요.

탐색(Explore, /opsx:explore). 사고 파트너 역할을 하는 명령입니다. 코드베이스를 읽고 여러 선택지를 비교해 모호한 아이디어를 구체적인 계획으로 다듬습니다. 코드를 작성하지 않으며, 탐색을 변경 사항으로 기록해 달라고 요청하거나 기록 제안을 수락하지 않는 한 다른 내용도 작성하지 않습니다. 문제가 있지만 계획이 없을 때 권장되는 시작점입니다. 먼저 탐색하기를 참조하세요.

CLI. 터미널에서 실행하는 openspec 프로그램입니다. 프로젝트를 설정하고 변경 사항을 나열 및 검증하며 대시보드를 열고 변경 사항을 보관합니다. OpenSpec의 터미널 인터페이스입니다. CLI를 참조하세요.

스킬(Skill). AI 어시스턴트가 자동으로 검색해 따르는 지침 폴더(.../skills/openspec-*/SKILL.md)입니다. 스킬은 어시스턴트에 OpenSpec 워크플로를 제공하기 위한 새로운 도구 간 표준입니다.

명령 파일(Command file). 도구별 슬래시 명령 파일(.../commands/opsx-*)입니다. 스킬과 함께 계속 지원되는 이전 전달 방식이며, 직접 수정할 일은 거의 없습니다.

프로필(Profile). 프로젝트에 설치되는 슬래시 명령 집합입니다. 기본 Core 프로필에는 propose, explore, apply, update, sync, archive가 포함됩니다. 확장 프로필에는 new, continue, ff, verify, bulk-archive, onboard가 추가됩니다. openspec config profile로 변경하세요.

전달 방식(Delivery). OpenSpec이 도구에 스킬, 명령 파일 또는 둘 다를 설치할지 지정합니다. 전역으로 구성하고 openspec update를 실행해 적용합니다.

사용자 지정

스키마(Schema). 워크플로에 어떤 산출물이 있으며 서로 어떻게 의존하는지 정의합니다. 기본 제공 스키마는 spec-driven(proposal → specs → design → tasks)입니다. 이를 포크하거나 직접 작성할 수 있습니다. 사용자 지정을 참조하세요.

템플릿(Template). 특정 산출물에 대해 AI가 생성할 내용을 구성하는 스키마 내 Markdown 파일입니다. 템플릿을 편집하면 다시 빌드하지 않아도 AI 출력에 즉시 반영됩니다.

프로젝트 구성(openspec/config.yaml). 프로젝트별 설정으로 기본 스키마, 모든 계획 요청에 주입되는 context:, 산출물별 rules:를 포함합니다. OpenSpec에 기술 스택과 관례를 알려 주는 가장 쉬운 방법입니다. 사용자 지정을 참조하세요.

컨텍스트 주입(Context injection). 프로젝트 배경 정보를 config.yaml의 context: 필드에 넣어 AI가 생성하는 모든 산출물에 자동으로 추가하는 방법입니다. AI가 별도 파일을 읽기를 기대하는 것보다 안정적입니다.

의존성 그래프(Dependency graph). 산출물의 requires: 관계로 구성되는 방향성 그래프입니다. DAG(방향성 비순환 그래프: 화살표가 순환하지 않고 한 방향으로만 진행)이며, OpenSpec은 이를 통해 다음에 만들 수 있는 산출물을 결정합니다.

관문이 아니라 촉진 요소(Enablers, not gates). 산출물 간 의존성은 다음에 가능해지는 작업을 나타낼 뿐, 반드시 해야 하는 작업을 뜻하지 않는다는 원칙입니다. 언제든 모든 산출물을 다시 열어 수정할 수 있습니다. 핵심 개념 한눈에 보기를 참조하세요.

저장소 간 조율(베타)

이 용어는 계획이 여러 저장소에 걸치는 경우에만 적용됩니다. 베타 기능이므로 대부분의 사용자는 무시해도 됩니다. Stores 사용자 안내서를 참조하세요.

Store. 계획을 전담하는 독립된 저장소입니다. 이미 알고 있는 사양과 변경 사항으로 구성된 openspec/ 구조에 작은 식별 파일을 더한 형태입니다. 컴퓨터에 이름을 지정해 한 번 등록하면 어디서든 OpenSpec 명령으로 작업할 수 있습니다.

참조(Reference). 코드 저장소의 openspec/config.yaml에서 해당 저장소가 활용하는 store를 선언한 것입니다. 참조는 읽기 전용입니다. 저장소는 자체 루트를 유지하고 openspec instructions에는 참조된 store의 사양 색인과 각 항목을 가져오는 정확한 명령이 추가됩니다.

작업 컨텍스트(Working context). openspec context가 현재 저장소에 대해 구성하는 정보입니다. OpenSpec 루트와 참조된 모든 store, 그리고 각 항목을 가져오는 방법을 포함합니다. “지금 무엇을 대상으로 작업하고 있나요?“에 대한 답입니다.

작업 세트(Workset). 함께 열어 두는 개인용 로컬 폴더 집합입니다(store와 작업 중인 코드 저장소를 함께 포함할 수 있습니다). openspec workset create로 명시적으로 만듭니다. 이러한 로컬 경로는 공유 계획 저장소에 커밋되지 않습니다.

관련 항목

• 핵심 개념 한눈에 보기: 다섯 가지 핵심 개념을 한 페이지에서 확인
• 개념: 자세한 설명
• 명령 작동 방식: 슬래시 명령과 CLI의 차이