자주 묻는 질문

자주 묻는 질문에 대한 간단한 답변입니다. 문제가 발생한 경우에는 문제 해결을, 용어의 뜻을 알고 싶다면 용어집을 참조하세요.

기본 사항

OpenSpec을 한 문장으로 설명하면 무엇인가요?

코드를 작성하기 전에 사용자와 AI 코딩 어시스턴트가 무엇을 만들지 문서로 합의하도록 돕는 가벼운 계층입니다.

왜 필요한가요?

AI 어시스턴트는 틀렸을 때도 자신 있게 답하기 때문입니다. 요구 사항이 채팅 기록에만 있으면 AI가 빈틈을 추측으로 채우고, 코드가 만들어진 뒤에야 이를 알게 됩니다. OpenSpec은 실수를 적은 비용으로 바로잡을 수 있도록 합의 시점을 앞당깁니다. 자세한 내용은 핵심 개념 한눈에 보기를 참조하세요.

모든 작업에 사용해야 하나요?

아니요. 대부분의 사소하지 않은 작업처럼 합의가 중요한 경우에 사용하세요. 한 글자 오타를 고치는 데는 절차가 번거로울 수 있으니 굳이 사용할 필요가 없습니다.

신규 프로젝트뿐 아니라 기존의 대규모 코드베이스에서도 사용할 수 있나요?

기존 코드베이스가 주요 사용 대상입니다. OpenSpec은 기존 시스템을 우선으로 하므로 앱 전체를 미리 문서화할 필요가 없습니다. 각 변경 사항이 건드리는 내용만 사양에 기록하고 실제 작업을 거치며 사양을 점차 채워 나갑니다. 자세한 안내는 기존 프로젝트에서 OpenSpec 사용하기를 참조하세요.

특정 AI 도구에 종속되어 있나요?

아니요. OpenSpec은 Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex 등 30개 이상의 어시스턴트에서 작동합니다. 전체 목록과 도구별 세부 정보는 지원 도구를 참조하세요.

명령 실행하기

/opsx:propose는 어디에 입력하나요?

터미널이 아니라 AI 어시스턴트의 채팅창에 입력합니다. 가장 자주 혼동하는 부분이라 별도의 안내 페이지가 있습니다. 명령 작동 방식을 참조하세요. 간단히 말해 openspec ...은 터미널에서, /opsx:...는 채팅에서 실행합니다.

“대화형 모드”는 어떻게 시작하나요?

별도로 시작할 모드는 없습니다. 평소처럼 AI 어시스턴트를 열고 채팅창에 슬래시 명령을 입력하면 됩니다. 슬래시 명령을 통해 OpenSpec을 “시작”합니다. (실제로 대화형인 유일한 터미널 기능은 사양과 변경 사항을 탐색하는 대시보드 openspec view입니다.) 자세한 설명은 명령 작동 방식을 참조하세요.

슬래시 명령을 입력했는데 아무 일도 일어나지 않습니다. 왜 그런가요?

대개는 AI 채팅이 아니라 터미널에 입력했거나 도구에서 인식하지 못하는 명령 표기를 사용했거나 명령이 아직 설치되지 않은 경우입니다. 파일이 없거나 도구를 설정하지 않았다면 openspec init을 실행하세요. openspec update는 이미 있는 파일만 새로 고칩니다. 그런 다음 어시스턴트를 다시 시작하고 “시작하기” 아래에 출력된 명령 형식을 사용하세요. 호출 방법을 참조하세요. 전체 점검 목록은 문제 해결에 있습니다.

도구에 따라 /opsx:propose와 /opsx-propose로 표기가 다른 이유는 무엇인가요?

AI 도구마다 사용자 지정 명령을 표시하는 방식이 조금씩 다르며, OpenSpec은 도구가 생성된 파일을 불러오는 방식에 맞춰 명령을 표기합니다. opsx-propose.md라는 명령 파일은 /opsx-propose로 입력하고 commands/opsx/ 아래에 있는 파일은 /opsx:propose로 입력합니다. 명령 대신 스킬을 사용하는 도구에서는 스킬 이름을 사용합니다. Codex에서는 $openspec-propose, Kimi Code에서는 /skill:openspec-propose가 필요합니다. openspec init의 “시작하기” 줄에 선택한 도구에 맞는 표기가 출력됩니다. 전체 표는 호출 방법을 참조하세요.

스킬과 명령의 차이는 무엇인가요?

둘 다 어시스턴트가 워크플로를 실행할 수 있도록 OpenSpec이 작성하는 파일입니다. 스킬(.../skills/openspec-*/SKILL.md)은 최신 도구 간 표준이고, 명령(.../commands/opsx-*)은 이전 방식의 도구별 슬래시 명령 파일입니다. 둘 중 하나를 선택할 필요는 없습니다. 슬래시 명령을 입력하면 OpenSpec이 해당 도구에서 사용하는 방식을 설치합니다.

