Rules pack · 4 files
generic-rules
Claude Code rules for security, code quality, architecture and CSS. Use this baseline alongside a language pack.
The rules I want Claude to follow on every project, regardless of language. Four files that carry the discipline without any project's specifics baked in.
What's inside
security-discipline.md(always on): input validation, injection, output escaping, least-privilege access, secrets, timing-safe comparison, time-of-check to time-of-use (TOCTOU) races. Language-neutral; the language pack names the exact calls.code-quality.md(always on): single responsibility, DRY without over-abstraction, minimum code, replacing old code instead of adding a second version beside it, complexity thresholds, measure-before-optimize.architecture.md(always on): layered separation (transport, logic, persistence), clear boundaries, fail-fast, the add-a-feature checklist.css-discipline.md(loads on*.css): token-first, search-before-adding, no hardcoded colors, no inline styles, focus and reduced-motion.
How to use
Download the pack and copy its rule files (architecture.md, code-quality.md, css-discipline.md and security-discipline.md) into your project's .claude/rules/. If you copy from a clone of the GitHub repo instead, leave out STOREFRONT.md; it is the website description, not a rule, and the download does not include it. Files with no paths: front matter load on every turn; css-discipline.md scopes itself to stylesheets. Layer a language pack (PHP, Python) on top for the stack-specific enforcement.
Want these tuned to your actual codebase instead of generic? Run /a-rules-optimizer from the dev-workflow-forge plugin: it reads your repo and rewrites the rules around your real conventions.
What's in the bundle
architecture.md2.5 KB
# Architecture Discipline Always-on. A pattern, not a framework. Adapt the names to your stack; keep the separation. ## Layered Separation - Keep transport concerns, business logic, and persistence in separate layers. A request handler that also runs business rules and writes to the database is three responsibilities in one place. - A common shape: Handler (transport) to Service (business logic) to Model or Repository (persistence). Handlers translate requests and responses; services own the rules and the mutations; models own data access. - Mutations go through the logic layer. Reads may skip it. Don't put validation, business rules, or cache invalidation in the transport layer. ## Boundaries and Interfaces - Each unit has one clear responsibility, a well-defined interface, and can be understood without reading its internals. - If you can't change a unit's internals without breaking its callers, the boundary is wrong. - Trace the data flow before writing code: know where input enters and where output goes. ## Failure Handling - Fail explicitly with context. No silent exception swallowing. - A catch block with no log call and no re-raise inside it is a bug, not a style choice. This is the checkable form of the rule above: if the block neither records the failure nor propagates it, the failure is gone. - Don't raise the language's generic base exception for a domain condition. A caller cannot tell a domain failure from an unrelated runtime error, so it either catches too much or catches nothing. - Include the inputs that caused the failure, sanitized if they may carry personal data. "Failed to parse JSON" without the path is unactionable. - Watch for fail-open error paths: an error branch that returns a success-looking default (null, true, an empty list) turns a failure into a wrong answer that nothing reports. - Error-suppression operators and blanket output redirection on state-changing commands hide real failures. Acceptable on a read-only probe, not on a mutation. - Validate early, fail fast: check preconditions at the entry of a function, not deep inside it. - The user-facing message stays friendly; the log carries the full detail. Never leak internals to the user. ## Adding a Feature (checklist shape) - Persistence change first (a migration if the schema moves), then the model, then the service, then the handler, then the view. Wire feature flags and navigation last. - Keep files that change together close together. Split by responsibility, not by technical layer.
code-quality.md1.8 KB
# Code Quality Always-on baseline for keeping a codebase legible and small. ## Single Responsibility - One function, one job. If a function needs a paragraph to explain, split it. - Side effects at the edges, pure logic in the middle. Isolate I/O from decisions so the decisions are testable. - Composition over inheritance. ## DRY, But Not Too Dry - Don't repeat yourself. Two copies is fine; three means extract. - Don't over-abstract. No flexibility or configurability nobody asked for. No abstraction for a single call site. ## Minimum Code - Write the least code that solves the problem. No features beyond what was asked. - No error handling for impossible states. Handle what can actually happen. - Senior-engineer test: could 200 lines be 50? If yes, rewrite before shipping. ## Replace, Don't Append - No `v2`, `_new`, `_final`, or `_improved` copies. Update the original and delete what you replace. - Remove imports and variables your change orphaned. Flag pre-existing dead code; don't silently delete it. ## Complexity Signals (refactor triggers) - Files over ~500 lines and functions over ~30 lines are review hot spots. New code in an already-large file should shrink it, not grow it. - Nesting deeper than 4 levels, or more than 4 parameters, is a signal to extract a value object or split the function. ## Comments - Comment the why, not the what. The code already says what it does. - Follow the established patterns in the file you're editing. Match its style even if you'd do it differently. ## Performance (measure first) - Profile before optimizing. Don't guess at bottlenecks. - Watch for N+1: never issue a query inside a loop. Batch-load before the loop. - Index the columns you filter, join, and order by. - Cache expensive work with real invalidation. A stale cache is worse than no cache. - Lazy-load. Don't fetch data you won't use.
css-discipline.md1.8 KB
--- paths: - "**/*.css" - "**/*.scss" --- # CSS Discipline Loads when you touch a stylesheet. This is method, not a design system: it assumes your project has design tokens and components, and keeps you using them instead of hardcoding around them. Read "tokens" as whatever your project calls its variables. ## Before Adding Any CSS 1. Search your token or variable file. Does a variable already exist for this color, space, or size? 2. Search your component styles. Does a similar component already exist? Most styling should already live there. 3. Search your utilities. Is there a utility class for this? If yes to any: use the existing code. Don't recreate it. Duplicate components are the most common source of CSS drift. ## Token Values Only - Use your design tokens and variables, never hardcoded colors, spacing, or sizes. A raw hex or px value in a component is the tell that a token was skipped. - One intentional scale. Don't invent one-off values that sit between two existing steps. ## Composition First - Compose existing primitives and utilities before writing a new class. - Only add a new class after searching all existing files and finding nothing. Put it in the right component file and give it hover and focus states. ## Anti-Patterns - No duplicate components. Search first, always. - No hardcoded colors or spacing. Use variables. - No inline `style="..."` for color, spacing, or sizing. Use classes. (Runtime custom-property bridges for per-request computed values are the one exception.) - No `-v2` or `-new` classes. Update the existing class, or discuss first. - No inline event handlers in markup. Bind in a script. ## States and Motion - Every interactive element gets a visible `:focus-visible` state. - Respect `prefers-reduced-motion`: gate or zero out transitions for users who ask for less motion.
security-discipline.md3.9 KB
# Security Discipline
Always-on baseline, language-neutral. The stack-specific enforcement (which escape helper, which hashing call) lives in the language pack that layers on top. This file is the discipline every project owes regardless of stack.
## Input Validation
- Validate and sanitize all input at system boundaries: request handlers, API endpoints, CLI args, queue consumers, webhook receivers.
- Whitelist, don't blacklist. Reject unknown values rather than trying to strip bad ones.
- Enforce length limits, type checks, and range bounds on every field.
- Only allow `http://` and `https://` for user-supplied URLs. Reject other schemes (`javascript:`, `file:`, `data:`).
- Cap array and batch sizes on ingest endpoints (for example, max 200 items) so one request can't exhaust memory.
- Bound date and time inputs to a sane range instead of trusting the parser.
## Injection
- Parameterized queries only. Never concatenate user input into SQL, shell commands, or any interpreter string.
- Context-appropriate escaping on output: HTML, SQL, shell, JSON, and URL each need their own escaping, applied at the boundary where the value leaves your control.
## Output Escaping (XSS)
- Escape every dynamic value before it lands in HTML. Treat all external data (DB rows, API responses, feed titles) as untrusted.
- Validate a URL's scheme before emitting it in an `href` or `src` attribute.
- When building HTML from data that arrived over the wire, prefer text nodes and safe builders over raw string interpolation.
## Access Control
- Least privilege by default: file permissions, DB users, API scopes, tokens.
- Return 404, not 403, for a resource a user isn't allowed to see. Don't confirm its existence.
- Enforce authorization on the server for every state-changing request. Never rely on a hidden UI control as the gate.
- CSRF protection on all state-changing requests.
- **Never emit a per-session CSRF token on a route a page cache can store.** A reverse proxy or edge cache saves the rendered HTML with one visitor's token baked in and serves it to everyone: the token leaks across visitors, and every other visitor's submit fails. The trap is a shared partial or layout, where a form lands on a page nobody remembers is cacheable. A form carrying a session token belongs on an explicitly no-cache route. Where one genuinely must live on a cached page (an anonymous signup, say), drop the session token and defend with other controls (double opt-in, honeypot, per-IP rate limit), then write down why the exception exists so a later audit doesn't "fix" it back.
## Secrets
- No secrets in source. Use environment variables or config files outside the web root.
- Never log secrets, tokens, passwords, or full external responses. Truncate and redact before logging.
## Credentials and Comparison
- Store passwords only as a slow salted hash (bcrypt, argon2, scrypt). Never md5, sha1, or plaintext.
- Compare secrets, tokens, signatures, and CSRF or OAuth values in constant time. A plain `==` on a secret is a timing oracle.
## Time-of-Check to Time-of-Use
- Don't check-then-act on shared state ("file exists? then open"). Operate directly and handle the error; the gap between check and act is a race.
- Writes to shared files or state need a lock or an atomic operation. A partial write under concurrency is a corruption bug.
## Dangerous Constructs
- Avoid dynamic code execution and unsafe deserialization on any value that could be attacker-influenced. Eval, template-from-input, and object deserializers are remote-code-execution surfaces.
## Outbound HTTP
- Verify TLS on outbound calls. Don't disable certificate checks to make something work.
- Set a timeout on every external call. A hung dependency shouldn't hang your process.
- Validate the destination of any request whose URL came from user input: allowlist schemes and hosts. `python-rules/python-security.md` has a worked SSRF section if you run that pack.