debugging
어떤 언어나 바이너리에서도 관측된 상태로 근본 원인을 확정하는 가설 기반 런타임 디버깅입니다.
debugging 스킬은 LazyCodex(LZX)가 실제 런타임 디버깅을 수행하는 방식입니다. 크래시, 조용한 실패, 잘못된 응답, 멈춘 프로세스, 메모리 누수, 비동기 오작동, 설명되지 않는 타이밍, 심지어 심볼이 제거된 바이너리의 리버스 엔지니어링까지 다룹니다. 가설 기반 루프를 돌리며, 관측된 상태가 근본 원인을 증명하기 전에는 버그를 고쳤다고 선언하지 않습니다. LazyCodex가 Codex에 설치하는 OmO(oh-my-openagent) 플러그인에 포함되어 있습니다.
"debug this", "why is X not working", "hanging", "attach a debugger", "reverse engineer", "trace this bug", "reproduce and fix", "silent failure", "HTTP 200 but empty", "stuck process" 같은 표현과 pwndbg, gdb, lldb, node inspect, tsx debug, pdb, dlv, delve, rust-gdb 같은 도구 이름이 트리거입니다.
매번 지키는 두 규율
- 런타임 진실이 코드 읽기를 이깁니다. 버그가 왜 일어나는지에 대한 모든 주장은 관측된 상태에서 나와야 합니다. 코드를 읽고 지어낸 그럴듯한 이야기에서 나오면 안 됩니다.
- 흔적을 남기지 않습니다. 디버깅은 아티팩트를 만듭니다. 모든 아티팩트는 만들기 전에 저널에 기록하고, 작업을 끝났다고 선언하기 전에 제거합니다.
HOW는 references에 있습니다
이 스킬은 의도적으로 작습니다. 실제 디버깅 지식은 references/에 있으며, 해당 레퍼런스를 읽는 것은 권고가 아니라 강제 게이트입니다. 어떤 레퍼런스 영역의 명령을 실행하기 전에, 이번 세션에서 그 레퍼런스를 읽어 두어야 합니다.
- 런타임 레퍼런스는 런타임별로 실행·어태치·브레이크포인트·검사 방법을 다룹니다: Python, Node.js / tsx / Bun / Deno, Rust, Go, 네이티브 바이너리, 번들 앱 바이너리(Bun/Node SEA, Deno compile, pkg, nexe, Electron, Tauri, PyInstaller). 각 레퍼런스는 시간을 조용히 잡아먹는 함정을 문서화합니다. 예를 들어
tsx+node inspect에는 라인 브레이크포인트가 절대 걸리지 않는 조용한 소스맵 실패가 있습니다. - 전문 도구는 해당 영역에서 정답인 도구입니다: 브라우저로 서빙되는 UI 버그에는 Playwright CLI,
strings/objdump로 추측하기 전 Ghidra의 디컴파일러, 그냥gdb대신 pwndbg, 바이너리·네트워크와의 재현 가능한 상호작용에는 pwntools.
네이티브 대 번들을 30초 만에 구별하는 법: file ./target은 둘 다 ELF/Mach-O라고 부르므로 du -h ./target(50 MB 이상이면 의심) 과 strings -n 12 ./target | rg -iE 'bun|node_modules|webpack|esbuild|deno|pkg/lib|electron|pyinstaller|nexe|NODE_SEA_FUSE|tauri'를 함께 씁니다. 히트가 있으면 번들, 깨끗하면 네이티브입니다.
페이즈 루프
각 페이즈에는 정확히 하나의 레퍼런스가 있으며, 기억이 아니라 페이즈에 진입할 때 읽습니다.
Phase 0-1 — 셋업과 저널
무언가를 어태치하기 전에 런타임, 포트, 심볼, 환경 변수, 워처를 파악합니다. 모든 아티팩트를 추적하는 단일 .debug-journal.md를 열어 되돌리기를 보장합니다.
Phase 2-3 — 가설과 병렬 조사
직교하는 축에서 최소 세 개의 가설을 세우고, 각각에 구별되는 증거를 둡니다. 이들을 병렬로 조사합니다. 팀 모드가 켜져 있으면 debug-squad 팀으로, 아니면 비동기 서브 에이전트로 진행합니다.
Phase 4 — 독립 검증 3회
연속 두 라운드가 실패하면 서로 다른 관점의 검증자 세 개를 띄워 답을 종합합니다. Codex에서는 가능한 경우 설치된 reviewer 역할을 쓰고, 아니면 역할 설명을 포함한 self-contained sub-agent로 실행합니다.
Phase 5-7 — 에스컬레이션, 확정, 수정
증거가 소진되고 판단에 정책적 함의가 있을 때만 사용자 결정으로 에스컬레이션합니다. 근본 원인은 의심되는 원인을 토글했을 때 버그도 토글될 때만 확정됩니다. 그런 다음 실패하는 테스트로 잠급니다(red → 최소 green, 범위 확장 없음).
Phase 8-10 — QA, 정리, 검증
시스템을 실제로 써서 QA합니다: CLI는 tmux, 브라우저는 Playwright, API는 진짜 curl, 바이너리는 진짜 재현. 저널을 따라가며 모든 아티팩트를 되돌려 git diff에 수정과 테스트만 남게 하고, 마지막 증거 게이트 네 개를 통과합니다.
안전 불변식
- 런타임 상태가 유일한 진실의 원천입니다. 관측값 없는 가설은 추측이고, 추측은 고치지 않습니다.
- 모든 디버그 아티팩트는 만들기 전에 저널에 기록합니다.
- 실패하는 테스트 없이는 어떤 수정도 출하하지 않습니다. red → green 전환이 필수입니다.
- 타입 체크나 컴파일 성공은 절대 완료로 치지 않습니다. 실제 사용자 시나리오만 완료입니다.
- 디버깅 중 오류를 조용히 삼키지 않습니다. 시스템이 오류를 삼킨다면 그게 바로 버그인 경우가 많습니다.
- 이 스킬 안에서는 절대
git commit하지 않습니다. 커밋은 사용자가 확인한 흐름의 몫입니다.