OpenSpec

용어집 ​

모든 OpenSpec 용어를 한곳에 모아 평이한 언어로 정의한 것입니다. 한 번 훑어보면 나머지 문서가 훨씬 빠르게 읽힙니다.

용어는 주제별로 그룹화되고, 각 그룹 내에서 알파벳 순으로 정렬됩니다.

핵심 명사 ​

Spec. 시스템의 일부가 어떻게 동작하는지를 설명하는 문서입니다. Specs는 openspec/specs/에 위치하며, 도메인별로 조직되고 요구사항과 시나리오로 구성됩니다. Spec은 "이 소프트웨어는 무엇을 하는가?"라는 질문에 대한 합의된 답변입니다. 개념을 참조하세요.

Source of truth. openspec/specs/ 디렉터리 전체를 가리킵니다. 시스템의 현재 합의된 동작을 담고 있습니다. 변경은 여기에 대한 편집을 제안하고, 아카이빙은 이를 적용합니다.

Change. openspec/changes/<name>/ 아래 폴더로 패키징된 작업 단위입니다. Change는 해당 작업에 관한 모든 것을 담고 있습니다: 제안서, 설계, 작업 목록, 그리고 도입하는 spec 편집 내용. 하나의 Change는 하나의 기능 또는 수정 사항입니다.

Artifact. Change 내부의 문서입니다. 표준 artifacts는 제안서, delta specs, 설계, 작업 목록입니다. 의존 순서대로 생성되며 서로에 피드백을 제공합니다.

Delta spec. Change 내부에서 전체 spec을 다시 서술하지 않고 ADDED, MODIFIED, REMOVED 섹션을 사용하여 변경되는 부분만 설명하는 spec입니다. 이것이 OpenSpec가 기존 시스템을 깔끔하게 편집할 수 있게 해줍니다. 개념을 참조하세요.

Domain. auth/, payments/, ui/와 같은 specs의 논리적 그룹입니다. 시스템에 대한 사고방식에 맞는 도메인을 선택합니다.

Spec 내부 ​

Requirement. 시스템이 반드시 가져야 하는 단일 동작으로, 일반적으로 RFC 2119 키워드를 사용하여 작성합니다: "시스템은 세션이 30분 후에 만료되도록 SHALL 합니다." Requirements는 무엇을 하는지, 어떻게 하는지를 서술하지 않습니다.

Scenario. Requirement가 동작하는 구체적이고 테스트 가능한 예시로, 일반적으로 Given/When/Then 형식을 따릅니다. Scenarios는 Requirement를 검증 가능하게 만듭니다: 하나로부터 자동화 테스트를 작성할 수 있습니다.

RFC 2119 keywords. MUST, SHALL, SHOULD, MAY라는 단어로, 요구사항의 엄격함에 대한 표준화된 의미를 지닙니다. MUST와 SHALL은 절대적입니다. SHOULD는 예외가 허용되는 권장 사항입니다. MAY는 선택 사항입니다. 이름은 이들을 정의한 인터넷 표준 문서에서 유래했습니다.

Artifacts ​

Proposal (proposal.md). Change의 왜와 무엇입니다: 의도, 범위, 고수준 접근 방식. 가장 먼저 생성하는 artifact입니다.

Design (design.md). 어떻게입니다: 기술적 접근 방식, 아키텍처 결정, 그리고 수정할 것으로 예상되는 파일들. 단순한 변경에는 선택 사항입니다.

Tasks (tasks.md). 체크박스가 있는 구현 체크리스트입니다. AI는 /opsx:apply 동안 이를 진행하며 항목을 체크해 나갑니다.

라이프사이클 ​

Archive. Change를 완료하는 행위입니다. Delta specs가 메인 specs에 병합되고, Change 폴더가 openspec/changes/archive/YYYY-MM-DD-<name>/로 이동합니다. 아카이빙 후 specs는 새로운 현실을 설명합니다. 개념을 참조하세요.

Sync. Change를 아카이빙하지 않고 delta specs를 메인 specs에 병합하는 것입니다. 일반적으로 자동 수행됩니다(아카이빙 시 제안), 하지만 장기 진행 중인 변경을 위해 /opsx:sync로 단독 사용도 가능합니다. 명령어을 참조하세요.

워크플로 및 명령어 ​

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

Slash command. AI 어시스턴트의 채팅에 입력하는 명령어로, /opsx:propose와 같습니다. Slash commands는 워크플로를 구동합니다. 터미널 명령어가 아닙니다. 명령어 작동 방식을 참조하세요.

