Skip to content
Skills Library
Programming · Review & audit

engineering-rules

/engineering-rules

Use when writing, modifying, or reviewing code in any language or framework. Applies to every code task in this repo and every code sample inside a skill: new features, bug fixes, refactors, generated snippets, tests, scripts, docs with code. Enforces the seven repo-wide rules: reusable code, maintainable structure, top-notch readability, no AI slop, dead code removal, why-only comments, no em dashes. Invoke for implementing changes, self-reviewing a diff, cleaning up generated code, writing reference examples, or reviewing a PR.

Licence
MIT
Last repository change
09.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing, modifying, or reviewing code in any language or framework. Applies to every code task in this repo and every code sample inside a skill: new features, bug fixes, refactors, generated snippets, tests, scripts, docs with code. Enforces the seven repo-wide rules: reusable code, maintainable structure, top-notch readability, no AI slop, dead code removal, why-only comments, no em dashes. Invoke for implementing changes, self-reviewing a diff, cleaning up generated code, writing reference examples, or reviewing a PR.

Original author description

Use when writing, modifying, or reviewing code in any language or framework. Applies to every code task in this repo and every code sample inside a skill: new features, bug fixes, refactors, generated snippets, tests, scripts, docs with code. Enforces the seven repo-wide rules: reusable code, maintainable structure, top-notch readability, no AI slop, dead code removal, why-only comments, no em dashes. Invoke for implementing changes, self-reviewing a diff, cleaning up generated code, writing reference examples, or reviewing a PR.

How it works

  1. When to Use This Skill
  2. Core Workflow
  3. Reference Guide
  4. Key Patterns
  5. Common Mistakes
Original SKILL.md headings · 81 lines, 736 words
SKILL.md preview
---
name: engineering-rules
description: Use when writing, modifying, or reviewing code in any language or framework. Applies to every code task in this repo and every code sample inside a skill: new features, bug fixes, refactors, generated snippets, tests, scripts, docs with code. Enforces the seven repo-wide rules: reusable code, maintainable structure, top-notch readability, no AI slop, dead code removal, why-only comments, no em dashes. Invoke for implementing changes, self-reviewing a diff, cleaning up generated code, writing reference examples, or reviewing a PR.
license: MIT
metadata:
  version: "0.1.0"
  category: core
  frameworks: language-agnostic
  triggers: code quality, refactor, cleanup, review, readability, naming, dead code, comments, duplication, reuse, maintainability, ai slop, diff review, self-review
  related: react-expert, nestjs-expert, go-expert, flutter-expert, playwright-expert
---

# 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.

## Reference Guide

Load detailed guidance only when the task needs it:

| Topic | Reference | Load When |
|-------|-----------|-----------|
| Reuse and structure (rules 1-2) | `references/reusability-and-structure.md` | Adding a helper/util, seeing duplicated logic, deciding module boundaries or where code lives |
| Readability and naming (rule 3) | `references/readability-and-naming.md` | Naming anything, untangling nested conditionals, code that needs a comment to be understood |
| AI slop checklist (rule 4) | `references/ai-slop-checklist.md` | Self-reviewing any diff, cleaning generated code, reviewing a PR |
| Comments, dead code, em dashes (rules 5-7) | `references/comments-and-dead-code.md` | Writing or deleting comments, removing a feature/flag/branch, touching a file with leftover code |

## Key Patterns

**Extract on the second occurrence, not the first, not the third:**

```typescript
// Two call sites already format money the same way: extract now.
const formatCents = (cents: number, currency = "USD") =>
  new Intl.NumberFormat("en-US", { style: "currency", currency }).format(cents / 100);
```

**Early return instead of nesting:**

```python
def ship(order: Order) -> Shipment:
    if not order.items:
        raise EmptyOrderError(order.id)
    if order.status is not Status.PAID:
        raise UnpaidOrderError(order.id)
    return carrier.dispatch(order)
```

**Comment carries the why, code carries the what:**

```go
// Stripe retries webhooks for 3 days; dedupe on event ID or refunds double-apply.
if store.SeenEvent(evt.ID) {
    return nil
}
```

## Common Mistakes

- Writing a new helper without searching first. The repo almost always has one; grep for the domain term (`grep -rn "formatCurrency\|toMoney"`) before writing line one.
- Extracting an abstraction for a single caller. One implementation needs no interface, factory, or base class; wait for the second concrete use.
- "Cleaning up" by commenting code out. Delete it; version control is the archive. Commented-out code fails review outright.
- Adding try/catch that only logs and re-throws, or swallows. Catch only where you can handle or add context; otherwise let it propagate.
- Narrating comments (`// increment counter`) and section markers (`// helpers`). Both are deleted on sight; restructure the code instead.
- Defensive null checks after calls whose types guarantee non-null. Trust the type system; a gratuitous check hides the real contract.
- Leaving the checklist at one pass. A rename fixes rule 3 but can orphan an export (rule 5); loop until a full pass reports nothing.
Files in this package (5)
  • SKILL.md 6 KB
  • references/ai-slop-checklist.md 6 KB
  • references/comments-and-dead-code.md 7 KB
  • references/readability-and-naming.md 7 KB
  • references/reusability-and-structure.md 7 KB

Versions

The database has no other skills named engineering-rules.

Database snapshot: 13.11.2026 · package version 4bff3f310455 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100review-repo
    Review the natural-language text of a whole code repository for AI slop and rule violations, covering every Markdown and plain-text file plus the comments and doc-comments of its source and config files, not just one document or a diff. Use when the user wants to audit the prose…
  • 100ipollowork-maintainable-code
    Mandatory iPolloWork code-change gate for modern, minimal, performant, reuse-first implementation and clean repository ownership. Use whenever AI creates, edits, deletes, or refactors application code, server code, packages, scripts, tests, dependencies, schemas, routes, UI, or…
  • 100code-comments
    Write, review, or remove code comments. Use when adding comments or doc comments, reviewing the comments in a diff, or cleaning up or removing comments.
  • 90engineering-craft
    Use when writing or changing any production code or tests — new features, bug fixes, refactors, or test authoring, in any language, by any model on any CLI.
  • 100audit
    (forwward) Aggressively audits and cleans a codebase — removes slop, dead code, and AI-generated noise; fixes DRY/SOLID violations; restructures toward the simplest correct implementation. One commit, no behavior changes. Use when the user says "audit the code", "clean up tech…
  • 90coding-rules
    Applies repository-aware rules for maintainable implementation, contracts, errors, and refactoring. Use when writing or modifying code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.