Claude Code나 GitHub Copilot 같은 AI 에이전트가 당연해진 지금, 개발 스타일은 크게 변했습니다. 지시를 내리면 코드는 점점 써 내려가집니다. 하지만 한편으로는, "AI에게 무엇을 만들어 달라고 할지"를 매번 구두나 채팅으로 다시 설명하고 있지는 않으신가요?

이것은 말하자면 목적지를 전달하지 않은 채 운전사(AI)에게 계속 지시를 내리고 있는 상태입니다. 그 자리에서는 동작하는 코드가 만들어지더라도, 시간이 조금 지나면 "왜 이렇게 구현되었는지", "본래 사양은 어떠했는지"를 알 수 없게 되어, 코드와 사양이 점점 어긋나게 됩니다. 많은 현장에서 일어나고 있는 일이 아닐까요?

실제로, "사양서가 애초에 존재하지 않는다", "사양서가 있기는 하지만 업데이트되지 않아 최신 버전이라고 부를 수 없다", "정신을 차려보니 아무도 전체상을 추적할 수 없어 이미 블랙박스화되어 무엇이 어떻게 움직이는지 모르겠다"와 같은 상황은 규모의 대소와 상관없이 어느 현장에서든 꽤 자주 발생하고 있습니다. 사양서는 "만들고 끝"인 일회성 문서가 되기 쉬우며, 구현이 진행됨에 따라 실태와의 괴리가 쌓여 최종적으로는 "코드가 사양서"인 상태에 빠지게 됩니다.

그래서 본 기사에서는, 먼저 AI에게 읽히기 위한 설계서(사양서)를 준비하고, 그 사양서를 축으로 AI에게 구현을 지시하는 사양 주도 개발(Spec Driven Development)을 베이스로 하되, 그곳에 구현한 내용에 맞춰 사양서를 써 내려가는 코드 선행 사양 추기형 개발(Code-First Spec-Backfill Development) 을 조합하여 운용하는 방법을 소개합니다. 사양서가 모든 기점이 되면서도, 구현 결과를 사양서 측에도 계속 반영함으로써 코드와 사양서 모두 항상 최신 상태로 유지되는 개발 사이클을 목표로 합니다.

참고로 "코드 선행 사양 추기형 개발(Code-First Spec-Backfill Development)"이라는 명칭은 이 기사를 위해 필자가 독자적으로 생각해낸 것입니다. 만약 이미 비슷한 사고방식을 가리키는 명칭이 존재한다면 꼭 알려주세요.

이번 기사는 다음과 같은 독자를 대상으로 합니다.

• Claude Code나 GitHub Copilot을 사용하여 일상적으로 개발하고 있다
• 정신을 차려보니 사양서보다 먼저 코드가 완성되어 있는 방식으로 진행되고 있다
• 사양서를 쓰는 것 자체가 솔직히 귀찮아서 뒤로 미루기 일쑤다
• "사양서, 정신 차려보니 전혀 업데이트하지 않았네..."라는 경험이 있다
• 사양서가 존재하지 않거나, 있어도 최신 버전이라고 부를 수 없는 상태가 되어 있다
• 코드와 사양의 대응 관계를 추적할 수 없어 블랙박스화되어 버렸다
• 코드와 사양의 추적성(Traceability)을 확보하고 싶다
• 애초에 개발이 처음이라 사양서를 어떻게 써야 할지 모르겠다

최근 업계에서는 AI에게 상세한 사양을 전달하지 않고 분위기(Vibe)만 전달하여 코드를 써 내려가게 하는 "바이브 코딩(Vibe Coding)"이라는 진행 방식도 있지만, 이는 간단한 프로토타이핑에는 강한 반면 대규모 애플리케이션에는 부적합하다고 알려져 있습니다. 본 기사에서는 이와 대조적으로 사양서를 베이스로 AI를 움직이는 진행 방식을 소개합니다. 다만 이 방식에도 사실 하나가 아닌 두 가지 방향성이 있습니다. 여기서 그 양쪽을 정리해 두겠습니다.

