BMAD Method + Claude Code: 명세 기반 AI 개발로 실제로 프로젝트를 완성하는 방법

나는 무언가 잘못되었다는 것을 인정하기 전까지, 3개월 동안 Claude Code 프로젝트들을 '바이브 코딩 (vibe-coding)' 방식으로 진행해 왔다. 코드는 대체로 잘 작동했지만, 나는 계속해서 동일한 문제로 시간을 허비하곤 했다. Claude와 나는 세션 중간에 원래의 의도에서 벗어나곤 했고, 두 번째나 세 번째 세션에 도달하면 우리 중 누구도 코드베이스의 결정 중 절반을 왜 그렇게 내렸는지 기억하지 못했다.

나는 v3에서 오케스트레이터 (orchestrator) 개념이 도입된 이후로 BMAD Method를 지켜봐 왔지만, 나에게는 불필요한 오버헤드처럼 느껴졌다. 그러다 진정한 아키텍처 개편 (NPM 배포, 모듈형 에이전트, 멀티 IDE 지원)을 담은 v4가 출시되었고, 나는 그것을 본격적으로 시도해 보았다. 거의 즉시 이해가 되었다. 나는 PM, 아키텍트 (architect), 스크럼 마스터 (scrum master), QA와 함께 팀 단위로 일하며 수년간 경력을 쌓아왔다. 전체 소프트웨어 개발 생명주기 (SDLC) 구성원들 말이다. BMAD는 이러한 역할들을 AI 에이전트 (agents)에 매핑하기 때문에, 워크플로 (workflow)가 생소하기보다는 익숙하게 느껴졌다. 나는 새로운 프로세스를 배우는 것이 아니었다. 단지 팀 구성원만 다를 뿐, 이미 알고 있는 프로세스를 실행하고 있었던 것이다. 그것이 대략 9개월 전의 일이다. 이제 나는 이것 없이는 개발하지 않는다.

60초 만에 보는 BMAD

BMAD (Breakthrough Method for Agile AI-Driven Development)는 명세 (specifications), 역할 기반 에이전트 (role-based agents), 그리고 단계별 워크플로 (phased workflows)를 중심으로 AI 보조 코딩을 구조화하는 오픈 소스 프레임워크이다. 명세가 진실의 원천 (source of truth)이며, 코드는 그 결과물이다.

v6 기준으로, 이 프로젝트는 19개 이상의 특화된 에이전트 (PM, Architect, Scrum Master, Developer, QA 등), 50개 이상의 명명된 워크플로, 그리고 스킬 (skills), 커맨드 (commands), 훅 (hooks)을 통해 Claude Code에 네이티브하게 연결되는 모듈 시스템을 갖추고 있다. GitHub 별점 40,000개를 돌파했으며, 생태계에는 여러 서드파티 Claude Code 플러그인들이 생겨났다.

수치를 차치하고, 이것이 실제로 당신의 작업 방식을 바꾸는가? 나에게는 그렇다. 상당히 많이.

설정 방법

나는 여러 활성 프로젝트에서 BMAD를 사용하고 있다. Bridgely, CoinFolio, FiveCrowns, 그리고 Vela는 모두 이런 방식으로 구축되었다. 도메인은 다르지만, 워크플로는 동일하다.

CLAUDE.md에서

많은 BMAD 가이드에서는 CLAUDE.md 파일을 함께 설정하라고 조언합니다. 하지만 저는 실제로 그렇게 하지 않습니다. BMAD 자체의 에이전트 설정 (agent configurations), 기술 (skills), 그리고 워크플로 정의 (workflow definitions)만으로도 충분한 컨텍스트 (context)를 제공하기 때문입니다. 그 위에 CLAUDE.md를 추가하는 것은 기껏해야 중복이며, 최악의 경우 충돌하는 지침이 생길 수 있습니다. CLAUDE.md는 한 가지를 말하고, BMAD의 에이전트 설정은 다른 것을 말하면, Claude Code는 마지막에 본 것을 선택하게 됩니다.

