workspace.json vs AGENTS.md: Prescriptive vs Descriptive Context
AI coding agents need context to work well. Two formats have emerged to provide it: AGENTS.md (and its variants CLAUDE.md, COPILOT-INSTRUCTIONS.md) and workspace.json. They look similar on the surface but solve fundamentally different problems.
The core distinction
Section titled “The core distinction”AGENTS.md is descriptive and instructional. It’s a markdown file you write in natural language telling the agent how to behave: “run tests with pnpm test”, “never modify files in vendor/”, “use conventional commits”.
workspace.json is prescriptive and structural. It’s a machine-readable JSON file that encodes what’s true about your repository: which packages exist, what files they own, what frameworks they use, how active they are.
One is a memo. The other is a manifest.
Why the distinction matters
Section titled “Why the distinction matters”When an agent reads AGENTS.md, it extracts meaning from prose. That works until it doesn’t — when the instructions are ambiguous, outdated, or conflict with what the agent observes in the code.
When an agent reads workspace.json, it gets structured facts it can validate, cross-reference, and reason about without interpretation. The spec’s type system makes it harder to be wrong.
Consider a monorepo with 12 packages. An AGENTS.md might say “check the packages directory”. A workspace.json enumerates every package with its manifest path, language, framework, and ownership — making it impossible for the agent to miss one or misunderstand the structure.
They’re complementary, not competing
Section titled “They’re complementary, not competing”The best setups use both:
workspace.jsonfor structural truth: packages, files, frameworks, conventionsAGENTS.mdfor behavioral guidance: workflow preferences, commit style, what to avoid
workspace.json reduces the surface area that AGENTS.md needs to cover. Fewer prose instructions means less drift, less ambiguity, and more reliable agent behavior.
Getting started
Section titled “Getting started”Add a workspace.json to your repo in under 10 minutes with the Getting Started guide. The agents-audit CLI will tell you how well your existing setup is doing.