변경 사항 구현하기

핵심 구현 스킬은 bmad-build입니다. 한 문장, 이슈, 사양, 계획이 끝난 스토리처럼 원하는 작업을 어떤 형태로든 전달할 수 있습니다. 스킬은 코드베이스와 상위 컨텍스트를 조사하고 변경을 계획·구현한 뒤, 결과를 검토하고 발견한 버그를 수정합니다. 전체 실행 과정은 bmad-build 실행하기에서 확인하세요.

작업 규모 정하기

변경 사항을 안전하게 처리할 수 있는 가장 간단한 BMad 경로를 선택하세요. 일반적인 세션은 하나의 목표를 다룹니다. 테스트를 제외하고 약 500줄의 코드를 추가하거나 수정하며 대상 파일도 몇 개 정도인 작업입니다. 이 범위에 들어오면 bmad-build에 맡기세요. 더 크다면 먼저 작업을 계획해야 합니다. 개발 경로 선택하기를 참고하세요. 시작하기 전에는 규모를 판단하기 어려울 수 있으므로 확신이 없다면 bmad-help에 물어보세요.

직접 검토해도 되는 단순한 편집은 이 과정을 건너뛰고 에이전트에게 바로 요청해도 됩니다. 다만 버그가 프로덕션에 반영될 가능성이 있다면 bmad-build를 사용하는 편이 안전합니다.

`bmad-build` 실행하기

bmad-build 워크플로 다이어그램

1. 새 채팅 시작

AI IDE에서 새 채팅을 여세요. 다른 워크플로에서 사용하던 세션을 재사용하면 컨텍스트가 섞여 실행에 혼란을 줄 수 있습니다.

2. 의도 전달

명령 전후나 명령과 함께 변경 내용을 설명할 수 있습니다. 깔끔하게 정리할 필요는 없습니다. 두서없는 설명, 음성으로 풀어낸 생각, 아직 구체화되지 않은 아이디어, 이슈 링크, 파일, 계획된 스토리 등 모델이 구체적인 목표로 바꿀 수 있는 형식이면 됩니다.

/bmad-build 빈 비밀번호를 허용하는 로그인 검증 버그를 수정해 줘.

/bmad-build https://github.com/org/repo/issues/42 이슈를 수정해 줘.

/bmad-build _bmad-output/implementation-artifacts/my-intent.md에 적힌 의도를 구현해 줘.

문제는 인증 미들웨어에 있는 것 같아. 토큰 만료를 확인하지 않고 있어.
살펴보니 src/auth/middleware.ts의 47번째 줄에서
exp 검사를 완전히 건너뛰고 있어. /bmad-build

/bmad-build
> 어떤 작업을 할까요?
콜백 대신 async/await를 사용하도록 UserService를 리팩터링해 줘.

3. 근거를 확인해 의도 확정

bmad-build는 사용자의 요청에서 출발해 코드베이스와 상위 계획 산출물을 조사합니다. 그런 다음 결정에 필요한 중요한 정보가 빠졌는지 판단합니다. 처음 요청이 거칠어도 근거가 충분하고 명확하다면 별도의 명확화 단계 없이 진행합니다. 불분명한 내용이 있으면 먼저 근거를 찾습니다. 저장소와 계획 컨텍스트로도 판단할 수 없는 사항만 완성된 설계의 미결 질문으로 남습니다. 작업을 시작하기도 전에 긴 인터뷰를 진행하지 않습니다.

미결 질문이 나오면 신중하게 답하세요. 이 단계의 잘못된 판단은 나중에 발견할수록 수정 비용이 큽니다.

4. 요청이 나오면 계획 승인

조사가 끝나면 bmad-build는 가장 간단하면서도 안전한 경로를 선택합니다. 확정된 설계를 기준으로 의도 누락, 되돌릴 수 없는 작업, 영향 범위라는 세 가지 정보를 보고합니다. 의도 누락이 없고 되돌릴 수 없는 작업도 없으며 영향 범위가 작다면 간단한 경로로 진행합니다. 같은 세션에서 최소 사양을 작성하고 구현한 뒤 결과를 검토합니다. 하나라도 문제가 있으면 먼저 상세 계획을 작성합니다. 의도 누락은 미결 질문으로 기록되며 사용자가 답한 뒤에야 계획을 승인할 수 있습니다.

계획이 올바른 결과를 설명한다면 승인하세요. 그렇지 않다면 수정을 요청하세요. 코드를 고치는 것보다 계획을 고치는 편이 훨씬 저렴합니다.

5. 구현 및 검토

경로가 정해지면 bmad-build가 변경을 구현하고 독립된 리뷰어로 작업을 검토합니다. 현재 변경에 속하는 문제를 수정한 뒤 로컬에 커밋합니다. 이 과정은 하위 에이전트를 생성할 수 있거나 적어도 명령줄에서 다른 모델을 호출하고 결과를 기다릴 수 있는 플랫폼에서 가장 잘 작동합니다.

