- Created: 2026-06-08
- Last Modified: 2026-06-08
An honest, in-progress record of standardizing how I work across my personal projects with Claude Code — spotting the failure modes that kept recurring, and working toward conventions that prevent them.
This is not a polished "best practices" repo. It is the working notebook of a still-running effort: surface every problem first, understand it, then decide what becomes a standard. The value here is the reasoning and the trail of mistakes — what went wrong, why, and what I'd do differently.
Working with an AI coding agent across a dozen-odd projects, the same problems kept resurfacing: documentation going stale, guidance files quietly bloating, research getting cited without checking whether it was still true, and projects drifting so far from their original intent that a rewrite felt easier than a fix. None of that is the tool's fault alone — a lot of it is workflow: the conventions I never wrote down, so every session reinvented them and the drift compounded.
This repo is the attempt to name those failure modes and design durable guardrails against them.
Start here, then:
docs/working-topics.md— the heart of it. Every topic area under examination, with findings from reviewing my own projects.docs/documentation-guidelines.md— the first standard actually pinned down (timestamps, doc location).
This is a curated public cut — the messier working scaffolding (session handoffs, the running task queue) lives in a private mirror, not here.
A few themes that recur throughout:
- Enforce at write time, not review time. The most consistent conclusion: guidance rots through silent incremental growth. A rule that fires at the moment of writing beats one that hopes for a later cleanup that never comes.
- Pointers over inlining. Large blocks of content belong in their own file, reached by a reference that explains what's there and when to consult it — never pasted inline where they bloat the guidance file.
- Drift is a signal. When a guidance file fills up with "what it currently does vs. what it was supposed to do" caveats, that's an early-warning siren, not a documentation style.
- Provenance over recency. LLMs reliably fail to check when information was published or whether a cited issue is still open. Confidence should rank the kind of source, not how often a claim is repeated.
Every reference to a specific personal project has been replaced with a descriptive label — "a job-search web app," "a knowledge-provenance system," and so on. The contrasts between projects are where most lessons live, so the labels are kept distinct and accurate; only the names are withheld. This public version is generated from a private working copy by a deterministic script, so nothing here was hand-edited after the fact.
Active and deliberately unfinished. The work is at the "surface and understand everything before ranking anything" stage — no premature prioritization. Expect this to grow.
© 2026 xVir. Licensed under CC BY 4.0 — share and adapt with attribution.