Skip to content

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

CLAUDE.md

What You Can Achieve

  • 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

🎯 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

![Badge](https://img.shields.io/badge/Category-Topic-blue.svg)

## What You Can Achieve

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

## Overview
Introduction...

## Implementation
Implementation details...

## Related Articles
- [Related Article](./related.md)

---

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

  1. Local state for UI-only state
  2. Context for cross-component state
  3. Redux for global application state
  4. 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

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