바이브 코딩의 한계 보완: AI 컨텍스트 파일(claude.md, agents.md)의 역할
2025년 2월, AI 연구자 Andrej Karpathy는 자연어 설명만으로 LLM이 코드를 생성하는 바이브 코딩(Vibe coding)이라는 용어를 소개했습니다. 바이브 코딩은 누구나 쉽게 소프트웨어를 개발할 수 있도록 도와주었으나, AI가 프롬프트의 맥락을 완벽히 이해하지 못해 버그, 보안 취약점, 그리고 예상과 다른 결과를 초래하는 등 여러 문제가 발생했습니다[1].
이를 보완하기 위해 claude.md, agents.md 같은 컨텍스트 파일이 등장했습니다.
claude.md는 Anthropic이 2025년 5월 공개한 Claude Code의 프로젝트 가이드 파일로, 대화를 시작할 때 자동으로 로드됩니다. 코드 베이스를 분석해 스스로 컨텍스트 파일을 생성할 수 있어, 초기 설정에 대한 사용자의 부담을 줄여주며 외부 도구 연계, 사용자 지정 명령 등 다양한 기능을 제공합니다[2].agents.md는 2025년 8월, OpenAI를 비롯한 AI 코딩 에이전트 개발사들이 협력하여 만든 에이전트 전용 표준 파일입니다. 다양한 환경에서 자유롭게 사용할 수 있는 공통 규칙을 지향하기 때문에, 하나의 파일로 프로젝트 내용을 공유할 수 있습니다. 현재 6만 개 이상의 오픈소스 프로젝트에 채택되었으며, 15개 이상의 주요 AI 에이전트를 지원합니다[3].
이러한 파일은 기본적인 명세 제공에는 유용했지만, 작업을 구조화하기에는 부족했습니다. 표준화된 작성 방식, 명확한 작업 순서와 판단 기준이 정의되어 있지 않았기 때문입니다. 공식 문서 역시 “프로젝트 아키텍처나 워크플로우를 설명하라”는 수준의 추상적인 안내에 그쳐, 실제 실행 로직은 개발자들이 시행착오를 통해 개별적으로 설계해야 했고, 그로 인해 결과의 일관성을 보장하기 어려웠습니다[4].
이러한 한계는 단순한 프로젝트 안내를 넘어, 작업 과정을 구조화하고 검증 가능한 형태로 관리할 수 있는 새로운 접근의 필요성을 드러냈습니다. 이 지점에서 다시 주목받은 개념이 있는데, 바로 명세 기반 개발(Spec-Driven Development, SDD)입니다.
지난 12월 3일 열린 GitHub Universe ’25 Recap Seoul 행사에서 Microsoft의 개발자 Justin Yoo는 SDD 도구 Spec Kit을 소개했습니다[5]. 이번 포스팅에서는 기존 바이브 코딩의 한계를 극복하기 위해 등장한 SDD의 개념을 소개하고, 대표적인 도구들을 비교합니다. 또한 파일 아키텍처는 어떻게 구성되었는지 살펴보려고 합니다. 마지막으로, 직접 따라 해볼 수 있는 Spec Kit 예제까지 함께 준비해보았습니다.
1975년 소프트웨어 요구사항 명세(Software Requirements Specification, SRS)를 시작으로, 개발 과정에서의 기능 요구사항과 이해관계자 간의 합의를 명세로 정리했습니다. 다만 구현과 직접 연결할 수 있는 수단이 부족해, 실제 개발 과정에서는 점차 형식적인 문서로 남게 되었습니다[6].
최근 다양한 AI 에이전트가 등장하면서, 명세를 실행 가능한 입력으로 활용할 수 있는 환경이 마련되었고, 이에 따라 SRS는 SDD라는 형태로 재정의되며, 바이브 코딩의 한계를 보완하는 대안으로 주목받고 있습니다.
SDD의 핵심은 코드를 작성하기에 앞서 “명세(spec)”를 먼저 완성해야한다는 것입니다. 요구사항, 설계, 에러 조건, 보안 기준을 사전에 명확히 정의함으로써 의도한 결과를 안정적으로 구현하는 것을 목표로 합니다. 이때 명세는 소프트웨어의 의도와 동작을 구조화한 파일이자, AI 코딩 에이전트의 행동을 직접 제어하는 기준으로 작동합니다.