저는 프로젝트 수준의 컨벤션 (conventions) (파일 명명 규칙, 디렉토리 구조, 비밀번호 커밋 금지 규칙 등)을 BMAD 자체 설정에 유지합니다. 두 개가 아닌, 하나의 단일 진실 공급원 (Single source of truth)을 만드는 것입니다.

실제 워크플로 (The Actual Workflow)

하나의 기능은 네 가지 단계를 거칩니다. 제 블로그 파이프라인을 위한 Dev.to 게시 기술 (publishing skill)을 구축하는 실제 작업을 통해 이 과정이 어떻게 진행되는지 살펴보겠습니다.

명세 우선 (Spec first). 저는 제가 원하는 것을 설명합니다. BMAD의 PM 에이전트가 제품 요구 사항 문서 (PRD)를 작성합니다. Architect 에이전트가 이를 검토하고 기술 설계 (technical design)를 생성합니다. 두 결과물 모두 docs/specs/ 내의 마크다운 (markdown) 파일로 저장되어 세션이 바뀌어도 유지됩니다.

> "Dev.to API를 통해 블로그 포스트를 게시하고,
>  초안 모드 (draft mode)를 처리하며,
>  프론트매터 (frontmatter) 검증을 관리하는 기술 (skill)이 필요합니다."

PM 에이전트는 사용자 스토리 (user stories), 수락 기준 (acceptance criteria), 그리고 범위 경계 (scope boundaries)를 제공합니다. Architect 에이전트는 이를 파일 구조, 의존성 (dependencies), 그리고 통합 지점 (integration points)으로 매핑합니다. 아직 코드는 없습니다. 오직 설계도뿐입니다.

스토리 분해 (Story breakdown). Scrum Master 에이전트는 명세를 구현 가능한 스토리로 나눕니다. 각 스토리는 명확한 완료 기준 (done-criteria)을 가지며, docs/stories/ 아래의 각각의 파일로 생성됩니다. 이 단계는 거대한 구현 프롬프트 (implementation prompt) 하나를 작성하던 저의 예전 습관을 대체했습니다. 더 작은 단위로 나눌수록 각 조각을 실제로 테스트할 수 있게 됩니다.

구현 (Implementation). Claude Code는 20분 전에 입력한 모호한 프롬프트가 아니라, 명세 (spec) 파일과 스토리 (story) 파일을 바탕으로 코드를 작성합니다. Dev 에이전트는 스토리 파일, 아키텍처 문서, 그리고 BMAD 설정에 있는 프로젝트 컨벤션을 가져옵니다. 결정 사항들은 채팅 기록 속으로 사라지는 대신 명세로 거슬러 올라가 추적될 수 있습니다.

검증 (Validation). QA 에이전트가 수락 기준 (Acceptance Criteria)에 따라 작업 내용을 확인하고, 테스트를 실행하며, 누락된 부분을 표시합니다. 바이브 코딩 (Vibe-coding)은 이 단계를 완전히 건너뛰는데, 이것이 바로 바이브 코딩으로 작성된 프로젝트에 막대한 기술 부채가 쌓이는 정확한 이유입니다.

무엇이 달라졌는가

앞서 언급했던 컨텍스트 드리프트 (Context-drift) 문제요? 사라졌습니다. 명세 (Spec) 파일은 Claude Code가 고정될 수 있는 지속적인 기준점을 제공하므로, 지난 화요일에 내린 결정을 다시 설명할 필요가 없습니다. 예전에는 두세 번의 세션이 걸리던 기능 구현이 이제는 한 번의 세션 만에 끝납니다. 명세가 기억을 대신해주기 때문입니다.

