src/developer/debug Development Guide for AI AgentsFollow these cross-cutting rules and progressive-disclosure gates when you write, refactor, or review code under //src/developer/debug.
README.md Pre-Edit GateEach subsystem maintains a local README.md contract with ## Interface, ## Invariants, ## Side Effects, and ## Verification sections.
Mandatory Pre-Edit & Code Review Gate: Before you edit or review (/review) any file in a subdirectory, read ## Invariants and ## Verification in its README.md.
Each subsystem maps to a local contract, build target, test suite, and architectural layer:
debug_agent/ (README.md, posix): Target-side Fuchsia and Linux stub (DebugAgent, DebuggedJob, DebuggedProcess, DebuggedThread, LimboProvider). Build //src/developer/debug/debug_agent and run fx test debug_agent_unit_tests.ipc/ (README.md): Versioned binary wire protocol (debug_ipc) between zxdb and debug_agent. Build //src/developer/debug/ipc and run fx test zxdb_tests.shared/ (README.md, logging): Cross-platform MessageLoop, StreamBuffer, BufferedStream, Arch, RegisterID, Status, and Result. Build //src/developer/debug/shared and run fx test zxdb_tests.zxdb/common/ (README.md): Layer 1 (Lowest) base utilities (Err, ErrOr, AddressRanges). Must not depend on other zxdb layers. Build //src/developer/debug/zxdb/common and run fx test zxdb_tests.zxdb/symbols/ (README.md): Layer 2 DWARF and ELF symbol indexing (Index, DwarfDieRef, LazySymbol) and DwarfExprEval. Build //src/developer/debug/zxdb/symbols and run fx test zxdb_tests.zxdb/expr/ (README.md): Layer 3 C++ and Rust parser, AST (ExprNode), bytecode VM (VmExec), and PrettyType. Build //src/developer/debug/zxdb/expr and run fx test zxdb_tests.zxdb/format/ (README.md): Layer 4 styled output buffers (OutputBuffer, AsyncOutputBuffer) and value or identifier formatting. Build //src/developer/debug/zxdb/format and run fx test zxdb_tests.zxdb/client/ (README.md): Layer 4 UI-agnostic session model (Session, Target, Process, Thread, Stack, ThreadController). Build //src/developer/debug/zxdb/client and run fx test zxdb_tests.zxdb/console/ (README.md, commands): Layer 5 (UI) interactive CLI frontend, noun and verb parser, and ConsoleContext. Build //src/developer/debug/zxdb/console and run fx test zxdb_tests.zxdb/debug_adapter/ (README.md, handlers): Layer 6 (UI) cppdap Debug Adapter Protocol (DAP) server sharing client::Session. Build //src/developer/debug/zxdb/debug_adapter and run fx test zxdb_tests.ffx_zxdb/ (README.md, src, ffx/AGENTS.md): Host Rust integration for ffx debug. Read //src/developer/ffx/AGENTS.md for FDomain and fho rules, and build //src/developer/debug/ffx_zxdb.e2e_tests/ (README.md): Host-driven .script E2E tests and dap_integration_tests. Run fx test --e2e zxdb_e2e_tests.Enforce this upward dependency rule across zxdb/:
zxdb/: Dependencies inside zxdb/ must point upward (common <- symbols <- expr <- {format, client} <- console <- debug_adapter).Apply these C++ and subsystem idioms across all files in //src/developer/debug:
Target*, Process*, Thread*, Frame*, Breakpoint*, FormatNode*) across asynchronous callbacks. Capture fxl::WeakPtr<T> (or fxl::RefPtr<T> for ref-counted Symbol, EvalContext, CommandContext, AsyncOutputBuffer) and check validity before dereferencing.debug_agent sends only the top 1 to 2 frames). Call Stack::SyncFrames asynchronously for full backtraces, and check process->AllThreadsStopped() before inspecting process-wide state.bool with out-parameter pointers for fallible parsing or validation. Return zxdb::ErrOr<T> (in zxdb) or debug::Status / debug::Result<T, E> (in shared, ipc, debug_agent). Reserve FX_CHECK and FX_DCHECK for internal programmer invariants.0): Never use 0 as an invalid sentinel for DWARF unit offsets or type signatures. 0 is valid in DWARF, so use std::optional<uint64_t>. For Zircon KOIDs (zx_koid_t), 0 (ZX_KOID_INVALID) is invalid, so reject 0 when parsing external or DAP IDs.std::function or C++ dynamic_cast (the build disables compiler RTTI). Use fit::function, fit::callback, or fit::deferred_callback, and call symbol->As<T>() to downcast Symbol objects.UncachedLazySymbol::Get() Lifetime & Empty Symbols: UncachedLazySymbol::Get() constructs a new fxl::RefPtr<Symbol> on each call and returns an empty Symbol (DwarfTag::kNone) instead of nullptr when invalid. Before you call symbol->As<T>(), store the fxl::RefPtr<Symbol> in a local variable so the pointer does not dangle. When you walk Symbol::parent() chains, verify is_valid() on the UncachedLazySymbol or verify tag() != DwarfTag::kNone so the loop terminates.AsyncTaskProvider subclasses or PrettyType formatters), resolve types and members through DWARF symbols and expression evaluation. Do not hardcode struct byte offsets. Do not compute raw pointer arithmetic against target memory.namespace, search sibling files and lower zxdb or fxl layers (common, symbols, expr). Follow the patterns in the existing code. Reuse lower-layer utilities instead of duplicating them. If a new helper is general-purpose, place it in the appropriate lower layer. Add unit tests..cc helpers in an anonymous namespace. Format bug links as https://fxbug.dev/<id>, and state the condition required to delete each TODO.ffx debug or zxdb Unix socket paths in skills/ documentation. Direct agents through supported CLI commands instead.Optimize code comments for the reader. Follow these guidelines:
can't, isn't, doesn't). Write non-acronym subsystem or protocol names in lowercase (zircon, starnix, fidl, banjo).// 1., // Step 1:) in source code comments. If an algorithmic flow has multiple phases, split it into named helper functions. Let symbol names show the execution order.Before you complete any work, follow these build, documentation, and testing gates:
# BAZEL2GN SENTINEL): Never hand-edit BUILD.gn files below a # BAZEL2GN SENTINEL marker. Edit the matching BUILD.bazel file and run fx bazel2gn.//docs/development/debugger/, local README.md contracts, and CLI help text in verbs.h / verb_*.cc) whenever you edit user-facing surfaces or internal architecture. Create new documentation if none exists.asd-ste100) and follow Google Technical Writing guidelines (technical-writing).0, invalid DWARF signatures, koid == 0). Test multi-threaded states with 2 or more threads (such as zxdb.AsyncBacktrace and pause synchronization).ThreadController subclasses and DebuggedThread exception paths, test early-exit paths (bottom frames, PLT trampolines, unrelated breakpoints). Use fit::defer or fit::deferred_callback to restore state on early returns.editing-zxdb to build targets, run unit and E2E tests, reload /core/debugger, and test with fx debug cli.