0

The Full CLAUDE.md Hierarchy: From Enterprise Policy to Subdirectory Rules

Posted by

A practical walkthrough of the full CLAUDE.md hierarchy, using a healthcare startup as the example.

Table of Contents

Every time you launch a Claude Code session, the agent starts with a blank slate. It doesn’t remember your tech stack, your HIPAA obligations, your naming conventions, or the fact that nobody should ever touch the migrations/ folder without a code review. That context vanishes the moment a session ends.

CLAUDE.md files fix this. They’re markdown instructions that Claude Code loads automatically at the start of every session, injected into the system prompt before you type a single command. Think of them as onboarding docs for an engineer with perfect recall but total amnesia.

Here’s the thing most teams miss: there isn’t just one CLAUDE.md. Claude Code supports a full hierarchy of memory files, each scoped to a different level of your organization. One file at the project root isn’t enough if you’re in a regulated industry like healthcare, where a misconfigured endpoint can mean a HIPAA violation.

This guide walks through every level, from organizational policy down to subdirectories, using a healthcare startup as the running example.

The Hierarchy at a Glance

Claude Code loads its memory files in a specific order, from highest to lowest precedence:

1. Managed Policy (Enterprise)    — IT/Security team controls, cannot be overridden
2. User-Level (~/.claude/)        — Your personal preferences across all projects
3. Project-Level (./CLAUDE.md)    — Shared team instructions, version-controlled
4. Modular Rules (.claude/rules/) — Path-scoped, context-specific directives
5. Auto Memory (.claude/projects/)— Claude's own notes from past sessions
┌─────────────────────────────────────────────────────────┐
│          🔒 MANAGED POLICY (Enterprise)                 │
│          IT/Security controls — cannot be overridden    │
└────────────────────────┬────────────────────────────────┘
                         │ overrides all below
                         ▼
┌─────────────────────────────────────────────────────────┐
│          👤 USER-LEVEL (~/.claude/)                     │
│          Personal preferences — across all projects     │
└────────────────────────┬────────────────────────────────┘
                         │ overridden by project
                         ▼
┌─────────────────────────────────────────────────────────┐
│          📁 PROJECT-LEVEL (./CLAUDE.md)                 │
│          Shared team instructions — version-controlled  │
└────────────────────────┬────────────────────────────────┘
                         │ extended by rules
                         ▼
┌─────────────────────────────────────────────────────────┐
│          🎯 MODULAR RULES (.claude/rules/)              │
│          Path-scoped, context-specific directives       │
└────────────────────────┬────────────────────────────────┘
                         │ supplemented by
                         ▼
┌─────────────────────────────────────────────────────────┐
│          🧠 AUTO MEMORY (.claude/projects/)             │
│          Claude's own notes from past sessions          │
└─────────────────────────────────────────────────────────┘

More specific instructions override broader ones. The exception is managed policy, which always wins, no matter what any other level says.

Level 1: Managed Policy (Enterprise/Organization)

What it is: A centrally deployed CLAUDE.md and settings file that your IT or security team pushes to every developer machine. No individual can exclude or override it.

Where it lives:

  • Server-managed via the Claude.ai admin console
  • MDM-deployed (Jamf, Kandji, Intune) on macOS/Windows
  • File-based at system directories (e.g., /etc/claude/ or Windows registry)

Who owns it: Your CTO, VP of Engineering, or Security/Compliance team.

Why it matters for healthcare: In a startup handling PHI, you need rules that no developer can accidentally bypass. Managed policy is where those rules live.

Example: Managed Policy CLAUDE.md

# MedVault Inc. — Organization-Wide Claude Code Policy

## Absolute Rules
- NEVER hardcode API keys, secrets, tokens, or credentials in any file.
- NEVER log, print, or write PHI (Protected Health Information) to console,
  debug output, or non-encrypted storage.
- NEVER commit .env files, private keys (.pem, .key), or secret configuration
  to version control.
- NEVER disable TLS/SSL verification in any HTTP client configuration.
- NEVER use reflection, `Runtime.exec()`, or dynamic code execution with user input.

## Security Standards
- All new endpoints MUST require authentication middleware.
- All database queries MUST use parameterized queries or ORM methods.
  Raw SQL string concatenation is prohibited.
- All user input MUST be validated and sanitized before processing.
- Use AES-256 encryption for data at rest containing PHI.
- Use TLS 1.2+ for all data in transit.

## Compliance
- This codebase is subject to HIPAA, SOC 2, and state health data privacy laws.
- Every PR touching patient data flows must include a privacy impact note.
- Audit logging is mandatory for all data access operations involving PHI.
- Data retention policies must be enforced programmatically — no manual deletion.

