Comprehensive Claude Module

Overview

A Comprehensive Claude Module is a structured configuration approach for maximizing Claude Code's effectiveness across an entire project. It encompasses CLAUDE.md files (project-level and directory-level), global configuration in ~/.claude/CLAUDE.md, slash commands, custom skills, agent definitions, and workflow conventions that together form a complete "operating system" for Claude Code within your codebase.

This matters because Claude Code's quality is directly proportional to the context it receives. A well-configured module system turns Claude from a generic assistant into a project-specific expert that knows your architecture, follows your coding standards, understands your testing conventions, and integrates with your deployment pipeline. Teams that invest in module configuration report substantially fewer corrections and faster iteration cycles.

When to Use

• Setting up Claude Code for a new project or onboarding a new team
• Standardizing AI behavior across a monorepo with multiple services (frontend, backend, infra)
• Creating reusable configuration patterns that can be shared across projects
• Building custom workflows (commit conventions, PR templates, review processes)
• Establishing coding standards that Claude enforces automatically
• Setting up directory-specific context so Claude understands different parts of your codebase

Quick Start

Copy
# Initialize Claude Code configuration
claude /init

# This generates a starter CLAUDE.md -- customize it:
# Edit the root CLAUDE.md with project-specific conventions

# Create directory-specific modules
mkdir -p frontend/.claude backend/.claude infra/.claude

# Set up global defaults (applies to all projects)
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'GLOBAL'
# Global Claude Configuration

## Development Philosophy
- No speculative features -- only build what is requested
- No premature abstraction -- wait for the third use case
- Replace, do not deprecate -- remove old code immediately
- Function max length: 40 lines. If longer, extract.

## Code Quality
- TypeScript: strict mode, no `any` types, prefer interfaces over types
- Python: type hints on all function signatures, docstrings on public functions
- All code must pass lint and type checking before committing

## Workflow
- Always run tests after making changes
- Create atomic commits with conventional commit messages
- Never push directly to main -- use feature branches
GLOBAL

Copy
<!-- CLAUDE.md (project root) -->
# Project: MyApp

## Architecture
- Frontend: Next.js 14 (App Router) in /frontend
- Backend: Express + TypeScript in /backend
- Database: PostgreSQL with Prisma ORM
- Infrastructure: AWS CDK in /infra

## Build & Test Commands
- Frontend: `cd frontend && npm run build`
- Frontend tests: `cd frontend && npm test`
- Backend: `cd backend && npm run build`
- Backend tests: `cd backend && npm test`
- Full test suite: `npm run test:all`
- Lint: `npm run lint`
- Type check: `npm run typecheck`

## Code Style
- Use ES modules (import/export), never CommonJS (require)
- Prefer named exports over default exports
- Use Zod for runtime validation at API boundaries
- Error handling: always catch and wrap with custom error types

## File Conventions
- Components: PascalCase.tsx (e.g., UserProfile.tsx)
- Utilities: camelCase.ts (e.g., formatDate.ts)
- Tests: co-located as *.test.ts or *.test.tsx
- API routes: kebab-case folders (e.g., /api/user-profile/)

