Adding Project-Specific Commands to Claude's Memory
What You'll Learn
How to add project-specific commands, conventions, and instructions to Claude's memory using CLAUDE.md so they persist across all conversations in your project.
Prerequisites
- Claude Code CLI installed
- A project directory initialized with Claude Code
Steps
Step 1: Create or Locate CLAUDE.md
Check if your project already has a CLAUDE.md file:
ls -la CLAUDE.md
If it doesn't exist, create it:
touch CLAUDE.md
Step 2: Add Your Project-Specific Commands
Open CLAUDE.md and add your custom commands. Here's a practical example for a Node.js project:
cat > CLAUDE.md << 'EOF'
# CLAUDE.md
This file provides guidance to Claude Code when working with this repository.
## Project Overview
This is a Node.js REST API for managing user authentication and profiles.
## Development Commands
### Running the Application
```bash
# Development mode with hot reload
npm run dev
# Production mode
npm start
# Run with debugging
npm run debug
Testing Commands
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
Code Quality Commands
IMPORTANT: Always run these before committing:
npm run lint
npm run format
npm run typecheck
Project Conventions
- Use async/await instead of promises
- All API endpoints must have corresponding tests
- Use snake_case for database columns, camelCase for JavaScript
- Add JSDoc comments for all public functions
- Never commit .env files or secrets
File Structure
/src/controllers/- Request handlers/src/models/- Database models/src/routes/- API route definitions/src/utils/- Shared utilities/tests/- Test files matching source structure EOF
### Step 3: Test That Claude Remembers
Start a new Claude Code session and ask about your project:
```bash
claude "What commands should I run before committing?"
Claude should respond with the lint, format, and typecheck commands from your CLAUDE.md.
Step 4: Update as Your Project Evolves
Add new sections as needed:
cat >> CLAUDE.md << 'EOF'
## Database Migrations
```bash
# Create a new migration
npm run migrate:create -- --name add_user_roles
# Run pending migrations
npm run migrate:up
# Rollback last migration
npm run migrate:down
API Documentation
The API documentation is auto-generated. After making changes:
npm run docs:generate
EOF
## Example Usage
Here's a complete CLAUDE.md for a Python project:
```markdown
# CLAUDE.md
## Project Overview
FastAPI application for processing image uploads and generating thumbnails.
## Development Setup
```bash
# Create virtual environment
python -m venv venv
# Activate it (macOS/Linux)
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
Running the Application
# Development server
uvicorn main:app --reload
# Production server
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
Testing Commands
IMPORTANT: Run before pushing:
pytest
black .
isort .
mypy .
Project-Specific Rules
- Always use type hints
- Images must be validated before processing
- Use dependency injection for database connections
- Log all image processing operations
- Maximum upload size: 10MB
Common Tasks
- To add a new endpoint: Create handler in
/api/endpoints/, add to router - To add image processor: Extend
BaseProcessorin/processors/ - Database changes: Create Alembic migration with
alembic revision -m "description"
## Expected Output
When you ask Claude about your project after adding CLAUDE.md:
You: "How do I run tests for this project?"
Claude: According to your project's CLAUDE.md, you should run:
For Python project:
pytest- Runs all tests- Also run
black .,isort ., andmypy .before pushing
For Node.js project:
npm test- Run all testsnpm run test:watch- Run tests in watch modenpm run test:coverage- Run with coverage report
## Tips & Variations
- **Team Conventions**: Include coding standards, PR guidelines, and review checklists
- **Environment Setup**: Document required environment variables and their purposes
- **Troubleshooting**: Add common issues and their solutions
- **Integration Instructions**: Include API keys setup, third-party service configuration
- **Performance Guidelines**: Add benchmarking commands and optimization tips
## Troubleshooting
- **Issue**: Claude doesn't seem to remember the instructions
**Solution**: Ensure CLAUDE.md is in the project root, not in a subdirectory
- **Issue**: Instructions are too long
**Solution**: Focus on commands and conventions specific to your project, not general best practices
- **Issue**: Want different rules for different directories
**Solution**: Create CLAUDE.md files in subdirectories for context-specific guidance
## References
- [Claude Code Memory Documentation](https://docs.anthropic.com/en/docs/claude-code/memory)
- [CLAUDE.md Best Practices](https://docs.anthropic.com/en/docs/claude-code/memory#best-practices)