깃허브의 Spec-Kit과 클로드 코드를 2개월간 사용해 본 결과: 효과적인 점과 그렇지 않은 점

r/LocalLLaMA의 한 개발자가 Claude Code를 주 에이전트로 GitHub의 spec-kit을 사용한 Spec-Driven Development(SDD) 2개월 후, 무엇이 잘 작동하고 무엇이 그렇지 않은지 보고합니다. github.com/github/spec-kit에서 제공되는 이 툴킷은 헌법, 명세, 계획, 작업, 구현의 5단계 워크플로우를 강제합니다. 핵심 아이디어: 프롬프트가 아닌 명세가 진실의 원천입니다.

실제로 좋은 점

• 에이전트에 무관함: 동일한 명세가 Claude Code, Cursor, Codex, Gemini CLI, Copilot에서 작동합니다. 작성자는 Claude Code로 코드를 생성한 후, 원활하게 Cursor에 명세를 넘겨 테스트 리팩토링을 수행했습니다.
• 단계 간 확실한 체크포인트: 계획 단계에서는 코드가 작성되기 전에 전체 제안된 아키텍처를 보여주어, 잘못된 결정을 5시간 대신 5분 수정 비용으로 잡아냅니다.
• 품질 관문으로서의 헌법 파일: 테스트 커버리지 최소치, 의존성 허용 목록, 성능 예산, 타입 엄격성 등 불가침 규칙을 미리 정의합니다. 에이전트가 이를 위반하려고 하면 자체 검증에 실패합니다.
• 향상된 결정론: 구현 단계를 다시 실행하면 원시 프롬프팅보다 더 일관된 출력을 생성합니다. 에이전트가 30가지의 암묵적인 결정을 채울 필요가 없기 때문입니다.

짜증나는 점

• 드리프트는 현실: 명세를 업데이트하지 않고 수동으로 코드를 수정하면 빠르게 불일치가 발생합니다. spec-kit에 도구가 있지만 초기 단계입니다.
• 작은 변경에 대한 오버헤드: 50줄 미만의 버그 수정이나 간단한 기능은 형식적입니다. 작성자의 규칙: 200줄 이상을 다루는 새 모듈이나 기능에만 전체 SDD를 사용합니다.
• 레거시 마이그레이션은 고통스러움: 3만 줄 코드베이스에 SDD를 적용하려면 몇 달이 걸립니다.
• 품질은 에이전트에 달림: Claude Code(Sonnet/Opus 4.6+)는 잘 처리하지만, 작은 모델은 컴파일은 되지만 아키텍처 추론이 부족한 계획을 생성합니다.

실용적 설정

• 설치: uv tool install --from git+https://github.com/github/spec-kit.git specify-cli. 공식 저장소만 안전합니다. PyPI에는 타이포스쿼터가 있습니다.
• 주 에이전트: Claude Code, Cursor 및 Gemini CLI로 교차 검증.
• 로컬 지속성: SQLite(명세/검증이 쉽고 클라우드 의존성 없음).
• 재사용 가능한 헌법 템플릿: 엄격한 타입, pytest 커버리지 80% 이상, 명시적 의존성 허용 목록, 필수가 아닌 한 클라우드 서비스 없음.

미해결 질문

• 로컬 모델(Qwen, DeepSeek-Coder, GLM, Llama)이 계획 및 구현을 유능하게 처리할 수 있을까? 작성자는 작은 모델이 형식은 따르지만 아키텍처 추론에 실패한다고 밝혔습니다.
• 다중 에이전트 SDD가 작동할까? 한 모델이 명세를, 다른 모델이 구현을, 세 번째 모델이 감사를 수행하는 방식이 이론적으로는 더 낫지만, 실제로 단일 에이전트보다 측정 가능하게 더 낫지는 않습니다.