## Git Conventions
- Branch naming: feature/*, bugfix/*, chore/*
- Commit format: type(scope): description
- Always include test coverage for new features

@import frontend/CLAUDE.md
@import backend/CLAUDE.md

Core Concepts

1. CLAUDE.md Hierarchy

Claude Code reads CLAUDE.md files at multiple levels, with more specific files taking precedence:

~/.claude/CLAUDE.md              # Global (all projects)
  |
  v
/project/CLAUDE.md              # Project root
  |
  v
/project/frontend/CLAUDE.md     # Directory-specific
  |
  v
/project/frontend/components/CLAUDE.md  # Sub-directory specific

Copy
<!-- frontend/CLAUDE.md -->
# Frontend Module

## Framework
- Next.js 14 with App Router
- React Server Components by default, "use client" only when needed
- TailwindCSS for styling, no CSS modules

## Component Patterns
- Use compound components for complex UI
- Server components fetch data, client components handle interaction
- All components must have TypeScript props interfaces

## State Management
- Server state: React Query (TanStack Query)
- Client state: Zustand (never Redux)
- Form state: React Hook Form + Zod validation

## Example: New Component
When creating a new component, follow this pattern:
```tsx
// components/UserCard/UserCard.tsx
interface UserCardProps {
  user: User;
  onSelect?: (userId: string) => void;
}

export function UserCard({ user, onSelect }: UserCardProps) {
  return (
    <div className="rounded-lg border p-4">
      <h3 className="font-semibold">{user.name}</h3>
      {onSelect && (
        <button onClick={() => onSelect(user.id)}>Select</button>
      )}
    </div>
  );
}

Testing

• Component tests: React Testing Library
• Always test user interactions, not implementation details
• Mock API calls with MSW (Mock Service Worker)

### 2. Example-Guided Generation

The most powerful Claude Code configuration technique is providing examples of your actual code patterns. Claude learns from examples far more effectively than from abstract rules.

```markdown
<!-- backend/CLAUDE.md -->
# Backend Module

## API Route Pattern
Every API route follows this structure. Reference: /backend/src/routes/users.ts

```typescript
// src/routes/resource-name.ts
import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler } from '../middleware/asyncHandler';
import { validate } from '../middleware/validate';
import { ResourceService } from '../services/resourceService';

const router = Router();
const service = new ResourceService();

const CreateSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
});

router.post('/',
  validate(CreateSchema),
  asyncHandler(async (req, res) => {
    const result = await service.create(req.body);
    res.status(201).json({ data: result });
  })
);

router.get('/:id',
  asyncHandler(async (req, res) => {
    const result = await service.findById(req.params.id);
    if (!result) {
      return res.status(404).json({ error: 'Not found' });
    }
    res.json({ data: result });
  })
);

export default router;

Service Layer Pattern

Reference: /backend/src/services/userService.ts

Copy
// src/services/resourceService.ts
import { prisma } from '../lib/prisma';
import { AppError } from '../lib/errors';

export class ResourceService {
  async create(data: CreateResourceInput): Promise<Resource> {
    return prisma.resource.create({ data });
  }

  async findById(id: string): Promise<Resource | null> {
    return prisma.resource.findUnique({ where: { id } });
  }

  async update(id: string, data: UpdateResourceInput): Promise<Resource> {
    const existing = await this.findById(id);
    if (!existing) throw new AppError('Not found', 404);
    return prisma.resource.update({ where: { id }, data });
  }
}

Error Handling

Always use the AppError class. Never throw raw Error objects. Always catch Prisma errors and wrap them with user-friendly messages.

### 3. Custom Workflow Commands

Define workflows in CLAUDE.md that Claude can execute as multi-step processes.

```markdown
<!-- Root CLAUDE.md section -->
## Workflows

### New Feature Workflow
When asked to implement a new feature:
1. Create a feature branch: `git checkout -b feature/{name}`
2. Implement the backend changes first (service -> route -> tests)
3. Implement the frontend changes (component -> page -> tests)
4. Run the full test suite: `npm run test:all`
5. Run lint and type checking: `npm run lint && npm run typecheck`
6. Create a commit with conventional commit format

### Bug Fix Workflow
When asked to fix a bug:
1. Reproduce the issue by understanding the error and tracing the code path
2. Write a failing test that demonstrates the bug
3. Implement the fix
4. Verify the test passes
5. Run the full test suite to check for regressions
6. Commit with `fix(scope): description of the fix`

### Code Review Workflow
When asked to review code:
1. Read all changed files
2. Check for: security issues, performance concerns, error handling gaps
3. Verify test coverage for new code paths
4. Check adherence to project coding standards
5. Provide feedback categorized by severity

4. Monorepo Module Organization

For large projects, organize CLAUDE.md files to match your architecture.

project/
├── CLAUDE.md                     # Project overview, cross-cutting concerns
├── frontend/
│   ├── CLAUDE.md                 # Frontend framework, components, state
│   ├── components/
│   │   └── CLAUDE.md             # Component patterns, design system
│   └── pages/
│       └── CLAUDE.md             # Page-level patterns, data fetching
├── backend/
│   ├── CLAUDE.md                 # API patterns, service layer, DB
│   ├── routes/
│   │   └── CLAUDE.md             # Route conventions, middleware
│   └── services/
│       └── CLAUDE.md             # Service patterns, error handling
├── shared/
│   └── CLAUDE.md                 # Shared types, utilities, constants
└── infra/
    └── CLAUDE.md                 # CDK patterns, deployment, env vars

5. Conditional Instructions

Use conditional context to change Claude's behavior based on what it is working on.

Copy
<!-- CLAUDE.md -->
## Context-Dependent Rules

### When editing files in /frontend/components/
- Always co-locate tests: ComponentName.test.tsx next to ComponentName.tsx
- Use React Testing Library, never Enzyme
- Export a Storybook story for visual components

### When editing files in /backend/routes/
- Always validate request body with Zod schema
- Wrap async handlers with asyncHandler middleware
- Include rate limiting for public endpoints

### When editing files in /infra/
- Never hardcode AWS account IDs or regions
- Use CDK context for environment-specific values
- Always tag resources with team, environment, and cost-center

### When writing tests
- Use descriptive test names: "should [expected behavior] when [condition]"
- Group related tests with describe blocks
- Prefer integration tests over unit tests for API routes
- Mock external services, never mock internal modules

Configuration Reference

File Location	Scope	Priority	Description
~/.claude/CLAUDE.md	Global	Lowest	Defaults for all projects
/project/CLAUDE.md	Project	Medium	Project-wide conventions
/project/module/CLAUDE.md	Directory	Higher	Module-specific patterns
/project/module/sub/CLAUDE.md	Sub-directory	Highest	Narrow, context-specific rules
@import path/to/file.md	Inline	Same as host	Import reusable instruction blocks

Configuration Key	Where	Description
Build commands	Project CLAUDE.md	How to build, test, lint, deploy
Code examples	Directory CLAUDE.md	Reference patterns for that directory
File conventions	Project CLAUDE.md	Naming, structure, organization rules
Git conventions	Project CLAUDE.md	Branch naming, commit format, PR process
Workflow steps	Project CLAUDE.md	Multi-step processes for common tasks
Tool preferences	Global CLAUDE.md	Preferred toolchains (ruff vs black, etc.)

Best Practices

1. Keep each CLAUDE.md file under 200 lines. For every line, ask: "Would removing this cause Claude to make mistakes?" If not, remove it. Use @import to split large configurations into focused files.

2. Include 1-2 real code examples per directory CLAUDE.md. Claude learns patterns from examples more effectively than from abstract descriptions. Point to actual files in your codebase as references.

3. Put build and test commands prominently at the top. These are the commands Claude needs most frequently. Do not bury them under paragraphs of philosophy.

4. Use conditional instructions tied to file paths. "When editing files in /backend/routes/" is more useful than generic rules because it activates only when relevant.

5. Check CLAUDE.md into version control. It is shared team configuration, not personal preference. Review CLAUDE.md changes in PRs just like code changes.

6. Run /init on existing projects to bootstrap. The generated CLAUDE.md detects your build system, test framework, and common patterns. Then refine it manually.

7. Update CLAUDE.md when you change conventions. If you switch from Jest to Vitest, update the CLAUDE.md immediately. Stale configuration causes more confusion than no configuration.

8. Use the global CLAUDE.md for cross-project standards. Language-specific toolchains (ruff for Python, oxlint for TypeScript), commit conventions, and quality hard limits belong in ~/.claude/CLAUDE.md.

9. Avoid overly prescriptive instructions. "Use functional components" is good. "Use functional components with exactly three props maximum" is too rigid and will be violated constantly.

10. Test your CLAUDE.md by asking Claude to perform common tasks. Create a new component, add an API endpoint, fix a mock bug. If Claude's output does not match your conventions, refine the instructions.

Troubleshooting

Problem: Claude ignores instructions in a sub-directory CLAUDE.md. Solution: Verify the file is named exactly CLAUDE.md (case-sensitive on Linux). Also check that you are working within that directory when the instructions should apply. Claude reads CLAUDE.md files based on the files it is currently editing, not the working directory.

Problem: CLAUDE.md is too long and Claude seems to "forget" early instructions. Solution: Trim to under 200 lines. Move detailed examples into sub-directory CLAUDE.md files. Use @import sparingly -- too many imports create the same problem.

Problem: Claude uses different patterns in different parts of the codebase. Solution: Add directory-level CLAUDE.md files with explicit examples for each module. Generic project-level instructions are not specific enough to enforce consistency across different codebases.

Problem: Team members have conflicting CLAUDE.md preferences. Solution: Use the project CLAUDE.md (committed to git) for team-agreed standards. Use ~/.claude/CLAUDE.md for personal preferences (editor behavior, verbosity level). Never mix personal preferences into project configuration.

Problem: Claude does not run tests after making changes. Solution: Add an explicit workflow instruction: "After making any code changes, always run the relevant test suite and report the results." Put this near the top of the project CLAUDE.md where it will not be missed.