Is there any decision file that you maintain for your AI project?
Several weeks after starting on the previous project, I could not understand why the dates were stored as text strings. It was proposed by the agent, I accepted the proposal, but there was no reason behind the choice. As soon as there was a bug in the calendar view, I spent an evening trying to re-understand the choice that I never actually made.
Therefore, I created an unformatted DECISIONS.md file. Every record includes the date, our choice, reasons for making this choice and alternatives. The agent prepares the initial version at the end of a session and I adjust it. It takes me two minutes.
The surprise advantage is that it can be used as context. In beginning a new session, I show the agent the file first, and it stops suggesting ideas which I have already vetoed. This saved me many repeat vetoes.
The disadvantage is maintenance. After a month, I had forty items in mine, and some were contradictory. I am considering putting in an "active" or "replaced" flag on each item. Is anybody else doing this? I would like to see other peoples' formats and whether they keep them in the repo or private.
Replies
replaced ones i'd keep, just flagged superseded with a link to whatever replaced them
Yes, but split in two, which sidesteps the forty-items problem.
A small notes folder the agent reads at the start of every session. One fact per file, each with a why line. Stuff like 'npm, not pnpm, because that's what the host installs with'. That one is private, outside the repo.
One markdown file per feature inside the repo (payments, the API, the AI coach). How it works, plus the things to know that would bite later.
When a decision gets replaced I rewrite that one file, so there's no active vs replaced flag to keep up. Git remembers the old version.
The decisions log exists because the agent kept reporting clean builds while silently undoing prior fixes. The problem wasn't the agent being wrong, it was being told everything was fine. Now the file records rejected paths so it stops re-trying them.
Yes, and I hit the same contradiction problem. Mine is split in two: an index with one line per entry that loads every session, and the details in separate files. What fixed the contradictions was one rule. Before adding anything, check whether an entry already covers it and update that one instead, and delete entries that turn out to be wrong. For the bigger "why", I keep a separate log of real mistakes, 161 so far, each with the rule it taught me.