Best Practices & Recipes

Concrete patterns for structuring memory, writing good entries, and building reliable routing.

Structuring CLAUDE.md

The "Always-On Rules" Pattern

Inline your 5-6 most universal behavioral rules at the top of CLAUDE.md. These apply to every task and should never require a file read:

# Always-On Rules (apply to every task)
- One fix at a time: only implement the specific approved change.
- Verify claims: label uncertain statements as "Claim:" and verify before acting.
- Evidence first: debug from logs/data, never speculation.
- No magic strings: use constants or enums for property checks.
- Timebox debugging to ~1h, then build a minimal reproduction.

The "Before X, Read Y" Trigger Pattern

For topic-specific knowledge, use explicit triggers:

# Context Triggers
- Before deploying anything — read [deploy-guide.md](memory/deploy-guide.md)
- Before writing Svelte code — read [svelte-pitfalls.md](memory/svelte-pitfalls.md)
- Before working on CVs — read [cv-methodology.md](memory/cv-methodology.md)
- Before using Chrome MCP tools — read [browser-automation.md](memory/browser-automation.md)

Link Memories from Project Entries

# Projects
- **Video Platform**: `~/projects/video-platform/`
  See [ownership.md](memory/ownership.md) for service boundaries.
- **Trading App**: `~/projects/trader/`
  See [deploy-guide.md](memory/deploy-guide.md) for monorepo deploy.

Writing Good MEMORY.md Entries

The Sonnet memory selector reads only filenames and one-line descriptions. Bad descriptions = missed files.

Group MEMORY.md by Type

# Memory Index

## Behavioral Rules (always apply)
- [feedback_one_fix.md](feedback_one_fix.md) — Only implement the approved change
- [feedback_evidence.md](feedback_evidence.md) — Debug from logs, cite timestamps
...

## Tool Guides (triggered by CLAUDE.md)
- [deploy-guide.md](deploy-guide.md) — Deploy script, server, monorepo handling
...

## Project Knowledge
- [ownership.md](ownership.md) — Video platform service boundaries
...

## Reference
- [pdf-convert.md](pdf-convert.md) — Use weasyprint for HTML-to-PDF

Memory File Best Practices

Frontmatter Format

---
name: Evidence-first debugging
description: Every claim needs evidence (log line, timestamp). Add logging before fixing.
type: feedback
---

Content here...

The description field is critical — it's what the Sonnet selector reads. Make it specific enough to match against task descriptions.

Consolidate Overlapping Memories

Regularly check for:

• Two files teaching the same lesson (merge them)
• A feedback file that duplicates content already in a reference file (delete the duplicate)
• Files that are no longer relevant (archive or delete)

Archive Convention

Move obsolete memories to memory/archived/ and remove from MEMORY.md. This prevents index bloat and stale guidance.

Path-Scoped Rules Recipes

# .claude/rules/frontend-conventions.md
---
paths:
  - "**/*.svelte"
  - "**/*.tsx"
  - "**/*.vue"
---
# Frontend Rules
- Never write reactive state inside high-frequency events
- Use requestAnimationFrame for imperative library calls

# .claude/rules/service-worker.md
---
paths:
  - "**/sw.js"
  - "**/sw.ts"
  - "**/service-worker.*"
---
# Service Worker Safety
- fetch handler must not use respondWith(fetch())
- This breaks ES module caching

# .claude/rules/ci-deploy.md
---
paths:
  - "**/.github/workflows/**"
  - "**/Dockerfile"
  - "**/*.service"
---
# CI/Deploy Rules
- Read the deploy guide before changing deploy configs
- Use systemctl for systemd services

Anti-Patterns

Phased Improvement Plan