에이전트로 실패 테스트 디버그

이 가이드에서는 print 문으로는 설명되지 않는 실패에 대해 에이전트가 디버거를 사용하도록 하는 방법을 보여 줍니다.

debug 도구는 실제 Debug Adapter Protocol 세션을 구동합니다. 중지된 프레임은 그 순간에 관한 모든 질문 — 모든 지역 변수, 모든 호출자, 그리고 프레임 자체의 스코프에서 평가된 표현식 — 에 한 번에 답하는 반면, print 문은 실행하기 전에 생각해 낸 질문에만 답합니다.

시작하기 전에

이 도구는 에이전트가 추측하는 대신 왜 아무것도 쓸 수 없는지 물어볼 수 있도록 도구 표면에 그대로 남아 있습니다. 어댑터가 실제로 시작될 수 있는 것은 다음 두 가지 조건이 모두 성립할 때뿐입니다:

체크아웃에 프로젝트 마커가 있을 것, 그리고
어댑터의 바이너리가 해석될 것.

에이전트에게 다음을 확인하도록 요청합니다:

debug(op: "adapters")

도구는 찾은 내용을 답하거나, 어댑터에는 두 조건이 모두 필요하다고 설명합니다.

언어	어댑터	마커	설치
Dart / Flutter	`dart debug_adapter`	`pubspec.yaml`	SDK에 포함 — 할 일 없음
Python	`python3 -m debugpy.adapter`	`pyproject.toml`, `setup.py`, `requirements.txt`	`pip install debugpy`
Rust / C / C++	`lldb-dap`	`Cargo.toml`, `CMakeLists.txt`	LLVM에 포함
Go	`dlv dap`	`go.mod`	`go install github.com/go-delve/delve/cmd/dlv@latest`

중단점을 먼저 설정하고 실행하기

순서가 중요하며 도구가 이를 강제합니다: 중단점은 세션이 존재하기 전에 설정할 수 있는데, 그것이 프로토콜이 요구하는 순서이기 때문입니다.

에이전트에게 다음과 같이 요청합니다:

bin/main.dart의 compute 함수가 잘못된 값을 반환합니다. product를 할당하는 줄에 중단점을 설정하고, 디버거에서 실행한 뒤 a와 b가 실제로 무엇인지 알려 주세요.

그러면 대략 다음을 실행합니다:

debug(op: "breakpoints", file: "bin/main.dart", lines: [7])
debug(op: "launch", program: "bin/main.dart")

launch는 어디에서 멈췄는지 보고합니다:

Launched bin/main.dart on dart (session dart-1). Stopped: breakpoint. Use `stack` to see where.

프레임 읽기

debug(op: "stack")
→ #1 compute (bin/main.dart:7:3)
  #2 main (bin/main.dart:2:18)

그런 다음 그 내부를 살펴봅니다:

debug(op: "scopes", frame_id: 1)
→ Locals (reference 12)

debug(op: "variables", reference: 12)
→ a (int) = 6
  b (int) = 7
  product (int) = 42

자식이 있는 객체는 [expand: reference N]을 보고합니다. 다만 그 뒤에 실제로 무언가 있을 때만 그렇습니다. 따라서 에이전트가 쓸 수 없는 확장은 결코 제공되지 않습니다.

지역 변수로는 보이지 않는 값이 있다면:

debug(op: "evaluate", expression: "config.timeout.inSeconds", frame_id: 1)

단계별 실행

원하는 작업	연산
다음 중지 지점까지 실행	`continue`
다음 줄, 같은 프레임	`step_over`
호출 안으로	`step_in`
호출자 밖으로	`step_out`
실행 중인 프로그램 중지	`pause`

이미 실행 중인 대상에 연결하기

새로 시작하는 프로세스가 아니라 멈춰 버린 프로세스의 경우:

debug(op: "attach", port: 5858)

마무리

debug(op: "terminate")

항상 세션을 끝내야 합니다. 디버그 어댑터는 중지된 프로세스를 소유하며, 그 프로세스가 쥐고 있는 것 — 포트, 잠금, 데이터베이스 연결 — 을 함께 붙듭니다.

출력 제한

깊은 객체 그래프에 대한 variables 확장은 본질적으로 무한합니다. Flutter 위젯 하나가 전체 요소 트리에 닿기 때문입니다. 스코프당 자식은 50개, 값은 400자, 스택 프레임은 30개로 제한됩니다. 컨텍스트 창을 가득 채우는 도구 결과는 자신이 돕던 실행을 끝내 버리는 도구입니다.