하나는 지금까지 소개한 사양 주도 개발(Spec Driven Development) 입니다. 요건 정의·기본 설계·상세 설계·구현 계획과 같은 "사양서"를 먼저 준비하고, 그것을 베이스로 AI 에이전트를 움직여 가는 워크플로우입니다.

생각은 심플합니다.

사전에 상세한 사양서를 준비해 둠으로써 AI 에이전트의 행동을 정확하게 제어한다

바이브 코딩이 "AI에게 분위기로 움직이게 하는" 접근 방식인 것에 반해, 사양 주도 개발은 "설계서로 AI를 인도하는" 접근 방식입니다. 특히 앱의 토대를 아무것도 없는 상태에서 만들기 시작하는 첫 타이밍에서는 이 "사양서 → 코드"라는 순서가 가장 큰 위력을 발휘합니다.

한편, 실제로 개발을 진행하다 보면 세세한 수정이나 기능 추가가 있을 때마다 "반드시 먼저 사양서를 고친 뒤에 구현한다"를 매번 엄격하게 지키는 것은 솔직히 상당히 답답합니다. 작은 변경일수록 먼저 손을 움직여 코드를 고치고, 문제가 없다면 나중에 사양서에 반영하는 역방향의 흐름이 더 현실적인 상황이 많아집니다.

이것이 본 기사에서 또 하나의 축으로 사용할 코드 선행 사양 추기형 개발 (Code-First Spec-Backfill Development) 입니다. 「코드 → 사양서」라는, 사양 주도 개발 (Specification-Driven Development)과는 반대되는 순서로 진행하면서도, 최종적으로는 사양서와 코드를 일치시키는 것을 목표로 한다는 사고방식입니다.

참고로 「코드 선행 사양 추기형 개발 (Code-First Spec-Backfill Development)」이라는 명칭은 이 기사를 위해 필자가 독자적으로 고안한 것입니다. 만약 이미 유사한 사고방식을 가리키는 명칭이 존재한다면 꼭 알려주시기 바랍니다.

이것들은 대립하는 것이 아니라, 프로젝트의 상황이나 페이즈 (Phase)에 따라 나누어 사용하는 것이라고 이해해 주세요.

앱의 토대를 아무것도 없는 상태에서 만들 때

→ 사양 주도 개발 (Specification-Driven Development) (사양서 → 코드)

이미 앱은 존재하지만 사양서가 없거나, 부족하거나, 최신이 아닐 때

→ 먼저 코드를 해석하여 사양서 (spec.yaml)를 생성한다 (코드 → 사양서)

완성된 앱을 조금씩 개수해해 나갈 때

→ 코드 선행 사양 추기형 개발 (Code-First Spec-Backfill Development) (코드 → 사양서)

기존 애플리케이션에서는 「사양서가 존재하지 않는다」거나 「사양서는 있지만 구현 내용과 일치하지 않는다」는 케이스도 적지 않습니다. 그러한 경우에는 현재의 코드를 AI에게 해석하게 하여, 구현 내용을 바탕으로 spec.yaml을 생성하는 것부터 시작합니다. 그 후, 사람이 내용을 리뷰하고 수정하며, 그 사양서를 기점으로 사양 주도 개발이나 코드 선행 사양 추기형 개발로 이행합니다.

어떤 접근 방식을 취하더라도 최종적인 목적은 동일하며, 코드와 사양서를 항상 일치시켜 나가는 것입니다.

그리고 이 기사에서는 사양서의 포맷으로 YAML을 채택합니다.

최근에는 LLM에 대해 JSON이나 YAML 같은 **구조화된 포맷 (Structured Format)**으로 정보를 전달하는 기법이 활발히 연구되고 있습니다. Elnashar 등(2025)은 GPT-4o를 대상으로 JSON, YAML, Hybrid CSV/Prefix의 세 가지 프롬프트 스타일을 비교하여, 프롬프트 형식이 출력 품질이나 토큰 비용, 처리 시간에 영향을 미친다는 것을 보여주었습니다. 또한, YAML은 가독성과 효율성의 균형이 뛰어난 포맷이라고 보고되었습니다.

