Outdated Documentation Can Send Your AI Coding Assistant Backwards

I had already abandoned and removed an opening-hours implementation from a restaurant project. The documentation was still there.

When I returned to the feature with an AI coding assistant, those documents caused confusion about what still existed and which direction we were taking.

The requirement itself had survived. Restaurants still needed opening hours. The earlier implementation had not. That distinction needed to be explicit in the project documentation.

How old plans become current instructions

A repository can contain several descriptions of the same feature: an initial proposal, an approved plan, implementation notes, and a later decision to replace it.

All of them may have been accurate when written. Together, without clear status, they can give a coding assistant conflicting directions.

Some documents have an especially direct route into the model’s context. Cursor’s project rules, for example, provide reusable instructions that are included when the rules apply. A stale architectural assumption in those rules can influence subsequent work.

Ordinary project documents are different. They are not necessarily loaded automatically, but they can still become context when an assistant searches the repository or follows a reference.

The practical risk is that a detailed old plan looks ready to execute. It has filenames, models, endpoints, and acceptance criteria. The decision that invalidated it might exist only in a conversation.

Separate the requirement from the implementation

“Remove Hours” is an ambiguous instruction. It could mean remove the product capability, discard the current implementation, or replace the underlying approach while keeping the user-facing behavior.

In this case, the old implementation had been abandoned, but the product still needed a way to handle restaurant availability.

1. 01Product requirementStill required

   Restaurants need opening hours. Removing a particular implementation does not remove that need.

2. 02Earlier implementationAbandoned and removed

   The previous Hours implementation was discarded. Its documentation must not direct new work toward extending it.

3. 03Surviving requirementNeeds a current decision

   Availability still belongs in the product. Confirm the intended behavior and approach separately from the retired plan.

4. 04Replacement statusVerify before editing

   Inspect current code, decisions and tests. The old plan cannot establish whether a replacement exists or works.

A useful status note would make that separation explicit. The example below is a documentation pattern, not a claim that the replacement has been completed.

Give each document a clear job

I would separate project documentation into three roles:

A plan should not become evidence that a feature exists. Approval should not become evidence that it works.

For implementation notes, use statuses that describe observable facts: planned, implemented, verified, or removed. For decisions, use proposed, accepted, superseded, or abandoned.

These describe different things. A decision can be accepted while its implementation is still unfinished.

Try the distinction

What does the evidence actually prove?

“The endpoint exists and its handler is wired up. Nobody has checked the full user flow yet.”

Read the explanation

Implemented. The code exists. This statement does not establish that the complete user flow works. Record what was tested before calling it verified.

Retire the references as well as the code

When an approach is abandoned, deleting its source files leaves part of the cleanup unfinished.

Find the documents that still direct someone toward it. Check the project overview, task lists, instruction files, and newer plans that link back to the original design.

1. Mark the previous approach as abandoned or superseded.
2. Record what remains valid, including the underlying requirement.
3. Link to the replacement decision if one exists.
4. Remove instructions that still tell the assistant to extend the old implementation.
5. State what has actually been checked.

Moving a document into an archive folder helps people navigate. It does not guarantee that an assistant will ignore it. Search can still find it, and another file can still reference it. The status needs to be visible inside the document.

Check documentation against implementation evidence

Current code shows what is implemented. Tests provide evidence about behavior. Product decisions explain what should change. None of these can answer every question alone.

If the code contains an old implementation, that does not automatically make it the intended architecture. If a document describes a replacement, that does not prove it has shipped.

Before editing an uncertain feature, give the assistant a narrow investigation:

This is a review step, not a guarantee. Claude Code’s documentation explicitly distinguishes contextual instructions from enforced configuration and recommends reviewing instruction files for outdated or conflicting guidance.

Make documentation part of removing a feature

For an abandoned implementation, I would consider the cleanup complete only when:

• The code has been handled according to the removal decision.
• Active instructions no longer point development toward it.
• Historical documents clearly identify their status.
• The surviving product requirement is documented separately.
• The replacement’s progress is described without overstating what has been tested.

There is no need to erase the history. The reasoning behind a failed or abandoned approach can still be useful. But the next development session should be able to tell that it is history.

In the opening-hours case, the missing information was straightforward: the previous implementation was gone, the requirement remained, and the next step needed to start from the current project state. That belongs in the repository, where the next person or coding assistant can find it.