이미지 1. SDD 워크플로우 (제논 재구성). 출처: Marmelab[7]
현재 SDD는 아직 명확하게 정립된 개념이 아니며, 도구와 접근 방식에서 다양한 형태로 발전하고 있습니다. 세계적인 IT 컨설팅 기업 소트웍스(Thoughtworks)의 AI 서비스 전문가 Birgitta Böckeler는 아래 두 가지 기준을 바탕으로 SDD를 세 가지 유형으로 분류했습니다.
개발 완료 이후에도 초기 명세 파일을 유지하는가
인간이 코드를 직접 관리하는가, 혹은 명세(spec)만 관리하는가

이미지 2. SDD 분류 (제논 재구성). 출처: Thoughtworks[8]
첫번째, 명세 우선(Spec-first) 방식에서 명세는 초기 기능 개발을 돕기 위한 일회성 파일이며, 코드 작성 이후에는 삭제되고 별도로 관리되지 않습니다. 따라서 수정이 필요할 때는 명세 파일을 새롭게 작성해야 합니다.
두번째, 명세 고정(Spec-anchored) 방식에서 명세는 개발 이후에도 코드와 함께 지속적으로 관리됩니다. 이로 인해 기능 변경으로 명세 수정이 필요할 경우, 기존 명세를 불러와 내용을 갱신할 수 있습니다.
세번째, 명세 소스(Spec-as-source) 방식에서 개발자는 명세만 수정하며 코드는 수정하지 않습니다. 또한 명세 고정 방식과 마찬가지로, 수정된 명세는 관리되며 계속 사용됩니다. 이 방식에서는 명세 자체가 주요 소스 파일로써 동작합니다.
이제 SDD가 무엇인지 살펴보았으니, SDD 도구인 Spec Kit에 대해 알아보겠습니다.

이미지 3. 바이브코딩의 끝, Spec Kit. 출처: Meta-Quantum[9]
Spec Kit[10]은 2025년 8월 GitHub가 공개한 오픈소스 CLI 도구로 Claude, Copilot, Gemini 등 다양한 AI 코딩 어시스턴트에 맞는 작업 공간을 자동으로 구성합니다. 초기 작업 공간 구조가 설정되면, 사용자는 명령어를 통해 AI 에이전트와 단계적으로 상호 작용할 수 있으며, 아래에 정리한 세 가지 SDD 도구 중에서도 사용자 정의에 유연한 편에 속합니다.
Kiro[11] | Spec Kit[10] | Tessl[12] | |
|---|---|---|---|
개발 및 운영 | AWS | GitHub | Tessl |
방식 | 명세 우선(Spec-first) 방식 | 명세 고정형(Spec-anchored) 방식 | 명세 고정형(Spec-anchored) 접근 방식, 명세 소스(Spec-as-source)로 활용 탐구 중 |
워크플로우 | Requirements→ Design → Tasks → Implements | Constitution → Specify → Plan → Tasks → Implements | Plan → Specify → Implements → Test |
지원 | 다중 모드 입력(codebase, file, docs 등) | 커맨드 기반 명령어로 워크플로우 실행 | CLI가 MCP 서버 역할 수행 |
Memory bank | - steering | - memory - constitution.md | - .tessl/framework |
배포 | IDE | CLI | CLI |
운영체제 | Window, macOS, Linux | Window, macOS, Linux | macOS, Linux (x64,arm64), WSL2 |
기타 | - | - 패키지 매니저 :
- Git | - Node.js v22.17.0+ |
Specs 네이밍 방식 | category-label-enhancement | specs/[숫자]-[기능명] | [기능명].spec.md |
Specs 구성 파일 | - requirements.md | - data-model.md | 단일 spec 파일 |
명세-코드 매핑 | 1:n | 1:n | 1:1 |
코드 수정 | O | O | X |
다중 파일 생성 | O | O | X (향후 가능성 언급됨) |
표 1. SDD 도구 비교표 Kiro vs Spec Kit vs Tessl
아래 이미지 4에서 보이는 것처럼 Spec Kit은 3개의 주요 폴더으로 나눌 수 있습니다.

