GitHub 사양 키트 워크플로 및 선택적 명령 검사
GitHub 사양 키트는 사양을 AI 코딩 도우미와 통합하여 SDD(사양 기반 개발)를 가능하게 하는 오픈 소스 도구 키트입니다. 고급 기능을 살펴보기 전에 기본 개념을 검토해 보겠습니다.
GitHub 사양 키트 기본 사항 검토
GitHub 사양 키트는 코딩 도우미와의 여러 상호 작용에서 컨텍스트 및 일관성을 유지하는 AI 지원 개발의 근본적인 과제를 해결합니다. 다음 세 가지 필수 기능을 제공합니다.
- 영구 아티팩트: 사양, 계획 및 작업은 리포지토리에 markdown 파일로 저장됩니다.
- 표준화된 워크플로: 정의된 프로세스는 사양, 계획, 작업 분석 및 구현의 네 가지 SDD 단계를 안내합니다.
- 재사용 가능한 명령: 기본 제공 슬래시 명령은 모범 사례 프롬프트 패턴을 캡슐화합니다.
핵심 구성 요소
GitHub 사양 키트는 다음과 같은 핵심 구성 요소를 구현합니다.
| 구성 요소 | 목적 |
|---|---|
specify 커맨드 라인 인터페이스 (CLI) |
사양 기반 프로젝트를 초기화하고 관리합니다. |
| Markdown 아티팩트 파일 |
constitution.md, spec.md, plan.mdtasks.md 개발 추진. |
| 슬래시 명령 |
/speckit.specify, /speckit.plan/speckit.tasks, /speckit.implement GitHub 사양 키트 워크플로를 호출합니다. |
AI 에이전트
GitHub Spec Kit는 GitHub Copilot, Claude Code, Cursor, Windsurf, Amazon Q Developer 등의 AI 에이전트를 지원합니다. 각 에이전트는 동일한 기본 아티팩트 파일을 사용하는 동안 특정 프롬프트 형식으로 서식이 지정된 템플릿을 받습니다.
기능 추적을 위한 환경 변수
GitHub 사양 키트는 환경 변수를 사용하여 현재 개발 중인 기능을 추적합니다. 변수는 SPECIFY_FEATURE 활성 기능 디렉터리를 나타냅니다.
Git 기반 워크플로에서 GitHub 사양 키트는 분기 이름에서 기능을 유추합니다. 분기 feature/document-upload에 있는 경우 GitHub Spec Kit은 features/document-upload/ 디렉터리에서 자동으로 작동합니다.
Git이 아닌 워크플로 또는 수동 기능 사양의 경우 환경 변수를 명시적으로 설정합니다.
$env:SPECIFY_FEATURE = "001-document-upload"
이 설정은 Git 분기와 관계없이 디렉터리에서 features/001-document-upload/ 아티팩트를 읽고 쓰도록 GitHub 사양 키트에 지시합니다.
이 기능 추적은 호출 /speckit.plan할 때 AI가 다양한 기능의 사양을 혼합하는 대신 현재 기능에 대한 올바른 spec.md 파일을 읽도록 합니다.
Git 워크플로와 GitHub 사양 키트 통합
GitHub 사양 키트는 여러 메커니즘을 통해 기존 개발 사례에 통합됩니다.
버전 제어 통합
모든 GitHub 사양 키트 아티팩트는 Git 리포지토리에 저장된 일반 마크다운 파일입니다. 이 접근 방법에는 여러 가지 이점이 있습니다.
변경 내용 추적: 사양, 계획 또는 작업을 수정할 때마다 Git 커밋이 만들어집니다. 요구 사항 변경 기록을 검토하고, 결정이 내려진 이유를 이해하고, 문제가 있는 변경 내용을 되돌릴 수 있습니다.
분기 기반 개발: 사양 아티팩트와 구현 코드를 모두 포함하는 기능 분기를 만듭니다. 이 방법은 요구 사항 및 구현을 동기화하고 코드를 포괄적으로 검토합니다. 검토자는 빌드하는 항목(사양)과 빌드 방법(코드)을 모두 확인합니다.
끌어오기 요청 워크플로: 기능에 대한 끌어오기 요청을 제출할 때 코드 변경 내용과 함께 spec.md, plan.md 및 tasks.md 포함합니다. 검토자는 구현이 사양과 일치하고 사양이 프로젝트 목표와 일치하는지 확인합니다.
예를 들어 새 기능을 구현하는 경우 기능 분기에는 다음이 포함됩니다.
-
spec.md업로드 요구 사항을 정의합니다. -
plan.mdAzure Blob Storage 아키텍처를 설명합니다. -
tasks.md구현 단계를 나열합니다. - 기능을 구현하는 소스 코드입니다.
- 사양 준수를 확인하는 테스트입니다.
이 전체 그림을 통해 철저한 검토를 수행할 수 있습니다. 검토자가 파일이 50MB로 제한되는 이유를 질문하는 경우 spec.md 참조하고 이 요구 사항이 관련자 토론에서 나온 것을 확인할 수 있습니다.
AI 도우미 통합 시나리오 - GitHub Copilot
GitHub 사양 키트는 Visual Studio Code의 채팅 인터페이스를 통해 GitHub Copilot에서 작동합니다.
specify init --ai copilot을 실행한 후, 도구 키트가 /speckit.* 명령을 인식하도록 작업 영역을 구성합니다.
GitHub Copilot 채팅을 열고 /speckit.specify를 입력하면 GitHub Copilot이 .github/prompts/ 디렉터리에서 미리 정의된 템플릿에 액세스합니다. 이러한 템플릿은 사용자 스토리, 수용 조건, 기능 요구 사항, 비기능 요구 사항 및 에지 사례 등 필요한 모든 사양 섹션을 포함하도록 AI의 출력을 구성하는 데 도움이 됩니다.
통합은 원활하게 진행되므로 템플릿을 수동으로 관리하지 않습니다. GitHub 사양 키트는 템플릿 로드 및 컨텍스트 삽입을 자동으로 처리합니다. 사용자의 할 일은 기능 설명을 제공하고 명확한 질문에 답하는 것입니다. GitHub Copilot는 사양 서식 및 완전성을 처리합니다.
프로젝트 구조 규칙
GitHub 사양 키트는 일관된 디렉터리 구조를 사용하여 아티팩트를 구성합니다.
my-project/
├── .github/
│ ├── agents/
│ └── prompts/
├── .specify/
│ ├── memory/
│ │ └── constitution.md
│ ├── scripts/
│ └── templates/
├── SourceCode/
│ └── ...
├── specs/
│ └── 001-document-upload-feature/
│ ├── plan.md
│ ├── spec.md
│ └── tasks.md
이 구조체는 동일한 리포지토리에 유지하면서 구현 코드와 사양 아티팩트가 분리됩니다. 기능은 개발 순서를 추적하기 위해 순차적으로 번호가 매겨집니다(001, 002, 003).
여러 기능을 동시에 작업하는 팀의 경우 각 기능에는 전체 사양, 계획 및 작업이 포함된 자체 디렉터리가 있습니다. 이 격리는 혼동을 방지하고 충돌 없이 병렬 작업을 가능하게 합니다.
지속적인 워크플로 지원
GitHub Spec Kit는 명령 체인을 통한 반복 개발을 지원합니다. 초기 사양을 생성한 후 점진적으로 구체화할 수 있습니다.
- 초기 사양 생성:
/speckit.specify. - 격차 식별:
/speckit.clarify. - 답변에 따라 사양을 업데이트합니다.
- 구현 계획 만들기:
/speckit.plan. - 일관성 확인:
/speckit.analyze. - 작업 생성:
/speckit.tasks. - 증분 방식으로 구현:
/speckit.implement.
요구 사항이 변경되면 언제든지 이전 단계로 돌아가 아티팩트 업데이트 및 다운스트림 아티팩트 다시 생성할 수 있습니다. 관련자가 작업을 생성한 후 파일 크기 제한에 대한 생각을 변경하는 경우 spec.md 업데이트하고, 아키텍처 의미를 반영하도록 plan.md 다시 생성하고, 업데이트된 유효성 검사 단계로 tasks.md 다시 생성한 다음, 구현 코드를 업데이트합니다.
이러한 유연성은 요구 사항이 진화하는 실제 개발을 지원합니다. 사양 우선 접근 방식을 사용하면 설명서를 업데이트하지 않고 코드에 패치되지 않고 변경 내용이 체계적으로 전파됩니다.
GitHub 사양 키트의 선택적 향상된 명령 활용
핵심 워크플로 명령 외에도 GitHub Spec Kit는 사양 품질 및 일관성을 향상시키는 선택적 명령을 제공합니다.
간격 분석에 /speckit.clarify 사용
이 /speckit.clarify 명령은 사양을 분석하여 모호성, 누락된 세부 정보 및 지정되지 않은 에지 사례를 식별합니다. 초기 사양을 생성한 후 이 명령을 호출하여 AI가 명확한 질문을 하도록 합니다.
AI는 사양을 검토하고 다음과 같은 질문을 생성합니다.
- "사양은 파일 업로드를 언급하지만 최대 동시 업로드를 지정하지는 않습니다. 제한이 있어야 하나요?"
- "네트워크 오류에 대한 오류 처리는 지정되지 않았습니다. 업로드 연결이 끊어지면 어떻게 될까요?"
- "사양에는 파일 유효성 검사가 필요하지만 유효성 검사 실패 메시지를 지정하지는 않습니다. 사용자에게 무엇을 표시해야 하나요?"
각 질문에 대해 AI는 종종 격차를 해결하는 방법에 대한 객관식 옵션을 제공합니다. 옵션을 선택하거나 사용자 지정 답변을 제공하면 AI가 그에 따라 사양을 업데이트합니다.
이 대화형 정교화 단계는 구현이 시작되기 전에 문제를 식별합니다. 숙련된 분석가가 사양을 검토하고 놓친 것을 지적하는 것과 같습니다.
일관성 확인을 위해 /speckit.analyze 사용
이 /speckit.analyze 명령은 아티팩트 간 일관성 검사를 수행합니다. 계획이 모든 사양 요구 사항을 구현하고, 태스크가 모든 계획 요소를 포함하며, 모든 것이 헌법에 부합한다는 것을 확인합니다.
plan.md 및 tasks.md 생성한 후 구현을 시작하기 전에 이 명령을 실행합니다. AI는 불일치를 식별합니다.
- "플랜은 PostgreSQL을 사용할 것을 제안하지만, 헌법에는 Azure SQL Database가 필요합니다."
- "사양에는 감사 로깅이 필요하지만 계획은 로깅 구현을 설명하지 않습니다."
- "작업 목록은 계획에 언급된 데이터베이스 마이그레이션 스크립트를 생략합니다."
식별된 각 불일치는 구현 또는 코드 검토 중에 나타나는 문제입니다. 분석 단계에서 이를 포착하면 재작업을 방지할 수 있습니다.
품질 유효성 검사에 /speckit.checklist 사용
이 /speckit.checklist 명령은 사양에 따라 사용자 지정 품질 검사 목록을 생성합니다. 이러한 검사 목록은 "영어 산문 단위 테스트"와 같은 요구 사항 완성도, 명확성 및 일관성을 확인하는 데 도움이 됩니다.
AI는 사양을 분석하고 확인 질문의 검사 목록을 생성합니다.
- "모든 사용자 스토리에 해당하는 수용 기준이 있나요?"
- "모든 오류 시나리오가 특정 오류 메시지와 함께 문서화되었습니까?"
- "비기능적 요구 사항에 측정 가능한 성공 기준이 포함합니까?"
- "모든 외부 종속성이 명시적으로 나열되었습니까?"
검사 목록을 통해 각 질문에 답변합니다. "아니요" 답변은 해결해야 하는 사양 간격을 나타냅니다.
이 자체 검토 프로세스는 관련자와 공유하거나 구현을 진행하기 전에 사양 품질을 향상시킵니다.
다양한 개발 시나리오에 GitHub 사양 키트 적용
GitHub Spec Kit는 처음부터 새로운 기능을 빌드하는 것 외에 다양한 개발 시나리오를 지원합니다.
그린필드 개발
아무것도 시작하지 않고 시작하는 새 프로젝트의 경우 GitHub Spec Kit는 고급 제품 비전을 구체적인 구현으로 변환하는 데 탁월합니다. 먼저 /speckit.constitution 프로젝트 원칙을 설정한 다음, 애플리케이션을 반복적으로 빌드할 때 각 기능에 사용합니다 /speckit.specify .
이 시나리오는 GitHub Spec Kit의 기본 사용 사례입니다. 워크플로는 아직 존재하지 않는 항목을 만드는 0대 1 개발을 위해 설계되었습니다.
브라운필드 개선
기존 애플리케이션의 경우 GitHub 사양 키트를 사용하여 기존 코드베이스와의 일관성을 유지하면서 새 기능을 추가할 수 있습니다. 헌법은 기존의 건축 패턴과 제약 조건을 문서화합니다. 새로운 기능 사양은 이러한 설정된 패턴을 참조합니다.
기존 직원 포털에 문서 업로드 기능을 추가하는 경우 사양은 기존 React 프런트 엔드, .NET 백 엔드 및 Azure 인프라를 승인합니다. 이 계획은 새 기능이 별도의 구현을 제안하지 않고 현재 아키텍처와 통합되는 방법을 보여 줍니다.
리팩터링 및 현대화
GitHub 사양 키트는 원하는 최종 상태를 사양으로 처리하여 리팩터링 작업을 안내할 수 있습니다. 리팩터링된 코드가 달성해야 하는 작업(구조가 개선된 동일한 기능)을 문서화하고, 리팩터링 방법에 대한 계획을 만들고, 증분 변경 작업을 생성합니다.
리팩터링에 대한 이 구조화된 접근 방식은 부분적으로 작동하는 코드로 리팩터링을 시작하고 중간 프로세스를 잃어버리는 일반적인 문제를 방지합니다.
예비 개발
여러 가지 잠재적 접근 방식을 탐색하는 경우 GitHub 사양 키트를 사용하여 동일한 사양에서 여러 계획을 생성합니다. 안정적인 사양은 달성하려는 항목을 나타내며, 다른 계획은 다양한 기술 접근 방식을 탐색합니다.
동일한 업로드 사양에서 Azure Blob Storage와 Azure Files를 사용하여 하나의 계획을 생성할 수 있습니다. 둘 다 구현하고, 결과를 비교하고, 가정보다는 실제 환경에 따라 더 나은 방법을 선택합니다.
요약
GitHub 사양 키트는 구조화된 워크플로, 영구 아티팩트 및 재사용 가능한 AI 명령 패턴을 통합하여 사양 기반 개발을 가능하게 하는 강력한 도구 키트입니다. 사양을 작업 구현으로 전환하는 체계적인 접근 방식을 제공하여 GitHub Copilot와 같은 AI 코딩 도우미로 작업하는 방법을 변환합니다. GitHub 사양 키트를 사용하면 요구 사항과 코드 간의 맞춤을 보장하고, 의사 결정의 추적 가능성을 유지하며, 개발 팀 간의 협업을 향상시킬 수 있습니다.