The Perfect CLAUDE.md for Enterprise Software Engineering

The most impactful artifact in agentic development isn’t code — it’s the specification that governs how code gets written. In the Claude Code ecosystem, that artifact is CLAUDE.md.

After 25 years of building enterprise software and leading engineering teams, I’ve watched companies struggle with the same problem: engineering standards exist in wikis nobody reads, onboarding docs that go stale, and tribal knowledge that walks out the door when senior engineers leave. Code reviews catch some issues, but they’re reactive — you’re fixing problems after they’ve been written.

CLAUDE.md changes this fundamentally. It’s not documentation about how you build software. It’s a living specification that actively shapes every line of code written in your repository — whether by a human or an AI agent.

What Makes a Great CLAUDE.md

Most CLAUDE.md files I’ve seen are thin — a few lines about the tech stack, maybe a note about formatting. That’s like giving a new engineer a laptop and saying “good luck.” A great CLAUDE.md encodes the full depth of your engineering culture:

1. Architecture Principles, Not Just Patterns

Don’t just say “we use microservices.” Specify why bounded contexts are separated the way they are, how inter-service communication works (sync vs. async, when to use each), and what the anti-corruption layer looks like at each boundary.

For enterprise SaaS, this means encoding multi-tenancy rules that are non-negotiable: every query scoped to tenant_id, Row-Level Security as a safety net, tenant context injected from middleware — never passed as a parameter.

2. Code Standards That Are Executable

“Write clean code” is aspirational. “Maximum 20 lines per function, maximum 3 parameters, no boolean parameters, guard clauses over deep nesting” is executable. When Claude Code reads these rules, it actually follows them. Every function it generates stays within bounds.

The same applies to naming conventions, error handling patterns, and documentation standards. If you can describe it precisely, the AI will do it consistently — more consistently than most human engineers, honestly.

3. Testing Strategy With Concrete Examples

The testing section is where most CLAUDE.md files fall short. You need to specify:

The testing pyramid proportions (75% unit, 20% integration, 5% E2E)
Coverage targets per layer (85% on domain logic, 95% on critical calculations)
Test patterns (Arrange-Act-Assert, factory functions over raw fixtures)
What must be tested (edge cases, tenant isolation, boundary values)
What tools to use (testcontainers for real databases in integration tests)

Include code examples. When Claude Code sees a concrete test example with your exact patterns, it generates tests that look like they belong in your codebase.

4. CI/CD Pipeline as a Quality Gate

Your CLAUDE.md should describe the full pipeline — from pre-commit hooks through canary deployment. Not because the AI deploys code, but because understanding the pipeline shapes how code is written. If the AI knows that migrations must be backward-compatible because you do blue-green deployments, it won’t generate a migration that renames a column.

5. Domain Context

This is the secret weapon. When your CLAUDE.md explains the business domain — what an order processing pipeline does, why confidence thresholds exist, how approval workflows chain — the AI generates code that makes domain sense, not just syntactic sense. It names variables correctly, structures services along domain boundaries, and writes tests that cover real business scenarios.

The Engineering Excellence Reference

Below is a complete CLAUDE.md I wrote for an enterprise SaaS platform. It covers everything: multi-tenancy architecture, clean code standards, testing strategy, CI/CD pipeline design, observability, domain-driven design structure, security practices, and performance patterns.

I’m sharing it in full because the best way to understand what a comprehensive CLAUDE.md looks like is to read one. Use it as a template — adapt the domain specifics to your product, but keep the structural depth.

View the complete Engineering Excellence CLAUDE.md (560 lines)