리뷰는 가능한 의견을 모두 쏟아내는 과정이 아니라 분류 작업입니다. 현재 변경 때문에 생긴 문제는 고치고 관련 없는 기존 문제는 보류합니다. 계획이 약해 코드가 잘못됐다면 계획 단계로, 목표가 잘못돼 계획까지 어긋났다면 목표 단계로 돌아갑니다. diff만 임시로 고치지 않고 문제가 시작된 계층부터 다시 생성합니다.

6. 결과 검토

작업이 끝나면 bmad-build가 완성된 변경 사항과 리뷰 기록을 보여줍니다. 이때가 주요 체크포인트입니다. 완성된 작업을 안내에 따라 살펴보려면 변경 사항 둘러보기를 참고하세요.

diff를 훑어 변경이 의도와 맞는지 확인합니다.
이상한 점이 있으면 에이전트에게 수정할 내용을 말하세요. 같은 세션에서 작업을 이어갈 수 있습니다.

결과가 만족스러우면 커밋을 푸시하세요. 스킬이 푸시와 PR 생성을 제안할 수도 있습니다.

얻는 결과

변경 사항이 반영된 소스 파일
프로젝트에 테스트 모음이 있다면 통과하는 테스트
Conventional Commit 형식의 푸시 준비 완료 커밋
실행에 대한 구현 기록. 상위 사양이나 스토리가 있다면 그 옆에 저장됩니다.

완성된 작업에 API 및 E2E 테스트를 추가하려면 완료된 작업 테스트하기를 참고하세요.

보류 작업

bmad-build는 실행마다 하나의 목표에 집중합니다. 요청에 여러 독립 목표가 있거나 리뷰에서 현재 변경과 관련 없는 기존 문제가 드러나면, 모두 한꺼번에 처리하지 않고 구현 산출물 디렉터리의 deferred-work.md에 기록합니다.

실행 후 이 파일을 확인하세요. 나중에 처리할 후속 작업의 백로그입니다. 각 항목은 새 bmad-build 실행에 다시 전달할 수 있습니다.

먼저 계획해야 할 때

다음과 같은 경우에는 bmad-build를 실행하기 전에 사양을 추가하거나 PRD, UX, 아키텍처, 스토리를 계획하세요.

여러 시스템에 영향을 주거나 많은 파일을 함께 수정해야 할 때
범위가 불분명해 먼저 요구사항을 구체화해야 할 때
팀이 참고할 문서나 아키텍처 결정을 남겨야 할 때
의도를 명확히 하는 과정에서 한 세션 안에 풀기 어려운 모순이 계속 드러날 때

큰 작업은 한 세션 단위의 변경 여러 개로 나뉩니다. 구현하면서 새로 알게 된 내용에 따라 작업 순서가 바뀔 수도 있습니다. 상위 사양은 공동 목표를 유지하고 스토리 기록은 결정 사항과 완료 상태를 전달합니다. 통합 검사와 회고는 전체 결과를 확인합니다. bmad-build는 이 중 한 단위만 담당하며 백로그를 관리하거나 다음 스토리를 선택하거나 이후 검사를 대신하지 않습니다.

기반을 만들거나 위험도가 높거나 이후 작업의 패턴을 정하는 중요한 스토리에는 bmad-build를 사용하세요. 패턴이 안정된 뒤에는 bmad-build-auto로 사람을 기다리지 않고 한 단위를 실행할 수 있습니다. 자율 개발 루프를 참고하세요.

이런 방식으로 작동하는 이유

LLM은 중요해 보이는 것은 찾을 수 있지만 실제로 무엇이 중요한지는 알지 못합니다. 사람의 주의가 전혀 없으면 작업 흐름은 금세 무너집니다.

추론에 10분을 쓰는 편이 사람의 주의를 10초 빼앗는 것보다 대체로 저렴합니다. 모든 단계를 직접 지켜보면 계속 진행하라는 응답만 반복하게 됩니다. 불필요하고 지루한 데다 사용자가 병목이 됩니다.

bmad-build는 단순히 계속 진행할지 판단하는 일을 기계에 맡깁니다. 사용자의 주의는 근거로 해결할 수 없는 미결 질문, 상세 경로의 계획 승인, 완성된 변경 검토처럼 꼭 필요한 순간에만 사용합니다. 안전하게 결정하지 못했을 때만 사용자를 다시 부릅니다. 이 분류가 언제나 완벽하지는 않습니다. 그래도 가치가 낮은 발견 사항을 놓치는 편이 수많은 잡음으로 사용자를 압도하는 것보다 낫습니다.