An Agent Takes the Shape of Its Context

You've started saving context between agent sessions so you can stop re-teaching agents what you already know.

But now the question becomes: how should I structure this information?

After all, an agent is a tool that takes the shape of the context it is given: save a fuzzy pile of information and you get a blunt instrument. But give it clear structure and you get a scalpel.

I don't know about you, but when I'm operating in production, I'd rather use a scalpel.

SCOPED is my working vocabulary for sharper context.

S: Scoped
C: Composable
O: Owned
P: Portable
E: Explicit
D: Directional

Scoped

Scoped is the “you are here” rule. It asks what is true here.

project/
├── AGENTS.md
├── src/
│   ├── payments/        ← you are here
│   │   └── CONTEXT.md
│   └── users/
│       └── CONTEXT.md
└── work-state/
    └── current.md

If the task is changing payment logic, src/payments/CONTEXT.md is local truth. Deployment notes and stale task updates should not compete for attention.

Scope turns the pile into a map.

Composable

Once you have rooms, you need labelled doors.

src/payments/CONTEXT.md
└── imports
    ├── ../../docs/decisions/api-style.md
    └── ../../review/security-checklist.md

The payment context is the room. The imported files are doors out of it. Those doors are declared, not assumed.

Shared material is useful when it is used on purpose. Without that, every shared note becomes ambient authority.

Owned

Owned asks what job a file is responsible for.

A messy prompt might mix API style, payment idempotency, release review, and current task state. Owned context separates those claims:

docs/decisions/api-style.md     → API style decisions
src/payments/CONTEXT.md         → payment rules
review/security-checklist.md    → release review criteria
work-state/current.md           → current task state

Ownership is not necessarily about a person. It is about responsibility. Each file should make it obvious what belongs there and what does not.

If nobody knows what kind of truth a file owns, every update becomes a small act of archaeology.

Portable

Portable instructions use the language of the work, not private theory.

Bad:

Apply Layer 2 context boundaries using scoped artifacts.

Better:

Use this folder when changing payment logic.
Preserve idempotency, do not log card details, and run the payment tests.

The agent should not need to understand your methodology before it can act.

Explicit

Explicit means the contract is visible.

Bad:

Be careful with payment changes.

Better:

Use this when changing payment logic.

You may change payment orchestration and tests.
Do not change stored payment data or migration files.
If stored payment data must change, stop and ask for review.

“Be careful” hides judgment. A contract makes the route visible.

Directional

Directional asks which source wins when context disagrees.

docs/decisions/payment-idempotency.md → src/payments/CONTEXT.md → current task

If the decision says payment retries require an idempotency key, a local task note should not quietly override it.

Bad:

For this fix, just retry failed charges directly.

Better:

Follow docs/decisions/payment-idempotency.md.
If the task requires direct retries, stop and update the decision first.

Local context can apply stable decisions. It should not silently rewrite them just because it was loaded later.

A better-shaped workspace

You can review an agent workspace by asking six questions: what is local, what is imported, what each file owns, whether instructions are written in the language of the work, what contract is visible, and which source wins.

Saving context gives the agent memory between runs. Context architecture gives that memory a better shape.

Not just saved context. A workspace the agent can navigate.