BMAD Method 튜토리얼 7편: 이미 있는 프로젝트에 BMAD 붙이는 법

요약#

참고 자료#

• BMAD Method - Established Projects - 기존 프로젝트에 BMAD를 붙이는 기본 흐름
• BMAD Method - Project Context - project-context.md의 역할과 로딩 범위
• BMAD Method - Established Projects FAQ - 기존 프로젝트에서 자주 나오는 질문
• BMAD Method - Workflow Map - 기존 프로젝트에서도 그대로 적용되는 workflow 구조
• BMAD Method - Skills - workflow skill과 naming convention

바로 써먹는 템플릿#

기존 프로젝트에서는 지금 이 코드베이스가 어떤 규칙으로 움직이는지를 먼저 잡는 편이 좋습니다.
이 글에서는 기존 프로젝트에서 특히 자주 쓰는 direct workflow skill 위주로 예시를 보여주겠습니다.

공식 skill 이름은 bmad-create-prd처럼 하이픈(-)이 들어가지만, 사용하는 AI 도구에 따라 bmad create prd처럼 띄어쓰기로 입력하는 편이 더 잘 인식될 수도 있습니다.

기존 프로젝트에서 자주 쓰는 흐름은 아래처럼 보면 됩니다.

여기서 DP는 Document Project, CP는 Create PRD의 약자입니다.

먼저 예전에 끝난 planning 산출물이 남아 있다면 정리하는 편이 좋습니다.
공식 Established Projects 문서는 완료된 PRD, epics, stories 파일을 그대로 남겨 두지 말고, 아카이브하거나 지우거나 버전 기록에 맡기라고 안내합니다.
특히 아래 위치에 완료된 산출물이 남아 있으면 현재 작업과 섞여 판단을 흐릴 수 있습니다.

• docs/
• _bmad-output/planning-artifacts/
• _bmad-output/implementation-artifacts/

먼저 현재 프로젝트를 문서화하고 싶다면 이렇게 시작하면 됩니다.

Analyst agent로 프로젝트 문서화를 시작하는 예시

1
bmad-analyst
2

3
DP

skill로 프로젝트 문서화를 바로 실행하는 예시

1
bmad-document-project
2

3
현재 코드베이스를 스캔해서
4
핵심 구조, 주요 기능, 중요한 규칙이 드러나는 문서를 만들어줘.
5
문서가 오래됐거나 비어 있는 부분이 있으면 같이 짚어줘.

그다음 현재 프로젝트 규칙을 project-context.md로 고정합니다.

project-context를 생성하는 예시

1
bmad-generate-project-context
2

3
현재 코드베이스의 기술 스택, 파일 구조, 이름 규칙, 테스트 방식,
4
지켜야 하는 구현 관습을 기준으로 project-context.md를 만들어줘.

변경 범위가 작다면 그 다음은 Quick Flow로 바로 가도 됩니다.

기존 프로젝트에서 작은 변경을 처리하는 예시

1
bmad-quick-dev
2

3
기존 코드베이스 관습을 유지하면서
4
일정 상세 화면에 승인 상태 배지를 추가하고 싶어.
5
관련 화면과 상태 처리 범위 안에서만 바뀌게 정리하고 구현해줘.

반대로 변경이 크다면 PRD부터 다시 만드는 편이 낫습니다.

기존 프로젝트에서 큰 변경을 기획으로 시작하는 예시

1
bmad-create-prd
2

3
기존 일정 관리 도구에 관리자 승인 플로우와 알림센터를 추가하려고 해.
4
현재 시스템 구조를 존중하면서도
5
이번 변경 범위와 제약이 드러나는 PRD를 만들어줘.

기존 프로젝트에서는 왜 접근 방식이 달라질까요?#

새 프로젝트에서는 빈 상태에서 아이디어를 문서로 만들면 됩니다.
하지만 기존 프로젝트는 이미 코드, 화면, 데이터 구조, 문서, 팀 관습이 존재합니다.

즉 기존 프로젝트에서 중요한 질문은 “무엇을 만들까?” 하나가 아닙니다.
그만큼 중요한 질문이 하나 더 있습니다.

지금 이 코드베이스는 어떤 규칙으로 움직이고 있는가?

이 질문을 놓치면 문제가 생깁니다.

• 기존 구조를 무시한 새 설계를 들고 오게 됩니다
• 문서와 실제 코드가 어긋난 상태로 진행됩니다
• AI가 현재 프로젝트 관습 대신 일반적인 베스트 프랙티스를 따라가 버립니다

