OpenSpec

자주 묻는 질문 ​

사람들이 가장 자주 묻는 질문에 대한 빠른 답변입니다. 질문이 실제로 "뭔가 고장났다"에 해당한다면 문제 해결 페이지가 더 적합합니다. 용어 정의가 필요하면 용어집을 참조하세요.

기본 사항 ​

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뿐입니다.) 자세한 설명은 명령 작동 방식을 참조하세요.

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

대부분 터미널에 입력했거나, 도구가 인식하지 못하는 철자를 사용했거나, 명령이 아직 설치되지 않았기 때문일 수 있습니다. 파일이 없거나 도구를 설정한 적이 없다면 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가 잘못된 것을 자신 있게 구축하는 것을 막아주는 가장 좋은 습관입니다. 먼저 탐색을 참조하세요.

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

text
/opsx:explore (선택 사항)   그 다음   /opsx:propose <원하는 것>   그 다음   /opsx:apply   그 다음   /opsx:archive

탐색으로 생각을 정리하고, 제안으로 계획을 초안 작성하고, 적용으로 구축하고, 보관으로 정리합니다. 정확히 무엇을 원하는지 이미 안다면 탐색을 건너뛰세요.

/opsx:propose와 /opsx:new의 차이점은 무엇인가요? ​

/opsx:propose는 기본 원스텝 명령입니다. 변경을 생성하고 모든 계획 산출물을 한 번에 초안 작성합니다. /opsx:new는 확장 명령 세트의 일부이며 빈 변경만 생성하고 /opsx:continue로 산출물을 하나씩 만들거나 /opsx:ff로 한 번에 만들 수 있게 합니다. 단계별 제어를 원하지 않으면 propose를 사용하세요. 명령을 참조하세요.

core와 expanded 프로필은 무엇인가요? ​

프로필은 설치할 슬래시 명령을 결정합니다. Core(기본값)는 propose, explore, apply, update, sync, archive를 제공합니다. expanded 세트는 new, continue, ff, verify, bulk-archive, onboard를 추가하여 세밀한 제어를 제공합니다. openspec config profile로 전환한 다음 openspec update로 적용하세요.

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

보통은 아닙니다. Sync는 변경의 델타 스펙을 메인 스펙에 병합하며, /opsx:archive가 대신 수행하겠다고 제안할 것입니다. 보관 전에 스펙을 병합하려는 경우(예: 장기 실행 변경)에만 수동으로 sync를 실행하세요. 명령을 참조하세요.

시작한 후 제안, 스펙 또는 작업을 어떻게 편집하나요? ​

파일을 그냥 편집하세요. 모든 산출물은 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/ 디렉토리와 생성된 도구 파일을 삭제하세요. 단계별 및 안전하게 유지할 수 있는 내용은 설치: 제거에 있습니다.

도움 받기 ​

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

문서가 잘못되었거나 혼란스럽습니다. 어떻게 해야 하나요? ​

알려주거나 직접 수정하세요. 문서 PR은 환영하며 가치 있게 여깁니다. 이슈를 열거나 풀 리퀘스트를 보내세요.