Agent Skills의 /spec 에 알아보자

이 글은 Google Cloud AI 디렉터 Addy Osmani가 만든 agent-skills의 6단계 프로세스 중, 첫 단계인 DEFINE을 정리한 글입니다. 특히 DEFINE 단계에서 사용하는 /spec 명령이 왜 중요한지, 그리고 이 명령이 단순히 “앱을 만들어주는 기능”이 아니라 요구사항을 명확하게 만드는 도구라는 점을 중심으로 설명합니다. (GitHub)

처음 AI 코딩 에이전트를 쓰면 보통 이렇게 요청하게 됩니다.
“할 일 앱을 만들어줘.”
문제는 이 한 문장만으로는 화면 범위, 저장 방식, 로그인 필요 여부, 우선순위 기능, 테스트 기준이 전혀 정해지지 않는다는 점입니다. agent-skills의 /spec은 바로 이 모호함을 줄이기 위해 존재합니다. 코드를 먼저 쓰는 대신, 무엇을 만들지 문서로 먼저 고정하게 만듭니다. (GitHub)

https://github.com/addyosmani/agent-skills

agent-skills/skills/spec-driven-development/SKILL.md at main · addyosmani/agent-skills

 

이 글을 읽으면 다음을 이해할 수 있습니다.
첫째, 왜 AI에게 바로 구현을 시키는 방식이 종종 아쉬운 결과로 이어지는지.
둘째, /spec이 어떤 식으로 질문을 던지고 문서를 만드는지.
셋째, 왜 이 과정이 실무에서 결과 품질을 크게 좌우하는지입니다.
기획이 흐릿한 상태에서 AI를 쓰고 있는 개발자, 또는 “AI가 코드는 빨리 짜는데 결과가 자꾸 엇나간다”고 느끼는 개발자에게 특히 도움이 됩니다.

왜 이 문제가 중요한가

AI 코딩 에이전트는 속도가 빠릅니다.
하지만 속도가 빠르다는 것과, 원하는 것을 정확히 만든다는 것은 전혀 다른 문제입니다.

기존 방식의 가장 흔한 문제는 “대충 요청하고 바로 구현 들어가기”입니다.
겉보기에는 효율적이지만, 실제로는 아래 같은 비용이 생깁니다.

• 기능 범위가 제멋대로 커집니다
  “할 일 앱”이라고 했는데 AI가 필터, 태그, 로그인, 다크모드까지 넣어버릴 수 있습니다. 반대로 정말 필요한 반복 일정이나 우선순위 기능은 빠질 수도 있습니다.
• 사용자 기대와 결과물이 어긋납니다
  사용자는 모바일 중심 앱을 생각했는데, AI는 데스크톱 웹 기준으로 만들 수 있습니다. 저장도 로컬스토리지인지, 서버 DB인지 달라질 수 있습니다.
• 테스트 기준이 없어 검증이 애매해집니다
  “잘 동작한다”는 말만 있고 성공 조건이 없으면, 어디까지가 완료인지 판단하기 어렵습니다.
• 구조와 경계가 불명확해집니다
  어떤 폴더에 무엇을 둘지, 어떤 변경은 먼저 물어봐야 하는지, 어떤 것은 절대 하면 안 되는지 기준이 없으면 결과물이 금방 산만해집니다.
• 수정 비용이 뒤로 밀립니다
  처음에는 빨라 보이지만, 나중에 “이건 내가 원한 게 아닌데?”가 나오면 다시 설명하고 다시 수정해야 합니다. 결국 초기 요구사항 정리가 더 싸게 먹힙니다.

agent-skills는 이런 문제를 해결하기 위해 개발 과정을 DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP으로 나누고, 각 단계에 맞는 스킬과 명령을 연결합니다. 이때 /spec은 DEFINE 단계의 대표 진입점입니다. (GitHub)

Agent Skills의 /spec이란 무엇인가

한 문장으로 정리하면, /spec은 코드를 쓰기 전에 요구사항과 성공 기준을 문서로 정리하게 만드는 명령입니다. (GitHub)

중요한 점은 이것입니다.
/spec을 쓰기 전에는 “할 일 앱을 만들어줘”가 곧바로 구현 요청으로 해석될 수 있습니다.
하지만 /spec을 사용하면 같은 요청도 명세 작성의 출발점으로 바뀝니다.

