You have one CLAUDE.md template. You copy it into every new project. But your CLI tool doesn't need UI component rules, your API server doesn't need routing conventions, and your npm library doesn't care about database access patterns.
A single template can't cover everything. Different project types need different instructions.
After configuring CLAUDE.md across 20+ projects in our AI Autonomous Revenue Project, we developed a clear framework: identify your project type, then prioritize accordingly.
The 3 Things Every CLAUDE.md Needs (Regardless of Type)
Before we diverge by project type, every CLAUDE.md shares this skeleton:
# Stack
- [Language] + [Primary framework/library]
- [Package manager]
# Commands
- Build: [build command]
- Test: [test command]
- Lint: [lint command]
# Critical Rules (3-5 max)
- [Your most important constraint — with a "why" clause]
This is your universal foundation. Everything below builds on top of it.
Type A: Web Application (Frontend + Backend)
What Makes It Different
- Heavy UI component generation
- Many structural decisions (routing, state management, auth)
- File placement rules are critical
Priority Sections
# Architecture
- Rendering: Server Components by default, "use client" only when needed
- Data fetching: Server Actions for mutations, fetch() for queries
- State: URL params for shareable state, React state for ephemeral UI
# File Placement
- Pages: app/[route]/page.tsx
- Components: src/components/[feature]/
- Server Actions: app/[route]/actions.ts
# UI Rules
- Use shadcn/ui from src/components/ui/
- Styling: Tailwind utility classes only (no CSS modules)
- Responsive: mobile-first (sm:/md:/lg: breakpoints)
- Accessibility: all interactive elements need aria labels
Skip These
- Publishing config (no npm publish needed)
- SemVer rules (apps typically don't version this way)
Type B: API Server (No Frontend)
What Makes It Different
- Endpoint design is the core activity
- Request/response type definitions matter most
- Error handling must be consistent across all routes
Priority Sections
# API Design
- Response format: { data: T | null, error: { code, message } | null }
- Status codes: 200 (ok), 400 (validation), 401 (auth), 404 (missing), 500 (server)
- Validation: Zod at route entry. Never trust req.body directly
- Auth: Bearer token, validated by middleware before handlers
# Error Handling
- Never expose internals (no stack traces, no SQL in responses)
- All errors logged via structured logger (src/lib/logger.ts)
- Unexpected → 500 with generic message + full internal log
# Database
- All queries through repository pattern (src/repositories/)
- Never raw SQL in route handlers
- Multi-table writes use db.transaction()
Skip These
- UI rules, component structure, styling
- Detailed routing conventions (framework handles this)
Type C: CLI Tool
What Makes It Different
- stdin/stdout/stderr separation matters
- Argument parsing and help message consistency
- Error messages are user-facing (not developer-facing)
Priority Sections
# CLI Conventions
- Entry point: src/cli.ts
- Argument parsing: use commander/yargs — NOT manual process.argv
- Output: normal → stdout, errors → stderr, progress → stderr
- Exit codes: 0 = success, 1 = user error, 2 = system error
# User-Facing Output
- Errors: explain what's wrong + how to fix it
- No stack traces unless --debug flag is set
- Colors: only when stdout is TTY (check isTTY)
- Progress bars: for operations > 2 seconds
# Configuration
- Config: ~/.config/[tool-name]/config.toml (XDG)
- CLI flags override config file
- Env vars: [TOOL_NAME]_[OPTION] format
Skip These
- Database rules
- Auth/session management
- UI/styling
Type D: Library / Package
What Makes It Different
- Public API stability is the #1 concern
- Backward compatibility and SemVer are non-negotiable
- Documentation (JSDoc/docstrings) is mandatory, not optional
Priority Sections
# Public API Rules
- All exports through src/index.ts (barrel file). No deep imports
- Every public function: JSDoc with @param, @returns, @example
- Breaking changes = major version bump (SemVer strict)
- Internal helpers: underscore prefix or src/internal/
# Compatibility
- Support: Node >= 18 (or your minimum)
- No platform-specific code without fallback
- Dependencies pinned to exact versions
# Testing (stricter than app projects)
- 100% coverage for public API
- Edge cases: null, undefined, empty, large inputs
- Type tests with tsd or expect-type
# Publishing
- CHANGELOG.md updated with every PR
- Pre-publish: full test + build + type check
- Version: use npm version / bump2version / cargo release
Skip These
- Deploy procedures (CI/CD handles this)
- Framework routing/middleware
- Database access
Quick Decision Chart
Does the project have a UI?
├─ Yes → Type A (Web App)
└─ No
├─ Does it serve HTTP? → Type B (API Server)
├─ Do users run it from terminal? → Type C (CLI Tool)
└─ Do other projects import it? → Type D (Library)
For hybrid projects (CLI + API, monorepo), apply the right type to each sub-package independently.
Summary Table
| Type | Focus On | Safe to Skip |
|---|---|---|
| A: Web App | File placement, UI rules, routing | Publishing, SemVer |
| B: API Server | Response format, error handling, DB | UI, styling |
| C: CLI Tool | Output targets, exit codes, UX | DB, auth, UI |
| D: Library | Public API, compatibility, docs | Deploy, DB |
Start With a Template
If you want to skip the setup from scratch:
🎁 Claude Code Config Starter Pack (FREE) — 3 templates (Next.js, TypeScript Library, Python FastAPI) covering Types A, B, and D.
🛠️ Claude Code Config Pack — 20 Templates ($5) — All 4 types covered across 20 project configurations including Go, Rust, Flutter, Terraform, Django, and more.
📘 The AI Coding Prompt Toolkit ($5) — 52 prompts for project setup, implementation, testing, and refactoring.
What project types do you use CLAUDE.md with? I'd love to hear about configurations for project types I haven't covered — data pipelines, mobile apps, embedded systems, etc.
Top comments (0)