BMAD 커스텀 설치 도구 — 리뷰 3단계·CI/CD 규칙·플랫폼 비고정 설계

프로젝트마다 AI 개발 규칙이 달라 같은 사고(검사 미실행, 테스트 문자 실발송)가 반복됐다. 기존 4개 프로젝트의 CI/CD·리뷰 규칙을 BMAD와 대조해 리뷰 3단계와 고객 보호 규칙을 정하고 시나리오 시험 42회로 검증한 뒤, 명령 한 번으로 까는 설치 도구와 배포 플랫폼을 고정하지 않는 2차 설계까지 만들었다.

문제

• BMAD는 내 컴퓨터에 커밋하는 데까지만 책임진다. PR·테스트·배포는 개인 규칙 영역인데 강제 장치는 배포 직전에만 몰려 있었다
• 한 서비스는 main에 머지된 뒤에야 테스트가 돌아, 테스트 1개 실패로 "머지는 됐는데 배포는 안 된" 상태가 하루 지속됐다
• 개발 중 테스트 문자가 실제 고객에게 발송된 사고가 있었다
• 리뷰 강도가 설정 한 줄로 고정돼 문구 1줄 수정에도 리뷰어 4명이 약 2.5분씩 돌았다
• 규칙이 문서·설정·시험 기록 여러 곳에 흩어져 새 프로젝트마다 손으로 옮겨야 했다

육하원칙

누가	필자 + Claude (Cowork에서 설계·문서·설치 도구, 로컬 Claude Code에서 시험 실행)
언제	2026-10-03 오후 ~ 10-04
어디서	개인 설정 저장소(dev-system), BMAD 시험용 샌드박스, 기존 프로젝트 4곳
무엇을	리뷰 3단계 · 고객 보호 최우선 규칙 · 설치 도구 1차 · GitHub 쪽 2차 설계
왜	검사가 있는데 안 돌아서 생긴 사고를 막고, 규칙을 모든 프로젝트에 똑같이 적용하려고
어떻게	기존 규칙 추출 → BMAD와 대조 → BMAD 공식 조정 방식으로 반영 → 시나리오 반복 시험 → 설치 도구로 묶기

단계별 진행과 결과물

#	단계	한 일	결과물
1	규칙 추출·대조	프로젝트 4곳의 브랜치·테스트·리뷰·배포 규칙을 뽑아 BMAD가 다루는 범위와 비교	CI/CD 검토 문서(규칙 인벤토리, 배치표, 결정 현황)
2	리뷰 도구 비교	기존 분야별 리뷰 패널(보안·데이터·회귀) vs BMAD 코드 리뷰(방법별 렌즈·지적 검증·기록)	합치는 방향 결정: 분야 렌즈 + BMAD 방법 렌즈, 검증·기록은 BMAD 방식
3	리뷰 3단계	없음 0명 / 기본 2명 / 안정 4명(+보안·데이터 1명)을 BMAD 설정만으로 구현	조정 파일 + 시험 9/9, 재확인 9/9
4	고객 보호 규칙	운영 DB ≠ 개발·프리뷰 DB, 개인정보 가짜 값, 비운영 환경 발송 차단을 3겹으로 설계	최우선 규칙 S1 (구현은 3차)
5	설치 도구 1차	BMAD 고정 설치 + 조정 + 원칙 문서 + 위험 명령 차단 + 개발 시작 체크리스트	설치 스크립트, 단위 테스트 9/9, 실제 설치 확인
6	2차 설계	PR 이후 흐름, 리뷰 깊이 라벨, 실패 알림, 배포 어댑터	2차 계획 문서 (구현 전)

무엇이 어디로 깔리나

flowchart LR
  subgraph DS["개인 설정 저장소 (원본은 여기 한 곳)"]
    T1["조정 파일 원본<br>bmad-build / bmad-prd"]
    T2["원칙 문서<br>아키텍처 적정 규모"]
    T3["위험 명령 차단 목록"]
    B["BMAD 검증 커밋 고정"]
  end
  subgraph P["새 프로젝트"]
    P0["BMAD 본체"]
    P1["_bmad/custom/<br>모드·리뷰 3단계·lint / 분석 확인 게이트"]
    P2["docs/dev-system/ 원칙 문서"]
    P3[".claude/settings.json<br>차단 목록 병합"]
    P4["설치 도장<br>어떤 버전이 깔렸나"]
  end
  B --> P0
  T1 --> P1
  T2 --> P2
  T3 --> P3
  P1 -. "file: 로 읽음" .-> P2

PR 이후 (2차 설계)

