Spec-Driven Development 도입기 (with OpenSpec)

요즘 AI를 활용하다보면 코드 개발을 위한 문서가 엄청나게 많이 만들어진다.

그러다보니 문서를 어떻게 설계하고 관리하는지에 대한 고민이 생기게 되었다.

 

이번 글에서는 실제 세미나에서 다뤘던 내용을 기반으로,
Spec-Driven Development(SDD)와 이를 구현하기 위한 OpenSpec Framework에 대해 정리해보려고 한다.

 

개념 설명뿐만 아니라, 실제 도입 과정과 결과까지 함께 다뤄보겠다.

SDD란?

주변에서 AI를 활용한 개발을 보면, 보통 다음과 같은 흐름을 따른다.

PLANNING

→

IMPLEMENT

→

DONE

문제는 이 구조에서 한 번 구현 단계로 넘어가면 되돌아가기 어렵다는 점이다.

요구사항이 바뀌거나 설계가 잘못된 경우, 결국 코드를 수정하는 방향으로만 해결하게 된다.

 

이런 문제를 해결하기 위해 나온 개념이 바로 SDD(Spec-Driven Development)이다.

명세

→

설계

→

작업

→

구현

위 flow와 같이 코드를 먼저 작성하는 것이 아니라 문서(명세)를 먼저 도출하는 방식이다. 

 

👉 한 줄 요약

설계 문서(명세)를 중심으로 개발을 진행하는 방식

SDD Framework란?

Spec-Driven Development의 이론을 

개발에 적용할 수 있도록 도와주는 것이 SDD Framework이다.

 

예를 들어, Spring Framwork를 생각해보면,

복잡한 설정 없이 API 개발을 쉽게 할 수 있도록 구조와 환경을 제공한다.

 

이처럼, SDD Framwork 역시 명세 기반 개발 이론을 더 쉽게 실현할 수 있도록

개발 환경과 흐름을 제공하는 역할이라고 보면 된다.

 

대표적인 예로는 OpenSpec, Spec Kit, BMAD..가 있는데,

다른 이유는 없고 이름이 마음에 드는 OpenSpec으로 진행해보았다.

GitHub - Fission-AI/OpenSpec: Spec-driven development (SDD) for AI coding assistants.

 

OpenSpec은 다음과 같은 특징을 가진다.

• AI Agent가 명세 기반 개발 흐름을 따르도록 유도
• 명령어 기반 인터페이스를 통해 다양한 AI Agent 연동 가능 (Claude, Codex ...)
• 문서 → 코드 생성까지 자연스럽게 연결

 

OpenSpec의 흐름은 아래와 같다.

proposal → specs → design → tasks → implement

문서 구현

1️⃣ proposal

/osx:proposal "요구사항"

개발자가 요구사항을 입력하면,

해당 내용을 기반으로 구체적인 proposal 문서가 생성된다.

 

즉, 개발자는 "무엇을 만들 것인가"만 정의하면 된다.

 

2️⃣ specs → design → tasks

proposal 명령어 이후, specs·design·tasks 순서대로 문서가  자동으로 생성된다.

• specs: 요구사항을 구체화한 명세 (요구사항 명세서)
• design: 시스템 구조 및 설계 (아키텍처, 구조)
• tasks: 구현을 위한 작업 단위 (체크리스트)

 

3️⃣ implement

/osx:implement

앞에서 생성된 문서(specs, design, tasks)를 기반으로 실제 코드 구현이 진행된다.

실무 도입

실제 사례로 간혈적으로 JWT가 인코딩되는 문제를 해결하는 과정을 적용해봤다.

 

📝 문제 상황

• 특정 외부 통신에서 JWT 토큰을 인코딩해서 전달
• 간헐적으로 발생 → 원인 추적 어려움

🛠 해결 방향

• 토큰 수신 시, 디코딩 처리
• 정상 토큰은 그대로 유지

이정도 방향만 세워둔 상태로, OpenSpec을 활용한 문제 해결 방법을 소개하겠다.

 

 

1️⃣ 설치 및 초기 세팅

npm install -g @fission-ai/openspec@latest
openspec init

위 화면처럼 시작하게 되면,

Enter 후 사용하고 있는 Agent를 선택하면 된다.

 

그러면 아래와 같은 폴더가 프로젝트 루트에 생성된다.

