← 10.110.3 →
1348 words Slides

10.2 Project-Specific Instructions

Course: Claude Code - Power User Section: Customizing Claude Code Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

Your project has opinions. A React team codes differently than a Rust team. A security-critical system needs different Claude behavior than a prototype. CLAUDE.md is the file that bakes your project's rules into every Claude Code session. Once you write it, Claude reads it automatically and adapts.

Key Talking Points

1. What is CLAUDE.md and Where It Lives

  • CLAUDE.md is a special file in your project root
  • Claude Code automatically reads it at session start
  • It contains persistent instructions that apply to everyone working on the project
  • Lives in version control alongside code—not in .claude/ (which is optional config) What to say: "Think of CLAUDE.md as a Claude Code .editorconfig. It's project-wide, it's tracked in git, and everyone on your team uses it." What to show on screen: File browser with CLAUDE.md in project root. Open it and show its structure.

2. What to Include in CLAUDE.md

  • Architecture guidelines: how the project is organized, key modules, dependency flow
  • Coding standards: naming conventions, style rules, linting preferences
  • Testing requirements: test locations, frameworks, coverage expectations
  • Libraries and frameworks: preferred packages, version constraints, anti-patterns
  • Security rules: sensitive data handling, API patterns, authentication
  • Domain knowledge: business context, user types, key constraints
  • Performance expectations: targets, profiling tools, optimization zones What to say: "Don't write a 50-page manual. Write the stuff that Claude needs to know to write code that feels like it belongs in your project." What to show on screen: Two CLAUDE.md files—one for a Node.js API, one for a Python ML project. Show differences in emphasis.