flowchart LR
  A["브랜치 push + PR"] --> B["공통 CI"]
  B --> B1["타입 검사 ✋"]
  B --> B2["테스트 ✋<br>DB 없는 것만"]
  B --> B3["lint 📝 보고만"]
  A --> C["리뷰 깊이 라벨"]
  A --> D["Claude 자동 리뷰"]
  A --> E["배포 어댑터<br>프리뷰 확인 📝"]
  B1 --> F{"✋ 통과?"}
  B2 --> F
  F -- 아니오 --> X["머지 막힘 + 실패 알림"]
  F -- 예 --> H["사람이 보고 직접 머지"]
  C --> H
  D --> H
  E --> H

배포 플랫폼을 고정하지 않는 구조

flowchart TB
  CORE["공통: 브랜치 규칙 · CI · 리뷰 (플랫폼 무관)"] --> P{"deploy.target"}
  P -- vercel --> V["Vercel 어댑터<br>프리뷰·운영 응답 확인, 환경변수 분리 점검"]
  P -- "ssh 서버 (보류)" --> H["SSH 어댑터<br>배포·스테이징·롤백"]
  P -- none --> N["배포 없음"]

핵심 발견

1. BMAD의 구조 변경이 조용히 조정을 무력화한다. 공식 태그(v6.12.0)는 이후 버전과 설정 키 이름이 달라, 같은 조정 파일이 오류 없이 무시된다 → 태그가 아니라 검증한 커밋으로 고정
2. "0명"은 설정으로 만들 수 없었다. BMAD는 리뷰어가 0명이면 멈춘다 → "정책상 생략"만 보고하는 빈 리뷰어로 채움. 문서만 보고는 몰랐고 렌더링 결과를 직접 읽어서 발견
3. 좁힌 규칙이 망설임을 없앴다. "정산" 한 단어 때문에 화면 문구 수정도 매번 "안정인가?"를 따지던 것이, "정산 계산·데이터"로 좁히자 즉시 판단. 필요한 안정 판단(부분환불 등)은 그대로 유지

AI 빌더 관점

관점	이번 작업에서	근거	상태
워크플로 재설계	리뷰: "매번 사람이 강도를 정해 손으로 여러 회 요청" → "변경 성격에 따라 자동으로 0·2·4(+1)명, 사람은 머지 판단만". 새 프로젝트: 규칙 손 복사 → 명령 한 번 설치	리뷰 3단계 시험 18/18, 설치 도구 실제 설치 확인	구현·검증
생산성·효율 개선	문구·스타일 변경의 리뷰 비용 제거, 일반 기능은 4명 → 2명	문구 1줄 수정: 리뷰어 4명·약 2.5분 → 0명 (시험 6/6)	구현·검증
병목 해소 시스템	① "머지는 됐는데 배포는 안 됨" → 테스트를 PR 단계로 당기고 실패 시 머지 차단·알림 ② 규칙이 여러 곳에 흩어져 사람 기억에 의존 → 원본 한 곳 + 설치 도장 + 체크리스트	① 과거 하루 배포 정지 사례 ② 프로젝트 4곳 규칙 차이 조사	① 설계(2차) ② 구현
(추가) 검증 가능하게 만들기	"약하게 리뷰하면 실패, 세게는 허용"처럼 사람이 정한 기준으로 AI의 판단을 반복 측정	시나리오 시험 42회, 단위 테스트 9개	완료
(추가) 안전·통제	AI가 틀려도 사고가 나지 않게: 고객 보호 3겹, 위험 명령 차단, 덮어쓰기 금지·백업, 머지는 사람	차단 목록 20개, 보호 동작 테스트 3개	일부 구현 (고객 보호 코드는 3차)
(추가) 재사용·자산화	한 번 만든 규칙이 모든 프로젝트로 퍼지고, 배포 플랫폼이 바뀌어도 어댑터 하나만 교체	설치 도구 1차, 어댑터 설계	1차 구현 · 어댑터 설계

다음 단계

• 2차 구현: GitHub 인증이 있는 로컬 Claude Code에서 테스트 저장소로 단계별 진행 (공통 CI부터)
• 첫 실제 프로젝트에 설치해 긴 대화 후에도 규칙이 유지되는지 확인
• 3차: 고객 보호 가드 코드 (서비스별)
• 블로그 글: 블로그용 자료 기반

자료

1) 블로그용 정리 (HTML · PDF)

embed

설치 도구 정리 — 블로그용 (PDF)

2) 원본

• 회사·서비스 이름이 들어간 내용과 원본 HTML·PDF는 같은 DB의 "[원본]" 항목에 있음 (비공개)