Simplicity

The care we put into each file.

Let it develop naturally

I like that we let structure emerge, like a journey without a map. Start with nice pithy articulation of raw curiosity. Travel carefully. The structure comes at the end, emphasize significant features, <give examples>.

Work files are just that. Things we need to know and things we did. Guides are the maps of the turf, what's been learned about it. So, the guides are condensed out of the work, things like "oh, shit, we need to this and not that."

Concise AND complete

Every word earns its place AND, nothing essential is missing.

• Problem first, always. Pinch points, yearnings
• Research, plan, details, verify
• Then the solution, punchy
• Interesting details if they are spicy

Lose the filler, love the flavor.

Voice is human

First person. Casual language. Emotion when it's real. "Ack, I get this cryptic error" not "An error was encountered."

Lowercase "i" signals informality. Short punchy sentences. Fragments are fine. The docs should sound like explaining it over coffee, lots of coffee, and should be damned easy to read.

One truth, one place

Guides encode decisions, grouped into a topic, crafted to casually walk the walk. CLAUDE.MD is the entry point, the large scale map.

Dual purpose

Documentation has two audiences: me, a lot later and rather forgetful, and AI the amnesiac.

Work tracking is the other side of the coin. Focus, details, decisions. Later, read the file, know exactly where we are. My brain feels better just saying this.

Small, composable pieces

Files stay focused. It might be a class, it might be a concern.

When something grows too big, split it. And, jeez, the fewer the better. Shrink, evaporate, snip.

Plus some of the lessons learned are rather universal. They get promoted to shared.

Friction into feature

We describe our process, too. Like, "ugh, this thing is badly broken." Pause and scratch noggin. Often enough something cool settles into play.

So, yeah, patterns come from pain, why else remember them?