An AI-Era Code Style Checklist

This is the short version: the rules, stripped of the reasoning. If you want the case for why each one earns its place, read the long form, Writing Code for Readers Who Don’t Remember. Here, just the checklist.

The one rule above the rest: when “easier for the AI right now” conflicts with “maintainable for a human for years,” the human wins.

Types and contracts

Use types at every boundary. Make illegal states unrepresentable: an enum beats a string the reader can misuse. Validate untrusted input once at the edge, then pass typed values inward and trust the interior.

Tests

Treat tests as primary documentation. Name them so a failure reads like a sentence: rejects_sync_when_cursor_is_stale. Cover the gotchas and the ordering surprises, not just the happy path.

Comments

Comment why, never what. // loop over users is noise. // vendor API rejects batches over 50, see TICKET-411 is gold. Delete stale comments on sight. Never narrate intent for the model’s benefit.

Error handling

Fail loudly, fail early. No silent catches. Write messages that name the thing and the expectation: “expected non-empty sync_id, got null in reconcileBatch.”

Indirection

Minimize runtime indirection that cannot be traced statically: deep inheritance, dynamic dispatch, reflection, event spaghetti. Aim for one obvious path through the common case.

Naming and structure

Names state intent, not mechanics: retryableHttpClient over client2. Make them unique enough to grep. Avoid data, handler, process, value as standalone names. One verb per operation. One concept per file, named after the concept. No utils.js junk drawer.

Functions

Small, single-purpose, honest signatures, no hidden side effects. Prefer obvious code over clever code. Abstract on the third repetition, not the first. Do not split a module just to fit a context window.

Context layer

Keep a project-root CLAUDE.md or strong README: conventions, the architecture in three honest paragraphs, the landmines. Add per-module notes for anything non-obvious. Fix context here before contorting the code.

The merge test

Before you merge, ask: could a sharp newcomer with no project context understand this by reading and searching, without asking anyone? If yes, the AI can too, and so can you in six months.