From Documentation to Executable Context

A few days ago I was thinking about agent artifacts and context compression.

The discussion quickly moved to syntax. If agents start using more structured artifacts, will we end up with giant YAML files nobody wants to read? Will we reinvent programming languages? Will knowledge work slowly turn into another form of configuration hell?

These are fair concerns.

But I think there is a deeper question underneath them.

Who is supposed to read these artifacts?

For decades, documentation existed to explain systems to humans. Requirements, specifications, wiki pages, onboarding notes, design docs, decision records, and project histories all tried to solve the same problem: preserving meaning so people could understand what was happening.

The weakness is that documentation usually lives outside execution.

The system can continue running while the document is wrong. The team can ship code while the wiki is outdated. A product can change while the specification remains frozen in the past.

Most teams do not ignore documentation because they hate reading. They ignore it because documentation often has no direct connection to reality. If the document is wrong, nothing necessarily breaks.

Agent systems may change this.

If an agent reads a memory file, a project scroll, a specification, or a structured artifact before acting, that artifact is no longer just describing the system. It becomes part of how the system behaves.

If the artifact changes, the agent’s output changes.

If the artifact is wrong, the agent acts on the wrong model.

At that point, the artifact starts looking less like documentation and more like infrastructure.

This also changes the readability question.

Today we assume knowledge artifacts should be optimized for humans, because humans are the primary readers. But if agents become primary consumers of some artifacts, the optimization criteria may change.

The stored form may need to be optimized for structure, relationships, constraints, density, and execution.

Not beauty.

Not prose.

Not readability in the traditional sense.

A human may not need to read the stored form directly every time. Another agent can translate it into whatever representation is needed: a product brief, a technical explanation, an audit report, a summary, an onboarding guide, or a critique.

The stored form and the human-facing explanation no longer have to be the same thing.

We already accept this in software.

Most people do not read machine code. Many people do not read database schemas directly. Different users see different interfaces, dashboards, reports, and explanations generated from underlying structures.

Agent systems may push knowledge work in the same direction.

The interesting question is no longer whether future artifacts will look like Markdown, YAML, JSON, diagrams, or DSLs.

The interesting question is whether they remain passive documentation at all.

Maybe some knowledge artifacts will still be written for humans.

But others may become executable context: structured knowledge that agents use directly to decide what to do, what to remember, what to ignore, what constraints to follow, and how to act.

That changes the role of documentation.

A document that explains a system can be ignored.

Executable context cannot be ignored in the same way, because it participates in the system. It affects behavior.

This creates new risks.

Bad documentation is annoying.

Bad executable context is operationally dangerous.

If an agent relies on outdated assumptions, broken project memory, unclear ownership, or compressed artifacts nobody can audit, the system can scale mistakes very quickly.

So the future is not simply “write less documentation” or “let agents handle it.”

The real question is how to design artifacts that are both useful for agents and accountable to humans.

Some layers may need to be dense and structured.

Some layers may need to remain readable and reviewable.

Some layers may need translators, validators, audits, and version history.

But the direction seems clear.

As agents become more capable, context becomes more important. And as context becomes more important, the artifacts that store it stop being secondary project notes.

They become part of the system itself.

Knowledge work may be moving from documentation to executable context.

Short Version

Documentation explains the system. Executable context shapes how the system behaves.