Detailed Analysis
A developer working with Claude Code and Codex has surfaced a practical governance problem that many teams are now confronting as coding agents take over more of the actual writing of software: how do humans stay meaningfully in control of a codebase they no longer type line-by-line into existence. Rather than treating this as an abstract concern, the author ran a controlled experiment comparing agent behavior with and without access to a folder of committed Architecture Decision Records (ADRs) referenced by a single instruction line in CLAUDE.md. The results were striking—45 out of 45 runs on Claude Opus correctly consulted and respected the ADRs in the treatment condition, with all 120 control runs actively using Read, Grep, or Glob tools to search the ADR folder before making architectural choices. Notably, a more elaborate custom retrieval layer built specifically for this purpose showed no measurable advantage over simply committing plain-text decision records and pointing the agent at them.
The deeper argument draws on Peter Naur's 1985 paper "Programming as Theory Building," which contends that programming is fundamentally not about producing code but about constructing a shared mental theory of how a system maps onto the problem it solves. That theory—the reasoning behind why a system is built one way rather than another—cannot be fully captured by dumping context into Markdown files for an agent to grep. It has to live with people who can explain and defend it. This framing reframes the "should you read AI-generated code" debate: the more urgent intervention point isn't after code is written but before implementation, when an agent is making choices that subsequent agents will inherit as unquestioned precedent. If an agent's design decisions are treated as settled fact by later agents without human review, the codebase's underlying theory silently drifts out of human hands even though the code itself is being read and merged.
This insight led to Nauro, a tool the author built largely using Claude Code (and later tested with Codex against the same decision record) that formalizes a human-in-the-loop checkpoint for architectural judgment. When an agent proposes a project-level decision, it drafts reasoning and alternatives considered; a human then accepts, amends, or rejects it, and only approved decisions become part of the persistent record that future agent sessions consult. The project the author uses as an internal testbed has accumulated 482 such decisions, with 137 superseded over time—itself a data point suggesting that architectural judgment is iterative and needs versioning, not just accumulation. Nauro 1.0 launched as free, open-source (Apache 2.0) software that runs locally without telemetry or an account requirement, with optional cloud sync, positioning it as infrastructure for judgment continuity across agents, tools, sessions, devices, and eventually multiple human collaborators.
The broader significance lies in what this represents for the trajectory of agentic coding tools like Claude Code, Codex, and similar systems: as agents handle increasing volumes of implementation work, the bottleneck of trust shifts from "is this code correct" to "whose judgment governs this system's evolution." Memory and context tools that simply expand what an agent can retrieve risk encoding unreviewed agent decisions as institutional fact—a subtle form of governance erosion. The experiment's finding that a lightweight, human-curated ADR folder outperformed a bespoke retrieval system also pushes back against the assumption that more sophisticated memory infrastructure is inherently better; curation and provenance may matter more than retrieval sophistication. This mirrors a growing theme across the AI coding ecosystem in 2025–2026: as models like Opus become capable enough to be trusted with large swaths of implementation, the industry's attention is turning toward designing checkpoints, audit trails, and approval workflows that preserve human authorship over the "theory" of a system, even as authorship over its literal code becomes increasingly distributed between humans and models.
Read original article →