spec-driven-development
작성자 addyosmanispec-driven-development은 코드를 작성하기 전에 스펙을 먼저 만들고, 이후 계획·작업·구현 단계로 진행하면서 각 단계마다 사람의 검토를 거치는 워크플로 스킬입니다.
이 스킬의 평점은 74/100으로, 상위권은 아니지만 충분히 쓸 만한 후보입니다. 디렉터리 사용자에게는 스펙 우선 워크플로가 필요한 에이전트에 실제로 도움이 되며, 구조도 어느 정도 갖춰져 있어 시행착오를 줄여 주지만, 도입을 더 쉽게 만들어 줄 보조 파일과 패키지화된 안내는 아직 부족하다는 뜻입니다.
- 트리거 안내가 명확합니다: 새로운 프로젝트, 기능, 또는 모호한 변경을 시작할 때 사용하고, 사소한 수정에는 쓰지 않도록 분명히 구분합니다.
- 운영 워크플로가 탄탄합니다: Specify → Plan → Tasks → Implement의 4단계 게이트형 흐름에 각 단계별 사람 검토가 포함됩니다.
- 실무 깊이가 좋습니다: 여러 개의 제목, 제약 사항, 코드 예제가 담긴 충분한 분량의 SKILL.md가 있어 에이전트가 절차를 따라가기 쉽습니다.
- 지원 파일이나 설치 명령이 없어, 실제 도입은 거의 전적으로 SKILL.md 지침에 의존합니다.
- 단일 파일 제공 방식이라 워크플로를 보강하거나 예외 상황을 처리할 스크립트, 참고 자료, 추가 리소스가 없습니다.
spec-driven-development 스킬 개요
spec-driven-development는 코드를 쓰기 전에 먼저 명확한 스펙을 만들고, 그 스펙을 바탕으로 계획, 작업 분해, 구현까지 이어가는 워크플로 스킬입니다. 새 기능을 시작하거나 아키텍처를 바꾸거나, 요구사항이 모호해 최종 결과물에서 추정을 줄여야 할 때 특히 적합한 spec-driven-development 스킬입니다.
이 스킬이 필요한 상황
이 spec-driven-development 가이드는 “잘못 만들 위험”이 “대충 만들 위험”보다 클 때 가장 유용합니다. 구현에 들어가기 전에 범위, 동작, 제약 조건, 승인 기준을 정의하는 공통의 기준 문서로, 대략적인 아이디어를 팀이 함께 검토 가능한 형태로 바꾸는 데 도움을 줍니다.
도입하기 좋은 사례
이 스킬은 특히 사람 리뷰어와의 정렬도를 높이고 싶은 팀이나 1인 개발자에게 잘 맞습니다. 작업이 여러 파일에 걸치거나, 제품 의사결정에 의존하거나, “일단 코드부터” 접근하면 재작업이 생길 정도로 규모가 있는 경우에 효과적입니다. 또한 Skill Authoring에서 spec-driven-development를 적용해, 스킬 자체가 더 규율 있고 검토 가능한 결과물을 만들도록 하고 싶을 때도 유용합니다.
무엇이 다른가
핵심 가치는 단계별 게이트가 있는 워크플로에 있습니다. 먼저 스펙을 만들고, 그다음 계획을 세우고, 작업으로 쪼개고, 마지막에 구현하며, 각 단계마다 사람의 리뷰를 거칩니다. 이 점에서 단순한 일반 프롬프트보다 강력합니다. 숨은 가정을 줄이고, 수정 비용이 더 낮은 초반에 의사결정 지점을 드러내기 때문입니다.
spec-driven-development 스킬 사용 방법
설치 후 먼저 컨텍스트 불러오기
spec-driven-development 설치 시에는 에이전트 스킬 설정에 이 스킬을 추가한 다음, 가장 먼저 스킬 파일을 여세요.
npx skills add addyosmani/agent-skills --skill spec-driven-development
그다음 다른 것보다 먼저 SKILL.md를 읽어야 합니다. 이 저장소에는 rules/, references/, scripts/ 같은 보조 폴더가 없으므로, 스킬 컨텍스트는 거의 전부 메인 스킬 파일에 담겨 있습니다.
구체적인 출발점을 제공하기
spec-driven-development 사용 패턴은 목표, 제약, 이미 알고 있는 불확실성을 함께 줄 때 가장 잘 작동합니다. 약한 입력은 “대시보드 만들어줘” 수준입니다. 강한 입력은 다음과 같습니다.
“Create a spec for a dashboard that shows subscription health, supports role-based access, and must work with our existing REST API. Ask clarifying questions before drafting the spec. Do not propose implementation details yet.”
이 정도는 줘야 스킬이 가정을 표면화하고, 설계를 너무 일찍 굳히는 실수를 피할 수 있습니다.
단계별 게이트 워크플로를 지키기
이 스킬은 각 단계가 검증되기 전에는 다음 단계로 넘어가지 않도록 설계되어 있습니다. 실제 흐름은 다음과 같습니다.
- 문제와 가정을 명세합니다.
- 스펙이 승인된 뒤 접근 방식을 계획합니다.
- 계획을 작업 단위로 분해합니다.
- 작업 리뷰가 끝난 뒤에만 구현합니다.
리뷰 게이트를 건너뛰면 이 스킬의 가장 큰 장점도 함께 사라집니다. 즉, 검증되지 않은 가정 때문에 생기는 재작업을 줄이는 효과를 잃게 됩니다.
먼저 읽고, 그다음 적용하기
SKILL.md부터 읽고, 이어서 overview, when to use, gated workflow 섹션을 실제 운영 원칙처럼 활용하세요. 이 스킬을 자신의 에이전트 흐름에 맞게 변형하더라도, 리뷰 체크포인트와 “구체해질 때까지 질문하기” 동작은 유지하는 것이 좋습니다. 출력 품질을 가장 크게 끌어올릴 가능성이 높은 부분이 바로 여기에 있습니다.
spec-driven-development 스킬 FAQ
spec-driven-development가 일반 프롬프트보다 더 나은가요?
대체로 그렇습니다. 작업이 모호하거나, 여러 영역에 걸쳐 있거나, 다시 만드는 비용이 큰 경우에는 특히 그렇습니다. 일반 프롬프트는 빠르게 코드를 만들 수 있지만, 누군가 코드를 쓰기 전에 “무엇을 만들지”에 대한 합의가 필요한 상황에서는 spec-driven-development가 더 적합합니다.
언제 쓰지 말아야 하나요?
사소한 수정, 명확한 버그 수정, 제품적인 모호성이 거의 없는 독립적인 변경에는 spec-driven-development 스킬을 쓰지 않는 편이 좋습니다. 이런 경우에는 전체 스펙 사이클의 오버헤드가 실제 작업보다 더 느릴 수 있습니다.
초보자도 쓰기 쉬운가요?
네. 보충 질문에 답하고 초안을 검토할 의향만 있다면 충분히 쓸 만합니다. 에이전트에게 멈춰야 할 시점, 가정을 드러내는 방식, 단계를 순서대로 진행하는 법을 직접 설계할 필요가 없기 때문에, 처음부터 프로세스를 스스로 만드는 것보다 오히려 더 쉽습니다.
Skill Authoring 워크플로에도 맞나요?
네. 특히 새 스킬을 만들거나 기존 스킬을 개선할 때, 반복 가능한 프로세스가 필요하다면 Skill Authoring용 spec-driven-development에 잘 맞습니다. 작성 작업에서 명확한 범위, 리뷰 게이트, 구현 전에 검증 가능한 스펙이 필요한 경우 가장 유용합니다.
spec-driven-development 스킬 개선 방법
처음부터 더 날카로운 입력 주기
가장 좋은 결과는 대상 사용자, 원하는 결과, 제약 조건, 아직 불확실한 부분을 처음부터 분명히 적었을 때 나옵니다. 예를 들면 다음과 같습니다. “Migrate the checkout flow without changing the public API, preserve existing analytics events, and identify any dependency risks before planning.”
스킬이 가정을 직접 적게 만들기
자주 생기는 실패 패턴 중 하나는, 얼핏 완성된 것처럼 보이지만 중요한 결정이 빠져 있는 모호한 스펙입니다. 스펙 초안을 쓰기 전에 모델이 가정 목록을 먼저 적게 하세요. 그리고 계획 단계로 넘어가기 전에 그 가정을 인간 엔지니어와 함께 검토하세요. spec-driven-development가 가장 큰 시간을 아껴주는 지점이 대개 여기입니다.
코드를 고치기보다 스펙을 먼저 다듬기
첫 번째 결과가 어긋났다면, 구현을 시키기 전에 범위, 승인 기준, 제약 조건부터 바로잡으세요. 이 워크플로는 매 수정마다 계약이 더 정밀해질 때 가장 잘 작동합니다. 뒤 단계들은 결국 스펙의 정확도에 의존하기 때문입니다.
리뷰 비용이 큰 작업에서 쓰기
이 스킬의 가치는 잘못된 가정이 비싸게 돌아오는 상황에서 가장 큽니다. 예를 들어 여러 파일에 걸친 변경, 아키텍처 전환, 여러 이해관계자에게 영향을 주는 기능이 그렇습니다. 스펙 초안이 아직도 흐릿하다면, 작업 분해나 코드로 성급히 넘어가기보다 스펙 단계에 더 오래 머무는 편이 낫습니다.