변경 사항 둘러보기

bmad-walkthrough는 완성된 변경을 목적과 컨텍스트부터 세부 사항까지 차례로 안내합니다. 사용자는 설명을 따라가며 승인할지, 다시 작업할지, 더 논의할지를 결정할 수 있습니다. 전체 실행 과정은 bmad-walkthrough 실행하기에서 확인하세요.

이 스킬의 목적은 사람이 변경을 이해하도록 돕는 것입니다. bmad-build가 이미 수행한 리뷰나 bmad-code-review를 대신하지 않습니다.

사용 시점

가장 일반적인 사용 시점은 bmad-build가 끝난 직후입니다. 구현이 완료되고 리뷰 경로가 추가된 사양 파일이 열리면 출시 여부를 결정해야 합니다. 이때 “walkthrough”라고 말하면 됩니다.

Build는 사람의 개입을 줄인 채 오래 실행됩니다. Walkthrough에서는 사용자가 다시 운전대를 잡습니다. diff를 눈으로 훑을 수도 있지만 변경이 여러 파일에 걸치면 흐름을 놓치거나, 서로 떨어진 변경의 연결을 지나치거나, 충분히 이해하지 못한 채 승인할 수 있습니다. 원본 diff는 Git의 파일 순서로 내용을 보여주는데, 이 순서는 이해가 쌓이는 순서와 거의 일치하지 않습니다.

단독으로도 사용할 수 있습니다.

• PR 리뷰 - 특히 파일 수가 많거나 여러 영역에 걸친 변경을 검토할 때
• 변경 내용 파악 - 직접 작성하지 않은 브랜치에서 무슨 일이 있었는지 이해할 때
• 스프린트 리뷰 - 스프린트 상태 파일에서 review로 표시된 스토리를 찾아볼 때

“walkthrough” 또는 “이 변경을 따라가며 설명해 줘”라고 말해 실행하세요. 어떤 터미널에서도 작동하지만 VS Code나 Cursor 같은 IDE 안에서 사용하면 더 편리합니다. 각 단계에 path:line 참조가 표시되며 IDE 내장 터미널에서는 이 참조를 클릭할 수 있습니다.

bmad-walkthrough 실행하기

bmad-build가 끝난 뒤 같은 채팅에서 “walkthrough”라고 말하세요. 다른 변경을 검토하려면 새 채팅을 열고 /bmad-walkthrough에 PR, 브랜치, 사양 경로 또는 현재 Git 상태를 전달합니다.

walkthrough

/bmad-walkthrough https://github.com/org/repo/pull/42를 검토해 줘.

워크플로는 다섯 단계로 진행됩니다. 각 단계는 이전 단계에서 이해한 내용을 바탕으로 “무엇이 바뀌었나?”에서 “출시해도 되는가?”로 초점을 옮깁니다. 스킬은 diff와 사양이 있다면 해당 사양, 주변 코드베이스를 읽고 git diff의 파일 순서가 아닌 이해하기 좋은 순서로 변경을 보여줍니다.

1. 방향 잡기

워크플로는 PR, 커밋, 브랜치, 사양 파일 또는 현재 Git 상태에서 변경 대상을 식별합니다. 그런 다음 한 줄로 의도를 요약하고 변경 파일 수, 영향을 받은 모듈, 논리 코드 줄 수, 경계를 넘는 변경, 새 공개 인터페이스 같은 영향 범위 통계를 보여줍니다.

이 단계에서는 “내가 보려던 변경이 맞나?”를 확인합니다. 코드를 읽기 전에 올바른 대상을 보고 있는지 확인하고 예상 범위와 맞는지 가늠하세요.

2. 둘러보기

변경은 파일이 아니라 관심사를 기준으로 묶습니다. 관심사는 “입력 검증”이나 “API 계약”처럼 서로 밀접하게 연결된 설계 의도입니다. 각 관심사에는 이 접근 방식을 선택한 이유와 코드에서 따라갈 수 있는 path:line 지점이 붙습니다.

이 단계에서는 코드가 정확한지가 아니라 해당 접근 방식이 시스템에 적합한지를 판단합니다. 관심사는 가장 높은 수준의 의도부터 보조 구현까지 하향식으로 제시됩니다. 아직 살펴보지 않은 내용을 먼저 참조하지 않습니다.

