자율 개발 루프

bmad-build-auto는 표준 변경 사항 구현하기 모델에서 세션 하나에 들어오는 작업 단위 하나를 사람의 개입 없이 처리합니다. 호출 한 번으로 하나의 의도나 스토리를 명확히 하고 계획·구현·검토한 뒤, 사람이나 오케스트레이터가 후속 처리할 수 있는 종료 상태를 남깁니다.

Build Auto는 다음 스토리를 선택하거나 백로그 전체를 반복 실행하거나 에픽을 조율하거나 회고를 실행하지 않습니다. 자신이 실행하는 구현 작업과 새로 만들거나 이어서 쓰는 기록만 담당합니다. 백로그 정책과 작업 배정은 사람이나 AI 코딩 세션, bmad-loop 같은 오케스트레이터가 맡습니다.

하는 일

bmad-build-auto는 사람 개입 없는 구현 작업을 한 번 실행합니다.

1. 입력된 의도를 명확히 합니다
2. 사양 파일을 만들거나, 기존 파일을 찾아 이어서 진행합니다
3. 변경을 구현합니다
4. 결과를 리뷰합니다
5. 최종 상태를 사양 파일 또는 대체 결과 산출물에 기록해 실행을 마칩니다

전제 조건

실행 환경에서 하위 에이전트를 사용할 수 있어야 합니다. 그렇지 않으면 워크플로는 no subagents 조건과 blocked 상태로 멈춥니다. 여러 스토리를 조율하는 AI 코딩 세션은 스토리마다 Build Auto 작업자 하나를 시작해야 합니다. 각 작업자도 실행 중 필요한 검토 하위 에이전트를 직접 시작할 수 있어야 합니다.

버전 관리는 선택 사항이지만 사용을 강력히 권장합니다. 버전 관리를 사용한다면 작업 트리가 깨끗해야 합니다. 에이전트도 저장소 메타데이터를 갱신할 수 있어야 합니다.

입력

기본 호출 입력

기본 입력은 호출 프롬프트입니다. bmad-build-auto는 이 프롬프트를 완성된 구현 계획이 아닌 워크플로 입력으로 다룹니다.

의도는 다음과 같은 형태로 전달합니다.

• 짧은 자유 형식 변경 요청
• 티켓, 이슈 또는 스토리 식별자
• 의도 파일 경로
• 이 워크플로가 만든 기존 사양 파일 경로
• 특정 사양 파일 경로 없이 사양 폴더와 스토리 ID를 함께 전달하는 형태(폴더+ID 디스패치, 아래 참고)

재개 입력

호출이 기존 사양 파일을 가리키고 프런트매터에 알려진 status 값이 있으면, 워크플로는 해당 상태부터 재개합니다.

사양 상태	진입 지점
draft	계획
ready-for-dev	구현
in-progress	구현
in-review	리뷰
done	새로운 후속 검토로 다시 리뷰
blocked	즉시 중단

폴더+ID 디스패치

호출 프롬프트에 특정 사양 파일 경로 대신 사양 폴더와 스토리 ID를 전달할 수도 있습니다. 이때 호출자가 덧붙인 invoke_dev_with 지침 같은 나머지 프롬프트 텍스트는 작업 설명을 대체하지 않고 계획에 필요한 추가 컨텍스트로 전달됩니다.

워크플로는 <spec-folder>/stories.yaml을 읽고 id가 일치하는 항목을 찾은 뒤, 그 항목의 title과 description만 사용합니다. spec_checkpoint, done_checkpoint, invoke_dev_with는 디스패치를 요청한 호출자가 쓰는 필드이므로 파일에서는 읽지 않습니다.

그런 다음 <spec-folder>/stories/<story-id>-*.md를 ID 접두사로 확인해 첫 디스패치인지, 이어서 진행하는 상황인지 판단합니다.

디스크에서 찾은 항목	결과
없음	첫 디스패치입니다. <spec-folder>/SPEC.md가 있어야 합니다. 없으면 no epic spec found 조건으로 blocked에서 멈춥니다. SPEC.md와 동반 파일을 읽은 뒤 계획으로 진행합니다.
정확히 하나	해당 파일의 status에 따라 위 표와 같은 방식으로 재개합니다. 여기서 blocked 상태는 blocked spec supplied가 아니라 story already blocked 조건을 보고합니다. 호출자가 차단된 사양을 직접 넘긴 것이 아니라 build-auto가 ID로 파일을 찾았기 때문입니다. status가 없거나 인식할 수 없으면 unrecognized status in existing story file 조건과 blocked 상태로 멈춥니다.
둘 이상	ambiguous story file match 조건으로 blocked에서 멈춥니다.

