AI coding agents need context, and that part is obvious by now. What is less obvious is that context quality is only half the problem . The other half is context shape .

An instruction file that works well in one repository, one harness, or one workflow can be the wrong format for another. A dense single file may be perfect for one setup and awkward for another. A concise operational doc may be ideal in one environment and too shallow in another. A multifile structure may dramatically improve retrieval in one workflow while feeling unnecessary in a smaller repo.

So the real question is not only:

“Do you have an AGENTS.md ?”

It is also:

“Is it in the right format for the way your agent actually consumes it?”

That is the part I think we should talk about more.

Table of Contents

Overview

The Hidden Problem: Context Shape

Why One AGENTS.md Format Is Not Enough

Profiles: How Much Context Should an Agent Get

Layouts: How Should Context Be Packaged

Why the Best Format Depends on the Harness

Single vs…