즉, 에이전트는 바로 앱을 만들지 않습니다.
대신 이런 흐름으로 움직입니다.

• 무엇을 만들려는지 다시 해석합니다.
• 빠진 정보와 모호한 부분을 찾아냅니다.
• 본인이 가정한 내용을 먼저 드러냅니다.
• 더 자세한 정보를 요청합니다.
• 그 결과를 바탕으로 스펙 문서를 만듭니다.
• 이후 단계인 계획과 구현은 그 문서를 기준으로 진행합니다. (GitHub)

이 차이가 생각보다 큽니다.
결국 /spec은 “AI가 더 똑똑해지는 기능”이라기보다, AI가 멋대로 추측하지 못하게 만드는 장치에 가깝습니다.

핵심 특징

• 코드보다 스펙을 먼저 둡니다
  저장소 README에서도 /spec의 핵심 원칙을 “Spec before code”로 설명합니다. (GitHub)
• 모호한 요구를 그대로 넘기지 않습니다
  requirements가 ambiguous 하거나 vague idea 수준일 때 쓰라고 명시돼 있습니다. (GitHub)
• 가정을 먼저 드러냅니다
  “웹 앱인지”, “인증이 필요한지”, “DB가 무엇인지” 같은 가정을 숨기지 않고 먼저 밝히게 합니다. (GitHub)
• 질문을 통해 요구사항을 구체화합니다
  사람에게 clarifying questions를 던져 요구를 concrete 하게 만들도록 설계돼 있습니다. (GitHub)
• 문서의 필수 항목이 정해져 있습니다
  Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries 같은 핵심 항목을 반드시 포함하도록 안내합니다. (GitHub)
• 검토와 승인 단계를 전제로 합니다
  스펙은 사람과 AI의 공통 기준 문서이며, 구현 전에 사람의 리뷰와 승인을 받는 흐름을 전제로 합니다. (GitHub)

실제로 어떤 효과가 있는가

공개된 자료 기준으로 agent-skills는 /spec을 포함한 명령을 통해 개발 생명주기의 각 단계를 분리하고, 각 단계마다 검증 가능한 워크플로를 따르도록 설계돼 있습니다. 특히 spec-driven-development는 새 프로젝트, 새 기능, 중요한 변경처럼 범위가 큰 작업에서 먼저 스펙을 만들라고 권장합니다. (GitHub)

실제 효과를 정리하면 이렇습니다.

1) 결과물의 방향이 덜 흔들립니다

막연한 요청을 바로 코드로 바꾸면, AI가 알아서 비어 있는 부분을 채웁니다.
문제는 그 “알아서”가 사용자 의도와 맞지 않을 수 있다는 점입니다.

/spec을 거치면 최소한 다음이 정리됩니다.

• 누구를 위한 기능인지
• 무엇이 성공인지
• 어떤 명령으로 빌드/테스트/개발할지
• 어디까지는 해도 되고 어디부터는 먼저 물어봐야 하는지 (GitHub)

2) “완료”의 기준이 생깁니다

이 스킬은 vague한 요구를 success criteria로 다시 쓰라고 합니다.
예를 들어 “더 빠르게 해줘”를 “LCP 2.5초 미만”, “초기 로드 500ms 미만” 같은 식으로 바꾸는 예시를 제시합니다. (GitHub)

이건 실무에서 매우 중요합니다.
완료 조건이 숫자나 조건으로 표현되지 않으면, 나중에 검증 단계에서 끝없는 해석 싸움이 생깁니다.

3) 수정 비용이 앞단으로 당겨집니다

요구사항이 잘못된 상태에서 코드를 먼저 만드는 것보다,
초기에 질문 몇 개 더 받고 문서를 고치는 편이 훨씬 저렴합니다.

특히 여러 파일을 건드리거나 구조적 결정을 내려야 하는 작업은, 문서 없이 바로 구현에 들어가면 되돌리기 비용이 커집니다. agent-skills도 이런 경우에 /spec 사용을 권장합니다. (GitHub)

4) 사람과 AI가 같은 기준을 보게 됩니다

문서상 확인되는 범위에서, 스펙은 human engineer와 agent 사이의 shared source of truth로 설명됩니다. 즉, 대화 로그가 아니라 문서가 기준이 됩니다. (GitHub)

이건 팀 작업에서도 유리합니다.
나중에 다른 사람이 봐도 “왜 이렇게 만들었는지”를 추적할 수 있기 때문입니다.