본 기사에서는 사람이 읽고 쓰기 쉬우면서도 AI에게 구조를 전달하기 쉽다는 점 때문에, 사양서의 포맷으로 YAML을 채택합니다.

이유는 다음과 같습니다.

• 구조가 단순하여 계층 관계를 표현하기 쉽다
• 주석을 달 수 있다 (JSON은 불가능)
• 사람이 읽고 쓰기 쉽고 유지보수하기 용이하다
• AI에게 구조화된 정보를 전달하기 쉽다

먼저 Claude Code나 GitHub Copilot을 사용하여 spec.yaml이라는 설계서를 작성합니다.

여기서 중요한 것은 **작성하는 입도 (Granularity)**입니다. 이 사양서를 AI에게 읽히는 것만으로 곧바로 앱을 구현할 수 있는 수준까지 구체적으로 기술합니다. 애매한 표현은 극력 피하고, 「AI가 망설이지 않는 설계서」를 목표로 합시다.

또한, API나 데이터베이스 설계뿐만 아니라, 컨트롤러(Controller)・서비스(Service)・리포지토리(Repository)의 책임이나 클래스명・함수명(메서드명)까지 설계서에 포함하는 것을 권장합니다. 여기까지 정의해 둠으로써 AI가 독자적인 명명 규칙이나 아키텍처로 구현해 버리는 것을 방지하고, 코드와 사양서의 추적 가능성 (Traceability)도 확보하기 쉬워집니다.

그렇다고는 해도, 아무것도 없는 상태에서 갑자기 이 정도 수준의 설계서를 써 내려가는 것은 솔직히 난이도가 상당히 높습니다. 그래서 추천하고 싶은 방법은, 이 설계서 자체도 AI와 대화하며 함께 만들어가는 방식입니다. 「이런 앱을 만들고 싶다」라는 대략적인 이미지만을 먼저 전달하고, 필요한 항목을 하나씩 AI와 정리하며 YAML로 옮겨갑니다. 이 작업은 언뜻 번거롭게 느껴질 수 있지만, 그 이후의 구현 페이즈에서는 AI에 대한 지시가 매우 단순해지며 수정으로 인한 재작업도 줄어듭니다.

또한, 기존 애플리케이션에서 시작하는 경우도 사고방식은 같습니다. 사양서가 존재하지 않거나 오래된 경우에는 먼저 AI에게 현재 코드를 해석하게 하여 spec.yaml의 초안을 생성하게 합니다. 다만, 한 번 생성한 것으로 완성이라 생각하지 말고, 「이 기능의 사양은?」 「이 API의 책임은?」 「이 클래스 구성으로 문제없을까?」와 같이 AI와 몇 번이고 대화를 거듭하며 내용을 다듬고, 실제 사양에 맞춰 키워 나갑니다.

즉, 신규 개발이든 기존 앱이든, 처음부터 완벽한 사양서(Specification)를 만드는 것이 아니라, AI와의 대화를 반복하며 사양서를 완성해 나가는 방식이 중요합니다. 사양서의 품질이 높아질수록, 이후 AI에 의한 구현 품질과 유지보수성(Maintainability)도 향상됩니다.

이때 사용하는 언어(Language)나 프레임워크(Framework), 데이터베이스(Database) 등의 기술 선정에 대해서도 AI와 상담하며 결정하는 것을 추천합니다. 다만, AI의 제안을 그대로 맹신하지 말고, "정말로 이 구성으로 문제가 없는가", "다른 선택지는 없는가"를 스스로도 조사 및 검증해야 합니다. AI는 어디까지나 설계를 지원하는 파트너이며, 최종적인 설계 및 기술 선정의 책임은 개발자 자신에게 있습니다.

최소한 다음 항목들은 명기해 두는 것을 권장합니다.

• 앱의 목적·개요
• 사용하는 언어 (프론트엔드 / 백엔드)
• 사용하는 프레임워크
• 사용하는 DB (종류, 테이블 구성 등)
• API 설계 (엔드포인트, 요청/응답)
• 화면 구성, 기능 목록
• 클래스 설계 (Controller / Service / Repository 등)
• 함수명(메서드명)과 책임
• 디렉터리 구성
• 인증·인가 방식
• 환경 변수 목록
• 외부 서비스·API 연동
• 테스트 방침 (Unit / Integration / E2E)
• 코딩 규약·명명 규칙
• 제약 사항 (비기능 요구사항 · 성능 요구사항 · 보안 요구사항 등)
• 변경 이력 (Changelog)
• 미구현·향후 과제 (TODO / Backlog)

