7.2 KiB
Claude.md Structure Guide
This guide explains what makes an effective claude.md file and how to structure documentation for maximum utility when working with Claude.
Purpose of claude.md Files
A claude.md file serves as context documentation that helps Claude (and humans) understand:
- What this directory contains - Purpose and scope
- How code is organized - Structure and patterns
- Key relationships - Dependencies and connections
- Important context - Gotchas, conventions, and decisions
Core Principles
1. Be Specific and Concrete
❌ Avoid vague descriptions:
## Overview
This directory contains utilities.
✅ Be specific:
## Overview
This directory contains database utility functions for connection pooling,
query building, and transaction management. These utilities are used across
all services to ensure consistent database interactions.
2. Prioritize Actionable Information
Focus on information that helps someone understand how to work with the code:
- Entry points - Where to start reading/editing
- Key patterns - How things are typically done
- Dependencies - What relies on what
- Gotchas - Non-obvious behavior or limitations
3. Keep it Current
A stale claude.md is worse than none at all. Include:
- Maintenance notes ("Last updated: 2025-10-21")
- Who maintains this area
- How to update the documentation
Recommended Structure
Essential Sections
1. Header and Overview (Required)
Start with a clear title and 1-3 sentence overview:
# src/api/
This directory implements the REST API layer, handling HTTP requests,
validation, and response formatting. All endpoints follow OpenAPI 3.0
specification defined in `openapi.yaml`.
2. Directory Structure (If Complex)
Show the layout with brief descriptions:
## Directory Structure
api/ ├── routes/ # Route handlers grouped by resource ├── middleware/ # Express middleware (auth, validation, logging) ├── validators/ # Request/response validation schemas └── serializers/ # Response formatting utilities
3. Key Files (If Applicable)
Highlight important files and their roles:
## Key Files
- **index.ts**: API server initialization and middleware setup
- **routes.ts**: Central route registration
- **error-handler.ts**: Global error handling middleware
- **openapi.yaml**: API specification (source of truth for endpoints)
4. Important Patterns (Critical)
Document conventions and patterns used in this directory:
## Important Patterns
### Route Handler Structure
All route handlers follow this pattern:
1. Validate request (using Zod schemas in `validators/`)
2. Call service layer (never direct database access)
3. Serialize response (using serializers)
4. Handle errors (throw specific error types)
### Error Handling
- Use `ApiError` class for all API errors
- Status codes: 400 (validation), 401 (auth), 404 (not found), 500 (server)
- Errors are caught by global error handler middleware
### Naming Conventions
- Routes: kebab-case (`/user-profiles`)
- Files: kebab-case (`user-profile-routes.ts`)
- Handlers: camelCase (`getUserProfile`)
5. Dependencies (Important)
Explain relationships with other parts of the codebase:
## Dependencies
### Imports From
- `src/services/` - Business logic layer
- `src/models/` - Data models and types
- `src/lib/` - Shared utilities (logger, config)
### Used By
- All services make HTTP requests to these endpoints
- Frontend application at `/frontend`
### External Dependencies
- Express.js for routing
- Zod for validation
- OpenAPI Tools for spec validation
6. Usage/Getting Started (For Complex Areas)
Help someone get started quickly:
## Usage
### Adding a New Endpoint
1. Define the route in `openapi.yaml`
2. Create handler in `routes/{resource}-routes.ts`
3. Add validation schema in `validators/{resource}-validator.ts`
4. Add serializer in `serializers/{resource}-serializer.ts`
5. Register route in `routes.ts`
Example:
[Include minimal working example]
### Testing
Run API tests:
```bash
npm run test:api
Test single endpoint:
npm run test:api -- --grep "GET /users"
### Optional Sections
#### Architecture Decisions
Document important "why" decisions:
```markdown
## Architecture Decisions
### Why Express over Fastify?
- Team familiarity
- Better TypeScript support at time of decision
- Larger middleware ecosystem
### Why Separate Validators?
- Reusable across routes and tests
- Type inference for request/response objects
- Easier to maintain OpenAPI spec sync
Gotchas and Known Issues
Save others from pain:
## Gotchas
- **Async Handler Wrapping**: All async route handlers must be wrapped with
`asyncHandler()` or errors won't be caught properly
- **Query Parameter Parsing**: Express doesn't parse nested query params by
default. Use `qs` library for complex queries.
- **Rate Limiting**: Applied at middleware level, not per-route. See
`middleware/rate-limiter.ts` for configuration.
What NOT to Include
Avoid these common pitfalls:
❌ Don't duplicate what's obvious from code:
## Files
- user.ts - Contains user-related code
- product.ts - Contains product-related code
❌ Don't write tutorials for basics:
## What is an API?
An API is an Application Programming Interface...
❌ Don't include things that change frequently:
## Team
Current maintainers:
- Alice (alice@company.com) - Lead
- Bob (bob@company.com) - Backend
[This will be stale immediately]
✅ Instead, link to maintained sources:
## Maintenance
See [CODEOWNERS](../../CODEOWNERS) for current maintainers.
Hierarchy and Inheritance
Root claude.md
The root claude.md provides high-level project context:
# Project Name
## Overview
[High-level description of the entire project]
## Architecture
[System architecture overview]
## Directory Guide
- `/src` - Application source code ([claude.md](src/claude.md))
- `/tests` - Test suite ([claude.md](tests/claude.md))
- `/docs` - Documentation ([claude.md](docs/claude.md))
## Getting Started
[Setup and development workflow]
Child claude.md Files
Child files inherit context from parent, so avoid repetition:
# src/api/routes/
Specific information about route handlers only. See parent
[src/api/claude.md](../claude.md) for overall API structure.
Maintenance
Keep It Fresh
Add maintenance metadata:
---
Last Updated: 2025-10-21
Maintainer: API Team (@api-team)
---
Update Triggers
Update claude.md when:
- Major architectural changes occur
- New patterns are introduced
- Important files are added/removed/renamed
- Gotchas are discovered
- Team conventions change
Review Regularly
- Quarterly reviews of all
claude.mdfiles - Update during major refactors
- Validate during onboarding (new team members test docs)
Templates by Directory Type
See examples.md for complete templates for:
- Source code directories
- Test directories
- API/Service layers
- Configuration directories
- Documentation directories
- Library/utility directories