Claude Rules

Personal AI coding agent configuration for a freelance frontend creative developer. Claude Code native format with a built-in conversion step for Windsurf, Copilot, and Aider.

Add to an Existing Project

Already have a codebase? Run one command to copy the rules into it:

cd your-project

# Pick your package manager — all work the same
bunx @nickbevers/claude-rules init
npx @nickbevers/claude-rules init
pnpm dlx @nickbevers/claude-rules init
yarn dlx @nickbevers/claude-rules init

This copies three things into your project root:

| What | Where | Effect | | ------------------- | ------------ | ----------------------------------------------------------- | | CLAUDE.md | Project root | Always-on rules (~68 lines), loaded every interaction | | rules/*.md | rules/ | Path-scoped rules, loaded only when touching matching files | | skills/*/SKILL.md | skills/ | On-demand skills, zero cost until triggered |

Running init is safe on existing projects — it merges and adds, never overwrites:

• CLAUDE.md — if one already exists, the global rules are merged on top and your project-specific content is preserved below a # --- Project Rules --- marker. Re-running init updates the global section while keeping your project rules intact.
• rules/ — new rule files are added by name. Existing rules you've customized are kept as-is.
• skills/ — new skills are added by name. Existing skills are kept as-is.

After init, add any project-specific configuration below the # --- Project Rules --- marker in CLAUDE.md, then commit the rules/ and skills/ directories alongside your code.

Re-running init (updating an existing project)

Running init again is safe and encouraged when new rules or skills are added upstream:

bunx @nickbevers/claude-rules init

What happens:

| Component | First run | Re-run | |---|---|---| | CLAUDE.md (no existing) | Copied from package | — | | CLAUDE.md (existing) | Merged: global rules on top + project rules below marker | Global section updated, project rules preserved | | rules/frontend.md (new) | Added | — | | rules/frontend.md (exists) | Kept as-is | Kept as-is | | skills/code-review/ (new) | Added | — | | skills/code-review/ (exists) | Kept as-is | Kept as-is |

Force re-init (overwrite everything)

If you want to reset all rules and skills to the latest package versions — for example after a major update — use --force:

bunx @nickbevers/claude-rules init --force

