Claude-Code-Workflow/docs/guide/claude-md.md

CLAUDE.md Guide

Configure project-specific instructions for CCW using CLAUDE.md.

What is CLAUDE.md?

CLAUDE.md is a special file that contains project-specific instructions, conventions, and preferences for CCW. It's automatically loaded when CCW operates on your project.

File Location

Place CLAUDE.md in your project root:

my-project/
├── CLAUDE.md          # Project instructions
├── package.json
└── src/

File Structure

# Project Name

## Overview
Brief description of the project.

## Tech Stack
- Frontend: Framework + libraries
- Backend: Runtime + framework
- Database: Storage solution

## Coding Standards
- Style guide
- Linting rules
- Formatting preferences

## Architecture
- Project structure
- Key patterns
- Important conventions

## Development Guidelines
- How to add features
- Testing requirements
- Documentation standards

Example CLAUDE.md

# E-Commerce Platform

## Overview
Multi-tenant e-commerce platform with headless architecture.

## Tech Stack
- Frontend: Vue 3 + TypeScript + Vite
- Backend: Node.js + NestJS
- Database: PostgreSQL + Redis
- Queue: BullMQ

## Coding Standards

### TypeScript
- Use strict mode
- No implicit any
- Explicit return types

### Naming Conventions
- Components: PascalCase (UserProfile.ts)
- Utilities: camelCase (formatDate.ts)
- Constants: UPPER_SNAKE_CASE (API_URL)

### File Structure

src/ ├── components/ # Vue components ├── composables/ # Vue composables ├── services/ # Business logic ├── types/ # TypeScript types └── utils/ # Utilities

## Architecture

### Layered Architecture
1. **Presentation Layer**: Vue components
2. **Application Layer**: Composables and services
3. **Domain Layer**: Business logic
4. **Infrastructure Layer**: External services

### Key Patterns
- Repository pattern for data access
- Factory pattern for complex objects
- Strategy pattern for payments

## Development Guidelines

### Adding Features
1. Create feature branch from develop
2. Implement feature with tests
3. Update documentation
4. Create PR with template

### Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Coverage: >80%

### Commits
Follow conventional commits:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- refactor: Refactoring
- test: Tests

## Important Notes
- Always use TypeScript strict mode
- Never commit .env files
- Run linter before commit
- Update API docs for backend changes

Sections

Required Sections

Section	Purpose
Overview	Project description
Tech Stack	Technologies used
Coding Standards	Style conventions
Architecture	System design

Optional Sections

Section	Purpose
Testing	Test requirements
Deployment	Deploy process
Troubleshooting	Common issues
References	External docs

Best Practices

1. Keep It Current

Update CLAUDE.md when:

• Tech stack changes
• New patterns adopted
• Standards updated

2. Be Specific

Instead of:

## Style
Follow good practices

Use:

## Style
- Use ESLint with project config
- Max line length: 100
- Use single quotes for strings

3. Provide Examples

## Naming
Components use PascalCase:
- UserProfile.vue ✓
- userProfile.vue ✗

Multiple Projects

For monorepos, use multiple CLAUDE.md files:

monorepo/
├── CLAUDE.md           # Root instructions
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md   # Frontend specific
│   └── backend/
│       └── CLAUDE.md   # Backend specific

Template

# [Project Name]

## Overview
[1-2 sentence description]

## Tech Stack
- [Framework/Language]
- [Key libraries]

## Coding Standards
- [Style guide]
- [Linting]

## Architecture
- [Structure]
- [Patterns]

## Development
- [How to add features]
- [Testing approach]

## Notes
- [Important conventions]

::: info See Also

• Configuration - CLI tools config
• Workflows - Development workflows :::