CLAUDE.md – Project Instructions for AI-Assisted Development

CLAUDE.md is a special Markdown file placed in the root directory of a project that is automatically included in every Claude Code prompt. It functions like an extended project description for AI assistants – a structured collection of rules, best practices, architecture documentation, and workflows that Claude should understand and follow.

Unlike generic documentation, CLAUDE.md is specifically designed for AI assistants to actively use this information. The file contains concrete, non-negotiable rules (using words like "NEVER", "ALWAYS", "MANDATORY"), rather than vague recommendations.

What Is CLAUDE.md?

CLAUDE.md is a project file that Claude Code automatically reads and incorporates into the context of every prompt. It functions as an "operating manual for this project" from the perspective of an AI assistant.

Core Functions:

• Automatic context inclusion: Claude Code loads CLAUDE.md automatically and takes the contents into account with every prompt
• Persistent rules: Rules defined once apply consistently across all sessions
• Team communication: New developers (human or AI) immediately understand the project conventions
• Improved quality: Structured guidelines lead to more consistent, better code
• Error prevention: Anti-patterns can be explicitly prohibited before they occur

Why Is CLAUDE.md Important?

Without CLAUDE.md the developer must repeat all relevant information in every prompt. With CLAUDE.md:

• Claude immediately understands the architecture of the project
• Code quality rules are applied consistently
• Security guidelines (e.g. "no hardcoded credentials") are automatically observed
• Deployment workflows are documented and followed
• The AI works like an experienced project team member, not like a newly trained intern

Structure of a CLAUDE.md

A professional CLAUDE.md typically has the following structure:

1. Critical Rules (at the top!)

The most important, non-negotiable rules – often with warning icons and NEVER/ALWAYS in uppercase:

## ⚠️ CRITICAL RULES - ABSOLUTELY BINDING

- **NEVER hardcode anything!** There are clear instructions: always use the API.
- **NO DATA FALLBACKS** – only empty "" fallbacks allowed.
- **NEVER hardcode credentials** – ALWAYS use environment variables.
- **Language:** Everything in English with correct spelling.

2. Quick Start Commands

The most important commands for starting the project:

## Quick Start Commands

### Development Server
```bash
npm run dev              # Start all services
npm run lint             # Code style check
npm run build            # Production build
```

3. Server & Architecture

Table with ports, URLs, and technical details:

## Server & Architecture

| Service | Port | URL |
|---------|------|-----|
| Frontend (Vite) | 5175 | http://localhost:5175 |
| Backend (Express) | 3030 | http://localhost:3030 |
| Production | - | https://elasticbrains.de |

4. Code Style Guidelines

Concrete, actionable conventions:

## Code Style Guidelines
- **Project:** Vue 3 with Vite, Composition API
- **Indentation:** 2 spaces
- **Components:** PascalCase naming (ComponentName.vue)
- **JavaScript Variables:** camelCase
- **CSS Classes:** kebab-case
- **State:** ref/computed for local state, provide/inject for global state

5. Security and Testing Requirements

Concrete security measures and testing checklists:

## Security
- Use Helmet security headers
- Rate limiting for API endpoints
- JWT authentication with access & refresh tokens
- Input validation for all user inputs

## Testing
```bash
npm run test             # Unit tests
npm run build            # Build check
npx tsc --noEmit        # TypeScript check
npm run lint             # Linting
```

6. Documentation and Deployment

How to handle existing documentation and how deployment works:

## Documentation Maintenance
- After new pages: npm run generate-sitemap
- Admin area: update SEO metadata
- New code: add JSDoc comments

## Deployment
./deploy.sh             # Interactive deployment menu

CLAUDE.md vs. Other Project Instructions

There are several formats for project instructions. CLAUDE.md is specific to Claude Code, but there are alternatives:

Format	Tool	Location	Automatic Loading
CLAUDE.md	Claude Code (Anthropic)	Project Root	Yes, automatically into every prompt
.cursorrules	Cursor IDE	Project Root	Yes, automatically into every prompt
.github/copilot-instructions.md	GitHub Copilot	GitHub Repository	Yes, for Copilot Chat
README.md	General	Project Root	Only when manually referenced
MEMORY.md	Local	Project or user config	Optional, manual referencing