이미지 4. Spec Kit 파일 아키텍처(제논 재구성). 출처. Thoughtworks[8]
첫 번째, memory 폴더는 Spec Kit 명령어를 처음 실행할 때 자동으로 생성되며 내부에
constitution.md파일을 포함합니다. 이 파일에는speckit.constitution명령어를 통해 기술 스택, 보안 원칙, 코드 스타일 등 프로젝트 전반에 적용되는 불변 원칙을 정의할 수 있습니다. 또한 모든 Spec Kit 명령어 실행 시 AI 에이전트가 자동으로 참조하여 작업 일관성을 유지합니다.두 번째, templates 폴더는
plan.md,spec.md,tasks.md파일들의 기본 작성 형식이 정의되어 있습니다. 각 파일은 해당하는template.md파일을 기반으로 생성되며, 이는 에이전트가 명세를 해석하는 방식을 하나로 고정하기 위함입니다. 명세 구조가 고정되지 않으면 동일한 요구사항도 매번 다르게 해석될 수 있기 때문에, 템플릿을 통해 해석 기준을 일관되게 유지합니다. 이러한 기준(constitution.md,template.md)을 바탕으로 AI 에이전트는 Spec Kit 명령어를 통해 작업 산출물을 Specs 폴더에 생성합니다.세 번째, Specs 폴더에는
/speckit.specify명령어와 함께 사용자가 원하는 기능에 대한 프롬프트를 입력하면 [번호]-[기능이름] 형식(예: 001-when-a-user)의 폴더가 생성됩니다. 이때, 번호는 001부터 순차적으로 부여되며 중복되지 않기 때문에, 여러 브랜치에서 동시에 작업하더라도 파일명 충돌이 발생하지 않습니다. 또한 기능을 삭제하더라도 번호는 유지되어, 프로젝트의 히스토리 관리에도 용이합니다. 해당 폴더 안에는 기능의 요구사항을 담은spec.md가 생성됩니다.
이후 /speckit.plan 명령어를 실행하면, 해당 기능을 어떻게 구현할지에 대한 내용이 자동으로 확장됩니다. 이 과정에서 plan.md를 포함하여 data-model.md, research.md, contracts(api.md, component.md), quickstart.md 파일들이 함께 생성됩니다.

이미지 5. /speckit.plan 명령어로 생성되는 파일(제논 재구성). 출처. medium[13]
마지막으로, /speckit.tasks 명령어를 사용해 plan 단계에서 생성된 파일들을 종합적으로 분석하여, 구현 작업 목록을 단계별로 분해하고 tasks.md에 정리합니다. 이렇게 Spec Kit을 활용하면 기존에 바이브 코딩 시간을 크게 단축시키며, 기능 명세부터 구현 계획, API·데이터 모델, 테스트 시나리오, 버전 관리된 파일까지 한 번에 완성할 수 있습니다.

이미지 6. Spec Kit 워크플로우. 출처. 제논
Spec Kit은 요구사항을 정리하는 단계부터 구현까지 순서대로 진행하는 워크플로우를 제공하며, 각 단계의 역할과 결과물이 명확히 구분되어 있습니다.
단계 | 명령어 | 명령어 유형 | 역할 (무엇을 하는 단계인가) | 핵심 목적 | 명령어에 포함해야 할 것 | 명령어에 포함하면 안 되는 것 |
|---|---|---|---|---|---|---|
원칙 수립 |
| 핵심 (Core) | 프로젝트 전반에 적용되는 기본 원칙 정의 | 일관된 개발 기준 확립 | 품질 기준, 정확성, UX 원칙, 제약 조건 | 기능 요구사항, 기술 선택 |
요구사항 명세 |
| 핵심 (Core) | 무엇을, 왜 만들 것인지 정리 | 문제와 목표 명확화 | 사용자 질문, 기능 범위, 성공 기준 | 기술 스택, 시스템 구조 |
요구사항 명확화 |
| 선택 (Optional) | 애매한 요구사항을 질문과 답변으로 정리 | 요구사항 명확화 | - | 새로운 기능 추가, 구현 방법 제시 |
구현 계획 |
| 핵심 (Core) | 구현 방법과 구조 결정 | 구현 방향 수립 | 기술 스택, 시스템 구조, 데이터 흐름 | 요구사항 변경 |
명세 점검 |
| 선택 (Optional) | 요구사항과 설계 내용 점검 | 누락·모호함 확인 | - | 코드, 실제 구현 내용 |
작업 분해 |
| 핵심 (Core) | 구현 작업을 실행 단위로 분해 | 바로 실행 가능한 작업 정리 | - | 추상적인 설계 논의 |
사전 검증 |
| 선택 (Optional) | 파일 간 내용이 잘 맞는지 확인 | 누락·불일치 방지 | - | 요구사항 추가, 코드 수정 |
구현 |
| 핵심 (Core) | 앞 단계에서 정리한 내용을 바탕으로 코드를 작성하는 단계 | 기능 구현 | - | 요구사항·계획 변경 |
표 2. Spec Kit의 워크플로우[10]