동작 원리 / 구조

spec-driven-development는 단순히 “문서 하나 써라” 수준이 아닙니다.
문서상 이 스킬은 아래와 같은 4단계 게이트형 워크플로를 제시합니다.
SPECIFY → PLAN → TASKS → IMPLEMENT 순서이며, 각 단계는 사람의 검토를 전제로 합니다. (GitHub)

1. Specify

가장 먼저 높은 수준의 아이디어를 받습니다.
그리고 요구사항이 구체화될 때까지 질문을 던집니다. (GitHub)

이 단계의 핵심은 두 가지입니다.

1. 가정을 먼저 공개한다
2. 모호한 표현을 성공 기준으로 바꾼다

예를 들면 이런 식입니다.

• 이건 웹 앱인가, 모바일 앱인가
• 로그인 기능이 필요한가
• 데이터는 어디에 저장하는가
• 완료 조건은 무엇인가
• 어느 정도 품질이면 “끝났다”고 볼 것인가

2. Plan

검증된 스펙이 생기면, 그다음은 기술 구현 계획으로 넘어갑니다.

• 주요 컴포넌트 식별
• 의존 관계 정리
• 구현 순서 결정
• 위험 요소와 대응 방안 정리
• 검증 포인트 설정 (GitHub)

3. Tasks

계획을 더 작고 실행 가능한 작업 단위로 나눕니다.

• 한 세션 안에 끝낼 수 있을 정도로 작게
• 수용 기준이 명확하게
• 검증 단계가 포함되게
• 의존성 순서대로 정렬되게
• 너무 많은 파일을 한 번에 건드리지 않게 (GitHub)

4. Implement

그제야 구현에 들어갑니다.
즉, /spec은 사실상 “구현 전에 문제 정의와 완료 기준을 잠그는 장치”입니다.

설치 / 사용 방법

agent-skills 저장소 기준으로 Claude Code에서는 플러그인 형태로 설치할 수 있습니다. 저장소 README에는 아래 방식이 안내되어 있습니다. (GitHub)

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

로컬 저장소를 직접 연결하는 방식도 있습니다.

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

문서상 agent-skills는 Claude Code 외에도 Cursor, Gemini CLI, Windsurf, GitHub Copilot 등에서 사용할 수 있고, 기본적으로는 SKILL.md를 규칙 파일이나 시스템 프롬프트에 넣어 쓰는 구조입니다. (GitHub)

/spec 기본 사용 흐름

가볍게 감을 잡으려면 이렇게 볼 수 있습니다.

/spec
할일 앱을 만들어줘

여기서 중요한 점은, /spec 없이 요청했을 때와 결과가 달라진다는 것입니다.

• /spec 없이 요청
  → 에이전트가 바로 구현으로 들어갈 수 있음
• /spec과 함께 요청
  → 에이전트가 먼저 요구사항을 구체화하고 스펙 문서를 작성하려고 함 (GitHub)

스펙 문서에 들어가는 핵심 항목

문서상 /spec이 만드는 스펙은 대략 이런 구조를 가집니다. (GitHub)

# Spec: [Project/Feature Name]

## Objective
[무엇을 왜 만드는지]

## Tech Stack
[프레임워크, 언어, 주요 의존성]

## Commands
[build, test, lint, dev 명령]

## Project Structure
[디렉터리 구조]

## Code Style
[코드 스타일 예시와 규칙]

## Testing Strategy
[테스트 도구, 위치, 범위]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[완료 조건]

## Open Questions
[아직 결정되지 않은 부분]

즉, 단순 요구사항 메모가 아니라 구현과 검증까지 연결되는 작업 기준서에 가깝습니다.

자주 쓰는 예시 / 활용 시나리오

1. 아이디어는 있는데 범위가 흐릿할 때

“할 일 앱 만들어줘”,
“사내 대시보드 하나 필요해”,
“간단한 관리자 페이지가 있으면 좋겠어” 같은 요청은 대부분 너무 넓습니다.

이럴 때 /spec은 막연한 아이디어를 바로 코드로 바꾸지 않고, 먼저 범위를 좁히는 데 유용합니다. (GitHub)

2. 새 기능이 여러 파일에 걸쳐 퍼질 때