Explore (/opsx:explore). 사고 파트너 명령어입니다. 코드베이스를 읽고, 옵션을 비교하고, 모호한 아이디어를 구체적인 계획으로 명확히 하며, 어떤 artifact도 생성하지 않고 코드를 작성하지 않습니다. 문제가 있지만 아직 계획이 없을 때 권장하는 시작점입니다. Explore First를 참조하세요.

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

Skill. AI 어시스턴트가 자동 감지하고 따르는 지침 폴더(.../skills/openspec-*/SKILL.md)입니다. Skills는 OpenSpec 워크플로를 어시스턴트에 전달하기 위한 신흥 크로스툴 표준입니다.

Command file. 도구별 슬래시 명령어 파일(.../commands/opsx-*)입니다. 이전의 전달 메커니즘으로, skills와 함께 여전히 지원됩니다. 직접 수정할 일은 거의 없습니다.

Profile. 프로젝트에 설치된 슬래시 명령어 세트입니다. Core(기본값)는 propose, explore, apply, update, sync, archive입니다. expanded 세트는 new, continue, ff, verify, bulk-archive, onboard를 추가합니다. openspec config profile로 변경합니다.

Delivery. OpenSpec가 도구들에 skills, command files, 또는 둘 다를 설치하는지 여부입니다. 전역으로 구성되며 openspec update로 적용됩니다.

커스터마이징 ​

Schema. 워크플로가 어떤 artifacts를 가지는지, 그리고 이들이 어떻게 상호 의존하는지를 정의하는 것입니다. 내장 기본값은 spec-driven(proposal → specs → design → tasks)입니다. 포크하거나 직접 작성할 수 있습니다. 커스터마이징을 참조하세요.

Template. Schema 내부에서 AI가 특정 artifact에 대해 생성하는 내용을 형성하는 Markdown 파일입니다. 템플릿을 편집하면 재빌드 없이 즉시 AI의 출력이 변경됩니다.

Project config (openspec/config.yaml). 프로젝트별 설정: 기본 schema, 모든 계획 요청에 주입되는 context:, 그리고 artifact별 rules:입니다. OpenSpec에 스택과 컨벤션을 가르치는 가장 쉬운 방법입니다. 커스터마이징을 참조하세요.

Context injection. 프로젝트 배경을 config.yaml의 context: 필드에 넣어 AI가 생성하는 모든 artifact에 자동으로 추가하는 것입니다. AI가 별도 파일을 읽기를 기대하는 것보다 더 신뢰할 수 있습니다.

Dependency graph. Artifact의 requires: 관계로 형성되는 방향 그래프입니다. DAG(방향 비순환 그래프: 화살표는 오직 앞으로만 가리키고, 절대 루프를 형성하지 않음)이며, OpenSpec는 이를 사용하여 다음에 무엇을 생성할 수 있는지 파악합니다.

Enablers, not gates. Artifact 의존성이 다음에 무엇이 가능해지는지를 보여주는 것이지, 무엇이 필요한지를 보여주는 것이 아니라는 원칙입니다. 언제든지 어떤 artifact든 다시 방문하고 편집할 수 있습니다. 핵심 개념 한눈에 보기를 참조하세요.

리포지토리 간 조정 (베타) ​

이 용어들은 계획이 여러 리포지토리를 넘나드는 경우에만 적용됩니다. 베타 버전입니다. 대부분의 사용자는 무시해도 됩니다. Stores 사용자 가이드를 참조하세요.

Store. 계획이 유일한 목적인 독립 리포지토리입니다. 이미 알고 있는 동일한 openspec/ 구조(specs와 changes)에 작은 ID 파일이 추가됩니다. 한 번 이름으로 등록하면, 어디서든 모든 OpenSpec 명령어가 이 안에서 작동합니다.

Reference. 코드 리포지토리의 openspec/config.yaml에서 해당 리포지토리가 참조하는 store를 선언하는 것입니다. References는 읽기 전용입니다: 리포지토리는 자신의 루트를 유지하고, openspec instructions에 참조된 store의 specs 인덱스가 추가되며, 각 항목에는 가져오기 위한 정확한 명령어가 포함됩니다.

Working context. openspec context가 현재 리포지토리를 위해 조립하는 내용입니다: OpenSpec 루트와 참조하는 모든 store, 각 store의 가져오기 방법이 포함됩니다. "나는 무엇과 작업하고 있는가?"라는 질문에 대한 답변입니다.

Workset. 함께 여는 개인적, 머신 로컬 폴더 세트입니다(store와 작업하는 코드 리포지토리들). openspec workset create로 명시적으로 생성하며, 해당 로컬 경로에 관한 정보는 공유 계획 리포지토리에 커밋되지 않습니다.

관련 항목 ​