공식 Established Projects 문서가 기존 프로젝트 전용 가이드를 따로 두는 이유도 여기에 있습니다.
기존 프로젝트는 “이미 존재하는 현실”을 읽는 단계가 먼저 필요합니다.

먼저 정리할 것은 현재 코드베이스의 상태입니다#

공식 Established Projects 문서는 한 가지를 먼저 요구합니다.
이미 끝난 planning 산출물이 남아 있다면, 그것부터 정리하라는 점입니다.

이 단계가 필요한 이유는 단순합니다.
현재 작업과 상관없는 옛 PRD나 story 파일이 남아 있으면, 이후 workflow가 지금 해야 할 일과 이미 끝난 일을 섞어 읽을 수 있기 때문입니다.

즉 기존 프로젝트에서 BMAD를 다시 시작할 때는 아래 순서가 더 안전합니다.

• 끝난 planning 산출물을 먼저 정리합니다
• 그다음 현재 코드베이스를 읽습니다
• 마지막으로 project-context.md로 현재 규칙을 고정합니다

공식 문서가 그다음으로 강하게 권하는 것은 project-context.md입니다.
그리고 문서가 부실하거나 오래됐다면 bmad-document-project도 강하게 추천합니다.

이 흐름의 핵심은 단순합니다.

• 현재 코드베이스를 먼저 읽는다
• 현재 규칙을 문서로 남긴다
• 그다음부터 변경 작업을 시작한다

즉 기존 프로젝트에서 BMAD의 첫 단계는 “새 문서를 만드는 일”보다 “이미 있는 맥락을 복원하는 일”에 가깝습니다.

bmad-document-project는 언제 필요한가요?#

공식 FAQ는 이 질문에 아주 명확하게 답합니다.
bmad-document-project는 항상 필수는 아니지만, 아래 경우라면 강하게 권장됩니다.

• 문서가 거의 없습니다
• 문서가 오래돼서 실제 코드와 안 맞습니다
• AI가 현재 시스템을 이해할 만한 배경 정보가 부족합니다

즉 기존 프로젝트라고 해서 무조건 bmad-document-project부터 해야 하는 것은 아닙니다.
하지만 실제로는 문서가 부실한 코드베이스가 많기 때문에, 상당히 자주 도움이 됩니다.

좋은 기준은 이겁니다.

• docs/를 열었을 때 현재 구조를 설명하는 문서가 충분하면 건너뛸 수 있습니다
• 그렇지 않다면 먼저 현재 상태를 문서로 복원하는 편이 안전합니다

그리고 이 workflow는 꼭 처음에만 써야 하는 것도 아닙니다.
공식 FAQ도 잊고 지나갔더라도 나중에 실행해도 된다고 설명합니다.

기존 프로젝트에서는 project-context.md가 특히 중요합니다#

공식 Project Context 문서는 이 파일을 프로젝트의 구현 안내서, 더 강하게 말하면 AI가 따라야 할 헌법처럼 설명합니다.

왜 기존 프로젝트에서 더 중요할까요?
이유는 새 프로젝트보다 “당연한 규칙”이 훨씬 많기 때문입니다.

예를 들어 이런 것들입니다.

• 어떤 상태 관리 방식을 쓰는지
• API 호출을 어디서 처리하는지
• 테스트를 어떤 패턴으로 쓰는지
• 디렉터리 구조를 어떻게 유지하는지
• 이 프로젝트에서 특별히 피해야 하는 구현 방식이 무엇인지

이런 규칙은 코드 몇 줄만 읽어서는 잘 안 보입니다.
그래서 project-context.md가 필요합니다.

공식 문서에 따르면 이 파일은 아래 workflow들이 자동으로 읽습니다.

• bmad-create-architecture
• bmad-create-story
• bmad-dev-story
• bmad-code-review
• bmad-quick-dev
• bmad-sprint-planning
• bmad-retrospective
• bmad-correct-course

즉 한 번 잘 만들어 두면, 이후 거의 모든 구현 흐름에서 공통 기준으로 쓰입니다.

작은 변경이면 Quick Flow가 잘 맞습니다#

이 부분은 많은 분이 궁금해합니다.
“기존 프로젝트면 무조건 큰 문서 작업부터 해야 하나?”

공식 FAQ의 답은 아니다입니다.
기존 프로젝트에서도 Quick Flow는 아주 잘 맞습니다.

오히려 작은 수정과 작은 기능 추가는 기존 프로젝트에서 더 자주 나옵니다.
예를 들면 이런 작업입니다.