로그인 추가, 결제 도입, 검색 기능 확장처럼 한 군데만 건드려서 끝나지 않는 작업은 설계가 먼저 필요합니다.
문서상 이 스킬도 multiple files or modules에 걸치는 변경에서 쓰라고 안내합니다. (GitHub)

3. 아키텍처 결정을 내려야 할 때

서버에서 처리할지, 클라이언트에서 처리할지.
로컬 저장인지 DB 저장인지.
세션 기반 인증인지 토큰 기반 인증인지.

이런 결정은 초기에 안 박아두면 구현 중간에 흔들리기 쉽습니다. /spec은 이런 가정을 먼저 표면으로 끌어올립니다. (GitHub)

4. 팀원과 AI가 같은 기준을 봐야 할 때

혼자 개발할 때보다 팀 작업에서 더 유용합니다.
“대화로만 합의된 요구사항”은 금방 잊히지만, 스펙 문서는 기준점이 됩니다.
저장소 문서도 스펙과 태스크 아티팩트를 버전 관리 안에서 공유된 기준으로 유지하라고 설명합니다. (GitHub)

5. AI가 자꾸 엇나간 결과를 낼 때

AI가 코드는 빨리 쓰는데 결과가 원하는 방향과 어긋난다면, 많은 경우 문제는 모델 성능이 아니라 입력 요구사항의 불명확함입니다. /spec은 바로 그 문제를 다루는 단계입니다.

한계 / 주의할 점

좋은 도구이지만, 만능은 아닙니다.

작은 수정에는 오히려 과할 수 있습니다

문서상 이 스킬은 단순 오타 수정, 한 줄짜리 수정, 요구사항이 아주 명확한 변경에는 적합하지 않다고 설명합니다. (GitHub)

즉, 모든 작업에 /spec을 붙이는 것이 정답은 아닙니다.
작은 버그 수정마다 긴 스펙을 만드는 건 오히려 비효율적일 수 있습니다.

질문이 많아지는 만큼 초반 속도는 느려질 수 있습니다

처음에는 “그냥 만들어주면 되는데 왜 이렇게 많이 묻지?”라는 느낌이 들 수 있습니다.
하지만 그 질문이 나중의 수정 비용을 줄이기 위한 장치라는 점을 이해할 필요가 있습니다.

결국 사람의 판단이 여전히 중요합니다

agent-skills의 워크플로는 각 단계에서 human review를 전제로 합니다.
즉, 문서를 잘 만들어도 마지막 판단은 사람이 해야 합니다. (GitHub)

스펙이 좋다고 자동으로 구현까지 좋아지는 것은 아닙니다

좋은 스펙은 좋은 출발점이지, 자동 완성 버튼은 아닙니다.
이후에도 /plan, /build, /test, /review, /ship 같은 다음 단계가 필요합니다. 저장소 역시 전체 라이프사이클을 분리해서 운영하는 구조를 제시합니다. (GitHub)

마무리

agent-skills의 /spec은 “AI에게 더 자세히 말해라” 수준의 팁이 아닙니다.
이 명령은 정의되지 않은 요구를 먼저 정의된 문서로 바꾸는 단계를 강제합니다.

같은 “할 일 앱을 만들어줘”라는 요청도,
그냥 던지면 구현이 시작될 수 있고,
/spec과 함께 던지면 요구사항 정리부터 시작합니다.

이 차이가 실무에서는 꽤 큽니다.
좋은 결과물은 종종 더 좋은 모델보다, 더 좋은 문제 정의에서 나옵니다.
결국 이 도구는 AI에게 일을 시키기 전에, 내가 무엇을 원하는지 먼저 정리하고 싶은 개발자에게 특히 유용합니다.

핵심 요약

• /spec은 코드를 바로 만드는 명령이 아니라, 요구사항 문서를 먼저 만드는 DEFINE 단계의 도구입니다. (GitHub)
• 이 스킬은 모호한 요구를 그대로 넘기지 않고, 가정을 먼저 드러내고 질문을 통해 구체화합니다. (GitHub)
• 스펙에는 Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries, Success Criteria 등이 포함됩니다. (GitHub)
• 장점은 구현 전에 방향을 맞추고, 완료 기준을 명확히 하며, 사람과 AI가 같은 기준 문서를 보게 만든다는 점입니다. (GitHub)
• 다만 작은 수정에는 과할 수 있고, 결국 사람의 리뷰와 판단은 계속 필요합니다. (GitHub)