GitHub Copilot, Claude Code, Cursor와 같은 AI 코딩 어시스턴트가 보편화되기 전까지 소프트웨어 개발은 "코드 우선, 문서 이후"의 모델을 따랐으며, 세 가지 핵심 아픔을 겪고 있었습니다:
| 아픔 | 구체적인 표현 | 영향 |
|---|---|---|
| 의도와 구현 간의 간극 | 요구사항 문서가 흐릿하고 변경이 잦아, 코드와 문서가 오랫동안 이루어지지 않았습니다 | 커뮤니케이션 비용이 높고 리팩토링 위험이 크며 유지보수가 어려웠습니다 |
| 협업 효율 저하 | 팀원들이 요구사항을 달리 이해하고, 통일된 "사실의 출처"가 부족했습니다 | 반복적인 작업이 많고, 충돌이 자주 발생하며, 제공 주기가 길다 |
| 품질 보증이 지연되고 | 테스트가 코드 작성 후에 이루어지므로 결함 발견이 늦고, 수정 비용이 높다 | 제품의 안정성이 부족하여 사용자 경험이 손해를 입는다 |
AI 코드 작성 도구가 보편화되면서 이러한 문제들이 더욱 심화되고 있습니다: AI는 빠르게 코드를 생성할 수 있지만, 전체 시스템 아키텍처와 비즈니스 논리를 이해하지 못하여 "지역적으로 올바르지만 전반적으로 잘못된" 코드를 생성하기 쉽습니다; 또한 개발자들이 AI의 힌트에 과도하게 의존하여 코드 품질이 불균일해지고 유지보수성이 급격히 저하됩니다
규범에 의한 개발 (Spec-Driven Development, SDD)는 생성형 AI 시대에 맞는 엔지니어링 개발을 위한 새로운 소프트웨어 개발 방법론으로, 핵심은 기술자가 간결하고 테스트 가능하며 형식화된 시스템 사양 명세 (Spec)를 먼저 정의하고, 이를 인간, 팀, AI 간의 "동적 계약"으로서 개발 과정의 유일한 사실 출처로 사용하는 것입니다.
SDD는 세 가지 혁명적인 전환을 가져옵니다:
SDD는 새로운 개념이 아니라 전통적인 소프트웨어 공학 이론의 발전입니다:
| 대비 차원 | Spec-Kit (GitHub) | OpenSpec | Superpowers |
|---|---|---|---|
| 핵심 정의 | "도면파": 0부터 시작하는 완전한 계획, 0-1 프로젝트에 적합 | "농사인파": 기존 시스템의 점진적 개선, 1-n 프로젝트에 적합 | "전 과정 관리인": 요구사항부터 전달까지의 완전한 개발 프로세스 관리 |
| 설계 철학 | "규격은 법률"(고정된 규칙 체계), 통제 프로세스와 상세 문서 강조 | "OPSX 유연 작업 흐름"(단계가 아닌 행동), 변경 제안을 중심으로, 프로세스가 간결 | "테스트 우선, 증거 주도", 시스템화된 복잡성 감소 |
| 철학적 기초 | 심도 있는 규격 주도, 프로세스 완전성 및 제어 가능성 추구 | 가벼운 규격 주도, 빠른 반복 및 최소주의주의 추구 | 방법론 주도 (기술 시스템), 심리학적 지도 강조 AI 행동 |
| 적용 팀 | 조직화 완벽, 엄격한 프로세스 준수 규정을 가진 대규모 팀 | 점진적 팀, 초기 창업 회사, 빠른 반복이 필요한 프로젝트 | 독립 개발자, 품질 지향 팀, AI 대리인 집중형 프로젝트 |
| 비교 차원 | Spec-Kit (GitHub) | OpenSpec | Superpowers |
|---|---|---|---|
| 기술 스택 | Python (uv 패키지 관리자), CLI 드라이버, 다양한 플랫폼 지원 | TypeScript (npm), 웹 UI+CLI 이중 모드, 가벼운 | Markdown+JavaScript 플러그인, 에디터 통합, 다양한 플랫폼 |
| 핵심 프로세스 | 7단계 선형 프로세스: spec→plan→tasks→구현→검증→문서화→발전 | 3단계 점진적 프로세스: 제안→적용→보관, 관리 규범 점진적 증가 | 5단계 순환 프로세스: 아이디어 구상→분리→계획→TDD→검토 |
| 표준 형식 | 구조화된 마크다운, 복잡한 시나리오와 제약 조건 지원 | 최소한의 YAML, 변경 사항에 집중, 문서량 최소화 | 자연어 + 테스트 케이스, 실행 가능성 및 증거 검증 강조 |
| AI 통합 | 내장 지원 15+AI 코드 도우미, 통일된 인터페이스 관리 | Claude와 Copilot에 집중, 가벼운 통합 강조 | 깊이 통합 GitHub Copilot, 소크라테스식 대화 지원 |
| 변경 관리 | 동적 헌법 메커니즘, 버전화 표준화, 완전한 감사 추적 | 분리 변경, 합의 주도, 위험 관리 우선 | 미 작업 분리, 자동 충돌 해결, 빠른 롤백 메커니즘 |
| 학습 곡선 | 높은, 프로세스 의식 있는 팀에 적합 | 완만한, 빠르게 익힐 수 있는 시나리오에 적합 | 중간, 테스트 주도 개념 이해 필요 |
다양한 시나리오에 대해, 프로젝트 유형, 팀 규모, 규범 복잡도等多각도 요소를 고려하여 전반적으로 평가하여 가장 적합한 SDD 도구를 선택하십시오:
| 결정 요인 | Spec-Kit을 선택하세요 | OpenSpec을 선택하세요 | Superpowers를 선택하세요 |
|---|---|---|---|
| 프로젝트 유형 | 완전히 새로운 프로젝트, 기업급 프로젝트 | 점진적 변경, 유지보수 중인 시스템 | 프로토타이핑, AI 집중형 |
| 팀 규모 | 10명 이상, 다단체 | 3-10 사람, 민첩 팀 | 1-3 사람, 독립 개발자 |
| 규범 복잡도 | 높음 (상세한 제약 필요) | 낮음 (변경점에 집중) | 중간 (테스트 케이스 강조) |
| 프로세스 요구사항 | 엄격 (문턱 메커니즘) | 유연 (증분 프로세스) | 자동화 (전체 프로세스) |
| 학습 비용 | 높음 (교육 필요) | 낮음 (빠르게 시작) | 중간 (테스트 드리븐 이해) |
Spec-Kit의 핵심 혁신은 규격을 정적 문서에서 실행 가능한 개발 지시로 전환하는 데에 있다:
Spec-Kit의 핵심은 7단계 도어컨트롤 개발 프로세스는 각 단계마다 검증 가능한 엔지니어링 산출물에 대응하며, 요구사항부터 구현까지 강한 제약 체인을 형성합니다. 각 단계는 엄격한 순서로 실행되며, 이전 단계의 검증이 통과되지 않으면 다음 단계로 진행할 수 없습니다.
| 단계 번호 | 단계 이름 | 핵심 목표 | 산출 파일 | 핵심 제약 |
|---|---|---|---|---|
| 1 | Constitution | 프로젝트 헌법 및 기술적 적색선 설정 | constitution.md | 금지 사항, 승인 사항, 허용 범위 정의; 팀 합의 서명 필요 |
| 2 | 자연어 요구사항을 형식화 규범으로 전환 | spec.md | 구조화된 의미 템플릿을 사용해야 하며, 모호한 표현은 금지 | |
| 3 | Clarify | 의미 불명확성을 제거하고 경계와 예외를 확인 | clarification.md | 모든 모호한 지점은 제품/아키텍처 설계자의 서명으로 확인되어야 함 |
| 4 | Plan | 기술적 구현 경로와 아키텍처 선택 설계 | plan.md | 은 기술 스택, 데이터 흐름, 의존성 그래프, 위험 평가를 포함해야 합니다 |
| 5 | Tasks | 는 실행 가능하고 추적 가능한 개발 작업으로 분해되어야 합니다 | tasks.md | 각 작업은 담당자, 예상 작업 시간, 수락 기준을 연결해야 합니다 |
| 6 | Analyze | 규범 일관성 및 변경 사항 영향 분석 | 자동 분석 보고서 | 형식화 검증 통과율 ≥95%, 영향 범위는 시각화되어야 합니다 |
| 7 | Implement | AI로 코드 생성 및 코드 리뷰 제출 | 코드 생성 + 테스트 케이스 | 코드는 spec.md와 양방향 추적되어야 하며, 수동 덮어쓰기는 허용되지 않음 |
모든 단계는 specify CLI 도구로 주도되며, 각 단계의 공급물은 자동으로 버전 관리에 통합되어 검증 가능한, 추적 가능한, 검증 가능한 엔지니어링 계약 체인을 형성
어떤 단계도 게이트 체크를 통과하지 못하면 시스템은 후속 프로세스를 차단하여 "규범이 권위임"을 보장
Spec-Kit은 프로젝트 헌법 (Project Constitution) 개념을 도입하여 프로젝트의 "최고 법률"로서 기능:
Spec-Kit의 핵심 철학은 규범이 유일한 사실 출처이며, 모든 개발 활동은 규범을 중심으로 이루어집니다:
Spec-Kit는 먼저 의도를 명확히 하고 나서 구현을 고려한다는 점을 강조하며, 전통적인 "구현 우선" 모드와 명백한 대조를 이룹니다:
Spec-Kit는 개발자와 AI의 협업 모드를 재정의하여 "AI가 코드를 보조한다"에서 "규격이 AI 개발을 주도한다"로 업그레이드했습니다:
Spec-Kit은 모듈화되고 확장 가능한 아키텍처 설계를 채택하며, 핵심은 네 개의 계층으로 구성되어 있으며, 하부에서 상부로 차례로 다음과 같습니다.
Spec-Kit은 GitHub 공식 오픈 소스의 규격 주도 개발(Spec-Driven Development, SDD) 도구 키트입니다. 표준화된 워크플로우(Specify → Plan → Tasks → Implement)를 통해 개발자들이 AI 코딩 보조 도구(claude, opencode 등)를 활용하여 고품질 소프트웨어를 구축하고, '분위기 코딩'(Vibe Coding)으로 인한 코드 품질 불일치와 프로세스 누락 문제를 해결하는 데 도움을 줍니다.
Spec-Kit은 Python으로 개발되었으며, 패키지 관리자와 도구 실행기로 uv를 의존합니다. 이는 전통적인 pip/venv보다 더 빠르고 관리하기 쉽기 때문입니다.
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 验证安装
uv --version
# 使用 uv 安装 Spec-Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 验证安装
specify --version
기존 프로젝트 초기화:
# 在当前目录初始化
specify init .
# 指定特定的 AI 助手
specify init . --ai opencode
새 프로젝트 생성 및 초기화:
# 基本初始化
specify init project01
# 指定特定的 AI 助手
specify init project01 --ai claude
# 指定脚本类型 (Mac/Linux默认sh，Windows默认ps，也可强制指定)
specify init project01 --script sh
초기화 과정에서의 상호작용 안내:
# 编辑 .gitignore 文件，添加以下内容（根据你使用的 AI 工具调整）
.opencode
.omo
.claude
.specify
specs
초기화가 완료되면, AI 코딩 보조 프로그램을 엽니다(터미널에서 opencode, claude를 입력하여 해당 프로그래밍 도구를 시작하거나, VS Code/Cursor에서 프로젝트를 엽니다).
다음 Slash Commands(슬래시 명령어)이 사용 가능한지 확인:
| 명령 | 기능 설명 | 단계 |
|---|---|---|
| /speckit.constitution [필수] | 프로젝트 원칙 및 협상 불가능한 기준 설정 | 0. 준비 |
| /speckit.specify [필수] | "무엇을 하고, 왜 하느냐"를 정의하고 명세 문서 생성 | 1. 명세화 |
| /speckit.clarify | 계획 전에 질문을 통해 불분명한 요구 사항을 명확히 함 | 1.5 명확화 |
| /speckit.plan [필수] | 규격 및 기술 스택을 기반으로 기술 구현 계획 생성 | 2. 계획 |
| /speckit.tasks [필수] | 계획을 실행 가능하고 순서 있는 작업 목록으로 분해 | 3. 작업 분해 |
| /speckit.analyze | 작업 일관성 및 커버리지 분석 | 3.5 분석 |
| /speckit.implement [필수] | 작업 수행, 코드 및 테스트 생성 | 4. 구현 |
일반적인 워크플로우 예시：
문제: Spec 문서의 언어와 스타일을 어떻게 지정할까요？
## Communication Guidelines
- **Language**: All specifications, plans, tasks, code comments, and commit messages MUST be written in **Simplified Chinese (zh-CN); unless explicitly requested otherwise.
- **Tone**: Professional, concise, and direct.
우리는 "XXL-API 프로젝트 코드 리팩토링"을 예시로 삼아 Spec-Kit의 완전한 실천 프로세스를 보여줍니다.
이번 개선 프로젝트는 공식 오픈소스 프로젝트로, 코드 규범성과 품질에 대한 요구사항이 있습니다. 또한, 이 리팩토링 요구사항은 "9개의 기능 모듈", "프론트엔드 및 백엔드 코드 로직 수정"을 포함하며, 총 130개 이상의 프로젝트 파일을 수정해야 하므로 중간 크기의 미세한 요구사항입니다. 이번 개선 요구사항은 일정한 복잡성을 가지고 있습니다.
프로젝트 루트 디렉토리로 이동하여 다음 명령어를 실행하여 Spec-Kit 엔지니어링 계약 체인을 생성합니다.
specify init .
명령어를 실행한 후, ".specify 계약 체인 파일 디렉토리"가 생성됩니다.
다음 명령어를 실행하여 “프로젝트 헌법”(예: 프로젝트 약속, 기술 스택 및 제약 조건, 개발 워크플로우 등)을 생성하고, 이후 규범 및 코드 구현의 일관성과 관리 가능성을 보장합니다.
# 创建项目宪法
/speckit.constitution
# 创建项目宪法，补充指定中文约束（否则默认生成 英文 内容）
/speckit.constitution 补充1条规则：所有规范文档使用中文描述
명령어 실행 후 .specify/memory/constitution.md 파일이 생성되며, 내용은 다음과 같습니다:
다음 명령어를 실행하고 기능 요구 사항 설명을 작성하여 “기능 사양(Spec)”을 생성합니다:
/speckit.specify 针对XXL-API项目按照如下要求重构：
1、按照下面项目规范结构，重构重构项目目录结构：
xxl-api-admin/src/main/java/com/xxl/api/admin
- /framework: 基础框架代码，包含公共的 登录、util、过滤器等组件。
- /business：业务代码，包含具体业务模块的 controller、service、model、mapper 子分层代码。
xxl-api-admin/src/main/resources/templates
- /framework：基础模板，基础框架实体 对应的。
- /business：业务模板，业务领域实体对应的。
xxl-api-admin/src/main/resources/mapper
- /framework：基础Mapper文件，基础框架实体 对应的。
- /business：业务Mapper文件，业务领域实体对应的。
2、业务代码分类判断逻辑：Java代码部分，当前 com/xxl/api/admin/controller/biz 下除了 UserController 都是 业务领域，保留User相关Java代码不变，其他按照规范调整。模板部分，当前 help.ftl、index.ftl、login.ftl 属于基础框架，其他属于业务领域；Mapper部分，当前 XxlApiUserMapper.xml 属于基础框架，其他属于业务部分。
명령어 실행 후 .specify/specs/001-project-structure-refactor/spec.md 파일이 생성되며, 내용은 다음과 같습니다:
다음 명령어를 실행하여 “기술 계획”을 생성합니다:
/speckit.plan
명령어 실행 후 .specify/plans/001-project-structure-refactor/plan.md 파일이 생성되며, 내용은 다음과 같습니다:
다음 명령어를 실행하여 "Task List"을 생성하세요.
/speckit.tasks
실행 후 .specify/tasks/001-project-structure-refactor/tasks.md 파일이 생성되며, 내용은 다음과 같습니다.
다음 명령어를 실행하여 Task Decomposition(tasks.md)에 따라 "Code Generation"을 수행하세요.
/speckit.implement
Agent는 Task List(tasks.md)에 따라 각 Task를 순차적으로 구현하며, 각 Task가 완료되면 자동으로 requirements.md를 검사합니다.
모든 Task가 완료되면, 사람이 수동으로 Review를 진행하여 요구사항을 만족하는 경우 코드를 병합합니다(현재 이 PR은 XXL-API master branch에 병합되었으며, 기대에 부합합니다).
constitution.md결정되면 자주 변경하지 마시고, 모든 참여자가 통일된 규칙을 따르도록 보장해야 합니다SPEC.md과도한 구현 세부 사항의 제약을 피하고, AI에게 기술적 최적화 공간을 남겨야 합니다이 콘텐츠는 인셔셔RSS(RSS 리더)가 자동으로 집계한 것으로 읽기 참고용입니다. 원문 출처 — 저작권은 원저작자에게 있습니다.