project:
  name: TaskManagerApp
  version: 1.0.0
...

이 YAML은 어디까지나 하나의 예시입니다. 보다 AI가 이해하기 쉬운 설계서 작성법이나, "이런 항목도 넣으면 편리하다"라는 아이디어가 있다면 꼭 댓글로 알려주시면 감사하겠습니다.

이와 같이 "무엇을", "어떤 언어·기술로", "어떤 구조로" 만들 것인지를 상세히 적는 것이 포인트입니다. 이 사양서가 있으면 AI에게 매번 같은 설명을 다시 할 필요가 없어지며, 결과적으로 토큰(Token) 절약에도 도움이 됩니다.

사양서가 완성되었다면, 실제로 개발을 진행할 환경을 구축합시다.

코드의 변경 이력을 관리하고 추적할 수 있도록, 우선 Git을 도입합니다. GUI로 다루고 싶다면 GitHub Desktop 등의 도구가 편리합니다.

• GitHub 계정 생성하기
• 리포지토리(Repository) 생성하기 ( Private으로 설정해 두는 것을 추천합니다)

이러한 설정 방법은 세상에 자세한 글이 많이 있으므로, 이 글에서는 생략하겠습니다.

다음으로 Visual Studio Code 등의 에디터를 준비하고, Claude Code나 GitHub Copilot의 확장 기능 및 CLI를 설치합니다. 이 또한 설치 방법은 공식 문서를 참조해 주세요.

환경이 갖춰졌다면, 드디어 AI 에이전트에게 구현을 요청합니다. 여기서부터가 사양 주도 개발(Specification-Driven Development)의 본론입니다. 참고로 이 단계는 앱을 신규로 개발하는 경우를 상정하고 있습니다. 이미 앱이 존재하는 경우에는 이 절차를 건너뛰고, **Step 4의 "사양과 구현의 차이를 체크하기"**부터 시작해 주세요.

@spec.yaml
의 내용을 빠짐없이 읽어서, 앱을 구현해 주세요.

@spec.yaml
의 내용을 빠짐없이 읽어서, 테스트 코드도 작성해 주세요.

이 프롬프트를 던졌다면, 이제 기다리기만 하면 됩니다. 제 경험상 규모에 따라 어느 정도 시간이 걸릴 수 있으므로 느긋하게 기다립시다.

구현이 완료되면, 사양서와 실제 코드 사이에 차이가 없는지 AI에게 확인시킵니다. 이것이 추적성(Traceability) 확보의 중요한 포인트입니다.

@spec.yaml
과 현재 코드 사이에 차이가 있다면 알려주세요.

차이점에 대한 보고가 오면, 그 내용을 바탕으로 다음 지시를 내려갑니다. 차이가 발견된 경우에는 "구현이 spec.yaml과 다른 것인지", "spec.yaml이 구현과 다른 것인지"를 판단하여 어느 쪽을 수정해야 할지 결정합니다.

구현 측에 문제가 있는 경우 (코드가 spec.yaml을 따르지 않음)

방금 지적해 준 차이점을 수정해 주세요.
코드를 @spec.yaml에 맞춰 주세요.

사양서 측에 문제가 있는 경우 (spec.yaml이 구현과 다름)

방금 말한 변경 사항을 다음 문서에 반영하여 @spec.yaml을 업데이트해 주세요.

이렇게 항상 코드와 사양서의 내용을 동기화함으로써 다음 단계로 나아갈 준비를 마칠 수 있습니다.

완성된 앱은 처음 구상했던 이미지와 조금 차이가 있는 경우가 많을 것입니다. 여기서부터는 다음 루프(Loop)를 돌려 나갑니다.

그 시점의 상태를 일단 기록해 두기 위해 커밋(Commit)해 둡시다.