## Prohibited Actions
- Do not modify files in /infrastructure/terraform/ without explicit approval.
- Do not alter CI/CD pipeline configurations (.github/workflows/).
- Do not install new dependencies without checking license compatibility
  (no GPL in proprietary modules).

What Makes This Work

It’s short, imperative, and focused only on things that must never be violated. No project architecture, no coding preferences. Those belong at lower levels. Keeping the managed policy lean matters because files under 200 lines get significantly better rule adherence from Claude.

Level 2: User-Level (~/.claude/CLAUDE.md)

What it is: Your personal preferences that apply across every project you work on. Not version-controlled, not shared with anyone.

Where it lives: ~/.claude/CLAUDE.md on your local machine. You can also create modular files in ~/.claude/rules/.

Who owns it: Each individual developer.

Why it matters for healthcare: Your backend engineer working on FHIR integrations needs different things from Claude than your frontend developer building the patient portal. User-level files let each person configure their own context without polluting the shared project config.

Example: Backend Engineer’s User-Level CLAUDE.md

# Personal Preferences — Dr. Sarah Chen, Backend Engineer

## General
- Respond concisely. Skip preambles and summaries unless I ask.
- Always use proper Java generics and avoid raw types.
- Prefer Gradle over Maven for build management.
- Always suggest unit tests when implementing new methods.

## Code Style
- Use Javadoc on all public classes and methods.
- Prefer Java records or immutable DTOs over mutable POJOs.
- Use SLF4J with Logback for structured logging — never bare `System.out.println()`.

## Git Workflow
- Write conventional commit messages (feat:, fix:, chore:, etc.)
- Always create a feature branch — never commit directly to main.

## Healthcare Context
- I work primarily on the FHIR integration layer and patient data APIs.
- When I ask about "the service," I mean our core Patient Records Service.
- Remind me to add audit log entries when I write data access methods.

Example: Frontend Developer’s User-Level CLAUDE.md

# Personal Preferences — Marcus Rivera, Frontend

## General
- I use bun instead of npm for everything.
- Respond in English, keep it casual.
- I prefer Tailwind CSS utility classes over custom CSS.

## Code Style
- React functional components only — no class components.
- Use React Hook Form for all form handling.
- Prefer named exports over default exports.

## Testing
- Use Vitest + React Testing Library.
- Write integration tests for form submissions, not just unit tests.

## Context
- I work on the patient portal (apps/patient-portal/).
- When I say "the dashboard," I mean the clinician-facing dashboard.

The Rule of Thumb

If it’s about you regardless of the project, it goes here. If it’s about the project regardless of who’s working on it, it belongs in the project CLAUDE.md.

Level 3: Project-Level (./CLAUDE.md)

What it is: The most important file in the whole setup. It lives at the root of your repository, is version-controlled, and shared with every developer who clones the repo. This is the file that teaches Claude your codebase.

Where it lives: ./CLAUDE.md or ./.claude/CLAUDE.md at the project root.

Who owns it: The whole team. Treat it like living documentation.

Why it matters for healthcare: This file encodes architectural decisions, conventions, and context that every developer (human or AI) needs to work safely in a codebase handling sensitive health data.

Example: Project-Level CLAUDE.md

# CLAUDE.md — MedVault Patient Records Platform

## Project Overview
HIPAA-compliant patient records platform built with Spring Boot 3 (Java 21),
React 18, and PostgreSQL 16. Deployed on AWS ECS with Terraform.
Handles PHI for 50,000+ patients across 12 clinic partners.

## Repository Structure
- `services/api/` — Spring Boot backend (patient data, auth, FHIR)
- `services/worker/` — Spring Batch jobs for async processing (lab imports, notifications)
- `apps/portal/` — React patient-facing portal
- `apps/clinician/` — React clinician dashboard
- `packages/shared/` — Shared TypeScript types and utilities
- `infrastructure/` — Terraform, Docker, CI/CD (DO NOT MODIFY without DevOps review)
- `docs/` — Architecture decision records, API specs, compliance docs

## Critical Directories — Handle with Care
- `services/api/src/main/java/com/medvault/model/` — JPA entities. Changes require a Flyway migration.
- `services/api/src/main/java/com/medvault/middleware/AuditFilter.java` — Audit logging. Never bypass this.
- `infrastructure/terraform/` — Production infrastructure. Off limits for Claude.

