9.2 KiB
| title | description | sidebar | ||
|---|---|---|---|---|
| 포렌식 조사 | bmad-investigate가 모든 이슈를 현장처럼 다루고, 증거를 등급화하며, 엔지니어가 바로 행동할 수 있는 구조화된 사례 파일을 만드는 방법 |
|
bmad-investigate에 충돌 로그, 스택 추적, 또는 단순히 "예전엔 됐는데 지금은 안 돼요"를 건네면, 스킬은 실행되는 동안 조사자의 규율을 적용합니다. 바로 고치기 시작하지 않습니다. 사례 파일을 엽니다.
모든 발견 사항은 등급이 매겨집니다. 모든 가설은 상태를 가집니다. 잘못된 방향도 지우지 않고 남깁니다. 산출물은 다른 엔지니어가 아무 배경 없이 집어 들어도 이해할 수 있는 문서입니다.
이 페이지는 조사가 왜 별도의 규율인지, 그리고 일반 개발 워크플로가 주지 못하는 것을 이 스킬이 어떤 방식으로 제공하는지 설명합니다.
"그냥 디버깅해"의 문제
일반 디버깅은 세 가지를 섞습니다. 증거를 보고, 원인을 추론하고, 이론을 시험하기 위해 코드를 바꿉니다. 이것들이 섞이면 두 가지 실패 모드가 나타납니다.
첫 번째는 서사 고착입니다. 처음 그럴듯한 이야기가 작업 가설이 되고, 모든 관찰이 거기에 맞춰 끼워집니다. 누군가 포기하고 처음부터 다시 시작할 때까지 버그는 고쳐지지 않습니다. 몇 시간 뒤에야 말입니다.
두 번째는 증거 망각입니다. 무언가를 추적하고 배제했지만 왜 배제했는지 적지 않았습니다. 이틀 뒤 새로운 눈으로 같은 것을 다시 추적합니다. 더 나쁘게는 동료가 버그를 넘겨받아 이미 제거한 막다른 경로를 다시 실행합니다.
이 스킬의 설계는 이 둘에 대한 직접적인 응답입니다.
증거 등급화
조사의 모든 발견 사항은 세 가지 중 하나입니다.
- Confirmed(확인됨). 로그, 코드, 덤프에서 직접 관찰되었고 특정 참조(
path:line, 로그 타임스탬프, 커밋 해시)로 인용됩니다. 누군가 "어떻게 알아?"라고 물으면 인용을 가리킵니다. - Deduced(추론됨). 확인된 증거에서 논리적으로 따릅니다. 추론 사슬이 표시됩니다. 사슬의 한 단계가 틀리면 추론도 틀리고, 어느 단계인지 볼 수 있습니다.
- Hypothesized(가설). 그럴듯하지만 확인되지 않았습니다. 무엇이 확인하거나 반박할지와 무엇이 닫을지를 미리 선언합니다. 가설은 명시적으로 사실이 아닙니다.
등급화는 겸손해 보이기 위한 것이 아닙니다. 사례 파일을 읽을 수 있게 만들기 위한 것입니다. 독자는 Confirmed 섹션에서 무엇이 사실인지, Deduced 섹션에서 무엇이 따라오는지, Hypothesized 섹션에서 무엇이 아직 열려 있는지 훑어볼 수 있습니다. 이 셋의 혼동이 조사가 빙빙 도는 가장 흔한 이유입니다.
기준점 먼저 확보하기
조사는 이론에서 시작하지 않습니다. 하나의 확인된 증거에서 시작해 바깥으로 확장합니다. 그 기준점은 특정 오류 메시지, 스택 프레임, 타임스탬프가 있는 로그 항목일 수 있습니다.
이는 흔한 조사 방식과 반대입니다. 누군가 직감을 갖고 이론을 세운 뒤 그것을 지지하는 증거를 찾습니다. 직감이 맞을 수도 있지만, 그 방법은 확증 편향을 기본값으로 만들기 때문에 취약합니다.
기준점은 추론이 흐려질 때 돌아갈 수 있는 사실입니다. 추론이 이상한 곳으로 가면 기준점까지 되돌아가 다른 갈래를 시도할 수 있습니다. 기준점이 없으면 어느 단계를 되돌려야 하는지 알 수 없습니다.
증거가 부족하면 스킬은 그렇게 말하고 가설 주도 탐색으로 전환합니다. 가능한 것에서 가설을 만들고, 각각을 시험할 증거를 식별하며, 우선순위가 있는 데이터 수집 목록을 제시합니다. 빠진 증거 자체도 발견 사항입니다.
가설 규율
가설은 사례 파일에서 절대 삭제되지 않습니다. 증거가 확인하거나 반박하면 Status 필드가 Open에서 Confirmed 또는 Refuted로 바뀌고, 어떤 증거가 결론을 냈는지 Resolution이 설명합니다.
이 규칙에는 비용이 있습니다. 사례 파일이 길어집니다. 하지만 이점도 큽니다. 전체 추론 이력이 산출물의 일부가 됩니다. 여섯 달 뒤 비슷한 버그가 나타나면 다음 조사자는 원래 사례 파일을 읽고 어떤 경로가 이미 제거되었고 왜 그런지 볼 수 있습니다. 그 이력이 없으면 새 조사자마다 같은 막다른 경로를 다시 실행합니다.
현재의 조사자에게도 규율을 부여합니다. 틀린 가설을 지울 수 없다면, 인용된 증거로 반박해야 합니다. 불편해졌다고 조용히 떨어뜨리는 선택지는 사라집니다.
전제에 도전하기
사용자의 문제 설명은 사실이 아니라 가설입니다. "캐시가 깨졌다"는 사용자가 믿는 것입니다. 스킬은 그 전제를 중심으로 조사를 세우기 전에 기술적 주장을 독립적으로 검증합니다. 증거가 전제와 모순되면 보고서가 직접 그렇게 말합니다.
이것이 포렌식 감각입니다. 목격자 진술은 데이터이지 진실이 아닙니다. 때로 보고된 버그는 진짜지만 이름표가 틀립니다. 때로 설명된 증상은 다른 원인의 파생 결과입니다. 전제를 절대적 진실로 받아들이는 조사는 잘못된 결함을 진단하고, 버그는 약간 다른 형태로 돌아옵니다.
상황에 맞춘 조사 흐름
스킬은 두 가지 모드가 아니라 하나의 절차입니다. 입력이 요구하는 결함 추적과 영역 탐색의 비율을 계속 맞춥니다.
증상 기반 사례(티켓, 충돌, 오류 메시지, "예전엔 됐다")는 가설 추적, 타임라인 재구성, 수정 방향에 무게를 둡니다. 증상 없는 사례(만지기 전 모듈 이해, 재사용성 평가, 정신 모델 구축)는 I/O 매핑, 제어 흐름 필터링, 검증 계획에 무게를 둡니다. 실제 사례 대부분은 그 사이 어딘가에 있고, 사례 파일은 증거가 요구한 균형을 반영합니다.
사례가 어디에 있든 원칙은 같습니다. 먼저 기준점 확보, 증거 등급화, 가설 추적, 절대 지우지 않기입니다. 출력은 항상 {implementation_artifacts}/investigations/{slug}-investigation.md이며, 해당 사례에 적용되지 않는 섹션은 비어 있거나 생략됩니다.
깊은 버그가 더 넓은 하위 시스템 이해를 요구할 때 절차는 I/O 매핑, 제어 흐름 필터링, 출력에서 역추적하기, 구성 요소 간 경계 추적 기법을 한 흐름 안에 통합합니다. 영역 모델은 같은 사례 파일에 들어갑니다. 모드 전환은 없습니다.
방법론은 스킬 안에 있습니다
조사자의 원칙은 스킬 자체의 속성입니다. bmad-investigate를 호출한 사람은 실행되는 동안 방법론과 커뮤니케이션 스타일을 채택합니다. 냉정한 정확성, 증거 우선 언어, 회피 없는 표현, 사례 파일 중심의 구성입니다. 스킬이 끝나면 호출자는 이전 말투로 돌아갑니다. 페르소나 교체가 아니라 스킬 원칙에서 오는 말투 전환입니다.
조사와 구현은 서로 다른 감각을 보상하기 때문에 중요합니다. 조사자는 느리고 정확합니다. 구현자는 빠르고 자신감 있습니다. 같은 세션에서 둘을 모두 하려 하면 둘 다 애매해지는 경향이 있습니다. 스킬은 별도 정체성으로 컨텍스트를 전환하지 않고, 진행 흐름 안에서 조사자의 태도를 적용합니다.
얻는 것
완성된 조사 파일:
Confirmed발견 사항(인용 포함)을Deductions및Hypotheses와 분리합니다- 형성된 모든 가설을 최종
Status와Resolution과 함께 보존합니다 - 여러 증거 소스에서 이벤트 타임라인을 재구성합니다
- 데이터 공백과 그것이 무엇을 해결할지 식별합니다
- 증거에 기반한 실행 가능한 결론을 제공합니다
- 근본 원인이 식별되면 재현 계획을 포함합니다
- 아직 탐색할 경로의 조사 백로그를 유지합니다
그 자리에 없던 엔지니어에게 건네도 무슨 일이 있었고, 무엇을 알고 있으며, 무엇이 아직 불확실한지 이해해야 합니다. 기준은 그것입니다.
더 큰 아이디어
오늘날 대부분의 "AI 디버깅"은 증거, 추론, 코드 변경을 그럴듯한 텍스트의 한 흐름으로 섞습니다. 신호는 찾기 어렵고, 막다른 경로는 반복되며, 사례 파일이 있더라도 아무도 읽고 싶지 않은 채팅 로그처럼 보이는 경우가 많습니다.
bmad-investigate는 조사를 고유한 산출물이 있는 규율로 다룹니다. 증거에는 등급이 있습니다. 가설에는 상태가 있습니다. 잘못된 방향은 지워지지 않고 문서화됩니다. 사례 파일은 세션보다 오래 살아남습니다.
이미 본 적 있는 것처럼 보이는 다음 버그가 나타났을 때, 빈 프롬프트가 아니라 시작할 곳이 생깁니다.