Most engineering teams treat README(.md) as the front door to a repository, yet
By Elijah Dean · November 6, 2026 · Curated by George's Blog
Most engineering teams treat README(.md) as the front door to a repository, yet an AI coding agent needs completely different information than a human onboarding to a project.
Humans need setup guides and deployment steps. Coding agents hallucinate when they lack strict boundary conditions, state mutation rules, and explicit negative constraints detailing what to leave alone.
While the web industry is converging on public llms.txt files to help external crawlers index websites, mixing public documentation with internal architecture creates an obvious exposure risk. Over the past week, I wired up a multi-agent workflow in Roo Code built around a build-isolated root file (llms-dev.txt) paired with an automated decision archivist (compare the red "Yolo Loop" vs. the green "Epistemic Isolation" pipeline in the flowcharts below):
PARALLEL CONTINUITY (README(.MD) VS. LLMS-DEV.TXT): README(.md) stays strictly for human operators. Alongside it in the project root sits llms-dev.txt (explicitly blocked from public builds via ignore rules). Capped at 250 lines with domain sharding for larger codebases, it feeds every coding pass a token-dense map of file responsibilities, data contracts, intentional platform workarounds, and hard "do not touch" invariants before a single line of code is edited.
DEFERRED ANNOTATION AND READ-ONLY QC: Letting a single context window write code, write comments, and grade its own work invites sunk-cost bias and comment bloat. In our loop, the coding pass writes 100% executable logic with zero new inline comments so the model cannot rationalize sloppy architecture in prose. An isolated, read-only efficiency auditor then grades every modified block A through F, forcing rework on any C, D, or F grade before handing the verified code off to a lighter, lower-cost model for documentation.
THE ARCHIVIST AND ADR VAULT: Across both hardware fabrication and software, teams rarely document the dead ends. Six months later, someone inevitably burns $60/hr to $80/hr of engineering time re-attempting an approach that was already ruled out. To bridge brainstorming sessions into the repository, a dedicated archivist skill packages the governing math and rejected alternatives into permanent Architecture Decision Records (docs/decisions/ADR-*․md), while placing a compact one-line pointer in llms-dev.txt so active context windows stay lean.
Coming from mechanical engineering and equipment manufacturing, this applies shop-floor print tolerances, independent QC inspection, and Engineering Change Orders directly to software maintenance.
#SystemsEngineering #MechanicalEngineering #ReliabilityEngineering #OperationsManagement #SoftwareArchitecture