Your Project Documentation Is Also a Prompt

I once opened a project README and found one version of an app described as "the corrupted refactor."

That phrase sounds like a technical conclusion. It was not. It was one person's view during a disagreement about which version of the app should survive.

The problem was not just that the wording was unfair. The problem was that every AI assistant entering the project read it as fact.

One of those assistants began planning around the assumption that months of work were damaged and disposable. The README had quietly become a prompt, and it was a very powerful one.

AI reads confidence as authority

Human developers bring social context to documentation. We notice tone. We remember who wrote something and why. We may know that a sentence was added during an argument and never reviewed.

An AI agent usually has none of that.

It sees a file named README.md, AGENTS.md, DECISIONS.md, or PROJECT_NOTES.md and gives it weight. That is normally useful. Project files are how we tell an agent about conventions, architecture, commands, and constraints.

But the same mechanism makes careless wording dangerous.

Compare these:

The refactored app is corrupted and should not be shipped.

Two implementations currently exist. The team has not agreed which one will become the release version. Do not delete, deploy, or merge either version until that decision is recorded.

The first statement turns an opinion into a command. The second records the situation and gives the next person a safe boundary.

Documentation can change what the AI does

Developers often think of documentation as descriptive. With coding agents, it is also operational.

An agent may use the README to decide:

• which folder is authoritative
• which commands are safe to run
• whether a feature is complete
• whether old code should be removed
• which version should be deployed
• whether an apparent disagreement has already been settled

That means a casual sentence can affect real files and real releases.

Comments inside code have the same problem. A comment saying "temporary, remove later" can encourage an agent to remove something that became permanent. A stale note saying "unused" can outweigh the evidence that the function is still called indirectly.

The AI is not being reckless. It is following the project context we gave it.

Facts, decisions, opinions, and open questions

I now try to separate four kinds of information when writing project notes.

Facts are things that can be checked:

• The live iOS app uses bundle identifier X.
• The website deploys the public folder.
• Version 2 can read version 1 data.

Decisions say what has been agreed:

• We will keep the current store listing.
• New pages will use plain JavaScript.
• Production deployment requires a human confirmation.

Opinions need attribution:

• Arthur prefers the newer navigation.
• One reviewer believes the refactor is harder to maintain.

Open questions must remain visibly open:

• Which implementation will become the release branch?
• Is the old data format still present on user devices?

When these are mixed together, an agent has to guess. When they are labelled honestly, it can act with much better judgment.

Write the safety boundary into the file

If a disagreement affects an irreversible action, the documentation should say exactly what must not happen.

For example:

Release decision pending. Do not upload either build to an app store, delete either source tree, or change the production branch without confirmation from both maintainers.

That is much safer than hoping the next session will somehow inherit the conversation that produced the disagreement.

AI conversations are temporary and often platform-specific. A note in the repository is durable. It follows the project into the next session, the next model, and the next computer.

Review documentation like code

We review code because code changes behaviour. In an AI-assisted project, documentation can change behaviour too.

Before giving an agent broad access to a project, I now ask:

• Are any opinions written as facts?
• Are old decisions still presented as current?
• Do warnings explain when they can be removed?
• Are destructive or release actions clearly gated?
• Could a new contributor understand what is settled and what is disputed?

This does not require formal paperwork. A short, accurate note is enough. The goal is not to document every conversation. It is to prevent missing context from turning into confident action.

Your README is no longer only for people. It is part of the operating environment for every AI agent that works on the code.

Write it like the next reader may have the power to ship.