또 다른 변화는 더 미묘했습니다. 예전에는 "실행된다"는 것만으로 완료라고 생각했습니다. 하지만 이제 완료란 QA 에이전트가 수락 기준 (Acceptance Criteria)에 따라 승인했음을 의미합니다. 작은 차이처럼 들리겠지만, 이는 나중에 수행해야 할 재작업 (Rework)의 양을 완전히 바꿔 놓았습니다. 훨씬 줄어들었습니다.

리팩터링 (Refactoring)도 쉬워졌습니다. 무언가를 재구성해야 할 때, 구현 (Implementation) 옆에 원래의 의도 (Intent)가 문서화되어 있으면 Claude Code에게 코드가 현재 무엇을 하는지가 아니라, 원래 무엇을 하기로 되어 있었는지를 알려줄 수 있습니다.

과장해서 말하지 않겠습니다. 가장 큰 개선점은 단순한 속도가 아닙니다. 세션을 시작하기 전에 이미 정의해 두었기 때문에, 세션이 끝날 때 무엇을 얻게 될지 예측할 수 있다는 점입니다.

한계점

컨텍스트 윈도우 (Context window) 압박은 실재합니다. 규모가 큰 프로젝트에서는 BMAD 명세에 아키텍처 문서, 스토리 파일까지 더해지면 컨텍스트를 빠르게 소모합니다. 명세를 간결하게 유지하는 능력이 향상되긴 했지만, "유용할 만큼 충분한 상세함"과 "Claude Code가 끝을 읽을 때쯤 시작 부분을 잊어버리지 않을 정도의 적절함" 사이에는 긴장 관계가 존재합니다.

에이전트 간의 인수인계 (Handoff)는 거칠 수 있습니다. Architect 에이전트가 때때로 PM 에이전트가 명시한 내용과 일치하지 않는 가정을 할 때가 있습니다. 이를 포착하기 위해 스토리 파일에 명시적인 인수인계 체크리스트를 추가하기 시작했지만, 이는 아마도 더 긴밀한 통합이 이루어져야 할 부분을 수동으로 해결하는 임시방편입니다.

그리고 사소한 작업(오타 수정, CSS 미세 조정, 한 줄짜리 설정 변경 등)의 경우, 전체 BMAD 워크플로우를 사용하는 것은 과합니다. 세 개 미만의 파일을 수정하거나 실제적인 설계 결정이 포함되지 않은 작업에 대해서는 이 과정을 생략합니다.

직접 시도해보기

GitHub repo에 설치 안내가 있습니다. 제 조언은 이렇습니다. BMM Core(기본 모듈)부터 시작하고, 한꺼번에 모든 것을 설치하지 마세요. 실제 프로젝트의 실제 기능을 하나 골라, 코드를 작성하기 전에 먼저 명세(spec)를 작성해 보세요.

제가 내재화하는 데 가장 오래 걸린 사실은 프롬프트(prompts)보다 프로세스(process)가 더 중요하다는 점이었습니다. 저는 Claude Code에게 일을 시키는 방식을 미세 조정하는 데 몇 달을 보냈습니다. BMAD는 그 에너지를 Claude Code가 무엇을 구축하기를 원하는지 정의하는 방향으로 전환시켰고, 프롬프트는 대부분 알아서 해결되었습니다.

명세 기반 개발(Spec-Driven Dev)은 BMAD보다 더 큰 흐름입니다

BMAD가 이 방향을 추진하는 유일한 프레임워크는 아닙니다. Kiro, GSD, 그리고 RALPH-LOOP는 모두 동일한 논제의 변형을 기반으로 구축되었습니다. 즉, AI가 생성하는 코드는 당신이 제공하는 구조(structure)만큼만 훌륭하다는 것입니다.

BMAD가 저에게 효과적인 이유는 Claude Code의 확장 모델(extension model)에 직접적으로 매핑되기 때문입니다. 기술(Skills), 훅(hooks), 명령(commands). 이것은 Claude Code를 감싸는 래퍼(wrapper)가 아닙니다. Claude Code가 이미 가지고 있는 도구들을 위한 플레이북(playbook)입니다.