The AI Followed the Instructions. The Documentation Still Fell Apart.

joyrswd — Tue, 25 Aug 2026 08:18:48 +0000

AI disclosure: This article was generated with the assistance of AI based on my own development experience, observations, and ideas. I reviewed and edited the final content before publication.

AI coding agents are getting remarkably good at following instructions.

That creates a strange new kind of failure.

Sometimes the AI does exactly what you asked — and the repository still gets worse.

I ran into this repeatedly while using AI agents for ongoing software development. The problem was not hallucinated code, ignored instructions, or obviously bad output.

The agent was behaving reasonably.

The documentation structure was not.

Over time, I started seeing the same kinds of failures in different forms.

The following cases are not three abstract theoretical risks. They are representative examples of symptoms I actually encountered while letting AI agents maintain project documentation over multiple development cycles.

Case 1: Evidence Kept Accumulating

At first, keeping verification evidence in the repository seemed useful.

A change was implemented.

Tests were run.

The result was recorded.

So far, so good.

Then another change happened.

And another.

Each time, the AI preserved the previous evidence and added new material.

Eventually, the repository contained a growing collection of verification documents describing states that were no longer current.

Nothing was technically wrong with those files.

They really had been valid at some point.

But their continued presence created a new problem:

historical evidence started looking like current truth.

An AI reading the repository later could not always tell whether a document meant:

this was once observed,
this is still true,
this is required to remain true,
or this has already been superseded.

The agent had followed the rule:

Keep evidence.

The repository needed a better rule:

Evidence needs a lifecycle.

Case 2: Design Documentation Became an Implementation Transcript

Another problem appeared in design documents.

When asked to update the design after implementation changed, the AI often used the code as its strongest source of information.

That sounds reasonable.

The code is concrete.

The code is current.

The code is easy to inspect.

But over time, design documents began filling with details that were effectively descriptions of the current implementation:

class names
function names
file paths
framework-specific structures
internal data flow
low-level implementation choices

The document was still called "design."

But it was becoming a second copy of the codebase written in prose.

That introduced two problems.

First, the documentation required constant synchronization.

Second, and more importantly, future AI agents could treat those implementation details as architectural constraints.

A temporary implementation choice could quietly become "the design."

The agent was doing something rational:

Update the design to match the implementation.

But what I actually wanted was different:

Preserve the design principles that should constrain future implementations.

Those are not the same thing.

Case 3: Correct Placement Produced the Wrong Structure

A third failure was more subtle.

I had directory-level rules explaining where documents should go.

Application-specific information belonged near the application.

System-level information belonged elsewhere.

The AI followed those placement rules.

Then the project grew.

Deployment procedures appeared under multiple applications.

Operational documents multiplied.

System documentation became increasingly crowded.

Again, no individual placement decision was obviously unreasonable.

The problem only became visible at the repository level.

Each local decision was valid.

The global structure was deteriorating.

This is one of the harder problems in AI-driven development:

local compliance does not guarantee global coherence.

An agent may correctly answer:

"Where should this file go?"

while never asking:

"Should this file exist as a separate artifact at all?"

or:

"Is this responsibility actually shared by several parts of the system?"

The Common Failure

These looked like different documentation problems.

They were not.

They were all governance problems.

I had given the AI instructions about individual actions:

preserve this
update that
put this type of file here
record verification
keep design synchronized

But I had not clearly defined the lifecycle and authority of the information itself.

The missing questions were things like:

Which documents are normative?
Which documents merely record observations?
When does working material become durable knowledge?
When should old information be removed?
What can constrain future implementation?
Who owns information shared across multiple applications?
What does "verified" actually mean?
How long does verification remain valid?

These are not coding questions.

They are information governance questions.

I Started Treating the Repository as an Information System

That changed how I thought about repository structure.

Instead of organizing documentation only by document type, I started thinking in terms of several responsibilities.

Authority

What information is allowed to constrain future implementation?

A requirement can.

A design principle can.

A temporary investigation result probably should not.

Lifecycle

How does information move from:

investigation → adoption → verification → retention or disposal?

Not every useful note deserves to become permanent documentation.

Evidence

What supports a claim?

"This file exists" is different from:

"This is implemented."

And that is different again from:

"This was verified under these conditions."

Placement

Who actually owns this information?

Application-specific knowledge and system-wide operational responsibility should not be mixed merely because one application happened to trigger the work.

After Changing the Rules

Once I changed the repository governance, the AI did not suddenly become smarter.

That is the interesting part.

It was still the same kind of coding agent.

What changed was the environment in which it was reasoning.

Instead of asking the AI to infer the role of every document from context, the repository provided stronger boundaries between:

plans
formal deliverables
durable references
temporary working material
verification material
execution-environment configuration

This reduced a surprising amount of ambiguity.

The goal was not to tell the AI exactly what to write.

In fact, overly specific rules create their own problems.

The goal was to give the agent enough structure to answer a more important question:

What kind of information am I dealing with right now?

This Became AIDD Skeleton

I eventually extracted these ideas into a reusable repository template called AIDD Skeleton.

AIDD Skeleton on GitHub

It is a lightweight repository structure for AI-driven development, built around the idea that developers and coding agents need more than coding instructions.

They also need shared rules for:

planning
implementation
references
working material
verification
information ownership
document lifecycle

The structure currently looks roughly like this:

plans/       Project plans and sources of truth
products/    Formal implementations, tests, and deliverables
references/  Durable non-normative reference materials
workbench/   Working, exploratory, and verification materials
etc/         Execution-environment configuration

Directory-specific AGENTS.md files define the responsibilities and boundaries for each area.

The project is still evolving.

I am not claiming this is the universal solution to AI-assisted software development.

But the failures that led to it changed my view of the problem.

The Hard Part Is No Longer Just Getting AI to Follow Instructions

A lot of discussion around AI coding focuses on prompting:

How do we make the agent follow the rules?

That is obviously important.

But there is another problem waiting behind it.

What happens when the rules themselves produce bad long-term behavior?

An AI agent can be perfectly compliant while slowly creating:

duplicated documentation
stale evidence
accidental sources of truth
implementation-biased design
fragmented operational knowledge

At that point, better prompting is not enough.

The repository needs governance.

And as AI agents take on longer-running development tasks, I suspect this will matter more than we currently expect.

DEV Community: joyrswd