├── .codex
│   └── skills
│       ├── openspec-apply-change      ← /opsx:apply (spec 기반 코드 생성)
│       ├── openspec-propose           ← /opsx:propose (문서 생성)
│       ├── openspec-explore           ← /opsx:explore (문제 탐색, 요구사항 구체화)
│       └── openspec-archive-change    ← /opsx:archive (작업 결과 정리 및 아카이빙)
│
└── openspec
    ├── changes                        ← 작업 이력 관리 영역
    │   ├── archive                    ← 완료된 작업 보관
    │   └── 작업 폴더                    ← propose 실행 시 생성됨
    │       ├── proposal.md
    │       ├── spec.md
    │       ├── design.md
    │       └── tasks.md
    │
    ├── specs                          ← 공통/전역 spec 관리 (프로젝트 전체 기준)
    │
    └── config.yaml                    ← OpenSpec 설정

 

2️⃣ Propose

/opsx:propose "외부 통신 후, 간혈적으로 토큰 인코딩되는 문제 개선"

이 한 줄로 아래 과정이 자동으로 생성된다.

• 요구사항 정의 (specs)
• 설계 문서 (design)
• 작업 단위 (tasks)

📌 specs 문서 생성

상세내용 생략

간단하게 명령했던 "인코딩 문제 개선"이라는 제안을

프로젝트 분석 후, 조금 더 구체적인 요구사항으로 만들어주는 과정이다.

 

📌 design 문서 생성

상세내용 생략

구체적인 요구사항을 기반으로 전략을 설계하는 단계로

목표와 목표가 아닌 부분에 대해 명확히 경계를 나누고 Trade-off까지 고려하는 문서이다.

 

📌 task 설계

상세내용 생략

정의된 Spec, Design 문서를 기반으로 체크리스트를 만드는 과정이다.

실제 AI는 해당 체크리스트를 기반으로 작업을 수행한다.

 

3️⃣ Apply

/opsx:apply

정의한 문서(spec, design, task) 기반으로

코드 생성을 진행하며 해당 단계는 절차대로 진행하므로 굉장히 빠르게 끝난다.

 

📌 실제 생성한 코드 일부

    private static String normalizeReservedString(ChargePayResult result, String rawQuery) {
        String originalToken = result.token();
        String rawToken = extractRawQueryValue(rawQuery, "TOKEN");
        String candidate = rawToken != null ? rawToken : originalToken;
        if (candidate == null || candidate.isEmpty() || !candidate.contains("%")) {
            return candidate;
        }

        try {
            return URLDecoder.decode(candidate, StandardCharsets.UTF_8);
        } catch (IllegalArgumentException e) {
            log.warn(...);
            return originalToken != null ? originalToken : candidate;
        }
    }
		// 입력값에 대한 검증을 한번 더 수행 (전달받은 값에 의존하지 않음)
    private static String extractRawQueryValue(String rawQuery, String parameterName) {
        if (rawQuery == null || rawQuery.isEmpty()) {
            return null;
        }

        String prefix = parameterName + "=";
        for (String param : rawQuery.split("&")) {
            if (param.startsWith(prefix)) {
                return param.substring(prefix.length());
            }
        }

        return null;
    }

OpenSpec 사용후기

OpenSpec을 도입해보면서 느낀 점은, 문서가 상당히 디테일하게 생성된다는 것이다.

단순한 요구사항을 기반으로 영향 범위나 trade-off까지 함께 고려되며, 개발자인 나도 놓칠 수 있는 부분까지 자연스럽게 보완된다.

 

다만, 이러한 요소들을 모두 반영하려다 보니 구현 단계에서는

기존에 일반적으로 생성하던 AI 코드보다 훨씬 방어적인 코드가 작성되는 경향이 있었다.

(예를 들어, 입력값 검증이나 예외 처리와 같은 로직이 불필요하게 많다 라는 느낌이 들었다.)

 

처음에는 모델 차이인가 싶어 다양한 LLM으로 테스트해보았지만

OpenSpec의 구조 자체가 일반적인 코드 생성보다는 안정성을 우선시한다고 느겼다.

 

오늘의 결론

 

AI Native 개발 환경으로 점점 변경되면서 고민이 많아졌다.

개발 실력 그리고 지식은 AI가 이미 상당한 수준까지 올라왔다는 것을 부정하기 어렵다.

 

그래도 정리 능력과 요구사항 도출 능력은 AI보다 뛰어나다고 생각했다.

하지만 이녀석들 판을 깔아주니 정리, 요구사항 도출까지 잘해버린다. 스스로 문서를 만들고 개발까지 다해버린다.

 

이러한 변화를 보며, 앞으로의 개발 방법에 대한 기대와 동시에 불안감 역시 함께 느끼게 되었다.

 

그럼에도 불구하고, 이 격변하는 흐름 속에서 살아남을 수 있을 것이라는 확신은 있다.

다만, 살아남는 방식은 예전과는 분명히 달라질 것이므로 계속해서 탐색해 나갈 것이다.