3. Best Practices: Keep It Clear and Concise

  • Use Markdown formatting
  • Lead with the most important rules
  • Group by topic (Architecture, Coding, Testing, Security)
  • Keep entries brief and actionable
  • Avoid conflicts (don't say "use Prettier" and "use ESLint formatting" for the same rule)
  • Update regularly as standards evolve
  • Review pull requests: if Claude keeps making the same mistake, CLAUDE.md might need updating What to say: "A good CLAUDE.md lives. When your team learns something new, add it. When you realize a rule doesn't matter, delete it." What to show on screen: CLAUDE.md file with clear sections. Show before/after—an outdated version vs. an up-to-date one.

4. Team Benefits

  • Onboarding faster: new team members get Claude tuned to your standards on day one
  • Consistency: all Claude-assisted changes follow the same rules
  • Reduced review friction: fewer "can you rename this?" comments
  • Knowledge capture: standards are written down, not just in someone's head What to say: "A team without CLAUDE.md has to teach Claude the same lessons over and over. A team with it teaches Claude once." What to show on screen: Two workflows side-by-side—team without CLAUDE.md doing repetitive corrections, team with it sailing through review.

Demo Plan

  1. Create a new CLAUDE.md or open an existing one
  2. Show structure:
  3. Project Overview (2-3 sentences)
  4. Architecture (module breakdown, key patterns)
  5. Coding Standards (naming, style, imports)
  6. Testing (where tests go, frameworks, patterns)
  7. Security (data handling, auth patterns)
  8. Make a code change and show Claude respecting the CLAUDE.md rules
  9. Edit CLAUDE.md mid-session and show Claude picking up the changes in the next turn
  10. Commit CLAUDE.md to git to show it's version-controlled

Code Examples & Commands

Check if CLAUDE.md exists:

cat ./CLAUDE.md

CLAUDE.md template (Node.js API):

# Claude Code Guidelines for [Project Name]

## Project Overview
A RESTful API for [service]. Built with Node.js, Express, PostgreSQL. Used by [consumer].

## Architecture
- `/src/routes/` - HTTP route handlers
- `/src/services/` - business logic
- `/src/middleware/` - auth, validation, error handling
- `/src/db/` - database models and migrations
- `/tests/` - unit and integration tests

Key pattern: handlers -> services -> models. Keep database logic in `/src/db/`.

## Coding Standards
- Use ES6+ syntax (const/let, arrow functions, destructuring)
- Name routes like `listUsers`, `createUser` (camelCase, verb-first for actions)
- Async/await for all async code (no .then() chains)
- Import order: node modules, app modules, types
- Max line length: 100 chars
- Use TypeScript for new files (config in tsconfig.json)

## Testing
- Tests in `/tests/`, mirror `/src/` structure
- Use Jest for unit tests, Supertest for integration tests
- Minimum 70% coverage on services/ 
- Test names: describe what happens, use "should" (e.g., "should return 404 when user not found")

## Security
- Never log passwords, tokens, or API keys
- Use environment variables for secrets
- Validate all user input before passing to DB
- Use parameterized queries (never string interpolation for SQL)
- Expire tokens at 1 hour; refresh tokens at 7 days

## Dependencies
- Node 18+
- PostgreSQL 13+
- Avoid adding packages without team discussion

CLAUDE.md template (Python/ML):

# Claude Code Guidelines for [ML Project]

## Project Overview
Machine learning pipeline for [task]. Ingests [data source], trains [models], outputs [predictions].

## Project Structure
- `/data/` - raw and processed datasets
- `/models/` - trained model artifacts (.pkl, .h5)
- `/notebooks/` - exploratory analysis (don't edit .py from these)
- `/src/preprocessing/` - data loading and cleaning
- `/src/models/` - model definitions
- `/src/evaluation/` - metrics, validation
- `/tests/` - unit tests for preprocessing and evaluation
- `/scripts/` - training and inference scripts

## Coding Standards
- Python 3.10+
- Use type hints (PEP 484) on all function signatures
- Docstrings on all classes and functions (Google style)
- Import order: stdlib, third-party (numpy, pandas, sklearn), local
- Variable names: descriptive, lowercase_with_underscores
- Max line length: 88 chars (Black formatter)

## Testing
- Tests in `/tests/`, mimic `/src/` structure
- Use pytest and pytest-cov
- Test fixture data in `/tests/fixtures/`
- All preprocessing and model loading must have tests

## Dependencies
- scikit-learn for ML
- pandas for data ops
- numpy for arrays
- pytest for testing
- No TensorFlow (use scikit-learn, xgboost, or LightGBM instead)

## Domains & Models
- We currently train on [data], don't add new datasets without approval
- Performance target: [metric] > [threshold]
- Always validate on held-out test set before committing models

Update CLAUDE.md:

# Edit CLAUDE.md in your editor
nano ./CLAUDE.md
# or
code ./CLAUDE.md

# Commit it
git add CLAUDE.md
git commit -m "docs: update Claude Code guidelines for new testing requirements"

Gotchas & Tips

Gotcha: CLAUDE.md is read at session start. If you edit it, your current claude session won't see the changes. Restart with claude chat or /reset command.

Tip: Use CLAUDE.md to document decisions why things are done a certain way, not just what. "Use Prettier" is less helpful than "Use Prettier for consistent formatting across teams."

Tip: Link to external docs. "See API Design Guide for endpoint patterns" is better than copying the guide into CLAUDE.md.

Gotcha: If CLAUDE.md contradicts itself, Claude might get confused. Resolve conflicts before committing (e.g., don't say "use TypeScript" and "don't use TypeScript" in different sections).

Tip: Review pull requests for patterns Claude should have caught. If it missed something, consider adding a rule to CLAUDE.md.

Lead-out

Now you have Claude tuned to your project. Next, we'll create custom commands—automated workflows that save even more time by automating the most frequent tasks your team repeats.

Reference URLs

  • CLAUDE.md specification (local file)
  • Markdown guide for formatting CLAUDE.md
  • Version control best practices for docs

Prep Reading

  • Review your project's undocumented "rules"—the things you tell new developers in code review. Those belong in CLAUDE.md.
  • Think about what Claude gets wrong most often. Is there a pattern that a CLAUDE.md rule would fix?

Notes for Daniel: CLAUDE.md is the keystone of team consistency. Make it concrete—show real examples, not templates. Emphasize that it's a living document, not a set-in-stone manifesto. The demo should show the tangible benefit: Claude making decisions that align with the project, without being told twice.