## Development Commands
- API server: `cd services/api && ./gradlew bootRun`
- Run all tests: `cd services/api && ./gradlew test`
- Run single test: `./gradlew test --tests "com.medvault.PatientServiceTest.testCreate"`
- Lint: `./gradlew checkstyleMain spotbugsMain`
- Frontend dev: `cd apps/portal && bun dev`
- Frontend tests: `cd apps/portal && bun test`

## Coding Standards
- All API endpoints require Spring Security authentication — no unauthenticated endpoints.
- All database access goes through Spring Data repositories (`com.medvault.repository`).
- Never inject `EntityManager` directly into controllers.
- Use DTOs (`com.medvault.dto`) for all request/response validation — never expose JPA entities.
- All PHI fields must use the `@EncryptedField` annotation with the custom `AttributeConverter`.
- Log access to PHI using `auditLogger.logAccess()` — this is non-negotiable.

## Testing Requirements
- New endpoints need integration tests with `@SpringBootTest` and Testcontainers.
- Use test factories in `src/test/java/com/medvault/factory/` — never use real patient data in tests.
- PHI test fixtures must use synthetic data from `SyntheticDataFactory.java`.

## Architecture Decisions
For complex tasks, read the relevant docs before proceeding:
- See `docs/adr/003-repository-pattern.md` for data access patterns.
- See `docs/adr/007-fhir-integration.md` for FHIR resource mapping.
- See `docs/adr/012-encryption-at-rest.md` for PHI encryption approach.
- See `docs/compliance/hipaa-checklist.md` before touching patient data flows.

## Common Pitfalls
- The `Patient` entity has soft-delete. Use the repository method with `@Where(clause = "is_deleted = false")`
  — never query the table directly with custom JPQL.
- Lab results come in via HL7v2 messages. The parser is in `services/worker/src/.../parsers/`.
  It's fragile. Ask before modifying.
- The FHIR server has rate limits. Use the `FhirClient` wrapper which handles retry
  logic — never call the FHIR API directly with WebClient or RestTemplate.

What to Notice Here

The file follows a “What, Why, How” structure: what the project is, why certain decisions were made (via ADR references), and how to actually work in the codebase. Notice what it doesn’t include. There are no explanations of REST conventions or Java best practices. Claude already knows those. Focus on what’s unique to your project.

It also uses progressive disclosure. Instead of dumping every architectural detail into one file, it points Claude to specific docs and lets it decide which ones to read based on the task.

Level 4: Modular Rules (.claude/rules/)

What it is: Path-scoped markdown files in .claude/rules/ that activate based on the current task’s context. Think of them as “if working in this area, follow these extra rules.”

Where it lives: .claude/rules/ at the project level, or ~/.claude/rules/ at the user level.

Who owns it: The team, often with sub-teams owning their relevant rule files.

Why it matters for healthcare: Different parts of your codebase have very different risk profiles. The rules for your marketing site aren’t the same as the rules for your patient data API. Modular rules let you enforce the right level of rigor in the right place without bloating your root CLAUDE.md.

Example Rule Files

.claude/rules/phi-handling.md

# PHI Data Handling Rules

When working on code that touches patient data (com.medvault.repository,
com.medvault.model, services/worker/):

- Every read operation on PHI must call `auditLogger.logAccess(userId, resourceType, resourceId)`.
- Every write operation on PHI must call `auditLogger.logModification(userId, resourceType, resourceId, action)`.
- Never return raw PHI in error messages or log output.
- Use `PhiSerializer` to ensure sensitive fields are masked in API responses
  unless the requesting user has the appropriate RBAC role.
- Always check `patient.getConsentStatus()` before sharing data with third-party
  integrations.

.claude/rules/api-security.md

# API Security Rules

When working on API endpoints (com.medvault.controller):

- Every controller must be annotated with `@PreAuthorize` or use method-level
  security — no unauthenticated endpoints in the patient data service.
- Rate limiting is handled by a servlet filter — do not implement custom rate limiting.
- CORS is configured in `SecurityConfig.java`. Never use `allowedOrigins("*")`.
- All file uploads must be scanned with the `FileScanner` service before storage.
- JWT tokens use RS256 signing. Token configuration is in `SecurityConfig.java`.
  Do not modify signing algorithms.

.claude/rules/frontend-portal.md

# Patient Portal Frontend Rules

When working on apps/portal/:

- This app is patient-facing. All copy must be written at a 6th-grade reading level.
- Accessibility is mandatory: all interactive elements need ARIA labels.
- Use the design system components from `packages/shared/ui/`. Do not create
  one-off styled components.
- PHI display components must use the `<MaskedField>` wrapper to support
  screen-reader-safe masking.