워크플로

무엇을 만들지 확신이 없을 때 어디서 시작해야 하나요?

/opsx:explore로 시작하세요. 코드를 작성하기 전에 코드베이스를 읽고 선택지를 제시하며 모호한 문제를 구체적인 계획으로 바꾸는 부담 없는 사고 파트너입니다. 기본 프로필에 포함되어 있어 언제든 사용할 수 있습니다. 계획이 명확해지면 /opsx:propose로 이어집니다. 적극적인 AI가 엉뚱한 것을 자신 있게 만들지 않도록 막아 주므로 꼭 익혀야 할 습관입니다. 먼저 탐색하기를 참조하세요.

가장 간단한 작업 흐름은 무엇인가요?

/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive

explore로 충분히 생각하고, propose로 계획 초안을 작성하고, apply로 구현하고, archive로 보관합니다. 원하는 바를 정확히 알고 있다면 explore를 건너뛰세요.

/opsx:propose와 /opsx:new의 차이는 무엇인가요?

/opsx:propose는 기본 단일 단계 명령으로 변경 사항을 만들고 모든 계획 산출물의 초안을 한꺼번에 작성합니다. 확장 명령 모음에 포함된 /opsx:new는 빈 변경 사항의 기본 구조만 만들며, /opsx:continue로 산출물을 하나씩(또는 /opsx:ff로 모두 한꺼번에) 작성하도록 합니다. 단계별로 제어하고 싶은 경우가 아니라면 propose를 사용하세요. 명령을 참조하세요.

core 및 확장 프로필이란 무엇인가요?

프로필은 설치할 슬래시 명령을 결정합니다. 기본값인 Core에는 propose, explore, apply, update, sync, archive가 포함됩니다. 확장 명령 모음에는 더 세밀하게 제어할 수 있는 new, continue, ff, verify, bulk-archive, onboard가 추가됩니다. openspec config profile로 프로필을 바꾸고 openspec update를 실행해 적용하세요.

/opsx:sync를 실행해야 하나요?

대개 필요하지 않습니다. sync는 변경 사항의 델타 사양을 기본 사양에 병합하며, /opsx:archive에서 이를 수행할지 묻습니다. 장기간 진행되는 변경 사항처럼 보관 전에 사양을 병합하고 싶을 때만 직접 실행하세요. 명령을 참조하세요.

시작한 뒤 제안, 사양, 작업을 어떻게 편집하나요?

파일을 편집하면 됩니다. 모든 산출물은 openspec/changes/<name>/ 아래의 일반 Markdown 파일이며 잠긴 단계나 특별 편집 모드는 없습니다. 직접 수정하거나 AI에게 (“큐를 사용하도록 설계를 업데이트해 줘”처럼) 수정을 요청한 뒤 계속 진행하세요. AI는 항상 현재 파일 내용을 기준으로 작업합니다. 자세한 안내는 변경 사항 편집 및 반복 개선을 참조하세요.

일부 구현한 뒤 계획을 되돌아가서 바꿀 수 있나요?

네, 언제든 가능합니다. 워크플로가 유연하므로 검토와 편집이 특정 단계에 한정되지 않습니다. 산출물을 편집한 다음 계속 진행하세요. 코드가 여전히 계획에 맞는지 체계적으로 확인하려면 /opsx:verify를 실행하세요. 변경 사항 편집 및 반복 개선을 참조하세요.

코드를 직접 편집했습니다. 사양과 어떻게 맞추나요?

보관 시 사양이 공식 기록이 되므로 보관 전에 둘을 다시 동기화하세요. 코드가 맞다면 배포한 동작에 맞춰 델타 사양을 업데이트하고, 사양이 맞다면 코드가 일치할 때까지 구현을 계속하세요. /opsx:verify를 실행하면 불일치 항목이 표시됩니다. 변경 사항 편집 및 반복 개선을 참조하세요.

기존 변경 사항을 업데이트해야 할 때와 새로 시작해야 할 때를 어떻게 구분하나요?

같은 작업을 다듬는 경우에는 업데이트하세요. 의도가 근본적으로 바뀌었거나 범위가 별개의 작업으로 크게 확장된 경우에는 새로 시작하세요. 판단 흐름도와 예제는 워크플로를 참조하세요.

세션의 컨텍스트가 부족해지거나 구현 도중 요구 사항이 바뀌면 어떻게 하나요?

이럴 때 사양이 유용합니다. 계획이 채팅 기록에만 있는 것이 아니라 파일에 저장되므로 컨텍스트를 지우고 새로운 AI 세션을 시작한 뒤 /opsx:apply로 이어갈 수 있습니다. 산출물을 읽고 첫 번째 미완료 작업부터 계속합니다. 요구 사항이 바뀌면 새로운 상황에 맞게 산출물을 편집하고 진행하세요. 컨텍스트 창을 깨끗하게 유지하면 결과도 좋아지므로 구현 전에 지우는 것이 좋습니다.

