Go peer review guide
Overview
Good Go code in BusDK should be easy to understand, easy to test, and hard to misuse. A peer review should therefore look past formatting and obvious static-analysis findings. It should ask whether the code has the right owner, whether behavior is expressed through clear package boundaries, whether failures are deterministic, and whether tests prove the actual user-visible contract.
This guide is organized as small review pages that can also become source material for LLM-assisted linting. A finding should name the code location, explain why the current shape is risky, and suggest the smallest design improvement that would make the code clearer or safer.
Review Pages
Review order explains how to start with the product boundary, then move through public contracts, package design, implementation details, tests, and documentation.
Ownership and architecture
covers package responsibility, command boundaries, os.Exit, module ownership,
and predictable layering.
API and type design covers typed contracts, intentional exported surfaces, explicit dependencies, and interface ownership.
Source transforms and evaluators covers parsers, formatters, compilers, generators, linters, expression evaluators, and safe evaluation limits.
Data mapping covers import, extraction, alias, profile, prior-year, and external workspace mapping rules.
Control flow and mutation covers readable main paths, meaningful helper extraction, staged validation, deterministic writes, and no-partial-write behavior.
Destructive and batch operations covers delete, rename, overwrite, schema changes, batch preflight, trace modes, and command-file execution.
Errors and CLI diagnostics covers ordinary errors, panic boundaries, stable diagnostic context, stdout and stderr separation, fixed text output, and coupled flag surfaces.
Context, resources, and concurrency
covers context.Context, resource lifetimes, post-response obligations,
goroutine ownership, queues, timers, and tickers.
Determinism and side effects covers stable output, reproducible build settings, subprocess argument lists, localized environment reads, portability assumptions, and side-effect boundaries.
Workflows and backends covers backend parity, storage policy ownership, workflow idempotency, state transitions, delegation, and correlation identifiers.
HTTP and service boundaries covers bounded request decoding, explicit servers and clients, workspace path boundaries, capability endpoints, TLS shortcuts, and sensitive logging.
Browser and UI boundaries covers browser-adjacent Go, renderer safety, safe URLs, escaped markup, projected view models, and accessible rendered output.
Validation and domain safety covers schema and logical validation, durable audit identity, exact business quantities, and authorization test matrices.
Authentication and credentials covers OTPs, refresh tokens, account identity, credential clients, replaceable security primitives, and internal-token boundaries.
External runners covers runtime selection, model choice, timeouts, sandbox policy, prompt rendering, and typed runner outcomes.
Performance review covers measured
hot paths, repeated work, cache scope, streaming, pooling, unsafe, and
benchmark shape.
Tests and evidence covers unit tests, end-to-end tests, regression coverage, deterministic harnesses, and quality evidence.
Documentation and traceability covers code comments, help text, README material, module docs, public references, and invariant comments.
LLM finding patterns preserves the compact rule names and finding shape for future automated Go review.
Compact checklist gives the final approval checklist for reviewers.