Add ADR-023: Code Structure and Enforcement

Hayley Swimelarrequested to merge
worktree-adr-023-code-structure into main

Summary

  • Adds ADR-023 proposing standard Go project layout with package-per-feature organization and compiler-enforced boundaries (internal/ + depguard) for the Artifact Registry
  • Evaluated against Clean Architecture and DDD+Hexagonal through three demo projects, each implementing five package formats
  • Includes production extrapolation using the container registry as a reference for file size calibration, measured token counts for AI agent context window cost, and cross-cutting change amplification analysis (Anna Karenina framing)
  • Adds ADR-022 and ADR-023 to the design document index

What changed from the initial draft

The initial draft had surface-level demo analysis. This version deepens it with:

  • Actual measured metrics from all three demo repos (file counts, line counts, handler sizes, config sizes)
  • Production extrapolation at 15 formats using the container registry's manifests.go (1,848 lines) as a 2-2.5x multiplier reference
  • Real token count estimates (~8,900 / ~9,500 / ~11,700 across architectures) replacing the original rough estimates that were ~5x too low in absolute terms
  • Structural tax analysis showing DDD imposes +69% more code than Go Native for the simplest format (Generic)
  • Cross-cutting change amplification table projecting Clean Architecture to 34 files vs 19 for the others at 15 formats
  • Handler file splitting acknowledged as a planned negative consequence with guidance on when to split
  • Test overhead gap explicitly noted as an unmeasured dimension

Test plan

  • Handbook site builds without errors
  • ADR renders correctly with Mermaid diagram
  • Internal links to other ADRs resolve
  • Index page shows ADR-022 and ADR-023 entries

🤖 Generated with Claude Code

Merge request reports