CLAUDE.md Best Practices - Efficient Collaboration Between AI and Humans¶

Key Points¶

AI Behavior Optimization
Guide AI with project-specific rules
:material-checklist: Quality Control
Ensure consistency with checklists
Workflow Automation
Process routine tasks efficiently
Team Collaboration
Work together with common guidelines

📖 What is CLAUDE.md?¶

CLAUDE.md is a configuration file that provides project-specific instructions to Claude Code (AI development assistant). By properly configuring this file, AI can understand your project's rules and conventions, providing more effective assistance.

Basic Structure¶

# CLAUDE.md

## Project Overview
Description of project purpose and structure

## Development Guidelines
- Coding standards
- Naming conventions
- Architecture patterns

## Workflows
Standard procedures and commands

## Checklists
Quality control checkpoints

🚀 Creating an Effective CLAUDE.md¶

1. Project Overview Section¶

## Repository Overview

This is a [project type] built with [main technology stack].

### Key Features
- Feature 1: Description
- Feature 2: Description
- Feature 3: Description

### Target Users
- Primary: [main user base]
- Secondary: [secondary user base]

### Development Status
- Current Phase: [development phase]
- Version: [version number]
- Stability: [stability level]

2. Technology Stack and Dependencies¶

## Technology Stack

### Frontend
- Framework: React 18.2 with TypeScript
- UI Library: Material-UI v5
- State Management: Redux Toolkit
- Build Tool: Vite

### Backend
- Runtime: Node.js 18 LTS
- Framework: Express.js
- Database: PostgreSQL 15
- ORM: Prisma

### Infrastructure
- Hosting: AWS (EC2, RDS, S3)
- CI/CD: GitHub Actions
- Monitoring: DataDog
- Container: Docker

3. Development Guidelines¶

## Development Guidelines

### Code Style
- **Language**: TypeScript with strict mode
- **Linting**: ESLint with Airbnb config
- **Formatting**: Prettier with 2-space indentation
- **Naming**:
  - Components: PascalCase (e.g., `UserProfile`)
  - Functions: camelCase (e.g., `getUserData`)
  - Constants: UPPER_SNAKE_CASE (e.g., `API_BASE_URL`)
  - Files: kebab-case (e.g., `user-profile.tsx`)