openspec/ 폴더를 git에 커밋해야 하나요?

네. 사양, 진행 중인 변경 사항, 보관 기록은 프로젝트 이력의 일부입니다. 다른 소스와 마찬가지로 커밋하세요. 특히 보관 기록은 시스템이 현재 방식으로 작동하는 이유를 오래 보존하는 기록입니다.

사양 및 변경 사항

사양과 설계에는 각각 무엇을 기록하나요?

사양은 관찰 가능한 동작, 즉 시스템이 하는 일과 입력, 출력, 오류 조건을 설명합니다. 설계는 기술적 접근 방식, 아키텍처 결정, 파일 변경 등 구현 방법을 설명합니다. 외부에 보이는 동작을 바꾸지 않고 구현을 변경할 수 있다면 사양이 아니라 설계에 기록합니다. 자세한 내용은 개념을 참조하세요.

델타 사양이란 무엇인가요?

전체 사양을 다시 쓰는 대신 ADDED, MODIFIED, REMOVED 섹션을 사용해 바뀌는 부분만 설명하는 사양입니다. OpenSpec은 이를 통해 기존 시스템을 깔끔하게 수정합니다. 개념을 참조하세요.

보관된 변경 사항은 어디로 가나요?

모든 변경 산출물을 보존한 채 openspec/changes/archive/YYYY-MM-DD-<name>/으로 이동합니다. 변경 사항이 진행 중 목록에서 사라집니다. retire_capabilities: true를 명시한 변경 사항은 해당 기능의 마지막 요구 사항을 제거할 때 기본 기능 사양도 삭제할 수 있습니다.

구성 및 사용자 지정

AI에게 기술 스택을 알려 주려면 어떻게 하나요?

openspec/config.yaml의 context: 아래에 기록하세요. 이 텍스트는 모든 계획 요청에 포함되므로 AI가 기술 스택과 관례를 항상 파악할 수 있습니다. 사용자 지정을 참조하세요.

영어가 아닌 언어로 사양을 생성할 수 있나요?

네. 구성의 context:에 언어 지침을 추가하세요. 다국어 안내서에 여러 언어의 복사해 사용할 수 있는 예제가 있습니다.

워크플로 자체를 변경할 수 있나요?

네, 사용자 지정 스키마를 사용하면 됩니다. 스키마는 산출물 종류와 산출물 간 의존성을 정의합니다. openspec schema fork spec-driven my-workflow로 기본 스키마를 포크한 다음 편집하세요. 사용자 지정을 참조하세요.

모델, 개인정보 보호, 업그레이드

어떤 AI 모델을 사용해야 하나요?

OpenSpec은 추론 능력이 뛰어난 모델에서 가장 잘 작동합니다. README에서는 계획과 구현 모두에 Codex 5.5 및 Opus 4.7과 같은 모델을 권장합니다. 컨텍스트 창도 깨끗하게 유지하세요. 최상의 결과를 얻으려면 구현 전에 비우는 것이 좋습니다.

OpenSpec은 데이터를 수집하나요?

익명 사용 통계를 수집합니다. 명령 이름과 버전만 수집하며 인수, 경로, 콘텐츠, 개인 데이터는 수집하지 않습니다. CI에서는 자동으로 비활성화됩니다. export OPENSPEC_TELEMETRY=0 또는 export DO_NOT_TRACK=1을 설정해 수집을 거부할 수 있습니다.

어떻게 업그레이드하나요?

두 단계로 진행합니다. 패키지(npm install -g @fission-ai/openspec@latest)를 업그레이드한 다음 각 프로젝트에서 openspec update를 실행해 생성된 스킬과 명령을 새로 고칩니다.

OpenSpec을 어떻게 제거하나요?

전역 패키지와 프로젝트 파일로 구성되므로 별도의 제거 명령은 없습니다. 패키지(npm uninstall -g @fission-ai/openspec)를 제거하고, 원한다면 openspec/ 디렉터리와 생성된 도구 파일도 삭제하세요. 유지해도 안전한 항목을 포함한 단계별 안내는 설치: 제거를 참조하세요.

도움말 보기

질문하거나 버그를 보고하려면 어디로 가야 하나요?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• 터미널에서: openspec feedback "your message"를 실행하면 GitHub 이슈를 열 수 있습니다.

문서가 틀렸거나 이해하기 어렵습니다. 어떻게 해야 하나요?

알려 주시거나 직접 수정해 주세요. 문서 풀 리퀘스트는 언제든 환영하며 소중히 생각합니다. 이슈를 열거나 풀 리퀘스트를 보내 주세요.