OpenSpec을 활용한 규격 기반 개발(SDD) 입문 가이드

원문 발행 2026. 10. 13. 08:05원문 언어 중국어AI 한국어 번역Dev.to AI tag 원문 보기

요약

본 가이드는 OpenSpec 도구를 활용한 규격 기반 개발(SDD) 방법론을 소개합니다. SDD는 AI 모델의 컨텍스트 윈도우 제한과 세션 간 '기억 상실' 문제를 해결하는 컨텍스트 엔지니어링 기법입니다. 프로젝트의 '규격 문서'를 단일 진실 공급원으로 활용하여 안정적이고 확장 가능한 소프트웨어 개발을 목표로 합니다.

핵심 포인트

SDD는 AI 모델의 한계(컨텍스트 윈도우)를 극복하는 방법론이다.
프로젝트 규격 문서를 '단일 진실 공급원'으로 관리해야 한다.
규격 문서 작성은 코딩 전 필수 단계이며, 모든 개발 과정에 컨텍스트를 제공한다.

[

]

제1부: 서론 및 배경 소개 (시작 시간 0% - 10%)

강좌 목표 및 적용 범위

이 강좌는 '규격 기반 개발(Spec-Driven Development, SDD)'을 어떻게 사용하는지, 특히 OpenSpec 도구와 결합하여 학습하는 초보자 대상의 종합 과정입니다.
웹사이트, 백엔드, 모바일 애플리케이션 등 어떤 유형의 소프트웨어를 구축하든 이 방법론은 동일하게 적용됩니다.
학습 전제 조건

필수 조건:
- Claude Code, Codex, Copilot과 같은 AI 에이전트 도구(Agent Harness)가 필요합니다.
- 에이전트 작업을 실행할 터미널(Terminal)이 필요합니다.
권장 조건:
- Android Studio, VS Code와 같은 통합 개발 환경(IDE) 또는 코드 에디터를 보유하는 것이 좋습니다.
강사 소개

강사는 Google Developer Expert인 Philip입니다.
그의 목표는 개발자들이 AI와 에이전트를 활용하여 안정적이고 확장 가능한 아키텍처를 통해 더 나은 소프트웨어를 구축하도록 돕는 것입니다.

제2부: 규격 기반 개발(SDD)이 해결하는 문제점 (시작 시간 10% - 25%)

핵심 문제: AI의 컨텍스트 윈도우 제한

AI 모델은 '컨텍스트 윈도우'라는 개념을 가지고 있으며, 이는 단일 세션에서 처리할 수 있는 토큰(Token) 양이 제한적임을 의미합니다 (예: Fable 모델은 100만 개의 토큰).
소프트웨어 규모가 커질수록 작업은 더 작은 단위('Chunk')로 분할되어 여러 독립적인 AI 세션에서 완료되어야 합니다. 예를 들어, 세션 1에서는 기능 A를 구현하고, 세션 2에서는 기능 B를 구현하는 식입니다.
새로운 세션의 '기억 상실' 문제

새로운 AI 세션을 시작할 때마다, 이 세션은 이전 세션의 어떤 정보도 전혀 알지 못합니다.
하지만 프로젝트에는 소스 코드 파일, 요구사항, 설계 결정 및 아키텍처 결정 등 항상 관련성이 높은 '컨텍스트'가 대량으로 존재합니다.
해결책: 컨텍스트 엔지니어링 (Context Engineering)

'컨텍스트 엔지니어링'이란 AI 세션에 필요한 컨텍스트를 관리하고 공급하는 과정을 의미합니다.
**규격 기반 개발(SDD)**은 본질적으로 일종의 컨텍스트 엔지니어링 형태입니다. 이는 소프트웨어의 '규격(Specification)'을 단일 진실 공급원(Single Source of Truth)으로 사용합니다.
SDD의 작동 메커니즘

여러 세션 간에 컨텍스트를 공유하기 위해, 한 세션의 출력을 파일로 저장할 수 있습니다. AI 분야에서 Markdown(.md) 파일은 표준 형식인데, 이는 AI와 인간 모두에게 읽기 쉽기 때문입니다.
다른 새로운 세션은 이 Markdown 파일에 담긴 컨텍스트를 다시 지정할 필요 없이 직접 읽어올 수 있습니다.
SDD의 핵심 단계

1단계: 사고 및 계획: 어떤 작업이나 기능을 시작하기 전에, 무엇을 구축해야 할지 신중하게 생각합니다.
2단계: 규격 문서 작성: 즉시 실행에 옮기기보다는, 먼저 계획을 상세한 설계 문서(규격 문서)로 전환하는 것이 중요합니다. 이 문서에는 구축 목표, 이유, 대상 사용자, 개략적인 구현 계획, 작업 목록 및 실행 순서가 포함됩니다.
규격 문서의 역할