Why CLAUDE.md over README.md?

• README.md: Written for humans – project overview, features, installation
• CLAUDE.md: Written for AI – concrete rules, anti-patterns, "how do I work in this project"

README.md says: "This is a Vue 3 frontend with Express backend." CLAUDE.md says: "ALWAYS use the Logger from @/core/Logger, never console.log. All filters are persisted in localStorage. Admin views use full width without max-width."

Best Practices for CLAUDE.md

1. Concrete Rules Instead of Vague Recommendations

Wrong:

- Logger should be preferred
- Code should be TypeScript
- Components should be modular

Correct:

- **NEVER** use console.log/warn/error. **ALWAYS** use Logger from @/core/Logger.
- **ALL files MUST be TypeScript** (.ts or .tsx)
- **ALWAYS use Composition API**, Options API is forbidden

2. Provide Examples

Not just state the rule, but show how it looks correctly:

## Logging

// CORRECT:
import { Logger } from '@/core/Logger'
Logger.debug('ADMIN', 'Loading users', { count: users.length })

// WRONG - NEVER:
console.log('Loading users')
console.warn('Something happened')

3. Explicitly Prohibit Anti-Patterns

With warning icons so it is taken seriously:

## ⚠️ FORBIDDEN PATTERNS

- **NEVER hardcoded credentials** (passwords, API keys)
- **NOT window.innerWidth in onMounted** – causes layout reflow
- **NO mock data in production code** – only real API data
- **DO NOT hardcode /api/* endpoints** – use API service

4. Document Workflows

Not just WHAT, but also HOW – with exact commands:

## Deployment Workflow

### 1. Before Deployment
```bash
npm run build           # Full build
npm run lint            # Code quality
npx tsc --noEmit       # Type check
```

### 2. Deployment
```bash
./deploy.sh             # Starts deployment.sh with interactive menu
./deploy.sh --dry-run   # Preview without changes
./deploy.sh --force     # Deploy without confirmation
```

### 3. After Deployment
```bash
curl https://elasticbrains.de/api/health  # Health check
```

5. Visually Highlight Important Items

Use Markdown features to direct attention:

## ⚠️ CRITICAL: Production Environment

**NEVER on the production server:**
- Database commands without backup
- rm -rf without explicit path
- Change global nginx configuration
- Affect other services

6. Don't Forget Security

Clear rules for credentials and environment variables:

## ⚠️ NEVER HARDCODED CREDENTIALS

- **NEVER** passwords, API keys, tokens in code
- **ALWAYS** use environment variables: process.env.VARIABLE_NAME
- **ALWAYS** throw an error when a required ENV variable is missing:
  ```typescript
  if (!process.env.MONGODB_URI) {
    throw new Error('MONGODB_URI environment variable is required');
  }
  ```

Hierarchical Contexts: Global → Project → Task

There are several levels of context information that an AI should take into account:

Level 1: Global CLAUDE.md (~/.claude/CLAUDE.md)

Rules applying to ALL projects:

• Coding standards (TypeScript, Composition API, language)
• Security principles (no hardcoded credentials)
• Tool preferences (Logger instead of console.log)
• Personal working style

Level 2: Project CLAUDE.md (PROJECT_ROOT/CLAUDE.md)

Specific to the current project:

• Architecture (Vue 3 + Express, Vite, Tailwind CSS)
• Tech stack details (which libraries, which versions)
• Project-specific workflows (./deploy.sh, npm run generate-sitemap)
• Server configuration (ports, production URLs)
• Specifics (admin authentication, service worker, etc.)

Level 3: Memory Files & Task Context

Dynamic context for the current task:

• MEMORY.md with lessons learned and known issues
• Session handover files for long sessions
• Relevant files for the current task

This hierarchy ensures that global principles are preserved while project-specific details are also observed.

CLAUDE.md as an Onboarding Tool

CLAUDE.md also works perfectly as onboarding material for new developers:

For New Human Developers:

• "I'm new. What do I need to know about this project?" → Read CLAUDE.md
• "How do I start the dev server?" → Quick Start Commands in CLAUDE.md
• "What are the code style rules?" → Code Style Guidelines in CLAUDE.md
• "How do I deploy?" → Deployment section in CLAUDE.md

For AI Assistants:

• Claude Code loads CLAUDE.md automatically
• New AI assistants immediately understand the project rules
• No "cold start" – the AI knows the architecture from the beginning
• Consistent behavior over days, weeks, months

Knowledge Preservation:

• When developers leave the project, their knowledge stays in CLAUDE.md
• Lessons learned are documented
• Avoidance of "silo knowledge" with individual people
• New developers (human or AI) benefit from this documentation

CLAUDE.md at Elasticbrains

At Elasticbrains we have a two-layer system:

• Global CLAUDE.md: (~/.claude/CLAUDE.md) Defines our standards across ALL projects: language with proper spelling, TypeScript, no hardcoded credentials, clean code architecture
• Project CLAUDE.md: (/elasticbrains-website/CLAUDE.md) Specific to elasticbrains-website: Vite, Vue 3, Express backend, admin dashboard with JWT auth, SEO requirements, deployment via ./deploy.sh

The result: no matter which developer (human or AI) works on the project, quality and consistency are guaranteed.

Common Mistakes with CLAUDE.md

1. Too General ("Best Practices")

Wrong: "Code should be well-structured."

Correct: "Use Composition API, never Options API. Components in src/components/, Views in src/views/. Logger instead of console.log."

2. Too Much at Once

CLAUDE.md is included in the token context. A 10-page CLAUDE.md consumes precious tokens. Focus on what matters most:

• Critical rules (at top)
• Quick start
• Server configuration
• Code style
• Security
• Deployment

3. Rules Nobody Follows

If a rule is truly not followed, it is wrong. CLAUDE.md should be realistic:

• "Never debug" – unrealistic
• "Everything in TypeScript" – if the project is partly JS, adjust accordingly
• "No external dependencies" – if the project has 50 npm packages, adjust accordingly

4. Updated Too Infrequently

CLAUDE.md is a living document. If the architecture changes, CLAUDE.md must be updated. An old, outdated CLAUDE.md is worse than no CLAUDE.md.

Workshop Reference: Mastering Agentic Coding

CLAUDE.md is a central component of the Agentic Coding Workshop. In our workshop you will learn:

• How to write professional, maintainable CLAUDE.md files
• Best practices for project instructions from 3 years of experience
• How to combine CLAUDE.md, memory files, and session handover
• Practical exercises: write and test your own CLAUDE.md
• Context Engineering: how to make optimal use of context information
• Integration with Claude Code, Cursor, and other AI tools

The workshop demonstrates how systematic context engineering (of which CLAUDE.md is a part) improves the quality and efficiency of AI-assisted development many times over.

Tools and Integration

Claude Code (Anthropic)

• CLAUDE.md is automatically recognized and included in every prompt
• The latest file version is always used
• No manual configuration needed
• Full support for Markdown formatting

Cursor IDE

• .cursorrules file with a similar purpose
• Automatically loaded at startup
• Integration with Cursor Composer

GitHub Copilot

• .github/copilot-instructions.md
• Less mature than CLAUDE.md or .cursorrules
• Works with GitHub Copilot Chat

Further Resources

• Glossary: Context Engineering – comprehensive guide to structured AI context
• Glossary: Agentic Coding – practicing AI-assisted software development
• Glossary: Prompt Engineering – formulating individual AI prompts optimally
• Workshop: Agentic Coding Workshop – hands-on experience with project instructions and context engineering
• Tools: Claude Code, Cursor IDE, GitHub Copilot
• Documentation: Anthropic Claude API Documentation, Cursor Documentation

Summary

CLAUDE.md is not just a document – it is an interface between human developers and AI assistants. A well-written CLAUDE.md:

• Makes project knowledge permanent and shareable
• Improves the quality of AI-generated code
• Saves time through clear, repeatable rules
• Is an onboarding tool for new developers (human and AI)
• Preserves lessons learned, even when developers leave
• Enables professional, scalable Agentic Coding

The best CLAUDE.md is one that is regularly read and updated – a living document that grows with the project.