CLAUDE.md Optimization: Tips 16-25

CLAUDE.md files are the foundation of effective Claude Code usage. They provide persistent memory across sessions, establish project context, and dramatically improve the quality of Claude’s assistance. These 10 tips will help you create CLAUDE.md files that transform your development workflow.

Understanding CLAUDE.md Files

CLAUDE.md files serve as Claude Code’s persistent memory system. Unlike conversation history that gets cleared, these files are automatically loaded at the start of every session, providing consistent context about your project.

Key Benefits

• Persistent Context: Information persists across sessions and team members
• Reduced Token Usage: No need to repeatedly explain project details
• Team Alignment: Shared understanding of project conventions
• Improved Output Quality: Claude follows your specific patterns and preferences
• Faster Onboarding: New team members get up to speed quickly

Strategic Placement and Structure

Tip 16: Create Strategic CLAUDE.md Files

CLAUDE.md files can be placed at multiple levels in your project hierarchy. Claude Code automatically discovers and prioritizes them based on specificity:

project-root/
├── CLAUDE.md                    # Global project context
├── ~/.claude/CLAUDE.md          # Personal global preferences
├── frontend/
│   └── CLAUDE.md               # Frontend-specific guidelines
├── backend/
│   └── CLAUDE.md               # Backend-specific patterns
└── src/
    └── components/
        └── CLAUDE.md           # Component-level conventions

Priority order (most specific wins):

1. Current directory CLAUDE.md
2. Parent directory CLAUDE.md (recursive up to root)
3. Project root CLAUDE.md
4. Home directory ~/.claude/CLAUDE.md

Project Root

# Project Overview

This is an e-commerce platform built with Next.js and Node.js.

## Architecture
- Frontend: Next.js 14 with App Router
- Backend: Node.js with Express
- Database: PostgreSQL with Prisma ORM
- Authentication: JWT with refresh tokens
- State Management: Zustand

## Key Principles
- TypeScript for all new code
- Functional components with hooks
- RESTful API design
- Comprehensive error handling

Frontend Specific

# Frontend Guidelines

## Component Structure
- Use functional components with TypeScript
- Props interfaces defined above component
- Custom hooks in `/hooks` directory
- Shared components in `/components/shared`

## Styling
- Tailwind CSS for all styling
- No inline styles except for dynamic values
- Dark mode support required
- Mobile-first responsive design

Personal Global

# Personal Preferences

## Code Style
- Prefer early returns over nested conditionals
- Use descriptive variable names (no abbreviations)
- Comments for "why", not "what"
- Maximum line length: 100 characters

## Git Workflow
- Conventional commits format
- Squash commits before merging
- Always create feature branches

Tip 17: Use the Auto-Generation Feature

Claude Code can automatically generate a comprehensive CLAUDE.md file by analyzing your project:

claude
/init

This command:

• Scans your project structure
• Identifies frameworks and libraries
• Detects coding patterns
• Analyzes existing documentation
• Creates a tailored CLAUDE.md file

After generation, customize it to add:

• Team-specific conventions
• Business logic explanations
• Architectural decisions
• Performance considerations

Tip

Run /init periodically as your project evolves to capture new patterns and update documentation.

Tip 18: Document Common Commands

Include frequently used commands and scripts to reduce context switching:

# Common Commands

## Development
- `npm run dev` - Start development server (port 3000)
- `npm run build` - Build for production
- `npm run test` - Run test suite
- `npm run test:watch` - Run tests in watch mode
- `npm run lint` - Run ESLint with auto-fix
- `npm run typecheck` - Run TypeScript compiler check

## Database
- `npm run db:migrate` - Run pending migrations
- `npm run db:seed` - Seed development data
- `npm run db:reset` - Reset database (WARNING: destructive)
- `npm run db:studio` - Open Prisma Studio

## Deployment
- `npm run deploy:staging` - Deploy to staging (requires VPN)
- `npm run deploy:prod` - Deploy to production (requires approval)

