Basis posted on X a detailed account of how it reorganized its monorepo for coding agents, claiming the changes pushed token usage per developer up by “more than 5x” and weekly commit velocity up by “2.5x” over three months.
The company’s Atlas team, which it describes as responsible for internal agents and context, argued that a codebase now has to serve as both production software and the context agents use to make decisions. From there, Basis organized its approach around five principles: canonicality, localization, verifiability, interoperability, and “default-no.”
A central part of the post is a distinction between “canonical” and “non-canonical” material. Basis says canonical context includes root and nested AGENTS.md files, skills, docs, and inline code comments and docstrings, while non-canonical context includes plans, specs, Linear tickets, and historical notes. The company presents that split as a way to keep agents from treating old plans or abandoned ideas as present-day truth.
That taxonomy fed into a six-layer setup: a root AGENTS.md file, more than 100 nested AGENTS.md files, skills stored under .agents/skills/, specialized sub-agent roles under .agents/roles/, a unified MCP server for external systems such as Linear, Slack, Better Stack, PostHog, and a dev database, and a final layer of tests and hooks. Basis also included snippets showing how some of those files are written, with instructions that lean toward local conventions rather than broad documentation.
The post says the team rewrote about 20 AGENTS.md files after finding them “in rough shape,” shifting them away from descriptive text and toward operational instructions. Basis lists authoring rules such as “instruction quality,” “hierarchy-first placement,” “resilient references,” text-only content, and “default-no,” and says it moved cross-folder knowledge into skills rather than keeping it in folders where it applied only indirectly.
Basis also says it used coding agents to audit the codebase against the new standards, which surfaced nine projects with “thousands of lines of violations.” The company estimates the cleanup touched “20 to 30 percent” of the codebase across those projects. It then added ownership metadata, CI/CD checks, a daily scanner, and daily workers under what it calls Automatic Context to keep canonical material from drifting.
On testing, Basis states that it paired platform engineering work with agent-behavior work, with one side building unit tests, integration tests, fixtures, markers, and CI integration, while the Atlas team encoded testing expectations into agent instructions. The company says the result was a testing skill that tells agents when tests are required and how they should be structured.
The post drew a small stream of replies, including praise, a follow-up question about whether agents are encouraged to explore curated context in AGENTS.md, and a request for more detail on cleanup loops as token usage and PR volume grow. One commenter also said the post led them to apply for a role.
Source: Basis on X
