Claude Md Maintenance

CLAUDE.md Maintenance

Keep CLAUDE.md files lean, accurate, and useful.

Core Pattern

After mistakes or discoveries:

"Update CLAUDE.md so you don't make that mistake again"

This captures learnings before context resets.

When to Update

Add rules when:

• Same mistake happens twice
• Non-obvious convention discovered
• Critical project constraint identified

Remove rules when:

• Rule no longer applies (deps changed, pattern evolved)
• Duplicate or redundant with other rules
• Too specific (one-time fix, not pattern)

Structure Template

# Project Name

Brief purpose (1-2 lines).

## Key Commands

- `npm test` - run tests
- `npm run build` - production build

## Conventions

- Use X pattern for Y
- Always Z before committing

## Mistakes to Avoid

- Don't assume X (actually Y)
- Remember to check Z first

Hierarchy

Two levels, both loaded:

Project-level overrides global when conflicting.

Size Guideline

Keep under 500 lines. Claude scans on every request.

Too long? Extract to references:

## API Patterns

See [api-patterns.md](docs/api-patterns.md) for details.

References

• structure-guide.md - Section organization
• lesson-patterns.md - Writing effective rules
• hierarchy.md - Global vs project scope

CLAUDE.md Hierarchy

Two levels, both loaded on every request.

File Locations

Both concatenated into context. Project file shown after global.

What Goes Where

Global (~/.claude/CLAUDE.md)

Personal preferences across all projects:

# Global Preferences

## Style

- Be extremely concise, sacrifice grammar
- No emojis unless requested
- Show file paths as absolute

## Workflow

- Ask before creating new files
- Prefer editing over rewriting

Project (.claude/CLAUDE.md)

Repo-specific rules:

# my-app

SvelteKit app with Prisma + PostgreSQL.

## Commands

- `pnpm dev` - start dev server
- `pnpm db:push` - sync schema

## Conventions

- Use `$state()` rune for reactive state
- API routes in `src/routes/api/`

Conflict Resolution

When rules conflict, project wins:

Global:

- Use tabs for indentation

Project:

- Use 2 spaces (project standard)

Result: 2 spaces used in this project.

Commit Decisions

Exception: Don't commit if contains:

• Personal tool paths
• Local environment specifics
• Controversial preferences

Common Patterns

Split by concern:

~/.claude/CLAUDE.md     → How I work
.claude/CLAUDE.md       → How this project works

Avoid duplication: Don't repeat global rules in project file. They're already loaded.

Reference, don't repeat:

## Detailed Conventions

See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

Writing Effective Lessons

Rules that stick vs rules that waste tokens.

Good Rule Anatomy

- Don't X (actually Y because Z)

Three parts:

1. What not to do - the mistake 2. What to do instead - the fix 3. Why - brief context (optional but helpful)

Examples

Effective Rules

- Don't use `any` type (use `unknown` for truly unknown values)
- Import db from `$lib/server/db`, not `$lib/db` (server-only)
- Run `pnpm generate` after schema changes (creates types)

Ineffective Rules

- Be careful with types
- Make sure imports are correct
- Remember to generate things

Too vague. No actionable fix.

When to Add Rules

Add after:

• Correction: "No, use X instead"
• Second occurrence of same mistake
• Discovery: "This actually works because..."

Don't add:

• One-time fixes unlikely to recur
• Generic best practices (Claude knows)
• Rules requiring judgment calls

Rule Lifecycle

Mistake → Add rule → Time passes → Review → Keep/Remove

Remove when:

• Dependency/API changed
• You internalized it (don't need reminder)
• Turned out to be wrong

Specificity Spectrum

Too specific          Just right              Too vague
     |                    |                       |
"Fix line 42"     "Use X for auth"     "Be secure"

Aim for middle: specific enough to act on, general enough to apply.

Grouping Related Rules

Bad:

- Don't use `let` when `const` works
- Remember to handle null
- Use `??` not `||` for defaults
- Check array length before accessing

Better:

## Type Safety

- Prefer `const`, use `let` only when reassigning
- Use `??` for nullish coalescing (`||` catches falsy values)
- Check array length before index access

CLAUDE.md Structure Guide

Organize for scannability. Claude reads this every request.

Recommended Sections

1. Project Overview (Required)

# Project Name

One-line purpose. Tech stack if non-obvious.

2. Key Commands

Most-used commands only:

## Key Commands

- `pnpm dev` - start dev server
- `pnpm test` - run tests
- `pnpm build` - production build

Skip obvious ones (git commit, npm install).

3. Conventions

Project-specific patterns:

## Conventions

- Components in `src/components/`, one per file
- Use `$state()` rune, not `writable()`
- API routes return `{ data, error }` shape

4. Architecture Notes

Only if non-obvious:

## Architecture

- Auth handled by Clerk middleware
- DB queries go through `src/lib/db.ts`
- Feature flags in `src/config/flags.ts`

5. Mistakes to Avoid

Hard-won lessons:

## Mistakes to Avoid

- Don't import from `$app/server` in client code
- Remember: `load` runs on both server and client
- Check `locals.user` exists before accessing properties

Anti-Patterns

Too verbose:

## Testing

When writing tests, make sure to use the Jest testing framework.
We use React Testing Library for component tests. Always import
from '@testing-library/react'. Remember to wrap async operations...

Better:

## Testing

- Jest + React Testing Library
- Wrap state changes in `act()`

Section Order

1. Overview (what is this) 2. Commands (how to run it) 3. Conventions (how to write code) 4. Architecture (where things live) 5. Mistakes (what to avoid)

Put most-referenced sections first.