3. 상세 검토

설계를 이해한 뒤에는 잘못됐을 때 영향이 가장 큰 지점 2~5개를 보여줍니다. [auth], [schema], [billing], [public API], [security] 같은 위험 범주를 붙이고 문제가 생겼을 때 영향이 큰 순서로 정렬합니다.

이 단계는 버그 찾기가 아닙니다. 자동화 테스트와 CI가 정확성을 검사합니다. 상세 검토에서는 잘못됐을 때 비용이 큰 지점을 파악합니다. 특정 영역을 더 깊게 살펴보려면 “이 영역을 더 파고들어 줘”라고 말해 정확성에 초점을 맞춘 재검토를 요청할 수 있습니다.

독립 에이전트가 이미 사양을 검토했다면 관련 발견 사항도 이 단계에 나타납니다. 이미 수정된 버그가 아니라 사용자가 알아야 한다고 표시된 결정 사항을 보여줍니다.

4. 테스트

변경이 작동하는 모습을 수동으로 확인할 방법 2~5개를 제안합니다. 자동화 테스트 명령이 아니라 테스트 모음만으로 얻기 어려운 확신을 주는 관찰 방법입니다. 시도할 UI 동작, 실행할 CLI 명령, 보낼 API 요청과 각각의 예상 결과가 포함됩니다.

사용자에게 보이는 동작이 없다면 그렇다고 알려줍니다. 불필요한 확인 작업을 만들지 않습니다.

5. 마무리

승인, 재작업, 추가 논의 중 하나를 선택합니다. 로컬 bmad-build 결과를 승인한다면 푸시할 준비가 된 것입니다. 에이전트가 푸시와 PR 생성을 도울 수 있습니다. PR을 승인할 때는 gh pr review --approve 실행을 도울 수 있습니다. 재작업을 선택하면 문제가 접근 방식, 사양, 구현 중 어디에서 시작됐는지 진단하고 구체적인 코드 위치에 연결된 피드백을 작성하도록 돕습니다.

보고서가 아닌 대화

워크플로는 각 단계를 최종 답이 아닌 대화의 출발점으로 제시합니다. 단계 사이 또는 도중에도 LLM과 대화하고 질문하거나 구성 방식에 이의를 제기할 수 있습니다. 다른 스킬을 불러 새로운 관점에서 살펴볼 수도 있습니다.

• “오류 처리를 고급 도출로 다시 검토해 줘” - 특정 영역의 분석을 다시 생각하고 다듬습니다.
• “이 스키마 마이그레이션이 안전한지 파티 모드로 토론해 줘” - 여러 에이전트의 관점으로 집중 토론을 진행합니다.
• “코드 리뷰를 실행해 줘” - 적대적 검토와 엣지 케이스 분석을 포함한 구조화된 발견 사항을 생성합니다.

Walkthrough는 사용자를 정해진 순서에 가두지 않습니다. 구조가 필요할 때는 안내를 제공하고 더 깊이 탐색할 때는 자유롭게 대화할 수 있습니다. 다섯 단계는 전체 그림을 빠뜨리지 않도록 돕지만 각 단계에서 얼마나 깊게 살펴볼지와 어떤 도구를 사용할지는 사용자가 결정합니다.

리뷰 경로

둘러보기 단계는 권장 리뷰 순서가 있을 때 가장 잘 작동합니다. 사양 작성자가 변경 내용을 안내하려고 남긴 지점 목록입니다. 사양에 이 목록이 있다면 워크플로가 그대로 사용합니다.

작성자가 만든 경로가 없다면 워크플로가 diff와 코드베이스 컨텍스트를 바탕으로 생성합니다. 자동으로 만든 경로는 작성자가 직접 구성한 것보다 품질이 낮지만 파일 순서대로 변경을 읽는 것보다는 훨씬 낫습니다.

하지 않는 일

bmad-walkthrough는 리뷰 스킬이 아닙니다. bmad-build가 이미 수행한 리뷰, 완료된 스토리에서 같은 실행을 다시 호출하는 작업, bmad-code-review를 대신하지 않습니다. 린터, 타입 검사기, 테스트 모음을 실행하지 않으며 심각도 점수나 통과·실패 판정도 만들지 않습니다. 사람이 중요한 곳에 판단을 집중하도록 돕는 읽기 안내서입니다.