The dangerous thing about AGENTS . md is that it looks like a place to put everything you wish the agent knew. Most teams do not start with a context architecture. They start with friction. The agent misses a convention, so someone adds a line. Skipped validation? Add a rule. Used the wrong abstraction? Add an overly strict example. Misread old documentation? Add a warning. A few weeks later, the always-on file has become a project tour, architecture memo, QA checklist, style guide, change log, and warning label. All of that feels responsible. It also creates a new problem: always-on context has a carrying cost. A coding agent is not just a model pointed at a repo. It is operating inside a stack: model priors, vendor harness, system prompt, repo preamble, current task, open files, retrieved context, permissions, hooks, tests, CI, review, and deployment gates. Those layers do different jobs. When they collapse into one bucket called “the prompt,” teams lose the ability to reason about placement. A rule that must never be violated probably needs enforcement in hooks, permissions, CI, or review gates. A convention that only matters in one subsystem should live near that subsystem. Canonical examples should sit near the usage. Validation expectations can be always-on only if they apply broadly; otherwise they belong in the change path for the affected area. The driving question: Which layer should own this responsibility? AGENTS . md and CLAUDE . md are always on. They sit inside the sandwich of whatever the harness is already doing, whatever the current task is asking for, and whatever context the agent has opened or retrieved. So the always-on file should stay small, durable, and procedural. It should teach the agent how to enter the project: what has authority, where task-specific context lives, which rules are always active, what validation is expected, what “done” means, and where examples of good work can be found. But those things do not all live in the file. They get routed through the file. The bulk context should live in the repo behind progressive disclosure. This is where a lot of prompt advice gets blurry. Persona cosplay can nudge behavior, but it does not carry the structure people assign to it. “You are a senior engineer” is not an operating model. Examples can help, but only when they are treated as local precedent instead of global constraint. They should show what good looks like, not shrink the solution space to one approved shape. The mistake is making one file carry all of that. The stronger mental model is to treat the always-on file as a bootloader for the project’s operating layer. That is what I’ve been exploring through Embedded Delivery OS: treating the repo less like a pile of source files and more like a working environment an agent has to enter. The core shift: fewer giant preambles, better embedded systems. the work: https://lnkd.in/gGaYBnbM
Back to all writing ›