Engineers argue coding agents need ADRs and lean navigation docs

• Persistent repo specs are getting cut: colocated specs consumed compute, drifted, and failed to steer agents in zeeg's repo-spec post.
• The durable-docs shortlist is ADRs, glossaries, and navigation pointers: mattpocockuk made those exceptions in his follow-up and his navigation note.
• Specs still survive as handoff artifacts: the coding flow runs /wayfinder → /to-spec → /to-tickets → /implement in mattpocockuk's /wayfinder post, then specs get deleted once represented in code in his reply.
• Skills are where reusable procedure is moving: zeeg called a skill a macro in his explanation, while pauliusztin_ reported a 40% token reduction across 63 skills in his cleanup post.
• Model changes can turn old prompt files into spend: pvncher said agents.md and skill files are part of prompting in his audit note.

Claude Code's memory docs say CLAUDE.md and auto memory load at conversation start, and Claude treats them as context rather than enforced configuration. OpenAI's Codex guide says Codex builds one instruction chain from global and nested repo files, with a 32 KiB default project-doc cap. Anthropic's skill authoring guide makes the token trade explicit: only skill metadata loads at startup, then SKILL.md and reference files load when relevant.

Zeeg's experiment ran for months: colocated specs became docs, cost compute to keep updated, drifted enough to mislead the agent, and failed to make intent stick.

His replacement set is much smaller:

• policies/, lightweight no-prose rules such as where code comments belong.
• openspec/, retained for now but not treated as context docs.
• custom skills, mostly for third-party docs such as Vercel Sandbox or Slack API behavior.
• agents.md, primarily as a resource map.
• inline code comments for intent.

In one reply, zeeg said the specs were referenced and visible through a treemap, so the failure mode was steering rather than discovery. The hoped-for organic use did not show up, according to another zeeg follow-up.

The official Claude Code line is narrower than most repo-doc piles: its memory docs say concise and specific instructions are followed more consistently, and imported CLAUDE.md files are expanded into context at launch.

Mattpocockuk's exception is documentation for things code cannot express:

• alternatives considered
• domain language
• ADRs
• glossaries

Zeeg drew the same boundary when his terminology reply called terminology docs useful and pointed to a Sentry commit that restored canonical runtime terms for conversation, source, destination, message, turn, slice, and step.

That is the clean split: code owns mechanics, docs own decisions and vocabulary.

Navigation docs survived the purge because they act like roads through the repo, not mirrors of the repo.

In a progressive-disclosure reply, mattpocockuk described the useful layer as context pointers to the right areas, decoupled from code behavior. He later called those files roadsigns rather than docs in another reply.

The AGENTS.md standard uses the same shape: a predictable place for build steps, tests, conventions, and other agent-focused context that would clutter a human README. OpenAI's Codex guide adds layering: nearer AGENTS.md files override broader guidance as Codex walks from project root toward the working directory.

Zeeg described skills as macros: files read from disk and injected when referenced, with behavior differences coming from training, system prompts, cache behavior, and weights.

Anthropic's Claude Code skills docs define the same mechanism operationally: a skill has a required SKILL.md, optional supporting files, and a body that loads only when the skill is used. The official skill best-practices page frames SKILL.md as an overview that points to detailed materials, with a suggested body under 500 lines.

Pauliusztin_ moved shared domain knowledge into a resources folder so multiple skills could point at the same glossary, branding, writing profiles, and examples. Earlier, his skill cleanup post said Fable helped reduce 63 skills' token count by 40% by auditing invocation metadata, deleting duplicates, removing claims already baked into the model prompt, and pushing material behind progressive disclosure.

Specs remain in the workflow as temporary handoff artifacts.

Mattpocockuk's coding flow is explicit:

1. /wayfinder
2. /to-spec
3. /to-tickets
4. /implement

The map comes first, then the completed map becomes a spec, then implementation goes to an AFK agent. In his ticketing reply, mattpocockuk said /wayfinder creates decision tickets inside the issue tracker, not implementation tickets, and the map closes before turning into a spec.

The deletion rule is blunt: mattpocockuk told one user to delete specs as soon as they are represented in code in his reply.

Zeeg's Garfield screenshot shows the lean-doc approach still carrying policy, but through a review skill that classifies relevance before running work.

Garfield snapshots intent, uses independent no-edit reviewers, reads AGENTS.md plus policy and reference files, then splits tracks into applicable and skipped groups:

• Applicable tracks included behavior/spec, repo instructions, validation, specs/docs, dead code, delayering, type boundary, generated/dependency, code comments, implementation minimalism, interface design, test quality, frontend components, runtime boundary schemas, testing, and correctness complexity.
• Skipped tracks included context-bound systems, error handling, agentic semantics, evals, provider boundaries, serverless background work, test adapters, and tool design.

The screenshot is a good reminder that "delete docs" in this debate means deleting stale secondary truth, not deleting every agent-readable rule.

Prompt files are part of prompting, and model behavior changes can turn old guidance into new runtime cost.

Dexhorthy said GPT-5.6 models were much more eager to use subagents and skills in his Sol note. Pvncher described 5.6 Sol as more tenacious and thorough than 5.5 in his prompting-guide post.

Zeeg's failure mode was expensive: a cleanup or review skill auto-runs, iterates repeatedly, and each pass triggers a skill with roughly 20 subagents, as described in his scenario. Pvncher's suggested audit target was agents.md and skill files after every model release, with removals for anything that pushes longer runtimes or excessive validation in his reply.