Why Your AI Coding Agent Forgets Every Decision You Made

You run the same prompt on Monday and on Friday. The code that comes back is structurally different. Same agent, same repo, same task. Different file layout, different names, different edge cases handled.

The model is not broken. The decisions you made on Monday no longer exist anywhere the agent can read them. They live in a chat thread the agent has already forgotten.

Where the requirements actually are

Most AI coding workflows keep requirements in three fragile places: your head, the chat history, and the code the agent already wrote. None of these are a reliable source of truth.

Your head changes between sessions. Chat history scrolls out of the context window. The code itself only records what the agent decided last time, not what you actually asked for. So when you come back with a related change two weeks later, the agent reconstructs your intent from a half-visible thread and a few function names. It guesses. Different guess, different code.

This is the structural problem. It gets worse as the conversation gets longer, not better.

What changes when requirements live outside the chat

The fix is not better prompts or a smarter model. The fix is to write the requirements down somewhere both you and the agent can read, in a format that does not drift.

That is what OpenSpec does. It is a thin spec layer between you and the agent. Every change starts as a small folder of markdown files: what you want to build, what behavior changes, what the design decision was, what tasks are left. The agent reads those files before it writes code. When you come back later, those files are still there.

The workflow is three commands:

/opsx:propose add-dark-mode creates the folder with proposal, specs, design, and tasks. /opsx:apply runs the tasks. /opsx:archive merges the specs into your source of truth and stores the change.

The interesting part is not the commands. It is that the spec folder is now a real artifact in your repo. Two months from now, when you ask why dark mode works the way it does, the answer is in openspec/specs/, not in a Slack thread.

When this is overkill

If your project is a one-file script, OpenSpec is more structure than the work deserves. The cost of writing a proposal and spec is higher than the cost of just editing the file.

It also does not help if your agent work is mostly throwaway: prototypes you delete in a day, one-off migrations, scratch patches. Spec layers earn their keep on code you will touch more than once.

The smallest test

Before adopting anything, do this. Pick one feature your agent is about to build. Write down, in a markdown file in the repo: what the feature does, what it explicitly does not do, and one decision you made about how it should behave. Commit that file. Then run the agent.

If the output is closer to what you wanted, the problem was never the model. It was that your decisions had nowhere to live.