Opinionated conventions, architecture decisions, processes, and checklists — battle-tested and version-controlled. Every project reads it first. No reinventing the wheel, no tribal knowledge.
paste into your project's CLAUDE.md
or, at the start of any AI session
Everything in the playbook exists to protect these six rules. Get them right and the surprises stay in the product — not in the pipeline, not in the merge, not in onboarding.
No ad-hoc work. Track everything. The board is the single source of truth for what is in flight, why, and who owns it.
process/issues.md
Never push to main directly. Branch names carry the issue number, so six months from now the history still explains itself.
process/branching.md
Even solo. The pull request is your audit trail, your review surface, and the place where CI gets the final word.
process/pull-requests.md
No exceptions. Lint, test, build, scan — green or it does not ship. Tests are not optional, and red main is an incident.
process/ci-cd.md
One concern per commit. Conventional Commits make the changelog write itself and turn every revert into a one-liner.
process/commits.md
Make it work, make it right, then make it fast — in that order. The next person to read this code is you, with less context.
conventions/naming.md
“No ad-hoc work. No surprises in main.” — the two rules everything else protects.
The scenario: a mid-size team ships the same feature, on the same deadline.
Everyone means well, but nothing is written down…
Same people, but the standards do the remembering…
Same people · same deadline · different discipline
Every page is plain markdown. Read it in a sitting, adopt what fits, fork what you disagree with.
Opinionated on purpose. Pick the language or the concern — the standard is already decided.
conventions/namingVariables, files, branches, endpoints — one convention across every language.
conventions/api-designResource modeling, status codes, pagination, versioning. The contract, settled.
conventions/testingThe pyramid, what to mock, and coverage numbers that actually mean something.
conventions/error-handlingFail loud, fail typed. When to throw, when to return a result, never swallow.
conventions/performanceResponse-time budgets, caching tiers, and a standing war on N+1 queries.
conventions/accessibilityWCAG 2.1 AA, keyboard nav, focus order, and screen-reader basics baked in.
The conventions explain the standard. The checklists walk you through it — one box at a time.
From an empty repo to a CI-green skeleton — branch protection, hooks, and labels included.
Access, environment, first issue, first PR. Ship on day one, not week three.
Version bump, changelog, tag, deploy, announce. Repeatable and boring, the way releases should be.
Drop-in templates for issues, pull requests, and the CLAUDE.md that wires the whole thing into your repo.
Point Claude Code — or any agent — at the playbook from day one of a new repo.
What changed, why, how it was tested, and the issue it closes. No blank PRs.
Problem, proposed solution, acceptance criteria, and an honest scope line.
Steps to reproduce, expected vs. actual, environment, and severity.
A wiki works fine until it goes stale and nobody trusts it. A playbook in Git wins on version control, PR-reviewed changes, AI-readable markdown, and living next to your code. It is unapologetically opinionated — that is the feature, not the bug. Disagree? Fork it and make it yours.
“Every new project reads this repo first and follows these standards. No reinventing the wheel.”
Read the introduction
One repo. Every standard.
From the first branch to the post-mortem — the whole lifecycle, process/ and conventions/, in one place.
Point your next project at the playbook. The standards do the remembering — you do the shipping.