OpenSpec — AI 코딩 어시스턴트를 위한 스펙 주도 개발(SDD) 도구

본문

AI 코딩 어시스턴트는 강력하지만, 요구사항이 채팅 이력 속에만 존재할 때 결과가 불안정해지기 쉽습니다. OpenSpec은 이 문제를 해결하기 위해 코드가 작성되기 전에 사람과 AI가 무엇을 만들지 스펙으로 합의하도록 하는 경량 스펙 레이어를 제공합니다. 프로젝트는 fluid(유연함), iterative(반복적), easy(쉬움), brownfield 친화, 개인 프로젝트부터 엔터프라이즈까지 확장 가능이라는 다섯 가지 원칙을 내세웁니다.

워크플로우: explore → propose → apply → archive

OpenSpec의 새 워크플로우는 아티팩트 가이드 방식으로 재구축되었습니다. 먼저 /opsx:explore를 호출하면 AI가 코드베이스를 읽고 방향을 잡아주는 '사고 파트너' 역할을 합니다. 예시에서 사용자가 다크 모드를 추가하고 싶지만 방법을 모른다고 하자, AI는 스타일링 설정을 살펴본 뒤 CSS 변수와 테마 컨텍스트, 시스템 환경설정 감지를 조합하고 새 의존성 없이 구현하는 방안을 제안합니다.

방향이 정해지면 /opsx:propose add-dark-mode로 openspec/changes/add-dark-mode/ 폴더를 생성합니다. 여기에는 왜 하는지와 무엇이 바뀌는지를 담은 proposal.md, 요구사항과 시나리오를 담은 specs/, 기술적 접근을 담은 design.md, 구현 체크리스트인 tasks.md가 포함됩니다. 이후 /opsx:apply가 tasks.md의 항목(테마 컨텍스트 프로바이더 추가, 토글 컴포넌트 생성, CSS 변수 추가, localStorage 연동 등)을 순서대로 구현하고, 완료 후 /opsx:archive가 해당 변경을 openspec/changes/archive/ 아래에 날짜와 함께 보관하면서 스펙을 최신 상태로 갱신합니다.

스펙의 형태와 특징

스펙은 특별한 문법 없이 순수 Markdown으로 작성되며, 요구사항에는 구체적인 시나리오가 붙습니다. 예컨대 '앱은 사용자가 라이트/다크 테마를 전환할 수 있어야 하며(SHALL) 시스템 환경설정을 기본값으로 한다'는 요구사항 아래에 'WHEN 사용자가 테마 토글을 클릭하면, THEN 앱이 다크 모드로 전환되고 선택이 유지된다'는 시나리오가 따라붙습니다. AI가 이 문서들을 작성하고, 사람은 코드가 작성되기 전에 계획을 검토합니다. 프로젝트 자체가 OpenSpec으로 구축되어 있어 리포지터리에서 실제 스펙과 진행 중인 변경사항을 확인할 수 있습니다.

Stores: 팀 단위의 크로스 리포 계획

팀 환경에서는 하나의 기능이 API 서버, 웹 앱, 공유 라이브러리 등 여러 리포에 걸치고, 요구사항의 소유자와 소비자가 다른 팀일 수 있습니다. 이를 위해 OpenSpec은 계획 자체를 별도 리포에 두는 'Stores'(베타) 기능을 제공합니다. 동일한 openspec/ 구조(specs와 changes)를 git push로 공유하며, 여러 리포에 걸친 기능도 하나의 변경·하나의 계획으로 다루고, 플랫폼 팀이 소유한 스펙을 제품 팀이 읽기 전용으로 참조해 위키처럼 방치된 문서가 표류하는 문제를 막습니다.

설치와 도구 연동

Node.js 20.19.0 이상이 필요하며 npm install -g @fission-ai/openspec로 전역 설치 후 프로젝트에서 openspec init을 실행하면 됩니다. pnpm, yarn, bun, nix도 지원합니다. 슬래시 명령의 표기는 도구마다 다릅니다. /opsx:propose가 정식 명칭이지만 Cursor와 GitHub Copilot에서는 /opsx-propose, Amazon Q에서는 @opsx-propose, Codex에서는 $openspec-propose 형태로 호출되며, openspec init이 선택한 도구에 맞는 형태를 안내합니다. 30개 이상의 AI 어시스턴트를 지원하고, 기본 프로필 외에 /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard가 포함된 확장 워크플로우도 선택할 수 있습니다.

경쟁 도구와의 비교 및 운영 팁

GitHub의 Spec Kit과 비교하면 OpenSpec은 단계별 게이트나 Python 설정 없이 더 가볍게 자유롭게 반복할 수 있다고 주장하고, AWS의 Kiro와 비교하면 특정 IDE와 Claude 모델에 묶이지 않고 기존 도구 그대로 쓸 수 있다는 점을 강조합니다. 또한 고추론(high-reasoning) 모델에서 가장 잘 동작해 Codex 5.5와 Opus 4.7을 권장하고, 구현 전 컨텍스트를 비우는 컨텍스트 위생(context hygiene)을 권고합니다. 텔레메트리는 명령어 이름과 버전만 익명으로 수집되며 CI에서는 자동 비활성화되고, openspec config set telemetry.enabled false 또는 OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1 환경변수로 거부할 수 있습니다. 라이선스는 MIT입니다.

원문: GitHub / 번역·요약: Trawling