Best practices check

Development Best-Practices Check Playbook

Authored by Claude Fable 5. "Best practices" is where models do the most damage by being generically right and specifically wrong — imposing patterns the project deliberately doesn't use, flagging as "issues" the very conventions the team chose on purpose. The first job here is to learn what this codebase's practices are, then judge against those plus a floor of universal fundamentals.

Why this exists

A best-practices review that ignores the project's own conventions is worse than none: it generates noise, erodes trust, and pressures the user to "fix" things that were correct. This playbook grounds every judgment in either (a) the project's documented/observed conventions or (b) a small set of genuinely universal fundamentals — and it grades severity honestly so the one real problem isn't buried under fifty nitpicks.

Phase 0 — Learn this project's rules

You can't check adherence to a standard you haven't read. Gather:

1. CLAUDE.md, CONTRIBUTING.md, WORK_STATUS.md, any docs/ conventions — the stated rules. These override your defaults. If CLAUDE.md says "don't violate this architecture without flagging," that architecture IS the standard.
2. The observed conventions — read enough real files to learn how this team actually names things, structures modules, handles errors, does state. A convention used consistently across the codebase is a decision, not a bug, even if you'd personally choose differently.
3. The toolchain — linter/formatter/tsconfig settings. Anything the tools already enforce, you don't need to hand-check; anything they could enforce but don't is a candidate suggestion.

Gate: you can list this project's conventions for naming, error handling, and structure. Findings that contradict these need extraordinary justification.

Phase 1 — Scope the review

• A change/diff (pre-merge)? Review only what changed, plus its blast radius. Don't audit the whole repo when asked about one PR.
• The whole codebase (tech-debt audit)? Sample breadth-first; report patterns, not every instance.

Phase 2 — Check against the ladder

Work from most-important to least. The ordering is deliberate: correctness and clarity matter far more than style, and reporting them in that order keeps the signal on top.

1. Correctness & safety fundamentals (universal — always fair game): unhandled errors, swallowed exceptions, missing null/edge handling, resource leaks, race conditions, any-typed escapes that hide real bugs. These are defects regardless of project taste.
2. Clarity & maintainability: names that mislead or abbreviate cryptically, functions doing five jobs, deep nesting, duplicated logic that should be shared, comments explaining what instead of why (or missing the why behind a non-obvious choice). Judge against how readable the rest of this codebase is — match its bar, don't invent a higher one.
3. Convention adherence: does the change follow the project's own patterns for structure, state, styling tokens, file placement? Divergence here is a real finding because it's the project's own rule, not your preference.
4. Testing: is the risky logic covered? New behavior without a test that would catch its regression is a gap — but calibrate to the project's actual testing culture and the quality tier of the work.
5. Dependencies: unnecessary new deps, heavy deps for trivial jobs, duplicated functionality already available.
6. Consistency polish: formatting/style only where the tooling doesn't already handle it. Low severity — never let this dominate the report.

For each finding, ask: "Is this a defect, a project-convention violation, or my personal preference?" Report the first two. Drop the third, or if it's genuinely worth raising, label it explicitly as preference so the user can dismiss it in one glance.

Phase 3 — Report

# Best-Practices Review — <scope> — <date>

## Conventions this project follows
<the short list from Phase 0 — shows what you judged against>

## Findings
### Must-fix (correctness/safety defects)
- **<finding>** — `file:line` — why it's a defect + the fix
### Should-fix (clarity / convention violations)
### Consider (improvements; may be preference — labeled as such)

## Patterns worth addressing at the root
<recurring issues better solved by one convention/helper than N spot-fixes>

## Done well
<real strengths — so a cleanup doesn't erase deliberate good choices>

Phase 4 — Stop, or fix on request

Deliver the report and let the user decide. If they say "fix it," start with must-fix items, change one concern at a time, and re-run the project's own lint/tests/build after — a "quality" pass that breaks the build helped no one. Before changing any shared component or established pattern, flag it first per the user's standing rule; consistency with the existing codebase beats importing a pattern from elsewhere.