Spec Driven Development

PRD (Product Requirements Document) 제품 요구사항 문서
→ 제품이 왜 필요하고, 사용자를 위해 무엇을 해야하는지 서술하는 문서

SDD (Software Design Document) 소프트웨어 설계 문서
→ PRD에 명시된 요구사항을 기술적으로 어떻게 구현할 것인지 서술하는 문서

명세의 경우 OpenSpec, SpecKit, Kiro 같은 도구들을 이용하여 명세서를 쉽고 간편하게 생성할 수 있고 일관되게 관리 할 수 있음.

https://github.com/Fission-AI/OpenSpec

GitHub - Fission-AI/OpenSpec: Spec-driven development for AI coding assistants.

https://github.com/github/spec-kit

GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development

https://kiro.dev/

Kiro

SpecKit의 경우, 신규 프로젝트의 경우 쉽게 사용할 수 있지만 기존 프로젝트에 통합하는 것은 어렵다는 얘기를 Reddit에서 봤음.

OpenSpec은 좋다, 괜찮다는 얘기가 많았음.

Kiro는 IDE여서 패스.

 

OpenSpec을 써보자.

https://www.youtube.com/watch?v=cQv3ocbsKHY

 

OpenSpec의 동작 원리

┌────────────────────┐
│   변경 제안 초안 작성   │
└────────┬───────────┘
         │ AI와 의도 공유
         ▼
┌────────────────────┐
│      검토 및 조율     │
│    (사양/작업 수정)   │◀──── 피드백 루프 ──────┐
└────────┬───────────┘                     │
         │ 승인된 계획                        │
         ▼                                 │
┌────────────────────┐                     │
│      작업 구현       │─────────────────────┘
│   (AI가 코드 작성)    │
└────────┬───────────┘
         │ 변경 사항 배포
         ▼
┌─────────────────────┐
│      아카이브 및       │
│   사양 업데이트 (소스)   │
└─────────────────────┘

1.  원하는 사양 업데이트를 담은 변경 제안서 초안을 작성합니다.
2.  모두가 동의할 때까지 AI 어시스턴트와 함께 제안서를 검토합니다.
3.  합의된 사양을 참조하여 작업을 구현합니다.
4.  승인된 업데이트를 신뢰할 수 있는 원본(source-of-truth) 사양에 다시 병합하기 위해 변경 사항을 아카이브합니다.

openspec/AGENTS.md에 작성된 지침을 자동으로 감지하고 읽어온다고 함. 루트 디렉터리에 AGENTS.md를 작성한게 있다면 복사해서 openspec/AGENTS.md 위치로 옮겨야 함.

설치 후 초기 설정 명령어.

npm install -g @fission-ai/openspec@latest
openspec --version
cd my-project
openspec init

 

설치 후 사용하고 있는 AI Agent에 아래 명령어를 입력하여 OpenSpec을 호출할 수 있다.

Claude Code	/openspec:proposal, /openspec:apply, /openspec:archive
Cursor	/openspec-proposal, /openspec-apply, /openspec-archive
Factory Droid	/openspec-proposal, /openspec-apply, /openspec-archive (.factory/commands/)
OpenCode	/openspec-proposal, /openspec-apply, /openspec-archive
Kilo Code	/openspec-proposal.md, /openspec-apply.md, /openspec-archive.md (.kilocode/workflows/)
Windsurf	/openspec-proposal, /openspec-apply, /openspec-archive (.windsurf/workflows/)
Codex	/openspec-proposal, /openspec-apply, /openspec-archive (global: ~/.codex/prompts, auto-installed)
GitHub Copilot	/openspec-proposal, /openspec-apply, /openspec-archive (.github/prompts/)
Amazon Q Developer	@openspec-proposal, @openspec-apply, @openspec-archive (.amazonq/prompts/)

 

이후 아래 명령어로 명세서가 잘 생성되었는지 등을 확인.

openspec list                         # 변경 폴더가 있는지 확인합니다 
openspec validate add-profile-filters # 사양 서식의 유효성을 검사합니다
openspec show add-profile-filters     # 제안, 작업 및 사양 변경사항을 검토합니다

 

이후 아래 명령어로 명세서 기반으로 작업 시작.

/openspec:apply add-profile-filters

 

오, 요로코롬 명령어가 뜬다.

 

오..

 

명세서 생성해보라고 하니까 이런식으로 만들기 시작했다.

 

생성된 문서들을 보고 이상한 부분은 수정하고, 추가 컨텍스트도 넣어 준 뒤 구현을 시작하면 됨.

 

openspec 폴더 통짜로 SVC에 올려도 될까? 다른 동료들에게 방해가 되진 않을까? 에 대한 gemini 2.5 pro 씨의 답변.
→ OpenSpec 폴더 전체를 Git에 올리는 것은 '명세도 코드처럼(Specs as Code)' 관리하여 팀의 협업을 원활하게 하기 위함입니다. 이를 통해 모든 팀원이 동일한 최신 사양(specs)과 논의 중인 변경안(changes)을 공유할 수 있습니다. 또한, Git으로 모든 변경 이력을 투명하게 추적하고, 코드 수정과 관련 사양 변경을 하나의 Pull Request로 묶어 검토함으로써 코드와 문서가 따로 노는 현상을 방지하고 프로젝트의 일관성을 강력하게 유지할 수 있습니다.

openspec 폴더 내부는 이렇게 생겼는데, 각 폴더의 의미는 이렇다.

changes → 명세서 초안
specs → openspec apply로 실제 구현까지 완료된 명세서 요약본
archive → openspec archieve로 아카이브 처리한 명세서

 

아래 글도 읽어보면 좋다.
https://www.reddit.com/r/ChatGPTCoding/comments/1nnoh8l/cheap_my_go_to_vibecoding_stack/?tl=ko