(수정 내용)에 맞춰 코드를 수정해 주세요.

수정 결과에 문제가 없다면, 해당 변경분에 대한 테스트 코드(Test Code)도 작성하도록 합니다.

이번 변경분을 읽어 들여서 테스트 코드를 작성해 주세요.

반대로, 구현이 구상한 대로(즉, 사양서보다 구현이 더 올바른 경우)라면 코드에 맞춰 사양서 측을 업데이트합니다.

이번 변경분을 읽어 들여서
@spec.yaml
의 내용을 변경해 주세요.

마음에 드는 변경이라면 여기서도 커밋합니다.

그 후에는 다음 루프를 끊임없이 반복합니다.

• 코드를 수정·추가한다
• 테스트 코드를 작성한다
• 마음에 들면 사양서를 업데이트한다
• 커밋한다

이 사이클을 몇 번이고 반복함으로써, 코드와 사양서가 항상 최신 상태로 동기화되는 개발을 실현할 수 있습니다.

지금까지의 흐름은 최초 앱 실행 시의 프로세스이지만, 그 이후의 기능 추가나 개수(改修)에서도 이 사이클은 완전히 동일합니다. 여기서부터가 진정한 의미의 코드 선행 사양 추기형 개발의 위력이 발휘되는 지점입니다.

새로운 기능을 추가하고 싶을 때나 수정·개량이 필요할 때는, 먼저 코드부터 시작한다는 코드 선행 사양 추기형 개발의 접근 방식으로 진행합니다.

(수정·추가 내용)에 맞춰 코드를 수정해 주세요.

수정 결과에 문제가 없다면, 해당 변경분에 대한 테스트 코드도 작성하도록 합니다.

이번 변경분을 읽어 들여서 테스트 코드를 작성해 주세요.

구현이 구상한 대로라면 코드에 맞춰 사양서 측을 업데이트합니다.

이번 변경분을 읽어 들여서
@spec.yaml
의 내용을 변경해 주세요.

마지막으로 커밋하면 완료입니다.

이와 같이, 먼저 코드로 시도해 보고 마음에 들면 사양서에 반영한다는 코드 선행 사양 추기형 개발의 사이클을 몇 번이고 반복해 나가는 것입니다. 지금까지 "사양서를 쓰는 것은 번거롭다"고 느꼈던 사람이라도, 이 메커니즘에 올라타기만 하면 기능 추가나 수정이 일어날 때마다 자연스럽게 사양서가 업데이트됩니다. 이제 "사양서를 수동으로 업데이트한다"는 독립된 작업은 존재하지 않습니다. 모든 변경 사항이 코드와 사양서에 동시에 반영되어, 항상 양자가 일치하는 상태가 유지됩니다.

여러 명이서 개발하는 경우에는 README.md에 어떠한 프롬프트(Prompt)를 사용하는지를 정리해 두는 것을 추천합니다.

## AI를 위한 지시 템플릿
### 기능 추가·수정 시
(수정·추가 내용)에 맞춰 코드를 수정해 주세요.
...

이렇게 해둠으로써 팀원 전원이 동일한 절차와 동일한 품질로 개발을 진행할 수 있습니다. 누가 담당하더라도 항상 최신 사양서와 추적성(Traceability)이 확보된 코드를 유지할 수 있다는 것이 이 개발 기법의 큰 장점입니다. 신규 개발부터 기능 추가·수정까지 모든 단계에서 일관된 프로세스를 사용할 수 있기 때문에 프로젝트 전체의 품질이 대폭 향상됩니다.

이 기사의 내용을 정리하면 다음과 같습니다.