### Git Conventions
- **Branches**: feature/*, bugfix/*, hotfix/*
- **Commits**: Conventional Commits format
  - feat: New feature
  - fix: Bug fix
  - docs: Documentation
  - style: Code style
  - refactor: Code refactoring
  - test: Test updates
  - chore: Build/tooling updates

### Testing Requirements
- Unit tests: Jest with 80% coverage minimum
- Integration tests: Cypress for critical paths
- Performance tests: Lighthouse score > 90

4. Workflows and Commands¶

## Common Commands

### Development
```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Deploy to staging
npm run deploy:staging

# Deploy to production
npm run deploy:prod

Database Operations¶

# Run migrations
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

# Seed database
npm run db:seed

# Reset database
npm run db:reset

Code Quality¶

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Type check
npm run type-check

# Run all checks
npm run check:all

### 5. Checklist System

```markdown
## 📝 Task Checklists

### Feature Development Checklist
- [ ] **Requirements Review**: Understand the feature requirements
- [ ] **Design Review**: Review UI/UX designs if applicable
- [ ] **Implementation Plan**: Create implementation approach
- [ ] **Code Implementation**: Write the feature code
- [ ] **Unit Tests**: Write comprehensive unit tests
- [ ] **Integration Tests**: Add integration tests
- [ ] **Documentation**: Update relevant documentation
- [ ] **Code Review**: Submit PR and get approval
- [ ] **QA Testing**: Ensure QA team has tested
- [ ] **Deployment**: Deploy to production

### Bug Fix Checklist
- [ ] **Reproduce Issue**: Confirm bug reproduction steps
- [ ] **Root Cause Analysis**: Identify the root cause
- [ ] **Fix Implementation**: Implement the fix
- [ ] **Regression Tests**: Add tests to prevent regression
- [ ] **Verify Fix**: Confirm fix resolves the issue
- [ ] **Related Issues**: Check for similar issues
- [ ] **Documentation**: Update if needed
- [ ] **Deploy**: Release the fix

### Code Review Checklist
- [ ] **Functionality**: Code works as intended
- [ ] **Tests**: Adequate test coverage
- [ ] **Performance**: No performance regressions
- [ ] **Security**: No security vulnerabilities
- [ ] **Style**: Follows coding standards
- [ ] **Documentation**: Code is well-documented
- [ ] **Dependencies**: No unnecessary dependencies
- [ ] **Breaking Changes**: Identified and documented

🧠 Auto Memory¶

Claude Code automatically saves context and decisions to ~/.claude/projects/<project>/memory/. Note that MEMORY.md (the index) only loads the first 200 lines. For details on how it works and how to disable it, see Command Reference > Auto Memory Control.

📁 Rule Modularization with `.claude/rules/`¶

Cramming all instructions and constraints (coding style, test strategy, deployment steps, etc.) into CLAUDE.md leads to heavy token consumption and unnecessary context bloat. The 2026 best practice is to split purpose-specific rule files into the .claude/rules/ directory and reference them from CLAUDE.md via @import or links as needed.

.claude/rules/
├── code-style.md   # [TypeScript style] Referenced only when editing TS files
├── security.md     # [Auth & permissions] Referenced when editing security-related files
└── frontend/
    └── testing.md  # [Frontend test strategy] Referenced when writing test code

This keeps CLAUDE.md focused on "core system knowledge that only humans know (tacit knowledge)" and enables smarter agent operation.

🎯 Practical Examples¶

1. Documentation Site CLAUDE.md¶

# CLAUDE.md - Documentation Site

## Project Overview
Technical documentation site using MkDocs Material.

## Article Creation Workflow

### Pre-Writing
- [ ] Research topic thoroughly
- [ ] Check for existing similar content
- [ ] Define target audience
- [ ] Create article outline

### Writing
- [ ] Write primary language version
- [ ] Create translations
- [ ] Add code examples
- [ ] Include visual elements (diagrams, cards)
- [ ] Add cross-references

### Quality Assurance
- [ ] Grammar and spell check
- [ ] Test all code examples
- [ ] Verify all links
- [ ] Check formatting consistency

### Deployment
- [ ] Update navigation
- [ ] Git add, commit, push
- [ ] Deploy to production
- [ ] Verify live deployment
- [ ] Test search functionality

## Article Template

```markdown
# Article Title


## Key Points

<div class="grid cards" markdown>
-   :material-icon: **Feature**
    Description
</div>

## Overview
Introduction...

## Implementation
Implementation details...

## Related Articles
- [Related Article](/generative-ai/claude/related/)

---

Common Commands¶

# Local development
mkdocs serve

# Deploy to GitHub Pages
mkdocs gh-deploy

# Build static files
mkdocs build

### 2. API Project CLAUDE.md

```markdown
# CLAUDE.md - REST API Project

## Architecture Overview

src/ ├── controllers/ # Request handlers ├── services/ # Business logic ├── models/ # Data models ├── middleware/ # Express middleware ├── utils/ # Helper functions └── config/ # Configuration files

## API Development Guidelines

### Endpoint Naming
- Use nouns, not verbs
- Use plural for collections
- Use kebab-case for multi-word resources

Examples:
- GET /api/users
- GET /api/users/:id
- POST /api/users
- GET /api/user-profiles

### Response Format
```json
{
  "success": true,
  "data": {},
  "error": null,
  "metadata": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}

Error Handling¶

// Always use this error format
throw new AppError('Error message', 400, 'ERROR_CODE');

Testing Requirements¶

All endpoints must have: 1. Unit tests for business logic 2. Integration tests for API endpoints 3. Load tests for performance-critical endpoints

Security Checklist¶

Input validation on all endpoints
Authentication required (except public endpoints)
Rate limiting implemented
SQL injection prevention
XSS prevention

CORS properly configured

### 3. Frontend Project CLAUDE.md

```markdown
# CLAUDE.md - React Application

## Component Development

### Component Structure
```typescript
// components/UserProfile/UserProfile.tsx
import React from 'react';
import { UserProfileProps } from './UserProfile.types';
import { useUserProfile } from './UserProfile.hooks';
import styles from './UserProfile.module.css';

export const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {
  const { user, loading, error } = useUserProfile(userId);

  // Component logic
};

State Management Rules¶

Local state for UI-only state
Context for cross-component state
Redux for global application state
React Query for server state

Performance Guidelines¶

Use React.memo for expensive components
Implement virtual scrolling for long lists
Lazy load routes and heavy components
Optimize images with next-gen formats

Accessibility Requirements¶

All components must: - [ ] Have proper ARIA labels - [ ] Support keyboard navigation - [ ] Meet WCAG 2.1 AA standards - [ ] Pass automated a11y tests - [ ] Include screen reader testing

CSS Guidelines¶

/* Use CSS Modules */
.container {
  /* Mobile-first approach */
  padding: 1rem;

  @media (min-width: 768px) {
    padding: 2rem;
  }
}

