# Code decisions

A record of why a codebase is the way it is: how it fits together, where things are, and every decision with its reason, kept by the agents that change the code.

This is a recipe from flie: a person can read it first, and an agent follows
it. It makes one folder in the person's flie, with a README in it that holds
the rules, so every agent that opens the folder later works the same way.

## 1. Make sure flie is set up

If the `flie` command is not found or `flie whoami` says nobody is signed in,
and you have no flie tools over MCP, set flie up first, with the person's
authorization, by following https://flie.sh/setup.md
Then come back here.

The steps below are `flie` commands. Over MCP, call the tools of the same
names, with the same arguments written as named arguments, and pass a file's
text as `content` instead of `--from`.

## 2. Make the folder

`flie whoami` prints the person's Root folder. Make the folder there unless
the person names another place. If a folder called "Code decisions" is already
there (`flie agent list <root ID>`), use it: read its README and follow it
instead of starting again.

    flie agent mkdir <root ID> "Code decisions"
    flie agent mkdir <folder ID> "decisions"

Each command prints the new item's name and its ID; every later command names
the item by that ID. Laid out, the folder is:

    Code decisions/
      README.md             the rules
      architecture.md       how it fits together
      where things are.md   what lives where
      decisions/            one file per decision

## 3. Write the README, then start

Write this README into the folder, adapted where the person says so, with the
text on stdin:

    flie agent create --from - <folder ID> "README.md"

~~~markdown
# Code decisions

Why the code of <the repository> is the way it is. Agents keep this folder up to
date as they change the code; people read it.

- architecture.md: how the system fits together. Update it when the structure changes.
- where things are.md: where each part of the code lives and what it does.
- decisions/: one file per decision, named "0001 short title.md", numbered in order.

## A decision

    # 0012 Short title
    Decided: 2026-09-30, by <who>
    What: the choice, in one or two sentences.
    Why: the reason, and what would make it wrong.
    Instead of: what else was considered, and why not.
    Links: the files, commits or pull requests it touches.

## When to write one

- When you make, or are told, a choice someone reading the code later would ask
  "why" about: a dependency, a structure, a workaround, an approach turned down.
- Before you finish a task, check whether it made one.
- Never rewrite a decision. When one changes, write a new one that names the one
  it replaces.
~~~

Then create architecture.md and where things are.md the same way.

Fill both from the repository as it is now. Write a decision for each choice the code makes plain; where you are inferring the reason, write "Why (inferred):" so a person can confirm it.

## 4. Add one line to the repository

Add this line to the repository's AGENTS.md, or to CLAUDE.md if that is the
file it has, with the folder's real ID in place of fld_…:

    Before and after your work, read and update the flie folder "Code decisions" (fld_…), following its README.

If it has neither, create AGENTS.md with just this line. Tell the person, since
the change is theirs to commit.

## Done

Tell the person what you made and give them the folder's link
(`flie agent link <folder ID>`).
Editing its README changes the rules for every agent that reads it. How to
change a file without losing anyone's edits: https://flie.sh/skill.md.