이미지 7. 챗봇 실행 결과. 출처. 제논
Spec Kit을 활용하여 구현한 서울 윈터페스타 챗봇의 실행 결과입니다. 사용자는 데모 페이지에서 질문을 입력하면, 공식·신뢰 가능한 웹 정보를 기반으로 정리된 답변과 함께 출처를 확인할 수 있습니다. 이 챗봇은 복잡한 기능을 많이 포함하고 있지는 않지만, 짧은 시간 안에 검색형 질문에 대응하는 출처 기반의 정확한 챗봇을 구현했다는 점에서 의미가 있습니다.
다만 명세 보존 방식(Spec-anchored)을 사용하는 Spec Kit에서는 생성된 결과를 그대로 신뢰하기보다, 개발자가 직접 검증하는 과정이 권장됩니다. 이번 실습에서도 일부 답변이 2024년 기준 정보를 포함하거나 공식 출처가 아닌 링크를 사용해, 이를 직접 확인해 수정했습니다. 이를 통해 Spec Kit의 핵심은 명확한 명세를 기준으로 AI를 활용하되, 사람의 점검과 보완을 전제로 하는 개발 흐름임을 확인할 수 있었습니다.
이상으로 SDD와 Spec Kit의 개념, 그리고 실습 전 과정을 살펴보았습니다. 직접 명세를 정의하고 구현해 보면서, 개발이 실제로 어떻게 작동하는지 경험해 보시길 바랍니다.
저자 및 출처
저자
권민지(Minji Kwon | LinkedIn)
황나영(Nayoung Hwang | LinkedIn)
김현근(Hyun-geun Kim | LinkedIn)
출처
[1] Wikipedia. 2025. "Vibe coding". https://en.wikipedia.org/wiki/Vibe_coding
[2] Anthropic. 2025. "Using CLAUDE.md files: Customizing Claude Code for your codebase.". Claude Blog. https://claude.com/blog/using-claude-md-files
[3] Agentic AI Foundation. 2025. "AGENTS.md". https://agents.md/
[4] W Chatlatanagulchai et al. 2025. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding". arXiv. https://arxiv.org/abs/2511.12884v1
[5] Github. 2025. “GitHub Universe ‘25 Recap Seoul". GitHub Universe. https://github.registration.goldcast.io/events/a6bd39d0-520a-4d7b-b0a3-864f1c510ab7?utm_source=sdr&utm_medium=email&utm_campaign=recap25-SEL&utm_content=
[6] Wikipedia. 2025. "Software requirements specification". https://en.wikipedia.org/wiki/Software_requirements_specification
[7] François Zaninotto. 2025. "Spec-Driven Development: The Waterfall Strikes Back". Marmelab. https://marmelab.com/blog/2025/11/12/spec-driven-development-waterfall-strikes-back.html
[8] Birgitta Böckeler. 2025. "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl". Thoughtworks. https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
[9] Meta-Quantum.Today. 2025. "SpecKit: Github's NEW tool That FINALLY Fixes AI Coding". https://meta-quantum.today/?p=8026
[10] GitHub. 2025. "Spec Kit". https://github.com/github/spec-kit
[11] Kiro. "Agentic AI development from prototype to production". https://kiro.dev/
[12] Tessl. 2025. "What is Tessl?". https://docs.tessl.io/
[13] Meer Hashaam khan. 2025. "Spec-Driven Development with Spec Kit". Medium. https://medium.com/@hashaamkhan975/spec-driven-development-with-spec-kit-34c443e3eaf6


