My project context is moving into Markdown
I'm writing a lot more Markdown files lately. Stuff I'd have put in Linear, or next to the design system in Figma, now lives in files called PROJECT_STATUS.md and DESIGN_QA.md. I never decided to change how I work. I just kept needing a place for things both I and an agent could read.This one began as a to-do list
A task needs some history. A design decision needs a reason. A bug needs a note about what was supposed to happen. When that's spread across five tools, I end up copying it between them. The files started as a way to stop doing that.
It's a pretty boring fix. A heading, a few sentences, a list of what's still open. Enough to pick the work back up without rebuilding the whole conversation in my head.
# Portfolio — status
Updated **7 Sep**. Read this before touching the notes reader.
## Settled
- Prose runs at `--text-sm` over a 34rem measure. Don't reopen it.
- Marginalia is two notes an article, one in each gutter.
## Still open
- Whether the sheet keeps growing past `56rem` on very wide screens.
- The archive has no empty state. See [design QA](./DESIGN_QA.md).
> If a new element won't fit the four type steps, change the element.
The explanation belongs near the work
An agent can read a component and see how it's built. It can't see why. The odd spacing might be on purpose. The screen might be an experiment. The thing that looks unfinished might be waiting on a decision, and polishing it now is wasted work.
That's what I write down. The status file says what's settled and what's still open. The design QA file lists what feels off in the real interface. A few lines about the design system stop the next change from inventing a fourth version of the same button.
And I read these files too. I don't want instructions that only make sense to an agent. If I open a project after two weeks away and the file reminds me what I was thinking, it already earned its place.
A file can become another place to forget things
A file doesn't stay true on its own, though. A status file describing last week is worse than none. It has a confident name and it sounds sure of itself, so someone will believe it. Usually the agent.
Every new file is a small chore. Two files describing the same decision will eventually disagree. And if every passing thought turns into a rule, the project gets harder to understand, not easier.
I'd rather keep a short note about what we decided than a long log where every dead end looks as important as the current plan. History is fine. It just has to be obvious which parts still apply.
Use the format that helps the next step
I haven't given up on canvases or task trackers. Sometimes one picture saves three paragraphs. A team needs somewhere to assign work and see who's blocked. A folder of text files is bad at both.Kept Linear for the team parts anyway
But for the context I keep repeating, a small file next to the code is where I start now. I can edit it mid-task, and the next session doesn't start from zero.
Before I add another one, I ask what it'll help me or the agent understand next time. If I can't answer that, I don't make the file.
Acknowledgements
From my own draft. PROJECT_STATUS.md and DESIGN_QA.md are the two files I actually keep for this site.