- All forms must include client-side validation AND rely on server-side validation.
  Never trust client-side validation alone.

.claude/rules/testing.md

# Testing Rules

- Never use real patient data in tests. Use factories from `src/test/java/.../factory/`.
- Integration tests for PHI endpoints must verify audit log entries were created.
- Test coverage must not decrease. Run `./gradlew jacocoTestReport` to check.
- Flaky tests should be tagged with `@Tag("flaky")` and flagged for repair,
  not deleted.

Why This Matters

Claude Code loads these files based on relevance, so the agent isn’t wading through 400 lines of instructions when it only needs the 20 that apply to the current task. In a monorepo where different services have wildly different compliance requirements, this keeps things manageable.

Level 5: Auto Memory (.claude/projects/)

What it is: Notes that Claude Code writes for itself based on patterns it picks up during your sessions. If you correct it (“we use Gradle not Maven”), it may save that preference for next time.

Where it lives: .claude/projects/ — gitignore this, it’s machine-specific.

Who owns it: Claude, with your oversight.

Why it matters for healthcare: Auto memory is useful, but in a healthcare context you should review it regularly. You don’t want Claude memorizing shortcuts that bypass security patterns, and you definitely don’t want PHI leaking into memory files.

Best Practices

  1. Review periodically. Run /memory in a Claude Code session to see what’s been saved. Delete anything outdated or sensitive.
  2. Promote stable learnings. If Claude keeps saving the same thing (“this project uses Flyway for migrations”), move that into your project CLAUDE.md where it’s explicit and version-controlled.
  3. Gitignore the directory. Add .claude/projects/ to your .gitignore.
  4. Watch for PHI. After sessions involving patient data, check that no identifiable information ended up in auto memory notes.

How the Levels Interact

When instructions at different levels contradict each other, Claude Code follows a clear precedence:

Managed policy always wins. If your organization says “never use raw SQL,” no project-level file can override that.

Project-level overrides user-level. If your personal file says “use npm” but the project CLAUDE.md says “use bun,” the project wins. Project conventions should be consistent across all team members.

Modular rules are the most specific. A rule in .claude/rules/testing.md saying “use Jest” will override a root CLAUDE.md that mentions “Vitest,” because Claude applies the most specific instruction.

Auto memory never overrides. It adds context but defers to explicit instructions at every other level.

Putting It All Together

Here’s what the full file system looks like for our fictional healthcare startup:

# Enterprise (pushed by IT to all machines)
• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md  → Security absolutes, HIPAA rules
• Linux and WSL: /etc/claude-code/CLAUDE.md                 → Security absolutes, HIPAA rules
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md            → Security absolutes, HIPAA rules

# User (each developer's machine)
~/.claude/CLAUDE.md                    → Personal coding preferences
~/.claude/rules/
  └── workflows.md                     → Preferred commit & PR workflows

# Project (version-controlled, shared)
./CLAUDE.md                            → Project architecture, commands, conventions
./.claude/
  ├── rules/
  │   ├── phi-handling.md              → PHI-specific access and audit rules
  │   ├── api-security.md             → Endpoint security requirements
  │   ├── frontend-portal.md          → Patient portal UI standards
  │   └── testing.md                  → Test data and coverage rules
  ├── settings.json                    → Permissions and tool config
  └── .mcp.json                        → External tool integrations

# Auto Memory (gitignored, machine-specific)
./.claude/projects/
  └── MEMORY.md                        → Claude's accumulated observations

Final Thoughts

Start small. Begin with a 40-80 line project CLAUDE.md covering your architecture, key commands, and top 5 conventions. Add modular rules as friction points come up.

Be direct. Write “Use parameterized queries for all database access” instead of “The project prefers parameterized queries.” Claude follows commands more reliably than suggestions.

Keep files short. Under 200 lines gets noticeably better rule adherence. If your CLAUDE.md is growing past that, break it into modular rule files.

Treat it like code. Your CLAUDE.md should be code-reviewed and updated when conventions change. For Claude Code, it is the source of truth.

Deploy managed policy first. In healthcare, the enterprise level isn’t optional. It’s your compliance floor. Get it in place before your first developer opens a Claude Code session.

Give it a try. Start with the project-level CLAUDE.md, see how Claude’s behavior changes, and build out from there. The best CLAUDE.md files don’t teach Claude how to code. They teach it how your team codes.

Further Reading

If you’re interested in learning more about Claude Code and CLAUDE.md configuration:

“In matters of principle, stand like a rock; in matters of taste, swim with the current.”-Rushi

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>