## Custom Scripts
- `./scripts/generate-types.sh` - Generate TypeScript types from API
- `./scripts/analyze-bundle.sh` - Analyze webpack bundle size
- `./scripts/update-deps.sh` - Interactive dependency updater

Pro Tip

Include context about when and why to use each command, not just what they do.

Tip 19: Establish Code Style Guidelines

Document your team’s coding standards and preferences clearly:

# Code Style Guidelines

## TypeScript
- **ALWAYS** use explicit return types for functions
- **ALWAYS** define interfaces for component props
- **PREFER** type over interface for unions and primitives
- **AVOID** any type - use unknown and type narrowing instead

Example:
\`\`\`typescript
// ✅ Good
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

const Button: React.FC<ButtonProps> = ({ label, onClick, variant = 'primary' }) => {
  return <button className={styles[variant]} onClick={onClick}>{label}</button>;
};

// ❌ Bad
const Button = ({ label, onClick, variant }: any) => {
  return <button onClick={onClick}>{label}</button>;
};
\`\`\`

## Import Organization
1. External dependencies
2. Internal aliases (~/)
3. Relative imports (./)
4. Style imports

Example:
\`\`\`typescript
import React, { useState, useEffect } from 'react';
import { useRouter } from 'next/router';

import { api } from '~/lib/api';
import { Button } from '~/components/ui';

import { formatDate } from './utils';
import styles from './Component.module.css';
\`\`\`

## Error Handling
- Use custom error classes
- Always log errors with context
- Provide user-friendly error messages
- Include error boundaries for React components

Tip 20: Include Repository Etiquette

Document team practices and workflows to ensure consistency:

# Repository Etiquette

## Git Workflow
1. **Branch Naming**: `feature/description`, `fix/description`, `chore/description`
2. **Commit Messages**: Follow conventional commits
   - `feat:` New feature
   - `fix:` Bug fix
   - `docs:` Documentation only
   - `style:` Code style changes
   - `refactor:` Code refactoring
   - `test:` Test changes
   - `chore:` Build process or auxiliary tool changes

## Pull Request Process
1. **Self-Review**: Review your own PR first
2. **Description**: Use PR template, link to issue
3. **Tests**: All tests must pass
4. **Screenshots**: Include for UI changes
5. **Size**: Keep PRs under 400 lines when possible

## Code Review Guidelines
- Be constructive and specific
- Suggest improvements, don't just criticize
- Use "we" instead of "you" in comments
- Approve with "LGTM" (Looks Good To Me)

## Merge Strategy
- **Squash and merge** for feature branches
- **Rebase** for updating feature branches
- **No merge commits** in main branch

Content Optimization Techniques

Tip 21: Document Environment Setup Requirements

Help Claude understand your development environment:

# Development Environment

## Prerequisites
- Node.js 18.x or higher (use nvm)
- PostgreSQL 14.x
- Redis 6.x (for caching)
- Docker Desktop (optional, for containers)

## Initial Setup
1. Clone repository: `git clone <repo-url>`
2. Install dependencies: `npm install`
3. Copy environment variables: `cp .env.example .env`
4. Configure .env file:
   - DATABASE_URL: PostgreSQL connection string
   - REDIS_URL: Redis connection string
   - JWT_SECRET: Generate with `openssl rand -base64 32`
   - API_KEY: Obtain from team lead
5. Run migrations: `npm run db:migrate`
6. Seed database: `npm run db:seed`
7. Start development: `npm run dev`

## Environment Variables
- **Development**: Use .env.local (git-ignored)
- **Testing**: Use .env.test
- **Production**: Set in deployment platform

## Known Issues
- Hot reload may fail on Windows - restart dev server
- Port 3000 conflicts with other services - change in .env
- Database connections may exhaust - increase pool size

Tip 22: Add Project-Specific Warnings

Document gotchas and non-obvious behaviors:

# ⚠️ Important Warnings

## Performance Considerations
- **Product listing page**: Limits to 50 items due to performance
- **Image uploads**: Automatically compressed, max 5MB
- **Search indexing**: Runs async, may take 30 seconds
- **Cache invalidation**: Manual trigger required for some operations

## Security Notes
- **API Keys**: Never commit to repository
- **User data**: PII must be encrypted at rest
- **File uploads**: Validate MIME types server-side
- **SQL queries**: Use parameterized queries only

## Common Pitfalls
1. **State Management**
   - Don't mutate Zustand state directly
   - Use immer for complex updates

2. **API Calls**
   - Always handle loading and error states
   - Use AbortController for cleanup

3. **Database Queries**
   - N+1 queries common in user dashboard
   - Use includes for related data

4. **Testing**
   - Mock external services
   - Reset database between test suites

Caution

Keep warnings up-to-date as you discover new issues. Claude will remember these and avoid common mistakes.

Tip 23: Use the # Key for Dynamic Updates

Claude Code provides a quick way to update CLAUDE.md files during development:

# During a Claude Code session, press # and type:
Always use Tailwind classes for styling, never inline styles

# Claude responds:
I'll add that to the most relevant CLAUDE.md file.

This feature:

• Automatically determines the best CLAUDE.md file to update
• Adds the instruction in the appropriate section
• Maintains formatting and structure
• Works for both new rules and corrections

Common uses:

• Adding discovered patterns
• Correcting misunderstandings
• Documenting decisions made during development
• Capturing team preferences

Tip 24: Refine Instructions Like Prompts

Treat CLAUDE.md content as you would prompts - be specific and use emphasis:

Weak Instructions

# Guidelines

Use TypeScript for files.

Follow the style guide.

Write tests.

Strong Instructions

# Critical Guidelines

**ALWAYS** use TypeScript with strict mode enabled for ALL files.

**MUST** follow the Airbnb style guide with our modifications:
- 2 space indentation (NOT tabs)
- Semicolons required
- Trailing commas in multiline

**REQUIRED** for every feature:
- Unit tests with >80% coverage
- Integration tests for API endpoints
- E2E tests for critical user paths

**NEVER**:
- Use var keyword (use const/let)
- Commit console.log statements
- Disable ESLint rules without comment

Effective instruction patterns:

• ALWAYS/NEVER for non-negotiable rules
• PREFER/AVOID for strong recommendations
• CONSIDER for suggestions
• Examples to clarify expectations

Tip 25: Run Through Prompt Improver

Periodically optimize your CLAUDE.md files using Anthropic’s prompt improvement techniques:

1. Extract your CLAUDE.md content

   cat CLAUDE.md > claude-md-content.txt

2. Use Claude to improve it

   Improve this CLAUDE.md file to be more effective for Claude Code.
   Make instructions clearer, add helpful examples, and organize better:
   
   [paste content]

3. Focus on improvements like:

   • Clearer section organization
   • More specific instructions
   • Better examples
   • Removal of ambiguity
   • Addition of context

4. Test the improved version

   • Start a new Claude Code session
   • Verify instructions are followed correctly
   • Iterate based on results

Optimization Checklist

• Clear section headers with purpose
• Specific, actionable instructions
• Examples for complex concepts
• Warnings for common mistakes
• Links to additional resources
• Regular review and updates

Best Practices Summary

The most effective CLAUDE.md files share these characteristics:

1. Hierarchical Structure: Use multiple files for different contexts
2. Living Documentation: Update regularly as project evolves
3. Team Alignment: Share and version control CLAUDE.md files
4. Clear Examples: Show, don’t just tell
5. Specific Instructions: Be explicit about expectations
6. Context-Rich: Include the “why” behind decisions
7. Tool Integration: Document custom tools and scripts
8. Warning System: Highlight gotchas and pitfalls
9. Regular Review: Optimize based on actual usage
10. Quick Updates: Use # key for immediate improvements

Next Steps

With well-optimized CLAUDE.md files providing context, you’re ready to master the command-line interface. Continue to Command Line Mastery to learn essential commands and productivity shortcuts.