How to keep a decisions log for AI

How to keep a decisions log your AI will actually readMost decisions are made in a conversation and never written down anywhere. That was survivable when the only people who needed to know were in the room. It is not survivable now, because the thing doing half the work was not in the room and has no way to find out.So an agent reads your code, reaches a reasonable conclusion, and proposes the idea your team considered and rejected in March. It is not being stupid. Nothing it can read says the question was ever asked.One file, three listsA decisions log does not need a process. It needs to exist, to be in one place, and to be short enough that somebody keeps it up.# Decisions ## Decided - Launch in the UK only (March): regulation elsewhere is unclear - Price per clinic, not per seat (April): per-seat punished clinics for adding reception staff ## Ruled out, and why - A mobile app for launch: the web app works on phones, and one codebase is enough for two people - MongoDB: the billing tables need real transactions ## Still open - Whether to offer a free tierWhy each line has a reason attached

A decision without its reason is a rule, and rules get argued with. A decision with its reason survives the next person who thinks they have a better idea, including the next AI.

The reason is also how you know when to change your mind. "Regulation elsewhere is unclear" is a fact that can stop being true; "UK only" on its own tells you nothing about when to revisit it.

A date lets a reader judge how much weight to give it. A decision from last week and one from two years ago are not the same kind of claim.

The ruled-out list is the valuable halfEverything you decided to do leaves traces. It is in the code, the schema, the invoices. An AI can usually reconstruct it.What you decided not to do leaves nothing. The thing you refused never became a document, a commit or a table. It is the most expensive knowledge your project has and the only kind with no physical evidence — which is exactly why it is the thing that comes back, repeatedly, from every tool you use.If you write down nothing else, write down what you turned down and why.Making it a habit

Keep it at the top level of the project, named so that it is obvious: DECISIONS.md.

Point your instruction files at it. One line in AGENTS.md — "read DECISIONS.md before proposing a change to anything it covers" — is what makes an agent use it.

Add the line when the decision is made, in the meeting or straight after. A log written retrospectively is a log of what somebody remembered.

Never delete. Move things between the three lists. A decision you reversed is more useful than one that vanished, because the reversal is itself a decision.

Keep it to one file for as long as you can. Several decision logs is the same problem as several instruction files.

What a log cannot do on its ownA file only helps if whatever is about to repeat your mistake happens to read the relevant part of it first. Nothing guarantees that. An agent proposing something in a different document, in different words, months later, will not necessarily be looking at your decisions log, and will not know that the thing it has just invented has a history.This is the part Canonly does. When something proposes a change — you, an agent, or a skill reading your meeting notes — it checks what you have already decided about substantially the same thing, in whatever words it was decided, and answers with the earlier decision, its date and its reason. A refusal is kept as knowledge rather than discarded, which is what makes it possible to answer the same idea twice.Canonly · Pricing · For developers · Templates · Guides · AGENTS.md generator · Canonly and ChatGPT Projects · Help · Export format