Most developers have tried a note-taking system and quietly abandoned it. The pattern is predictable: an enthusiastic weekend of setting up folders, templates, and tags, followed by three weeks of dutiful filing, followed by nothing. The system failed not because notes are useless but because the system cost more than it returned.
This post describes a system designed around that failure mode. The principles: capture must be nearly free, structure must be optional, and retrieval must not depend on your past self's discipline.
What developers should actually capture
Not everything deserves a note. Four categories reliably pay for themselves:
Fixes and their causes. The moment a stubborn bug yields, write one line: the symptom and the actual cause. "Flaky auth test — timezone-dependent, freeze the clock." This is the highest-value note you can take, because the same error will find you again, and the error message is exactly what you will search for.
Decisions and their reasons. Why cursor pagination over offset. Why the retry lives in the worker, not the client. The decision itself survives in the code; the reason survives nowhere unless you write it down, and it is the reason that future-you needs.
Commands and incantations. The exact flag combination, the deploy sequence, the jq one-liner. Anything you have looked up twice.
Half-formed ideas. The refactor you cannot do today, the product thought that arrived mid-standup. These are the notes with the longest payback period and the highest evaporation rate.
What to skip: things your tools already record (git history, ticket systems) and raw transcripts of anything. Notes are for conclusions.
Rule one: capture must cost under five seconds
The size of your note vault is determined almost entirely by capture friction. At twenty seconds per capture — find the app, pick a folder, choose a title — only Important Thoughts clear the bar, and the four categories above mostly don't feel Important in the moment. At two seconds, everything clears the bar.
Concretely, that means capturing from wherever you already are:
In the terminal: a CLI capture tool. With Notez,
notez "the fix was the connection pool size"— a 3 MB binary that works over SSH and accepts piped output, so a stack trace goes in with| notez.In the browser: something reachable from the address bar. Typing
notez.dev/your thoughtturns the URL into a note — no app switch at all.In an AI session: if your assistants speak MCP, have them write findings and decisions directly into the vault ("save a note about what we decided here").
The common property: no destination decision, no title, no formatting at capture time. One inbox, everything lands in it.
Rule two: structure is added later, and only where it earns rent
The old advice — file every note into a hierarchy — was a tax paid to keyword search, which needs help finding things. With meaning-based search, an untitled two-line note is findable by content, so the default amount of organization should be zero.
Add structure only where it does a job search cannot:
Tags for enumeration. When you need all notes of a kind — every
1on1, everything taggedresearch— tag them. Search finds similar notes; tags guarantee complete sets.Links for relationships. Keep a stub note per project and system; link it (
[[in Notez) whenever it comes up. Backlinks then maintain a live index of everything touching that entity, with no filing.Boards for notes that behave like tasks. A kanban view over notes covers the "things to try" pipeline without a separate task app.
Favorites for the daily five. The notes you open constantly should be one click away, not one search away.
Rule three: retrieval must survive your own inconsistency
The system has to work in month six, when you no longer remember what words you used in month one. Two mechanisms cover this.
Semantic search matches meaning, not vocabulary — "that caching idea" finds the memoization note. This is the single biggest upgrade over grep-your-notes systems, because it removes the requirement that you and your past self agree on terminology.
Asking questions goes one step further: instead of hunting for the note, ask the vault. Notez's ask feature retrieves the relevant notes and answers with sources — "what have I written about the import pipeline?" returns an answer you can verify against the underlying notes.
A weekly ten-minute review, not a filing hour
The only recurring maintenance worth doing:
Skim the week's captures.
Promote anything durable: add a link to its project note, a tag if it belongs to a set.
Delete obvious ephemera. (Or don't — search tolerates noise better than you'd think.)
That's it. Reviews that take an hour stop happening; ten minutes survives busy weeks.
Own your exit
One meta-rule for choosing tools: your notes will outlive any app, so pick tools that admit it. Plain-text or markdown export at any time is the bar — Notez exports a whole workspace as a .zip of Markdown files with their attachments, and whatever you use should clear it too. A system you can leave is a system you can trust with ten years of thinking.
The whole system on one screen
Capture from where you are, in under five seconds, into one inbox.
No folders. Tags for complete sets, links for relationships, favorites for daily notes.
Retrieve by meaning; ask questions when hunting is slower.
Ten minutes of review a week.
Markdown export as the escape hatch.
It is deliberately boring. Boring is what survives contact with a busy month — and a system still running in month six is worth more than any elaborate one that didn't make it past three weeks.
Continue reading
How to Take Notes From the Terminal — three ways to take notes in a shell, from
echo >> ~/notes.mdto a capture CLI, and where each one breaks when you need the note back.Getting Started With the Notez CLI — the install commands for macOS, Linux and Windows, where
notez loginkeeps its key, and scripting with--json.Webhooks: turn anything that speaks HTTP into a note — one URL turns a GitHub event, a Zapier step or a cron job into a note, with tags, attachments and an optional signature check.