Write It Down, Sort It Later

The advice underneath all of my project docs: stop caring about structure, and if in doubt, write it down. How a plain folder of markdown notes became the place a team and its agents do their thinking.

A lot of my thinking now happens in conversation with an agent. I open a problem, talk it through, let it push back, and because I start the conversation inside the project repository, it already has the context: my past thinking on the topic, the code, the architecture, the decision records. It is not a blank assistant, it is one that knows the project. Do this across a whole team and the value compounds.

Which leaves the one question that has stalled me more often than I would like: wherever the conversation gets to, where does that thinking go? Getting it written down was never the hard part. Deciding what it is, which folder it belongs in, and what to call it, that is where I would freeze.

The friction is never the writing

I decide I need to introduce authentication into a project. I talk it through with an agent, get it to grill me on what I have not considered, and we reach some conclusions. Good. Now: what is this and where should it live?

It is not a spec yet, it is more of an exploration, so I drop it in some “explore” folder. A few days later I pick it up and it has firmed into something closer to a spec. Later still I break it into steps, and now it is a plan. Every time I come back I am not just working on the problem, I am grappling with what this document is, which folder it belongs in, and what it should be called.

And once I had picked a folder, I would want it to match the format: does this fit the spec template, have I filled in every heading, is the structure right?

The doorway costs more than the room.

Everything is a Technical Note

So stop deciding up front. Everything is a Technical Note.

A TN is one primitive. It has a status, a kind, an incremental number, and a link to the issue it came from. The kind is a loose label, closest fit rather than a rule: exploration, spec, plan, proposal, research. When the auth note graduates from exploration to spec, I change one word, and the note does not move, does not get renamed, keeps its number and its history. There is no template to satisfy, and a note can be a single bullet.

A document’s type is not fixed: the auth note was an exploration, then a spec, then a plan, the same thinking throughout at different stages of maturity. A system that makes you commit to a folder and a template up front is fighting that, because every folder is a bet on a classification that is about to change.

Parking a thought becomes cheap. Wherever a conversation with an agent gets to, I drop the result into a TN and move on, and later I open it again, say “grill me further on this,” and it grows. The note is a place the thinking rests between sessions, not a document I owe anyone.

Nothing lives in human (or agents) memory

The organising principle of working this way is that nothing important should live in someone’s head, or in a chat log, or in an external tool that is not in the repository. Everything about a project, aligned in one place, so the whole team and every agent can see all of it. A thought I had about CI/CD that only exists in my memory is a thought the agent cannot use and a teammate cannot find.

So the moment a thought forms, it goes in, at whatever level of completeness it happens to have. “I have been thinking about CI/CD, draft that into a TN.” Now it is a draft, out of my head and in the repo, and the next person to touch that area, human or agent, finds it.

It is also why I turn the agent’s own memory off. Most frameworks now offer one, Claude Code included, and they will quietly file away what they learn about a project into a store that lives on my machine. That store is invisible to everyone else: it does not travel to a teammate’s checkout, it does not survive me switching machines, and it means nothing to a different agent tomorrow. The knowledge the agent is leaning on has gone somewhere no one else can read or review. Written into a TN instead, the same fact sits in the repo, versioned, and there for every person and every agent that clones it. If it matters to the project, I want it in the project, not in a sidecar owned by one machine and one vendor.

If in doubt, write it down

The advice underneath this is plain: stop caring about structure, and if in doubt, write it down. There is no thought about the project too small or too unfinished to belong in the repo. The bar for starting a note is that you had a thought worth not losing, and that is the whole bar. It can be a couple of scrappy bullets marked draft, and it still counts, because even that beats the thought living in your head until the day you or a colleague need it and cannot find it.

What keeps it from being a swamp

If everything goes in, the fair worry is that the folder silts up into a swamp. Two small things I’ve found help with that.

The first is status. Every note says whether to trust it: draft is thinking out loud, active is agreed, superseded points you at whatever replaced it. That one field does most of the work, because it is what lets you write freely; half-formed ideas can sit in the open without being mistaken for settled decisions, and when a note finally hardens into something the project has to obey, it graduates out into a proper decision record. Nothing is deleted along the way, it just changes state.

The second is a number. Each note gets one, which gives it an identity to link to and gives the pile an order you can read top to bottom as the project’s history. That is close to all the structure there is.

It is also what an agent needs. It reads status to know what it is allowed to act on, follows a superseded pointer to the current thinking, and starts from the index instead of swallowing the whole folder. The thing that makes it cheap for me to park a thought at 11pm is the same thing that lets an agent pick it up the next morning or in a fortnight and trust the right parts of it.

What I do leave out

There are a couple of distinctions I do keep. The notes hold knowledge about the project: what it is, and how its thinking got to where it is. They are not a record of the work itself, items on the roadmap, where a task stands, who is on it, what is left to do. Currently I keep that in an agent-managed issue tracker, and I am content to leave it there for now.

I also have an explicit process to graduate TNs that encompass technical decisions (architectural and conventional) into separate ADR/CDR documents, which have a known format. These are cross-referenced to the TN system, but I use these additionally for agent guardrails (e.g. an “Architect reviewer” subagent blocks any new feature that introduces new concepts or violates existing DRs).

A well-worn pattern

Keeping project knowledge as markdown in a git repo is commonplace, especially nowadays, and it is settling into shared conventions: Google’s Open Knowledge Format, llms.txt, the broader LLM-wiki idea. That so many people arrive at “markdown with a little front matter, versioned in git, readable by people and agents” is a fair sign it is the natural shape rather than a clever one.

What I would like to see more discussion on is the process of storing information: what, when how and where. How should a piece of thinking move through its life, from a half-formed draft, to something agreed, to something superseded when a better idea replaces it.