이 문서는 프로젝트 내 독립된 폴더에 보관되는 '살아있는 문서(Living Document)'입니다.

미래의 팀원들도 이 문서를 읽고 특정 기능의 용도를 이해할 수 있습니다.
매번 새로운 AI 세션에서 이 규격 문서를 AI에게 제공하여, 현재 무엇을 구축하고 있는지 알게 할 수 있습니다.

제3부: 주류 SDD 프레임워크 비교 및 OpenSpec의 장점 (시작 시간 25% - 45%)

SDD 프레임워크의 필요성

SDD는 정해진 형식은 없지만, 사람들은 일반적으로 하나의 프레임워크를 따릅니다. 이 프레임워크는 일련의 단계로 정의됩니다: 브레인스토밍(Brainstorming) -> 명세서 작성(Create Specification) -> 명세서 구현(Implement Specification).

주요 SDD 프레임워크 3가지 소개

GitHub SpecIt: Microsoft가 유지 관리하며, GitHub에서 13.9만 개의 스타를 보유하여 매우 인기 있습니다. 하지만 발표자는 이를 너무 장황하다(Verbose)고 생각하여 선호하지 않습니다. 생성되는 MD 파일은 매우 길고 많으며, 브레인스토밍부터 명세서 생성까지의 경로도 길어 검토하는 데 시간과 노력이 많이 듭니다. 발표자의 경험에 따르면, 오히려 덜 상세한 명세서가 더 나은 결과물을 얻을 수 있습니다.
Cairo: SDD 기능을 내장한 독립적인 IDE(VS Code 기반)입니다. 장점은 바로 사용할 수 있다는 것이지만, 단점은 특정 도구에 종속되어 유연성이 떨어진다는 것입니다. Android/iOS와 같은 모바일 개발의 경우, Android Studio나 Xcode 같은 무거운 IDE를 대체할 수 없습니다.
OpenSpec: 발표자는 이것이 승자라고 생각합니다.

OpenSpec의 핵심 장점

경량성(Lightweight): 매우 빠르며, 명세서를 얻기 위해 많은 명령을 실행할 필요가 없습니다.
유연성(Flexible): 사용자 정의 명세서 템플릿을 사용하여 상세 정도를 제어할 수 있습니다. 다른 프레임워크처럼 프로세스가 고정되어 있지 않습니다.
브라운필드 개발 적합성(Brownfield Work): 기존 코드베이스에서 작업하는 데 특히 적합합니다.
델타 명세서(Delta Specs): OpenSpec만의 독특한 기능입니다. 요구사항이 변경될 때, 전체 문서를 다시 작성하는 대신 신구 명세서 간의 차이점만 기록합니다. 이는 효율적인 변경 관리 방식입니다.

제4부: OpenSpec 설치 및 핵심 워크플로우 상세 분석 (시작 시간 45% - 85%)

OpenSpec 설치

OpenSpec은 명령줄 도구(CLI)입니다. npm 또는 brew(MacOS) 명령을 통해 전역 설치할 수 있습니다.

프로젝트 초기화

프로젝트 루트 디렉터리의 터미널(AI 에이전트 세션 외부)에서 openspec init 명령을 실행합니다.
통합하려는 AI 에이전트 도구(예: Claude Code)를 선택합니다.
초기화 후, 프로젝트 구조에 일련의 명령어와 스킬(Skills)이 생성됩니다. '스킬'은 본질적으로 명령어의 자연어 버전입니다.

4가지 핵심 스킬(Commands/Skills)

