The open specification for AI agent workspace context and repository intelligence.https://www.workspacejson.dev/enhttps://www.workspacejson.dev/blog/workspace-json-vs-agents-md/https://www.workspacejson.dev/blog/workspace-json-vs-agents-md/AGENTS.md tells your AI what to do. workspace.json tells it what's true. Here's why that distinction is the difference between reliable and brittle agents. Thu, 07 May 2026 00:00:00 GMT<p>AI coding agents need context to work well. Two formats have emerged to provide it: <code dir="auto">AGENTS.md</code> (and its variants <code dir="auto">CLAUDE.md</code>, <code dir="auto">COPILOT-INSTRUCTIONS.md</code>) and <code dir="auto">workspace.json</code>. They look similar on the surface but solve fundamentally different problems.</p> <div><h2 id="the-core-distinction">The core distinction</h2></div> <p><code dir="auto">AGENTS.md</code> is <strong>descriptive and instructional</strong>. It’s a markdown file you write in natural language telling the agent how to behave: “run tests with <code dir="auto">pnpm test</code>”, “never modify files in <code dir="auto">vendor/</code>”, “use conventional commits”.</p> <p><code dir="auto">workspace.json</code> is <strong>prescriptive and structural</strong>. 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.</p> <p>One is a memo. The other is a manifest.</p> <div><h2 id="why-the-distinction-matters">Why the distinction matters</h2></div> <p>When an agent reads <code dir="auto">AGENTS.md</code>, 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.</p> <p>When an agent reads <code dir="auto">workspace.json</code>, 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.</p> <p>Consider a monorepo with 12 packages. An <code dir="auto">AGENTS.md</code> might say “check the packages directory”. A <code dir="auto">workspace.json</code> enumerates every package with its manifest path, language, framework, and ownership — making it impossible for the agent to miss one or misunderstand the structure.</p> <div><h2 id="theyre-complementary-not-competing">They’re complementary, not competing</h2></div> <p>The best setups use both:</p> <ul> <li><code dir="auto">workspace.json</code> for <strong>structural truth</strong>: packages, files, frameworks, conventions</li> <li><code dir="auto">AGENTS.md</code> for <strong>behavioral guidance</strong>: workflow preferences, commit style, what to avoid</li> </ul> <p><code dir="auto">workspace.json</code> reduces the surface area that <code dir="auto">AGENTS.md</code> needs to cover. Fewer prose instructions means less drift, less ambiguity, and more reliable agent behavior.</p> <div><h2 id="getting-started">Getting started</h2></div> <p>Add a <code dir="auto">workspace.json</code> to your repo in under 10 minutes with the <a href="https://www.workspacejson.dev/getting-started/">Getting Started guide</a>. The <a href="https://www.workspacejson.dev/audit/">agents-audit</a> CLI will tell you how well your existing setup is doing.</p>specagents-mdai-context