```markdown

Engineering Excellence Standards — Enterprise SaaS Platform

Purpose

These standards define how we build enterprise-grade, scalable, maintainable software for the platform. Every engineer, every PR, every deployment follows these principles. They are non-negotiable for enterprise customers processing millions of transactions and billions in throughput.

1. Enterprise SaaS Architecture Principles

Multi-Tenancy

Tenant isolation is absolute. Every database query, every API call, every background job is scoped to a tenant_id. There is no code path that can access another tenant’s data.
Use PostgreSQL Row-Level Security (RLS) as a safety net on top of application-level filtering. RLS policies enforce tenant isolation even if application code has a bug.
Tenant context is set at the middleware/request level and propagated through the entire call chain. Never pass tenant_id as a function parameter — inject it from context.
Shared infrastructure (queues, caches, compute) uses logical isolation. Dedicated infrastructure available for Tier 1 customers if contractually required.
Data export and deletion must be tenant-scoped and auditable (GDPR Article 17 right to erasure).

Configuration Architecture

Per-tenant configuration stored in a dedicated config service, not in application code or environment variables.
Configuration hierarchy: Global defaults → Customer-level → Legal Entity-level → Override rules. Child inherits from parent unless explicitly overridden.
Configuration changes are versioned and auditable. Every change records: who, when, what changed, previous value.
Feature flags (LaunchDarkly or Unleash) for per-tenant feature rollout. New capabilities deploy dark, then activate per customer.
Configuration is cached with TTL and invalidation. Config changes take effect within 60 seconds without deployment.

API Design

RESTful APIs with consistent conventions. Resource-oriented URLs, standard HTTP methods, proper status codes.
API versioning via URL path (/v1/, /v2/). Breaking changes require new version. Old versions supported for minimum 12 months.
Pagination on all list endpoints (cursor-based, not offset-based — offset breaks with concurrent writes).
Rate limiting per tenant, per endpoint. Configurable limits for different customer tiers.
Every API response includes request_id for tracing. Every error response includes machine-readable error code + human-readable message.
OpenAPI 3.0 specification is the source of truth. Generated from code annotations. Client SDKs auto-generated.

Authentication & Authorization

SSO mandatory for enterprise: SAML 2.0 and OIDC support. Tested against Okta, Azure AD, OneLogin, Ping Identity.
SCIM 2.0 provisioning: Automated user lifecycle. User created/deactivated in IdP → reflected within minutes.
RBAC with custom roles: Pre-defined roles (Agent, Team Lead, Manager, Admin) plus customer-configurable custom roles.
Permission model: Role → Permission Set → Resource Scope. Permissions are granular: orders:read, orders:approve, tickets:resolve, config:admin.
API authentication via short-lived JWT tokens (15 min) with refresh token rotation.
Service-to-service auth via mTLS or signed JWTs with strict audience validation.

Data Residency & Encryption

Encryption at rest: AES-256 via AWS KMS. Per-tenant customer-managed keys (CMK) available for regulated customers.
Encryption in transit: TLS 1.2+ everywhere. Internal service mesh uses mTLS.
Data residency: Tenant data pinned to region (eu-west-1, us-east-1). Cross-region replication only with explicit customer consent.
PII handling: Customer data classified by sensitivity. PII fields encrypted at field level with separate key hierarchy.
Key rotation: Automated quarterly. Zero-downtime re-encryption of active data.

Compliance

SOC 2 Type II: Continuous compliance. Controls embedded in CI/CD, not manual checklists.
ISO 27001: Information security management system. Annual external audit.
GDPR: Data processing agreements per customer. Right to access, rectify, erase. Data retention policies configurable per tenant.
Penetration testing: Annual third-party pentest. Quarterly automated security scanning (SAST + DAST).
Audit trail: Immutable, append-only log of every data mutation, every configuration change, every AI decision. Retained for 7 years minimum.

2. Clean Code Standards

Principles

Readability over cleverness. Code is read 10x more than it’s written. Optimize for the reader.
Single Responsibility. Every function does one thing. Every class has one reason to change.
Explicit over implicit. No magic. No hidden side effects. Function names say what they do.
Fail loudly and early. Validate inputs at the boundary. Throw meaningful exceptions.
Domain-Driven Design. Code structure mirrors the business domain.

Naming Conventions

Files & directories: kebab-case Classes: PascalCase → OrderProcessingEngine Functions: camelCase → validateOrderAgainstPolicy() Constants: UPPER_SNAKE → MAX_RETRY_ATTEMPTS Variables: camelCase → processedOrderCount Types/Interfaces: PascalCase → ValidationResult, OrderStatus Database tables: snake_case → order_line_items API endpoints: kebab-case → /v1/orders/{id}/validation-results

Function Design

Maximum 20 lines per function. If longer, extract sub-functions.
Maximum 3 parameters. More than 3 → use an options/config object.
No boolean parameters. processOrder(order, true, false) is unreadable.
Pure functions where possible. Same input → same output. No side effects.
Guard clauses over deep nesting. Return early for error conditions.

Error Handling

Custom domain exceptions for every error category.
Never catch generic exceptions unless re-throwing with context.
Structured error responses with: error code, message, details, request_id.
Retry with backoff for transient failures. Exponential backoff with jitter. Max 3 retries with circuit breaker.
Dead letter queues for messages that fail after max retries.

3. Testing Strategy

Testing Pyramid

Unit Tests (~75%): Domain logic, validation engine, business rule checks. Run on every commit (< 2 min).
Integration Tests (~20%): Service boundaries, DB queries, external API connectors. Run on every PR (< 10 min).
E2E Tests (< 5%): Full pipeline. Run nightly + before release (< 30 min).

Unit Tests

Coverage target: 85%+ on domain logic, 95%+ on validation engine and pricing calculations.
Factory functions for test data, not raw fixtures.
Test behavior, not implementation. Arrange-Act-Assert pattern.
Edge cases mandatory: null inputs, empty arrays, boundary values, currency rounding, timezone boundaries.
Mock external dependencies. Unit tests never touch the network.

Integration Tests

Test service boundaries: API endpoints, database queries, message queue producers/consumers.
Use testcontainers for PostgreSQL, Redis, and LocalStack — real services, not mocks.
Test tenant isolation: create data for tenant A, query as tenant B, verify zero results.
Test external API connectors against recorded API responses (VCR pattern).

AI/ML Model Testing

Golden set tests: 500+ documents with known correct results.
Regression tests on every model retrain.
Adversarial tests: near-duplicates, legitimate price changes.
Performance benchmarks: inference latency p95 must stay below threshold.

4. CI/CD Pipeline

Pipeline Flow

Pre-commit (local) → Build → Unit Test → Integration Test → Security Scan → Build Image → Staging Deploy → Production Canary

Branch Strategy

Trunk-based development. Main branch is always deployable.
Short-lived feature branches (< 2 days).
Conventional commits: feat:, fix:, refactor:, docs:, test:, chore:.
Squash merge to main. Clean, linear history.

Deployment Strategy

Canary deployments: 10% → 50% → 100%.
Automated rollback if error rate > 2% or latency > 2x baseline.
Blue-green for database migrations (expand-contract pattern).
Feature flags for per-tenant rollout.
Zero-downtime deployments. Rolling updates with health checks.

Database Migrations

Forward-only. Backward-compatible always.
New column? Add nullable first, deploy code, backfill, then add NOT NULL.
Migration review required from senior engineer.
Tested in CI against real PostgreSQL with representative data volume.

5. Observability

Structured Logging

Every log line is JSON with: timestamp, level, service, tenant_id, request_id, trace_id, event, duration_ms. Never log PII in plain text. Never log at DEBUG level in production.

Distributed Tracing

OpenTelemetry SDK in every service. Trace ID propagated through queues, workflows, and all service calls.

Alerting

Alert on symptoms, not causes. Every alert has a runbook. Three tiers: P1 (page, 15 min), P2 (Slack + ticket, 4 hours), P3 (daily digest).

SLOs

API availability: 99.9%
Document ingestion latency: p95 < 5s
Processing pipeline latency: p95 < 10s
Data sync freshness: < 15 min
Straight-through processing rate: > 80%

6. Domain-Driven Design

Bounded Contexts

document-intake/ — Channel adapters, normalization document-intelligence/ — AI extraction, confidence scoring validation/ — Core validation engine, business rule engine exception-management/ — Exception types, routing, SLA approval/ — Approval matrix, delegation, thresholds integration/ — External system connector layer with per-system adaptors platform/ — Auth, config, audit, events, observability orchestration/ — Temporal workflow definitions

Inter-Context Communication

Synchronous (API) for queries needing immediate response.
Asynchronous (Events via SNS/SQS) for state changes.
Never share databases between bounded contexts.
Anti-corruption layer at each boundary.

7. Security

Automated CVE scanning on every build. No deploy with Critical/High CVEs.
Secrets in AWS Secrets Manager. Never in code or visible env vars.
Parameterized queries only. ORM with strict mode.
Input validation via schema (Zod/Joi) on every API endpoint.
SBOM generated on every build. License compliance automated.
Container scanning before push to registry.

8. Performance & Scalability

Read-through cache (Redis, 5 min TTL) for reference data.
Cache invalidation via events. Keys always include tenant_id.
SQS FIFO for document ingestion (dedup + ordering).
Dead letter queue on every queue. Max 3 receives before DLQ.
Connection pooling via PgBouncer. Read replicas for analytics.
Table partitioning by tenant_id + created_date for high-volume tables.

Quality Gate Summary

No code reaches production without passing ALL of these:

Lint + Format: Zero errors (pre-commit hook)
Type check: Zero errors (CI build)
Unit tests: All pass, coverage ≥ 85% on changed files
Integration tests: All pass
Security scan: No Critical/High CVEs
License check: All dependencies approved
Contract tests: All consumer contracts satisfied
PR review: 1 approval minimum
Staging E2E: Smoke tests pass
Canary health: Error rate < 2%, latency < 2x baseline ```

