engineering-rules

Engineering Rules

Turns Claude into the repo's staff engineer: every diff it produces already passes the review these seven rules describe.

When to Use This Skill

• Implementing any feature, fix, or refactor, in any language
• Self-reviewing a diff before commit or PR
• Cleaning up AI-generated or copy-pasted code
• Writing code samples for skills, docs, or references
• Reviewing someone else's PR against repo standards
• Deciding whether to extract, inline, or delete code

Core Workflow

1. Search before writing. Grep the codebase for an existing helper, component, or util that already does the job (search by domain nouns and verbs, not just exact names). Reuse or extend it; only write new code when nothing fits.
2. Implement. Small single-responsibility units, follow the project's existing structure and idioms, configuration over hardcoded values, no new global state.
3. Run the rules checklist over the diff (the seven rules below, each is concrete and checkable):
   • Rule 1, Reusable: no copy-paste variants; shared shape appearing a second time is extracted.
   • Rule 2, Maintainable: units small, module boundaries clear, dependencies point one way, nothing hardcoded that belongs in config.
   • Rule 3, Readable: intention-revealing names (no data, tmp, handle, process2), early returns over nesting, reads top-down.
   • Rule 4, No AI slop: scan the diff against references/ai-slop-checklist.md item by item.
   • Rule 5, Dead code: everything your change made unreachable is deleted; zero commented-out code; orphaned exports removed.
   • Rule 6, Comments: every comment states a non-obvious why; any comment narrating what gets deleted or the code gets rewritten.
   • Rule 7, No em dashes: grep -rn "$(printf '\xe2\x80\x94')" over changed files, in code, comments, docs, and commit messages; returns nothing.
4. Fix all violations and re-run the checklist until clean. A single pass is never assumed sufficient; fixes for one rule often introduce violations of another.
5. Run the project's formatter and linter (e.g. prettier --check . + eslint ., ruff format --check && ruff check, gofmt -l . && go vet ./...); fix every reported issue and re-run until clean.
6. Verify behavior. Run the project's tests for the touched area; debug failures before declaring done.