CLAUDE.md Mastery: Writing Project Instructions That Claude Actually Follows

Why Most CLAUDE.md Files Don't Work

The most common CLAUDE.md mistakes fall into three categories: vagueness, breadth, and aspirational-only content.

The fix is specificity, scoping, and verification.

Replace every generic rule with a concrete command or constraint.

Specific rules are verifiable. Vague rules are not.

Every rule should have a built-in self-check. This is how Claude confirms compliance without asking you.

Example:

## Database Migrations

When modifying the schema:
1. Create a migration file in convex/schema.ts
2. Run: npx convex run verifyMigration --dev
3. Check the output for warnings. Do not proceed if you see "FULL_TABLE_SCAN"
4. Test locally: npm test
5. Verification: npm run schema:validate (should output "✓ Schema valid")

The npm run schema:validate command is your verification gate. Claude can run it, see the output, and know whether the rule was followed.

Without this, Claude might write the code and trust that it works. With verification, Claude knows.

The 7 Patterns That Make Instructions Stick

## DO NOT delete database records via direct mutation
❌ WRONG:
  db.patch(docId, { deleted: true }) // silent corruption

✓ RIGHT:
  await ctx.db.patch(docId, { isDeleted: true, deletedAt: Date.now() })
  // soft delete with timestamp

Negative examples stick because Claude sees the failure case first.

## Convex Production Database
- NEVER use --prod flag unless explicitly instructed
- NEVER run destructive commands (delete, patch batch) without --dry-run first
- ALWAYS verify output before applying changes

Absolute rules are black-and-white. No gray area, no interpretation needed.

## Rules for convex/schema.ts
When modifying convex/schema.ts:
- Never add a required field to an existing table without a default value
- Run: npx convex codegen after any schema change
- Verification: git diff should show no breaking changes

## Rules for src/components/
- Use React hooks, not class components
- Every component ≥200 LOC must have TypeScript types
- Verification: npm run type-check should pass

This keeps rules focused. Rules for the database schema don't clutter rules for React components.

## Before committing:
1. npm run lint:fix (must pass)
2. npm test (must pass with coverage ≥80%)
3. npm run type-check (must pass)
ONLY commit after all three gates pass.

Claude will follow this sequentially because it's a clear chain.

## Creating a new feature:
1. Update convex/schema.ts with new tables/fields
2. Run: npx convex codegen (depends on step 1)
3. Create API function in convex/myfeature.ts (depends on step 2)
4. Create React hook in src/hooks/useMyFeature.ts (depends on step 3)
5. Create component in src/components/MyFeature.tsx (depends on step 4)
6. Test in src/__tests__/MyFeature.test.tsx (depends on step 5)

Each step depends on the previous one — this isn't arbitrary.

## DO NOT modify production data

EXCEPTION: If you have explicit permission from the on-call engineer, 
use convex run --prod --dry-run first, show output, wait for approval.

This prevents Claude from getting stuck when rules conflict with real-world needs.

Every sprint, review CLAUDE.md: remove rules that no longer apply, add rules for new failure modes, update verification commands as your CI/CD pipeline changes. Old CLAUDE.md files are worse than no CLAUDE.md because Claude follows outdated rules.

Maintaining CLAUDE.md Over Time

CLAUDE.md is loaded into every context window. If it's 10KB, that's ~2,500 tokens. If it's 50KB, that's ~12,500 tokens. You're paying that cost on every single conversation.

• Aspirational content ("Here's our dream architecture...")
• Outdated rules from 6 months ago
• Overly detailed philosophy paragraphs
• Duplicate rules in different sections
• Rules that duplicate project documentation

• Is this rule referenced in the codebase (via comments or convention)?
• Does this rule prevent a real failure mode Claude has hit before?
• Could this rule live in project docs instead?
• Is this rule still true today?

If you answer "no" to any of these, consider removing it.

Claude scans CLAUDE.md quickly. Structure it for skim-reading, not deep study.

Use:

• Clear headings (## Section, ### Category)
• Bullet points for lists
• Code blocks for commands
• Bolded key terms

Avoid:

• Long paragraphs without headings
• Narrative prose (save that for your project wiki)
• Rules buried in explanatory text

```

Convex Database

• Never add required fields without defaults
• Command: npx convex codegen
• Verification: npm run type-check

• Never delete in place; use soft-delete pattern
• Add _isDeleted: Boolean, _deletedAt: Number fields
• Command: npx convex run migrateData

```

Once a quarter:

1. List all rules in CLAUDE.md
2. Check git history: how often was each rule relevant?
3. Ask: "If we removed this rule, would Claude break the project?"
4. If the answer is "probably not," move it to project docs or remove it

• Architecture overview (too large for CLAUDE.md)
• Historical context ("We used to do X, now we do Y")
• Philosophy and rationale (useful for onboarding, not daily work)

• Immediate constraints and failure modes
• Verification commands
• "Never do this" rules
• Path-scoped guardrails