/* Use CSS variables for theming */
.button {
  background-color: var(--primary-color);
  color: var(--text-on-primary);
}

## 💡 Best Practices

### 1. Clear and Actionable Instructions

```markdown
# Good ✅
## File Naming
- Components: PascalCase (e.g., UserProfile.tsx)
- Utilities: camelCase (e.g., formatDate.ts)
- Tests: *.test.ts or *.spec.ts

# Bad ❌
## File Naming
Files should be named appropriately.

2. Specific Code Examples¶

# Good ✅
## Error Handling Pattern
```typescript
try {
  const result = await apiCall();
  return { success: true, data: result };
} catch (error) {
  logger.error('API call failed', { error, context });
  return { success: false, error: error.message };
}

Bad ❌¶

Error Handling¶

Handle errors properly.

### 3. Effective Use of Checklists

```markdown
# Good ✅
## PR Checklist
- [ ] Tests pass locally
- [ ] No console.log statements
- [ ] Documentation updated
- [ ] Changelog entry added
- [ ] Performance impact assessed

# Bad ❌
## PR Requirements
Make sure everything is good before submitting.

🔄 Continuous Improvement¶

1. Regular Reviews¶

## Maintenance Schedule

### Weekly
- Review and update task checklists
- Check for outdated dependencies
- Review error logs

### Monthly
- Update documentation
- Review and refine guidelines
- Analyze code metrics

### Quarterly
- Major dependency updates
- Architecture review
- Performance audit

2. Feedback Collection¶

## Feedback Collection

### Developer Feedback
- What guidelines are unclear?
- What tasks are repetitive?
- What tools are missing?

### AI Performance
- Track successful completions
- Identify common mistakes
- Measure time savings

### Improvement Ideas
- [ ] Add more code examples
- [ ] Create video tutorials
- [ ] Build custom tools

🎓 Learning Resources¶

External Resources¶

🚀 Next Steps¶

Apply to Existing Projects: Add CLAUDE.md to your current project
Share with Team: Review content with team members
Continuous Refinement: Improve content through usage
Measure Impact: Quantify productivity improvements

CLAUDE.md Best Practices - Efficient Collaboration Between AI and Humans¶

Key Points¶

📖 What is CLAUDE.md?¶

Basic Structure¶

🚀 Creating an Effective CLAUDE.md¶

1. Project Overview Section¶

2. Technology Stack and Dependencies¶

3. Development Guidelines¶

4. Workflows and Commands¶

Database Operations¶

Code Quality¶

🧠 Auto Memory¶

📁 Rule Modularization with .claude/rules/¶

🎯 Practical Examples¶

1. Documentation Site CLAUDE.md¶

Common Commands¶

Error Handling¶

Testing Requirements¶

Security Checklist¶

State Management Rules¶

Performance Guidelines¶

Accessibility Requirements¶

CSS Guidelines¶

2. Specific Code Examples¶

Bad ❌¶

Error Handling¶

🔄 Continuous Improvement¶

1. Regular Reviews¶

2. Feedback Collection¶

🎓 Learning Resources¶

Recommended Articles¶

External Resources¶

🚀 Next Steps¶

📁 Rule Modularization with `.claude/rules/`¶