Skip to content
Fredrin
Documentation

Project memory

Writing project context

Three artifacts, one rule each. Get the routing right and project memory maintains itself as a side effect of shipping.

Start with AGENTS.md

One file at the root of your repository, describing how to work in it. This is the highest-return thing you will write all week.

It follows the AGENTS.md convention, so it is not Fredrin-specific: Claude Code, Codex, Cursor and others read the same file. Point CLAUDE.md at it with a symlink and you have one source of truth.

What belongs in it:

  • How to run things. Install, dev, test, build, the ports.
  • Where things live. The map you would draw on a whiteboard for a new hire.
  • The conventions that are not obvious from the code. Especially the ones you have had to correct twice.
  • The traps. The thing that looks right and breaks production. Write these down the day you discover them.

What does not belong: anything a reader can get faster by reading the code, and anything that changes weekly.

Route by the question your change answers

Once AGENTS.md exists, new knowledge goes to exactly one of three places.

Your change answersWrite toHow often
What changedThe changelog, from a clean commit messageEvery ticket
How it works nowThe concept doc for that conceptWhen documented behaviour changes
Why you took a costly-to-reverse pathA new decision recordRarely

Most changes need no decision record. A UI tweak, a copy change, a local refactor, a flag flip: ship a clean commit, and if it changed how a documented concept works, edit that one concept doc. That is it.

Write a decision record when the path is genuinely costly to reverse and a future reader would otherwise re-litigate it: a schema change, a new public contract, a load-bearing cross-cutting surface, or a reversal of an earlier decision. A reversal is always significant, and its record must name what it retires.

Two rules that keep parallel agents from colliding

This is where teams get it wrong, and the failure only shows up once several agents are working at once.

Concept docs stay small and atomic. One concept per file. Two Workers editing two different concepts then touch two different files, and merge cleanly. A single sprawling ARCHITECTURE.md is a merge conflict generator.

Decision records are append-only. One new file per decision, never edited, never deleted. New files never conflict. Name them by date rather than by an incrementing number, because two tickets racing on the same integer collide every time.

Break either rule and you reintroduce the merge storm the rules exist to prevent.

What a Worker actually reads

At the start of a run, before it writes anything:

  1. AGENTS.md at the repository root.
  2. The concept docs and decision records relevant to this ticket.
  3. The ticket itself, its plan, and its attachments.

Nothing is injected at runtime. The Worker reads files in its worktree, which means you can verify exactly what it saw by looking at the same files.

Let it write itself

The genuinely nice property: a Worker that learns something durable proposes it back into project memory in its own pull request, as separate commits from the code.

You review it. Most of the time it is a two-line edit to one concept doc, which is exactly the size of maintenance that actually happens.

Next steps