How to Adapt This for Your Project

Start with architecture. Multi-tenancy rules, API conventions, auth model. These are the non-negotiable guardrails.
Add concrete code standards. Not principles — rules. Line limits, parameter limits, naming conventions with examples. The more specific, the more consistently the AI (and your team) will follow them.
Encode your testing culture. Coverage targets, test patterns with code examples, the specific tools you use. An AI that sees a testcontainers example will generate integration tests with testcontainers.
Include domain context. Explain what your product does in business terms. The AI writes better code when it understands why a validation engine has confidence thresholds.
Keep it alive. A CLAUDE.md that’s written once and forgotten is just another stale wiki page. Update it when standards evolve. It should reflect how you build software today, not how you planned to build it six months ago.

The Multiplier Effect

Here’s what changed when we started using comprehensive CLAUDE.md files:

PR review time dropped by ~40%. The AI-generated code already follows standards, so reviews focus on logic and architecture, not formatting and patterns.
Onboarding accelerated. New engineers read the CLAUDE.md and immediately understand how the team builds software. The AI helps them write code that fits from day one.
Consistency across the codebase. Whether code was written by a senior architect or a junior engineer with Claude Code, it follows the same patterns. The CLAUDE.md is the great equalizer.
Standards become enforceable. A wiki page is aspirational. A CLAUDE.md is operational — it shapes every code generation in real time.

The CLAUDE.md is not about controlling the AI. It’s about encoding your engineering culture into a format that scales — to more engineers, more agents, more repositories. It’s the missing layer between “we have standards” and “our standards are actually followed.”