Blog
Record Decisions and Their Reasons as You Go
Part 3 of Knowledge Up, Context Down, about project knowledge. Recording decisions and their reasons while you work.

New to this series? Start with the overview. Previous: part 2. Next: part 4.
The project level
In Part 1 – Fast with AI I described a proof of concept where I lost track of decisions. Because it was just a proof of concept, I hoped I could skip some of the detail in decision-making. Only when it was too late did I find out I had moved too quickly. The project had no single place where decisions and their reasons were recorded. Every new session started from the code and the chat history, and neither fully explained why things were the way they were.
The question for this part: what is the minimum a project needs to record so that people and AI can keep working on it?
Why this level matters
Some knowledge frameworks skip the project level and go straight from personal notes to a team wiki. In my experience, projects are where personal knowledge first meets other people and gets tested in practice. That makes it the main link between personal and team.
What belongs at this level
- Goal and scope: what we're doing, and what we're not.
- Decisions and reasons: the reason matters more than the decision itself.
- Constraints: budget, deadlines, things not to touch.
- Status: what's done, what's open, what's next.
This knowledge is relevant now and mostly irrelevant once the project is over, except for a few lessons.
This list sounds simple, but knowing what actually matters is often the hard part, even for a proof of concept. You often need input from other people, and sometimes those people don't know yet what they want or need either. That is normal, especially early on. It's also why the open questions in a project's records matter as much as the decisions: they show what is still unknown, and who should decide.
A state file instead of chat history
Letting the AI read all earlier conversations doesn't scale: full chat histories get noisy, expensive and less accurate.
A short state file per project works better, read by people and agents at the start of each session. Agent tools already work this way: Claude Code reads CLAUDE.md files from the repository, and over 60,000 open-source projects use AGENTS.md, according to its site.
From my own experience I'd add one thing: record who made each decision. An AI decision based on an assumption is different from one you made deliberately.
Below is a state file for a small proof of concept, with an example of what each section could hold:
# Chatbot proof of concept
## Goal
Find out whether an AI assistant
can answer common support
questions.
## Out of scope
Live customer traffic.
## Owner
Sam
## Decisions
- 2 Oct: Use only the FAQ pages
as input, because they are
already reviewed.
Decided by: person, confirmed.
- 5 Oct: Split long pages into
one topic per section, because
answers improved after a first
trial.
Decided by: AI, not yet
confirmed.
## Open questions
- Should the assistant hand over
to a person?
Decides: product owner, before
the demo.
## Status
- Done: first version answers
questions from the FAQ.
- Next: try it out with the
support team.
Keeping it next to the code
In our team we keep project knowledge, like decisions and status, in the repository itself, as plain markdown files that people and agents both read. The format is the Open Knowledge Format (OKF), an open, vendor-neutral format from Google Cloud that stores knowledge as markdown files with YAML frontmatter. We use it for decision records, architecture diagrams, proposals, practices and handoffs between sessions. For writing and validating these files we use okf-skills, a toolkit by Marco Boffo: agent skills that help AI tools write the files correctly, and a GitHub Action that checks them automatically.
To maintain those files we use kmctl, a CLI and agent plugin built by my colleague Jasper. At the start of each session it gives the agent a briefing: where knowledge lives and what is due for review. When the agent records a decision, kmctl adds the bookkeeping and the agent writes the reasoning. On every pull request, kmctl checks that indexes and links agree, without using AI. Whether a page still matches the code takes judgment, so an opt-in audit agent reports drift, and a person decides what to fix.

At the end: what survives the project?
Projects rarely end cleanly. A proof of concept stops, or turns into something bigger. That moment is when to decide what to keep.
When my proof of concept was done, I archived its repository, so we can always go back and learn from it. The findings went into an RFC: a proposal the team could discuss and decide on. That's the pattern I'd recommend. Archive the project, and move what you learned up as a proposal.
Three questions to ask at that moment:
- What did the AI repeatedly get wrong? That usually means context is missing at a higher level.
- What would we do differently? That's a lesson for the team.
- Which decisions will other projects run into? Those may become team standards.
The rest goes to the archive: still searchable, but no longer part of the default context. Part 6 – The flow covers the signals for moving knowledge up.
Open questions
- When should a decision made by the AI need explicit confirmation before it is recorded?
- At what length does a state file become too long to be useful as context?
For leaders: ask your teams where their decision records are, and who confirms decisions the AI made.
For developers: start a state file in your current project, by hand or with a tool like kmctl that sets it up and keeps it current. Then let your agent read it at the start of each session.
Further reading for developers:
- Open Knowledge Format announcement: Google Cloud's introduction of OKF, markdown files with YAML frontmatter.
- kmctl: a CLI and agent plugin that keeps a repository's knowledge current, with a check on every pull request and an opt-in audit for drift.
Next, part 4: A Shared Way of Working That Everyone Can Check
Written by
Our Ideas
Explore More Blogs

Knowledge Up, Context Down
AI tools work better with the right context. This series covers four levels of knowledge, and when knowledge should move up, flow down or be removed.
Roel Bertens
Contact












