My project context is moving into Markdown
I've found myself creating more Markdown files lately. Things I would have put in Linear, or kept beside a design system in Figma, are ending up in files called PROJECT_STATUS.md and DESIGN_QA.md. It wasn't a big decision to change my workflow. I just kept needing somewhere to put information that both I and an agent could use.This one began as a to-do list
A task needs a little history. A design decision needs a reason. A bug needs an explanation of what should have happened. When those details are scattered across tools, I become the person carrying them between places. The files started as a way to do less of that.
What interests me is how ordinary the solution is. A heading, a few sentences, a list of things that still need attention. Enough context to pick up the work without reconstructing the whole conversation first.
# 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 inspect a component and see how it's built. That doesn't mean it knows why the component works that way. Maybe the unusual spacing is deliberate. Maybe a screen is an experiment. Maybe something that looks unfinished is waiting on a decision, and polishing it would be wasted effort.
Those are the details I want to write down. A status file can explain what's settled and what is still open. A design QA file can describe what feels wrong in the actual interface. A note about the design system can give the next change some boundaries before another slightly different version of the same button appears.
The useful part is that I can read the same context. I don't want a separate set of instructions that only makes sense to an agent. If I come back to a project and the file helps me remember what I was thinking, it's already doing something valuable.
A file can become another place to forget things
Of course, adding a document doesn't make it true forever. A status file that describes last week's work can be more confusing than no status file at all. It sounds authoritative. It has a sensible name. Someone will probably believe it.
This is the part I want to be careful about as I keep adding files. Every document creates a small maintenance job. If two files describe the same decision, they can disagree. If every passing thought becomes a rule, the project gets harder to understand instead of easier.
I'd rather have a short explanation of the current decision than a long record that makes every abandoned direction look equally relevant. There can be room for history, but the next person reading should be able to tell which parts still apply.
Use the format that helps the next step
I still see a reason for a visual canvas and a shared task tracker. A picture can explain a relationship that takes several paragraphs to describe. A team may need a place to assign work and see who is waiting on whom. A folder full of text doesn't automatically do either job well.Kept Linear for the team parts anyway
For the context I keep repeating, though, a small file is becoming a very comfortable place to start. I can change it while working, keep it close to the implementation, and give the next session something more useful than a blank slate.
The question I'm trying to ask before creating another one is simple: what will this help me or the agent understand next time? If I can answer that clearly, the file probably deserves to exist.
Acknowledgements
Expanded from my own draft. The file names are this site's: PROJECT_STATUS.md and DESIGN_QA.md are the two I actually keep.