blocked 상태의 스토리 파일은 영구 차단된 것으로 취급됩니다. 원인을 고친 뒤에도 같은 ID를 다시 디스패치하면 항상 story already blocked로 멈춥니다. 다시 시도하려면 스토리 파일을 삭제하세요. 그러면 해당 ID는 대기 상태로 돌아가고 다음 디스패치가 처음부터 시작됩니다.

계획 단계가 실행될 때마다 워크플로는 <spec-folder>/stories/*.md 패턴에 맞는 다른 스토리 파일도 모두 읽습니다. 첫 디스패치뿐 아니라 draft 상태에서 중단된 계획을 재개할 때도 마찬가지입니다. 각 파일의 Code Map, Design Notes, Spec Change Log, Tasks & Acceptance 체크리스트 상태, Auto Run Result 세부 내용을 추가 계획 컨텍스트로 가져옵니다. 이 덕분에 같은 폴더의 다른 스토리가 이미 결정하거나 만든 내용을 현재 계획에 반영할 수 있습니다. 계획 단계를 건너뛰는 재개 경로에서는 이 과정도 생략합니다.

한 번의 호출에서는 stories.yaml 항목 하나만 디스패치합니다. 결과와 관계없이 다른 항목을 읽거나 다른 스토리 ID로 넘어가지 않습니다.

사양 기반 에픽은 다음과 같은 공통 구조를 사용합니다.

<spec-folder>/
├── SPEC.md
├── stories.yaml
└── stories/
    ├── 1-<slug>.md
    ├── 2-<slug>.md
    └── ...

stories.yaml은 순서가 있는 스토리 목록입니다. Build와 Build Auto는 stories/ 아래의 Markdown 기록을 만들거나 기존 기록을 이어서 사용합니다. 각 기록은 프런트매터에 수명주기 상태를 저장합니다. 이후 워크플로는 어느 Build 스킬이 기록을 만들었는지에 기대지 않고 위치와 상태를 읽습니다.

오케스트레이션 선택지

아래 모든 선택지에서 Build Auto는 작업자입니다. 오케스트레이터가 작업 단위를 고르고 작업자 하나를 시작한 뒤, 결과를 읽어 다음 행동을 결정합니다.

bmad-loop로 순서가 지정된 목록 실행

선택 사항인 bmad-loop 오케스트레이터는 사양 폴더의 stories.yaml을 목록 순서대로 처리합니다. 의존성 그래프를 추론하지 않는 선형 스케줄러이므로 각 스토리의 선행 작업이 앞에 오도록 목록을 정렬해야 합니다.

스토리 하나를 선택하면 해당 스토리만 실행합니다. “여기서 시작해 나머지를 모두 실행”한다는 뜻이 아닙니다. 회고는 에픽을 마무리하는 별도 작업입니다. bmad-loop가 실행을 권할 수는 있지만 실제 회고는 bmad-retrospective가 수행합니다.

AI 코딩 세션을 오케스트레이터로 사용

AI 코딩 세션이 작업 단위마다 Build Auto 작업자 하나를 배정하고 결과의 근거를 확인할 수 있습니다. 구현 과정에서 상위 사양이나 스토리 목록이 더 이상 맞지 않는다는 사실이 드러나면 이후 작업도 수정할 수 있습니다. 이러한 수정이 상위 의도와 계속 일치하도록 관리하는 책임은 오케스트레이션 세션에 있습니다.

병렬 에픽 흐름 조율

프로젝트 수준의 병렬 실행에는 더 높은 조율 계층이나 에픽별 담당자가 필요합니다. 의존성과 통합 경계가 명확하다면 독립된 에픽 흐름을 병렬로 실행할 수 있습니다. bmad-loop의 순차 스토리 스케줄러는 이러한 프로젝트 수준 조율을 제공하지 않습니다.

컨텍스트 입력

활성화되면 워크플로는 다음 항목을 확인합니다.

• _bmad/config.toml, _bmad/config.user.toml, _bmad/custom/ 아래의 선택적 팀/사용자 오버라이드
• customize.toml, 팀 오버라이드, 사용자 오버라이드에 설정된 워크플로 커스터마이징
• 워크플로 설정에 나열된 지속 사실. 사용자가 따로 설정하지 않으면 비어 있으므로 기본적으로 이 단계에서 불러오는 내용은 없습니다

필요하면 다음도 참고합니다.

• BMAD 계획 산출물
• 에픽 기반 작업을 위해 캐시했거나 새로 취합한 에픽 컨텍스트 파일
• 같은 에픽에서 가장 최근에 완료된 이전 스토리 사양
• 폴더+ID 디스패치에서는 같은 사양 폴더 아래의 다른 stories/*.md 기록(위의 폴더+ID 디스패치 참고)

사양 상태

사양 프런트매터의 status는 오케스트레이터가 읽는 핵심 상태값입니다.

사양 상태	의미
draft	사양은 있지만 ready-for-dev 검증을 아직 통과하지 않았습니다
ready-for-dev	구현할 만큼 사양이 충분히 완성되었습니다
in-progress	구현이 진행 중입니다
in-review	리뷰 또는 분류가 진행 중입니다
done	워크플로가 성공적으로 완료되었습니다
blocked	사람 개입 없이 안전하게 계속할 수 없습니다

보류된 발견 사항

deferred는 실제 문제이지만 현재 스토리의 문제가 아닌 발견 사항을 보고하는 곳입니다. 각 항목에는 다음이 들어갑니다.

• summary — 보류된 문제를 한 문장으로 설명합니다
• evidence — 해당 발견 사항이 실제 문제인 근거입니다
• location — 선택 사항인 file:line 또는 컴포넌트 힌트입니다
• severity — 선택 사항인 최종 분류 심각도(high, medium, low)입니다

이 목록은 의도적으로 백로그 역할을 하지 않습니다. 기계가 읽을 수 있는 리뷰 결과일 뿐입니다. 티켓을 만들지, 중앙 대기열에 추가할지, 여러 실행에서 나온 중복을 식별할지, 아무것도 하지 않을지는 오케스트레이터가 결정해야 합니다.

ready-for-dev일 때

ready-for-dev는 보통 워크플로가 구현으로 넘어가며 통과하는 재개 상태입니다. 다만 호출 프롬프트가 계획 후 멈추라고 지시했다면 실제 중단 결과가 됩니다. 사양이 READY FOR DEVELOPMENT 관문을 통과하면 워크플로는 상태를 ready-for-dev로 설정하고 구현으로 넘어가지 않습니다. 같은 사양 또는 같은 사양 폴더와 스토리 ID를 다시 디스패치하면 위 라우팅에 따라 구현부터 재개합니다.

done일 때

성공적으로 완료되면 워크플로는 사양에 다음을 작성하거나 갱신합니다.

• 최종 status: done
• 다음 내용을 담은 Auto Run Result 섹션
  • 구현한 변경 요약
  • 변경된 파일
  • 리뷰 발견 사항 분류
  • 수행한 검증
  • 남은 위험
• followup_review_recommended 플래그. LLM이 추가 검토가 유용하다고 판단하면 true가 됩니다. 의무가 아니라 제안입니다. 같은 사양 파일을 가리켜 스킬을 다시 실행하는 것이 두 번째 검토를 시작하는 가장 간단한 방법입니다.
• baseline_revision — 구현 전 기준이 되는 전체 리비전입니다. 버전 관리가 없으면 NO_VCS입니다.
• 리뷰에서 defer로 분류한 발견 사항을 담은 프런트매터 deferred 항목입니다. 각 항목에는 summary, evidence, 가능한 경우 location과 severity가 기록됩니다.

워크플로는 커밋하지만 push하지는 않습니다. 종료 시 작업 트리는 깨끗합니다.

blocked일 때

차단 상태로 끝나면 워크플로는 다음을 작성합니다.

• 사양이 있으면 최종 status: blocked
• 차단 조건
• 사양 또는 대체 결과 산출물의 관련 세부 정보

대표적인 차단 조건은 다음과 같습니다.

• unclear intent
• intent gap
• no subagents
• missing spec_file before implementation
• implementation verification failed
• review repair loop exceeded 5 iterations (non-convergence)
• blocked spec supplied(직접 호출한 사양 파일이 이미 status: blocked였던 경우)
• no stories.yaml found
• story id not found in stories.yaml
• no epic spec found
• ambiguous story file match
• unrecognized status in existing story file
• story already blocked(폴더+ID 디스패치 전용. 위의 blocked spec supplied와 다릅니다)

intent gap은 실행 중 마주친 질문에 기록된 의도만으로 답할 수 없는 상태입니다. 코드가 아직 없는 계획 단계나 리뷰 단계에서 멈출 수 있습니다. 리뷰 중 이 조건으로 멈추면 작업 트리를 평소처럼 되돌립니다. 다만 시도했던 변경은 먼저 {implementation_artifacts} 아래의 패치 파일로 저장하고 사양의 분류 기록과 중단 출력에 경로를 기록합니다. 이 패치는 워크플로가 의도를 어떻게 해석해 구현했는지 보여 주는 구체적인 근거입니다. 그 해석이 맞다면 git apply로 패치를 적용하고 사양 상태를 in-review로 바꾸세요. 처음부터 다시 실행하지 않고 해당 변경의 리뷰를 이어갈 수 있습니다.

출력 산출물

워크플로는 실행 결과를 나중에도 확인할 수 있는 산출물로 남깁니다.

기본 사양 산출물

새 작업에서는 다음을 만듭니다.

{implementation_artifacts}/spec-<slug>.md

이 사양은 계획, 구현, 리뷰를 잇는 계약으로 다음 내용을 담습니다.

• 프런트매터 상태
• 프런트매터의 기계 상태(followup_review_recommended, warnings, deferred, 리비전 표시)
• 수정할 수 없는 <intent-contract> 블록
• 코드 맵
• 작업과 인수 기준
• 사양 변경 기록
• 리뷰 분류 기록
• 검증 메모

스토리 사양 산출물(폴더+ID 디스패치)

폴더+ID 디스패치에서는 기본 사양 또는 대체 결과 경로 대신 <spec-folder>/stories/<story-id>-<slug>.md에 씁니다. 계획이 시작되기 전에 멈추는 경우도 여기에 포함됩니다. 이 모드에서는 아래의 대체 결과 산출물을 사용하지 않습니다.

스토리 제목에서 slug를 만들기 전에 멈추면 쓰기 경로에 고정된 slug 조각을 사용합니다.

상황	사용하는 slug 조각
stories.yaml이 없거나 파싱할 수 없거나, 일치하는 항목이 없음	unresolved
이미 디스크에 <story-id>-*.md와 일치하는 파일이 둘 이상 있음	ambiguous
항목을 찾았고 디스크의 파일 일치가 모호하지 않음	title에서 만든 slug. 필요하면 description도 사용

결정된 경로에 파일이 이미 있으면 워크플로는 프런트매터의 status를 갱신합니다. 기본 사양 산출물과 마찬가지로 ## Auto Run Result 아래에 결과도 덧붙입니다. 파일이 없으면 최소 구성의 스토리 사양을 만듭니다. 이 파일에는 프런트매터 상태, 제목, ## Auto Run Result 섹션이 들어갑니다. 제목은 해당 항목의 title을 사용합니다. 항목을 찾을 수 없거나 디스크의 파일 일치가 모호하면 Story <story_id>를 사용합니다.

대체 결과 산출물

폴더+ID 디스패치가 아닌 경로에서 유효한 spec_file이 생기기 전에 워크플로가 멈추면 다음 파일을 씁니다.

{implementation_artifacts}/bmad-build-auto-result-<slug-or-timestamp>.md

여기에는 최종 상태와 차단 조건이 기록됩니다.

추가 산출물

경로에 따라 워크플로가 다음도 쓸 수 있습니다.

• {implementation_artifacts}/epic-<N>-context.md
• 리뷰 단계가 intent gap으로 멈출 때 시도했던 변경을 보존한 패치 파일(사양의 분류 기록에 경로 기록)

오케스트레이터 책임

bmad-build-auto를 통합하는 오케스트레이터는 다음을 해야 합니다.

• 한 번에 하나의 일관된 의도를 전달합니다
• 이전 작업을 재개할 때는 사양 경로를 직접 전달하는 방식을 우선합니다. 폴더+ID 디스패치라면 같은 사양 폴더와 스토리 ID를 전달합니다
• 생성된 사양 파일, 스토리 사양 산출물 또는 대체 결과 파일에서 최종 상태를 확인합니다
• 채팅 출력만 보고 성공을 추정하지 말고 status, blocking condition, followup_review_recommended를 읽습니다
• 사양 프런트매터의 deferred: 목록에서 보류된 발견 사항을 읽습니다
• 다음 스토리가 있다면 baseline_revision..<next story's baseline_revision>, 아직 없다면 종료 시점의 baseline_revision..HEAD로 해당 스토리의 커밋을 식별합니다
• 자율 실행으로 파일 변경과 로컬 커밋이 생길 수 있음을 예상합니다
• blocked를 단순 실패가 아니라 라우팅 신호로 처리합니다

blocked는 대개 워크플로가 사람 개입 없이 계속하기에는 안전하지 않은 상황을 만났다는 뜻입니다. 이때는 상위 오케스트레이터나 다른 워크플로, 또는 사람이 이어받는 편이 적절합니다.

차단 원인을 해결한 뒤에는 보통 bmad-build-auto를 새로 실행해야 합니다. 기존 작업을 재사용하려면 자동 탐색에 기대지 말고 검증된 사양 경로를 명시적으로 전달하세요.