Show HN: 명세 기반 개발 (Spec-Driven Development, SDD)을 위한 Claude Skill을 만들었습니다
요약
Claude, Cursor, Copilot 등 다양한 AI 도구 간의 작업 모순을 방지하기 위한 '명세 기반 개발(SDD)' Claude Skill을 소개합니다. 사용자와의 인터뷰를 통해 요구사항, 디자인, 작업 계획을 담은 표준화된 파일을 생성하여 AI 에이전트 간의 '공유된 진실의 원천'을 제공합니다.
핵심 포인트
- AI 도구 간의 작업 불일치 및 모순 문제 해결
- requirements.md, design.md, tasks.md를 통한 명세 표준화
- 모든 AI 에이전트가 동일한 계획을 공유하도록 유도
- 추적 가능하고 테스트 가능한 요구사항 관리
spec-driven-development
Claude, Cursor, 그리고 Copilot이 코드를 건드리기 전에 모두 동일한 계획을 읽습니다.
코드를 작성하기 전에 명세(specs)를 작성해 주는 Claude skill입니다. 사용자와 인터뷰를 진행하고, requirements.md, design.md, tasks.md를 생성하며, 사용하는 모든 AI 도구가 서로 모순되지 않도록 일치하는 설정 파일(config files)을 생성합니다.
이 도구가 해결하는 문제
Claude Code를 열고 기능을 만들어 달라고 요청합니다. 한 시간 뒤, 기술적으로는 인상적이지만 당신이 원했던 것과는 정확히 일치하지 않는 무언가가 완성되어 있습니다. Cursor에게 이를 수정해 달라고 요청합니다. Cursor는 Claude Code가 했던 작업과 모순되는 내용을 내놓습니다. Copilot에게 정리해 달라고 요청합니다. Copilot은 제3의 해석을 만들어냅니다.
근본 원인은 항상 동일합니다. 당신의 AI 에이전트들에게 공유된 진실의 원천 (source of truth)이 없기 때문입니다. 그들은 모든 공백을 자신만의 가정으로 채워 넣습니다.
이 skill은 코드가 작성되기 전에 세 가지 파일을 생성함으로써 이 문제를 해결합니다:
| 파일 | 답변 내용 |
|---|---|
requirements.md | 시스템이 반드시 수행해야 하는 것 |
| ... |
실제 파일들은 다음과 같은 모습입니다:
requirements.md — 모든 요구사항은 추적 가능하고 테스트 가능합니다:
- **REQ-001**: 사용자는 클라이언트 프로젝트에 대해 시간 입력(time entries)을 기록해야 한다.
- _수락 기준 (Acceptance）_: POST /entries는 entry id, duration, project_id와 함께 201을 반환해야 한다.
- **REQ-002**: 사용자는 기록된 입력값으로부터 월간 인보이스를 생성해야 한다.
...
tasks.md — 모든 작업은 해당 요구사항과 연결됩니다:
- [ ] **TASK-003** [REQ-001]: 유효성 검사가 포함된 POST /entries를 구현한다
- _출력 (Output）_: 라우트 핸들러 + duration 스키마 유효성 검사
- _검증 (Verify）_: POST /entries는 모든 필수 필드와 함께 201을 반환한다
모든 AI 도구는 코드를 건드리기 전에 이 파일들을 읽습니다. 드리프트(Drift, 괴리)가 중단됩니다.
빠른 시작 (Quick start)
빠른 시작 (Quick start)
Skill을 설치한 후, 다음 중 하나로 대화를 시작하세요:
"새 프로젝트를 시작하고 싶어"
"내 AI가 계속 스크립트를 벗어나는데, 도와줘"
"이미 코드베이스가 있지만, 명세(Spec)는 아직 없어"
...
Claude가 몇 가지 짧은 질문을 던진 후 명세(Spec) 파일들을 생성합니다.
별도의 설정은 필요하지 않습니다.
설치 (Installation)
Claude.ai / Claude 데스크톱 앱 (Chat 탭)
spec-driven-development-v1.0.skill을 다운로드합니다.- Claude 설정(Settings) → Skills → Install from file을 선택합니다.
또는 CLI를 통해 설치할 수 있습니다:
claude plugin install FredAntB/spec-driven-development
Claude Code (Code 탭)
git clone https://github.com/FredAntB/spec-driven-development
Code 탭에서 해당 폴더를 엽니다. CLAUDE.md 파일은 세션 시작 시 자동으로 읽혀 Skill을 부트스트랩(Bootstrap)합니다.
Windows 참고 사항: Code 탭이 로컬 폴더와 작동하려면 Git이 설치되어 있어야 합니다. git-scm.com에서 다운로드하세요.
제공 기능 (What you get)
새 프로젝트를 위한 경우 (Greenfield)
Claude가 대화하듯 한 번에 하나씩, 총 4개의 짧은 질문으로 인터뷰를 진행한 후 다음을 생성합니다:
your-project/
├── requirements.md ← 시스템이 수행해야 할 사항
├── design.md ← 구축 방법
...
requirements.md는 shall 언어와 REQ-xxx ID를 사용하여 모든 요구사항을 추적(Traceable)할 수 있게 합니다:
## 기능 요구사항 (Functional Requirements)
### 작업 (Tasks)
...
tasks.md는 모든 작업을 인라인(Inline)으로 해당 요구사항에 연결합니다:
## 2단계: 핵심 엔드포인트 (Core endpoints)
- [ ] **TASK-007** [REQ-001]: 유효성 검사가 포함된 POST /tasks 구현
...
기존 코드베이스를 위한 경우 (Retrofit)
사용자가 설명한 내용을 바탕으로 역공학(Reverse-engineered)하여 동일한 결과를 제공합니다:
your-project/
├── requirements.md ← v0-retrofit: 기존 코드에서 발견된 내용
├── design.md ← 추론된 모든 필드에 [TO VERIFY] 표시 포함
...
교차 AI 팀을 위한 경우 (Cross-AI teams)
팀에서 사용하는 모든 도구에 대해 동일한 지침 블록(Instruction blocks)을 생성합니다:
your-project/
├── CLAUDE.md ← Claude Code
├── .cursorrules ← Cursor
...
각 파일은 동일한 범용 지침 블록 (Universal Instruction Block)을 포함합니다. 즉, 에이전트들은 동일한 명령을 읽고, 동일한 명세 (spec) 파일을 인용하며, 동일한 분기 프로토콜 (divergence protocol)을 따릅니다. 유일한 차이점은 도구별로 추가된 사항뿐입니다.
지원되는 AI 도구 (Supported AI tools)
| 도구 (Tool) | 설정 파일 (Config file) | 상태 (Status) |
|---|---|---|
| Claude Code | CLAUDE.md | ✓ 테스트 완료 |
| ... |
범용 지침 블록 (The Universal Instruction Block)
모든 AI 설정 파일은 프로젝트 이름과 명세 버전 (spec version)만 채워진 상태로 이 블록을 포함합니다:
═══════════════════════════════════════════════════════════
명세 기반 개발 (SPEC DRIVEN DEVELOPMENT) — 프로젝트 헌법 (PROJECT CONSTITUTION)
프로젝트: 귀하의 프로젝트 이름
...
테스트 스위트 및 CI (Test suite & CI)
이 스킬은 3단계에 걸쳐 135개의 어설션 (assertions)을 포함하는 완전하고 실행 가능한 테스트 스위트를 함께 제공합니다. GitHub Actions 워크플로 (workflow)가 모든 푸시 (push) 및 풀 리퀘스트 (pull request) 시 자동화 가능한 체크 항목들을 실행합니다.
GitHub Actions 워크플로 (.github/workflows/ci.yml)
main/master로의 모든 푸시와 모든 PR에 대해 네 가지 작업 (jobs)이 실행됩니다:
| 작업 (Job) | 역할 | 통과 필수 여부? |
|---|---|---|
phase2a | Python을 통해 67개의 정적 어설션 (static assertions) 실행 | 예 — 필수 관문 (hard gate) |
| ... |
브랜치 보호 설정 (Branch protection setup) — 리포지토리 (repo) 설정에서 all-checks를 단일 필수 상태 체크 (required status check)로 추가하세요. 이는 이제 하나의 규칙이 모든 자동화된 단계와 향후 추가될 모든 단계를 커버함을 의미합니다.
로컬 실행 (Running locally)
# Phase 2A — 정적 어설션 (static assertions) (67개 체크)
python3 phase2a/run_assertions.py
...
또는 어떤 머신에서든 설정 없이 실행하려면 각 단계의 KICKOFF.md를 Claude Code 탭에 붙여넣으세요.
Claude Code에서 실행 (Code 탭)
| 단계 (Phase) | 붙여넣기 (Paste this) | 출력 (Output) |
|---|---|---|
| 2A | phase2a/KICKOFF.md | 스크립트 실행 및 실패 사항 설명 |
| ... |
Phase 2C 피스처 (fixtures)
Phase 2C는 Claude Code가 실제 명세 (spec) 파일을 생성하도록 요구하며, 생성된 파일은 CI가 매 푸시마다 확인할 수 있도록 피스처 (fixtures)로서 리포지토리에 커밋됩니다.
중요한 스킬 변경 후 피스처 (fixtures)를 다시 생성하려면:
- Code 탭에서 리포지토리 폴더를 엽니다.
phase2c/KICKOFF.md를 붙여넣습니다.- Claude Code가
phase2c/flow_a/,phase2c/flow_b/,phase2c/flow_c/에 작성한 파일들을 커밋합니다.
CI는 다음 푸시 (push) 시 새로운 피스처 (fixtures)를 자동으로 감지합니다.
현재 테스트 결과
| 단계 (Phase) | 유형 (Type) | 단언 (Assertions) | CI |
|---|---|---|---|
| 2A | 정적 파일 검사 (Static file checks) | 67 / 67 ✓ | 자동화됨 (Automated) |
| ... |
트리거 문구 (Trigger phrases)
이 스킬은 폭넓은 어휘에 반응하여 활성화됩니다. 예시는 다음과 같습니다:
프로젝트 시작 시:
"새 프로젝트를 시작하고 싶어" · "코딩하기 전에 계획 세우는 것을 도와줘" ·
"내 프로젝트를 위한 SDD를 설정해줘" · "명세 (spec)가 필요해"
AI 도구 설정 시:
"Cursor와 Claude Code를 설정해줘" · "cursorrules 파일을 만들어줘" ·
"내 AI가 자꾸 스크립트에서 벗어나" · "내 에이전트들이 일관성을 유지하게 해줘"
기존 코드베이스:
"이미 코드베이스가 있지만, 아직 명세는 없어" ·
"내 시스템이 무엇을 하는지 문서화하는 것을 도와줘" ·
"내 아키텍처를 설명해줘" · "기존 프로젝트에 명세를 추가해줘"
기능 요청 시:
"다크 모드를 추가해줘" → 코드를 작성하기 전 명세 존재 여부 확인을 트리거함
"그냥 코딩 시작해줘" → 안티 패턴 (anti-pattern) 경고를 트리거함
스킬이 방지하는 안티 패턴 (Anti-patterns)
| 안티 패턴 (Anti-pattern) | 스킬의 동작 |
|---|---|
| "그냥 코딩 시작해줘" | 구체적인 이유를 들어 반대하며, 명세를 요구함 |
| ... |
커뮤니티 베타 — 테스터가 필요합니다
이 스킬은 퍼블릭 베타 (public beta) 단계에 있습니다. 135개의 자동화된 단언 (assertions)과 3개의 엔드 투 엔드 (end-to-end) 생성 흐름을 통과했지만, 아직 자연어를 사용하는 낯선 사람들에 의한 테스트는 거치지 않았습니다.
다음 프로필에 해당하는 5명의 테스터가 필요합니다:
- 첫 번째 실제 프로젝트를 시작하는 완전 초보자
- 활발한 사이드 프로젝트(신규 프로젝트 또는 부분적 프로젝트)를 진행 중인 1인 개발자
- 팀원들이 여러 AI 도구를 사용하는 팀 리드 (team lead)
- 기존 코드베이스는 있지만 작성된 명세가 없는 개발자
- 3개 이상의 AI 코딩 도구를 동시에 활발하게 사용하는 개발자
자원하려면: [Beta] I'd like to test라는 제목으로 이슈 (issue)를 생성하고, 어떤 프로필이 본인에게 가장 잘 맞는지 설명해 주세요.
여러분이 해야 할 일은 실제 업무에 이 스킬을 자연스럽게 사용하고, 제대로 작동하지 않을 때 이슈 (issue)를 등록하는 것뿐입니다. 그게 전부입니다.
기여하기 (Contributing)
- 리포지토리 (repo)를 포크 (Fork) 하세요
SKILL.md또는 참조 파일 (reference files)을 수정하세요- Phase 2A 어설션 스위트 (assertion suite)를 실행하세요:
python3 phase2a/run_assertions.py - 어설션 (assertion)이 실패하면, PR (Pull Request)을 올리기 전에 수정하세요
- 변경 사항이 새로운 동작을 추가한다면, 그에 상응하는 어설션을 추가하세요
새로운 어설션은 phase2a/assertions.md (사람이 읽을 수 있는 명세)와 phase2a/run_assertions.py (기계가 실행 가능한 체크)에 작성합니다.
스킬 구조 (Skill structure)
spec-driven-development/
├── SKILL.md ← 스킬 (이것을 설치하세요)
├── CLAUDE.md ← Code 탭 부트스트랩 (bootstrap)
...
라이선스 (License)
MIT — 자유롭게 사용 가능하며, 출처 표기를 권장합니다.
감사의 글 (Acknowledgements)
Claude 스킬 프레임워크를 사용하여 구축 및 테스트되었습니다. 테스트 스위트 (test suite) 방법론은 skill-creator 평가 하네스 (eval harness)를 변형하여 적용했습니다. 135개의 모든 어설션은 해당 수정 사항이 나오기 전에 작성되었습니다 — 언제나 테스트 우선 (test-first) 원칙을 따릅니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 HN Code Generation의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기