• 사양 주도 개발 (Spec Driven Development): spec.yaml을 기반으로 AI를 가이드하여, 「사양 → 코드」 순서로 신규 앱을 구축하는 접근 방식
• 코드 선행 사양 추기형 개발 (Code-First Spec-Backfill Development): 기능 추가 및 수정 시 「코드 → 사양서」 순서로 진행하는 실무적인 접근 방식
• YAML 사양서에는 목적·사용 언어·프론트/백엔드·DB·API·클래스 설계·함수명·테스트 방침 등을 상세히 기재
• 기존 앱이 있는 경우, AI에게 코드를 해석하게 하여 spec.yaml의 초안을 생성하도록 함
• Git/GitHub + VS Code + Claude Code (또는 Copilot)로 개발 환경을 구축
• 신규 개발 단계: 사양 주도 개발로 견고한 토대를 구축
• 운영·개수 단계: 코드 선행 사양 추기형 개발로 「코드 → 테스트 → 사양서」 사이클을 회전
• spec.yaml을 활용하여 누가·언제·무엇을 변경했는지를 함수 단위까지 추적 가능하게 함
• README에 사용하는 프롬프트를 정리해 두면, 팀 개발에서도 모두가 동일한 품질로 개발할 수 있음

이 두 가지 접근 방식을 조합함으로써, 사양서가 코드의 변화에 자동으로 추종하여 항상 최신 상태가 유지되는 개발을 실현할 수 있습니다. 이제 더 이상 "사양서를 쓰는 것은 귀찮다"라는 고민은 사라질 것입니다.

많은 엔지니어가 마음 한구석에서 느끼고 있는 것이 있을 것입니다. 사양서를 작성하고 항상 최신으로 유지하는 것의 중요성은 이해하고 있습니다. 하지만, 사실 사양서를 계속 쓰는 것은 지루하고 즐겁지 않습니다. 왜냐하면, 코드의 동작이야말로 진실이며, 사양서는 어디까지나 그것을 사후에 설명하고 있을 뿐이기 때문입니다. 그래서 심리적으로는 "코드를 사양서에 맞춰야 한다"라고 생각하고 계시지 않나요? 이 딜레마를 기존의 개발 방식으로는 해결할 수 없었습니다.

또한, 팀 개발 현장에서는 또 다른 과제가 발생하고 있습니다. "OO 씨가 없으면 프로젝트의 전체상을 알 수 없다"라는 개인 의존성(属人性) 문제. 사양서가 완비되어 있지 않거나, 아무도 내용을 정확히 파악하지 못하고 있는 상황. 이러한 문제는 규모의 대소와 상관없이 업계 전체에서 흔히 일어나고 있습니다.

그리고 우리의 개발 현장은 크게 변했습니다. AI를 사용하면 정확하고 방대한 양의 코드를 빠르게 생성할 수 있는 시대입니다. 그에 따라 인간의 역할도 변할 수밖에 없습니다. 지금까지 대규모 엔지니어 팀이 필요했던 개발도, AI와 소수 인원으로 진행할 수 있게 되었습니다. 기존의 개발 방식에 그저 따르기만 해서는 이 급격한 변화를 따라갈 수 없습니다.

물론 기존의 개발 방식이 나쁜 것은 아닙니다. 수십 년간 실천되어 온 방식에는 많은 케이스 스터디와 지견이 축적되어 있습니다. 하지만 "지금 이 순간"의 최적의 방식과 "앞으로의 시대"의 최적의 방식은 다를 수 있습니다.

사실, 애자일 개발 (Agile Development)도 처음에는 "지나치다", "규율이 부족하다"라며 비판받았습니다. 하지만 지금은 많은 프로젝트에서 채택되는 개발 방식이 되었고, 나아가 스크럼 (Scrum)이나 칸반 (Kanban) 등 다양한 파생 형태가 생겨났습니다. 이와 유사한 진화가 코드 선행 사양 추기형 개발에도 일어나기를 기대합니다.

본 기사에서 소개한 "코드 선행 사양 추기형 개발"이라는 개념을 듣고 "과연 그렇군"이라며 납득하는 사람이 있는 반면, 부정적인 의견을 가진 사람도 적지 않을 것이라 생각합니다. 오히려 처음에는 부정적인 반응이 더 많을지도 모릅니다. 그것은 당연합니다. 왜냐하면, 이 방식에는 아직 약점이나 개선의 여지가 있기 때문입니다. 완벽한 개발 방식이란 존재하지 않습니다.

본 기사가 지금까지 언급해 온 과제에 직면해 있는 엔지니어들에게 도움이 된다면 더할 나위 없는 기쁨이겠습니다.