openspec explore (탐색):
- 목적: 공식 명세서 초안을 작성하기 전 브레인스토밍 단계입니다.
- 과정: AI 에이전트와 대화 루프에 진입하여 무엇을 구축할지 논의합니다. AI는 질문을 던져 아이디어를 개선하도록 돕습니다. 이 단계에서는 어떠한 명세서 파일도 생성되지 않습니다.
- 예시: 할 일 목록(To-Do) 앱을 만들겠다고 설명하면, AI는 iOS 지원 여부, 생성 방식, 데이터 모델, 저장 로직, 네비게이션 라이브러리 등과 같은 질문을 합니다.
openspec propose (제안):
- 목적: 탐색 단계의 합의를 바탕으로 실제 명세서 파일(Markdown 문서)을 생성합니다.
- 산출물: 프로젝트 openspec/changes/ 폴더 아래에 일련의 파일이 생성됩니다.
  - specs/ 폴더: 여러 '기능(Capability)' 하위 폴더를 포함하며, 각 기능은 특정 기능 슬라이스(예:
과정(Process): 완전히 새로운 AI 세션에서 이 명령을 실행합니다. 새 세션은 이전 대화를 기억하지 못하지만, 프로젝트 내의 규격 파일은 읽을 수 있습니다. 이것이 바로 컨텍스트 엔지니어링(Context Engineering)의 핵심입니다.
- 효과: 만약 규격 파일이 충분히 잘 작성되었다면, 코드 구현 과정이 매우 순조롭게 진행됩니다.
openspec archive (아카이브):
- 목적: 기능 하나가 완전히 구현된 후, 해당 규격 파일을 아카이브하여 그 기능이 완료되었음을 표시합니다.

중요 설정 파일: openspec-config.yaml
- AI 에이전트의 '시스템 프롬프트(System Prompt)'와 유사하지만, OpenSpec 프로세스에 특화되어 사용됩니다.
- 이 파일에서 기술 스택, 라이브러리, 코딩 스타일, 도메인 지식 등 프로젝트 수준의 일반 규칙을 정의할 수 있습니다.
- 적절하게 구성되면, explore 단계에서 AI는 이미 정의된 일반적인 질문들을 반복해서 묻지 않습니다.
워크플로우 시연 (To-Do List 앱 구축 예시)
- Explore 단계: App의 요구사항을 설명하면, AI가 8가지 질문(예: iOS 지원 여부, 생성 방식, 데이터 모델 필드, 저장 로직, 네비게이션 라이브러리 등)을 제기하고 사용자가 하나씩 답변합니다. 이 과정에서 기존 아이디어가 충분하지 않다고 판단하여 조정할 수 있습니다 (예: 자동 저장 기능을 수동 저장 버튼으로 변경).
- Propose 단계: AI는 논의 결과를 바탕으로 proposal.md, design.md, tasks.md 그리고 여러 개의 spec.md 파일을 자동으로 생성합니다.
- Apply 단계: 이전 세션 컨텍스트를 지우고, 새 세션에서 /opsx apply를 실행합니다. AI는 규격 파일을 읽어들이고, tasks.md에 있는 43개의 작업을 수행하기 시작하여, 최종적으로 기능이 완벽한 크로스 플랫폼(iOS & Android) To-Do List App을 성공적으로 구축합니다.

제5부: 요약 및 전망 (시작 시간 85% - 100%)

회고 및 강조
- 복잡한 요구사항의 경우, 규격을 수립하는 데 시간을 투자하는 것이 엄청난 이점을 가져온다는 점을 다시 한번 강조합니다.
- 최종적으로 구축된 App의 작동 효과를 보여줍니다: 생성, 편집, 삭제, 완료 표시, 필터링 등의 기능이 모두 정상적으로 작동합니다.
OpenSpec의 가치 재확인
- 이는 모든 프로젝트에 적용 가능하며 사용자 정의 워크플로우에 통합할 수 있는 초유연한 프레임워크입니다.
심화 방향성
- OpenSpec만으로는 충분하지 않으며, 완벽한 AI 워크플로우에는 테스트 케이스(단위 테스트, 엔드투엔드 테스트), 검증 메커니즘 등이 포함되어 진정한 시스템을 형성해야 합니다.
- 프로젝트가 커지고 배포 속도가 빨라짐에 따라, 줄 단위의 수동 검토에 의존할 수 없습니다.
결론 및 제언
- OpenSpec은 AI 에이전트 개발로 진입하기 위한 최고의 출발점이며, 컨텍스트 엔지니어링의 대부분의 어려움을 해결해 줍니다.
- 시청자들에게 채널을 구독하고 더 많은 관련 비디오와 리소스(예: 가이드 플랜)를 확인하도록 독려합니다.

AI 자동 생성 콘텐츠

원문 바로가기

OpenSpec을 활용한 규격 기반 개발(SDD) 입문 가이드

요약

핵심 포인트

제1부: 서론 및 배경 소개 (시작 시간 0% - 10%)

강좌 목표 및 적용 범위

이 강좌는 '규격 기반 개발(Spec-Driven Development, SDD)'을 어떻게 사용하는지, 특히 OpenSpec 도구와 결합하여 학습하는 초보자 대상의 종합 과정입니다.

학습 전제 조건

필수 조건: - Claude Code, Codex, Copilot과 같은 AI 에이전트 도구(Agent Harness)가 필요합니다. - 에이전트 작업을 실행할 터미널(Terminal)이 필요합니다.

강사 소개

강사는 Google Developer Expert인 Philip입니다.

제2부: 규격 기반 개발(SDD)이 해결하는 문제점 (시작 시간 10% - 25%)

핵심 문제: AI의 컨텍스트 윈도우 제한

AI 모델은 '컨텍스트 윈도우'라는 개념을 가지고 있으며, 이는 단일 세션에서 처리할 수 있는 토큰(Token) 양이 제한적임을 의미합니다 (예: Fable 모델은 100만 개의 토큰).

새로운 세션의 '기억 상실' 문제

새로운 AI 세션을 시작할 때마다, 이 세션은 이전 세션의 어떤 정보도 전혀 알지 못합니다.

해결책: 컨텍스트 엔지니어링 (Context Engineering)

'컨텍스트 엔지니어링'이란 AI 세션에 필요한 컨텍스트를 관리하고 공급하는 과정을 의미합니다.

SDD의 작동 메커니즘

여러 세션 간에 컨텍스트를 공유하기 위해, 한 세션의 출력을 파일로 저장할 수 있습니다. AI 분야에서 Markdown(.md) 파일은 표준 형식인데, 이는 AI와 인간 모두에게 읽기 쉽기 때문입니다.

SDD의 핵심 단계

1단계: 사고 및 계획: 어떤 작업이나 기능을 시작하기 전에, 무엇을 구축해야 할지 신중하게 생각합니다.

규격 문서의 역할

이 문서는 프로젝트 내 독립된 폴더에 보관되는 '살아있는 문서(Living Document)'입니다.

미래의 팀원들도 이 문서를 읽고 특정 기능의 용도를 이해할 수 있습니다.

제3부: 주류 SDD 프레임워크 비교 및 OpenSpec의 장점 (시작 시간 25% - 45%)

제4부: OpenSpec 설치 및 핵심 워크플로우 상세 분석 (시작 시간 45% - 85%)

제5부: 요약 및 전망 (시작 시간 85% - 100%)

댓글

제1부: 서론 및 배경 소개 (시작 시간 0% - 10%)

강좌 목표 및 적용 범위

이 강좌는 '규격 기반 개발(Spec-Driven Development, SDD)'을 어떻게 사용하는지, 특히 OpenSpec 도구와 결합하여 학습하는 초보자 대상의 종합 과정입니다.

학습 전제 조건

필수 조건: - Claude Code, Codex, Copilot과 같은 AI 에이전트 도구(Agent Harness)가 필요합니다. - 에이전트 작업을 실행할 터미널(Terminal)이 필요합니다.

강사 소개

강사는 Google Developer Expert인 Philip입니다.

제2부: 규격 기반 개발(SDD)이 해결하는 문제점 (시작 시간 10% - 25%)

핵심 문제: AI의 컨텍스트 윈도우 제한

AI 모델은 '컨텍스트 윈도우'라는 개념을 가지고 있으며, 이는 단일 세션에서 처리할 수 있는 토큰(Token) 양이 제한적임을 의미합니다 (예: Fable 모델은 100만 개의 토큰).

새로운 세션의 '기억 상실' 문제

새로운 AI 세션을 시작할 때마다, 이 세션은 이전 세션의 어떤 정보도 전혀 알지 못합니다.

해결책: 컨텍스트 엔지니어링 (Context Engineering)

'컨텍스트 엔지니어링'이란 AI 세션에 필요한 컨텍스트를 관리하고 공급하는 과정을 의미합니다.

SDD의 작동 메커니즘

여러 세션 간에 컨텍스트를 공유하기 위해, 한 세션의 출력을 파일로 저장할 수 있습니다. AI 분야에서 Markdown(.md) 파일은 표준 형식인데, 이는 AI와 인간 모두에게 읽기 쉽기 때문입니다.

SDD의 핵심 단계

1단계: 사고 및 계획: 어떤 작업이나 기능을 시작하기 전에, 무엇을 구축해야 할지 신중하게 생각합니다.

규격 문서의 역할

이 문서는 프로젝트 내 독립된 폴더에 보관되는 '살아있는 문서(Living Document)'입니다.

미래의 팀원들도 이 문서를 읽고 특정 기능의 용도를 이해할 수 있습니다.

제3부: 주류 SDD 프레임워크 비교 및 OpenSpec의 장점 (시작 시간 25% - 45%)

제4부: OpenSpec 설치 및 핵심 워크플로우 상세 분석 (시작 시간 45% - 85%)

제5부: 요약 및 전망 (시작 시간 85% - 100%)

필수 조건:
- Claude Code, Codex, Copilot과 같은 AI 에이전트 도구(Agent Harness)가 필요합니다.
- 에이전트 작업을 실행할 터미널(Terminal)이 필요합니다.

필수 조건:
- Claude Code, Codex, Copilot과 같은 AI 에이전트 도구(Agent Harness)가 필요합니다.
- 에이전트 작업을 실행할 터미널(Terminal)이 필요합니다.