• 화면 버튼 동작 수정
• 기존 API 응답 처리 보완
• 작은 관리자 기능 추가
• 버그 수정

공식 FAQ는 Quick Flow가 기존 프로젝트에서 아래를 잘 해준다고 설명합니다.

• 현재 스택을 자동으로 감지합니다
• 기존 코드 패턴을 분석합니다
• 기존 관습을 읽고 확인합니다
• 현재 프로젝트를 존중하는 spec을 만듭니다

즉 “기존 프로젝트라서 Quick Flow를 쓰면 안 된다”가 아니라,
“기존 프로젝트일수록 Quick Flow가 잘 맞는 경우가 많다”에 가깝습니다.

큰 변경이면 기존 시스템을 읽고 PRD부터 다시 시작해야 합니다#

반대로 변화 범위가 커지면 Quick Flow만으로는 부족합니다.
이럴 때는 새 프로젝트와 비슷하게 Product Brief → PRD → architecture → epics/stories 흐름으로 들어가야 합니다.

다만 차이가 하나 있습니다.
새 프로젝트는 아이디어에서 출발하지만, 기존 프로젝트는 현재 시스템에서 출발한다는 점입니다.

즉 큰 변경을 다룰 때는 PRD를 만들기 전에 적어도 아래가 머릿속에 있어야 합니다.

• 현재 구조가 어떻게 되어 있는지
• 지금 문서와 실제 코드가 얼마나 맞는지
• 이번 변경이 어디까지 영향을 주는지
• 기존 규칙을 유지할지, 일부는 바꿀지

그래서 기존 프로젝트에서의 PRD는 “새 기능을 상상하는 문서”라기보다, “기존 시스템에 어떤 변화를 안전하게 넣을지 정리하는 문서”에 가깝습니다.

기존 코드가 깔끔하지 않아도 BMAD를 쓸 수 있을까요?#

이 질문도 공식 FAQ에 나옵니다.
답은 가능하다입니다.

공식 문서가 좋은 점은, BMAD가 무조건 현재 코드를 뜯어고치라고 강요하지 않는다는 점입니다.
Quick Flow는 기존 관습을 읽고, 그대로 따를지 아니면 새 기준을 세울지 묻는 방향으로 설명됩니다.

즉 선택지는 두 가지입니다.

• 현재 관습을 따라 일관성을 유지한다
• 새로운 기준을 세우되, 왜 그렇게 바꾸는지 문서에 남긴다

이건 중요한 태도입니다.
기존 프로젝트에서는 “베스트 프랙티스”보다 “현재 시스템과의 일관성”이 더 중요할 때가 많기 때문입니다.

즉 BMAD는 기존 코드가 완벽하지 않아도 쓸 수 있지만,
그 대신 무엇을 그대로 따르고 무엇을 바꿀지 문서로 더 분명히 남겨야 합니다.

실전 예시: 운영 중인 일정 관리 도구에 승인 기능 붙이기#

이번 시리즈에서 계속 써 온 내부 일정 관리 도구 예시를 그대로 이어 가겠습니다.
다만 이번에는 이 도구가 이미 운영 중인 상태라고 가정하겠습니다.

현재 상태는 이렇습니다.

• 일정 조회와 생성 기능은 이미 있습니다
• 관리자 화면도 일부 있습니다
• 문서는 오래돼서 현재 코드와 조금 안 맞습니다
• 이번에 넣고 싶은 건 “관리자 승인” 기능입니다

이 상황이라면 보통 이렇게 갑니다.

7편의 핵심은 기존 프로젝트에서는 먼저 현재 시스템을 읽어야 한다는 점입니다#

이 글에서 꼭 기억할 것은 다섯 가지입니다.

• 기존 프로젝트에서는 새 기능보다 먼저 현재 코드와 문서 상태를 파악해야 합니다
• 문서가 부실하면 bmad-document-project가 큰 도움이 됩니다
• project-context.md는 기존 코드베이스에서 특히 중요합니다
• 작은 변경은 Quick Flow로, 큰 변경은 BMad 정식 플로우로 가는 편이 안전합니다
• 기존 관습이 완벽하지 않아도, 무엇을 따르고 무엇을 바꿀지 문서로 남기면 BMAD를 잘 쓸 수 있습니다

6편이 story 단위 구현 흐름을 다뤘다면, 7편은 그 흐름을 기존 코드베이스에 붙일 때 무엇이 달라지는지를 설명하는 글입니다.
다음 글에서는 그보다 한 단계 더 나아가, BMAD를 더 깊게 쓰고 싶을 때 어떤 고급 기능들이 있는지 정리하겠습니다.