This overwrites all existing rule and skill files with the package versions and re-merges CLAUDE.md (your project-specific rules below the # --- Project Rules --- marker are still preserved).

The merged CLAUDE.md looks like this:

# Global Rules
... (package global rules, updated on each init) ...

# --- Project Rules ---

... (your project-specific rules, never touched by init) ...

Also using Windsurf, Copilot, or Aider?

# Add another agent during init
bunx @nickbevers/claude-rules init claude windsurf

# Or all at once
bunx @nickbevers/claude-rules init all

Or convert later from an existing project that already has rules/:

bunx @nickbevers/claude-rules convert cursor       # -> .cursorrules
bunx @nickbevers/claude-rules convert windsurf     # -> .windsurfrules
bunx @nickbevers/claude-rules convert copilot      # -> .github/copilot-instructions.md
bunx @nickbevers/claude-rules convert aider        # -> .aider.conf.yml + CONVENTIONS.md
bunx @nickbevers/claude-rules convert all          # All of the above

Replace bunx with npx, pnpm dlx, or yarn dlx as needed.

The conversion strips YAML frontmatter from rules/ and skills/, concatenates into the flat format each agent expects, and appends agent-specific guidance automatically.

Start a New Project with These Defaults

Two approaches depending on whether you want rules applied globally or per-project.

Global Install (all projects get these rules)

git clone [email protected]:NickBevers/claude-rules.git ~/.config/claude-rules
~/.config/claude-rules/setup.sh

This creates three symlinks in ~/.claude/:

| Symlink | Target | Purpose | | --------------------- | ----------- | ----------------------------- | | ~/.claude/CLAUDE.md | CLAUDE.md | Always-on global rules | | ~/.claude/rules/ | rules/ | Path-scoped conditional rules | | ~/.claude/skills/ | skills/ | On-demand skills |

Every Claude Code session on this machine now loads these rules. No per-project setup needed.

To uninstall: ~/.config/claude-rules/setup.sh --uninstall

Per-Project Install (rules live in the repo)

mkdir my-project && cd my-project
git init
bunx @nickbevers/claude-rules init

Then edit CLAUDE.md to define your project's stack:

## Project Stack

- Runtime: Bun
- Frontend: Astro 6 + Preact
- Styling: CSS Modules
- Backend: Hono
- Database: PostgreSQL 16 + Drizzle ORM

Commit everything — teammates and CI get the same rules automatically.

How It Works

Three Loading Tiers

The system is designed around Claude Code's context window — every token in always-on rules costs on every interaction AND every subagent spawn.

Tier 1 — Always-On (CLAUDE.md, ~68 lines)

Loaded on every single interaction. Contains only:

• Stack defaults (Bun, Astro, Preact, CSS Modules, etc.)
• Rule index for cross-context loading
• Hard constraints Claude gets wrong without them (OKLCH colors, animation performance, Tabler Icons default)
• Anti-AI-slop guardrails (no generic gradients, no pure grays, tinted neutrals)
• Workflow rules (no drive-by refactors, ask when unsure)
• Subagent sparring instructions

Tier 2 — Path-Scoped Rules (rules/, ~676 lines total, ~26-79 per file)

Each file has YAML paths: frontmatter. Claude Code only loads them when touching matching files. Editing a .tsx file loads frontend.md and design.md but NOT backend.md, database.md, or security.md.

| Rule File | Triggers On | | ---------------- | ----------------------------------------------------------------------- | | frontend.md | *.tsx, *.astro, *.module.css, components/, pages/, layouts/ | | design.md | *.module.css, *.css, tokens*, theme*, design* | | backend.md | api/, routes/, services/, middleware/, *.server.ts | | database.md | drizzle/, *schema*, *migration*, *.sql, db/ | | security.md | auth/, session*, *guard*, *crypt*, *password* | | testing.md | *.test.*, *.spec.*, e2e/, vitest*, playwright* | | devops.md | Dockerfile*, docker-compose*, deploy*, .github/ | | git.md | .gitignore, .gitattributes, .github/ | | laravel.md | *.php, livewire/, *.blade.php, composer.json | | compliance.md | privacy*, cookie*, consent*, gdpr*, legal* | | incident.md | incident*, postmortem*, runbook*, status*, ops/ | | copywriting.md | components/, pages/, content/, copy*, *.astro | | ticketing.md | .claude/tickets/ | | planning.md | .claude/research/, decisions*, architecture* | | research.md | .claude/research/, spike* |

Tier 3 — On-Demand Skills (skills/, zero cost until triggered)

Proper Claude Code skills with SKILL.md + YAML frontmatter. Only loaded when invoked by name or when Claude's description matching triggers them.

| Skill | Triggers On | | ------------------------ | --------------------------------------------------- | | design-discovery | "pick fonts", "choose colors", "visual identity" | | micro-animations | "add animations", "hover effects", "add polish" | | frontend-design | "build page", "create component", "design UI" | | code-review | "review code", "check my code", "audit code" | | project-kickoff | "new project", "plan project", "kickoff" | | seo-audit | "SEO audit", "meta tags", "structured data" | | stack-detect | "detect stack", "what stack", "scan project" | | content-strategy | "write blog post", "case study", "content plan" | | proposal-writer | "write proposal", "pitch", "estimate" | | document-generator | "write SOW", "project brief", "handoff document" | | qa-audit | "audit", "QA check", "accessibility audit" | | analytics-reporter | "analytics", "dashboard", "tracking" | | app-store-optimization | "ASO", "app store optimization", "app listing" | | behavioral-nudge | "nudge", "conversion optimization", "persuasion" | | data-consolidation | "migrate data", "ETL", "merge databases" | | mcp-builder | "build MCP", "MCP server", "agent tool" | | threat-detection | "threat model", "security review", "attack surface" | | workflow-optimizer | "optimize workflow", "speed up build", "DX" | | merge-conflict | "merge conflict", "resolve conflict", "fix conflicts"| | frontend-react | "react component", "build in react", "react hook" | | frontend-preact | "preact component", "preact island", "preact signal" | | frontend-astro | "astro page", "astro layout", "content collection" | | frontend-hooks | "custom hook", "extract hook", "useEffect help" | | frontend-forms | "build form", "form validation", "form component" | | frontend-state | "state management", "global state", "zustand" | | frontend-testing | "test component", "write tests", "testing strategy" | | frontend-routing | "routing", "add route", "dynamic route" | | frontend-performance | "performance audit", "core web vitals", "bundle size"| | frontend-data-fetching | "fetch data", "tanstack query", "data loading" | | frontend-typescript | "type this", "fix types", "generic component" | | frontend-scaffold | "scaffold feature", "new feature", "set up feature" | | frontend-doc-sync | "check docs", "is this current", "verify api" | | astro-middleware | "astro middleware", "auth middleware", "onRequest" | | astro-view-transitions | "view transitions", "page transitions", "persist" | | astro-integrations | "astro integration", "astro adapter", "astro config" | | astro-i18n | "astro i18n", "multilingual", "locale routing" | | astro-server-islands | "server island", "server:defer", "personalized" | | astro-actions | "astro action", "defineAction", "astro form" | | preact-compat | "preact compat", "react library in preact", "alias" | | preact-signals-patterns| "signals pattern", "computed signal", "signal store" | | pagespeed-audit | "pagespeed", "lighthouse", "core web vitals" |

Token Budget

| Scenario | Lines Loaded | vs. Monolithic | | ----------------------------------- | ------------------------------------- | ----------------- | | Marketing site — editing components | ~176 (CLAUDE.md + frontend + design) | 76% reduction | | Marketing site — simple question | ~68 (CLAUDE.md only) | 91% reduction | | App with auth — editing API routes | ~162 (CLAUDE.md + backend + security) | 78% reduction | | Design Discovery (5 subagents) | ~68 x 5 = 340 base | 91% reduction |

Compared to loading all 744 lines on every interaction.

Directory Structure

~/.config/claude-rules/
├── package.json
├── CLAUDE.md                          # Always-on global rules (~68 lines)
├── setup.sh                           # Symlink into ~/.claude/ (git-clone workflow)
├── README.md
│
├── bin/
│   └── cli.js                         # CLI: init, setup, convert
│
├── rules/                             # Source of truth (Claude Code native)
│   ├── frontend.md                    #   Astro, Preact, CSS Modules, state
│   ├── design.md                      #   Spacing, tokens, motion, a11y
│   ├── backend.md                     #   Hono, API design, auth, middleware
│   ├── database.md                    #   PostgreSQL, Drizzle, md5 indexes
│   ├── security.md                    #   Rate limiting, headers, encryption
│   ├── testing.md                     #   bun:test, Vitest, Playwright
│   ├── devops.md                      #   Docker, Coolify, CI/CD
│   ├── git.md                         #   Branching, .gitignore
│   ├── laravel.md                     #   PHP, Laravel, Livewire
│   ├── compliance.md                  #   GDPR, cookies, licenses
│   ├── incident.md                    #   Severity levels, postmortem
│   ├── copywriting.md                 #   Error messages, empty states
│   ├── ticketing.md                   #   Ticket structure, prefixes
│   ├── planning.md                    #   Architecture decisions, phases
│   └── research.md                    #   Library/API evaluation
│
└── skills/                            # On-demand skills (Claude Code native)
    ├── design-discovery/SKILL.md
    ├── micro-animations/SKILL.md
    ├── frontend-design/SKILL.md
    ├── code-review/SKILL.md
    ├── project-kickoff/SKILL.md
    ├── seo-audit/SKILL.md
    ├── stack-detect/SKILL.md
    ├── frontend-react/SKILL.md
    ├── frontend-preact/SKILL.md
    ├── frontend-astro/SKILL.md
    ├── frontend-hooks/SKILL.md
    ├── frontend-forms/SKILL.md
    ├── frontend-state/SKILL.md
    ├── frontend-testing/SKILL.md
    ├── frontend-routing/SKILL.md
    ├── frontend-performance/SKILL.md
    ├── frontend-data-fetching/SKILL.md
    ├── frontend-typescript/SKILL.md
    ├── frontend-scaffold/SKILL.md
    ├── frontend-doc-sync/SKILL.md
    ├── astro-middleware/SKILL.md
    ├── astro-view-transitions/SKILL.md
    ├── astro-integrations/SKILL.md
    ├── astro-i18n/SKILL.md
    ├── astro-server-islands/SKILL.md
    ├── astro-actions/SKILL.md
    ├── preact-compat/SKILL.md
    ├── preact-signals-patterns/SKILL.md
    ├── pagespeed-audit/SKILL.md
    └── ... (55 total)

What Goes Where

| Content | Location | Why | | ------------------------------------ | ----------------------- | ---------------------------------------------- | | Stack choices, universal constraints | CLAUDE.md | Must be in every interaction | | Domain-specific rules | rules/*.md | Only load when touching those files | | Complex multi-step workflows | skills/*/SKILL.md | Zero cost until triggered | | Other agent configs | Generated via convert | Derived from rules/, not maintained separately |

Paired Subagent Sparring

Skills like design-discovery, micro-animations, and frontend-design use paired subagent sparring:

1. Gather context from the user (project type, audience, mood, existing brand)
2. Spawn Agent A and Agent B in parallel with opposing creative directions
3. Spawn Agent C and Agent D in parallel — each cross-critiques the other proposal
4. Synthesize into 2-3 options and present to the user
5. Iterate based on feedback (re-spar if needed)
6. Output production-ready CSS custom properties

The sparring prevents generic outputs. Agent A pushes for distinctiveness, Agent B pushes for polish, and the cross-critique forces the best of both.

Converting to Other AI Agents

These rules are written in Claude Code's native format (rules/*.md with YAML paths: frontmatter + skills/*/SKILL.md). If you also use Cursor, Windsurf, Copilot, or Aider, the convert command generates their config from the same rules.

Supported Agents

| Agent | Command | Output File | |---|---|---| | Cursor | bunx @nickbevers/claude-rules convert cursor | .cursorrules | | Windsurf | bunx @nickbevers/claude-rules convert windsurf | .windsurfrules | | GitHub Copilot | bunx @nickbevers/claude-rules convert copilot | .github/copilot-instructions.md | | Aider | bunx @nickbevers/claude-rules convert aider | .aider.conf.yml + CONVENTIONS.md | | All at once | bunx @nickbevers/claude-rules convert all | All of the above |

Replace bunx with npx, pnpm dlx, or yarn dlx as needed.

How It Works

rules/*.md (with YAML frontmatter)  ──┬──>  Claude Code (native, no conversion needed)
skills/*/SKILL.md                     │
                                      ├──>  .cursorrules
                                      ├──>  .windsurfrules
                                      ├──>  .github/copilot-instructions.md
                                      └──>  CONVENTIONS.md + .aider.conf.yml

The convert command:

1. Reads rules/*.md and skills/*/SKILL.md from your local project (falls back to the package if no local rules exist)
2. Strips YAML paths: frontmatter
3. Concatenates everything into the flat format each agent expects
4. Appends agent-specific guidance (e.g., "Cursor can't spawn subagents — use sequential sparring")

When to Re-run

Re-run convert after editing any rule or skill file so the other agent configs stay in sync:

# After editing rules/frontend.md
bunx @nickbevers/claude-rules convert all

No .ai/ directory. No sync scripts. No stale copies. One source, one conversion step.

Design Decisions

Why not one big CLAUDE.md? Every token in CLAUDE.md costs on every interaction. With subagent spawning (e.g., 5 agents for design discovery), a monolithic file becomes thousands of wasted context lines. Path-scoped rules eliminate 76-91% of that waste.

Why not just skills for everything? Skills require explicit triggering. Path-scoped rules load automatically when you touch matching files — no friction, no commands to remember.

Why Claude Code native as source of truth? Claude Code's rules/ format (markdown + YAML paths: frontmatter) is the most expressive: it supports conditional loading. Stripping frontmatter for other agents is trivial. Going the other direction (adding frontmatter to flat files) requires maintaining a separate path mapping. One direction is automatable; the other isn't.

Why frontend-first? This setup is for a freelance frontend creative developer doing ~80% marketing sites and ~20% apps with auth. Backend/database/security rules only load when actually touching those files, saving tokens on the 80% of work that's pure frontend.

Why are rules so specific? Generic best practices like "use semantic HTML", "write clean code", or "Arrange-Act-Assert" waste tokens — Claude already follows these by default. Every rule here exists because Claude gets it wrong without the instruction: OKLCH over hex, env(c) not Bun.env, MD5 hash indexes for TEXT columns, Argon2id via Bun.password, pgboss over BullMQ (Bun segfault). If a rule doesn't change Claude's actual behavior, it doesn't belong.