chore: split CLAUDE.md by domain for lazy context loading

[ryan-crabbe-berri]

Summary

• Split the root CLAUDE.md into nested CLAUDE.md files so Claude Code only loads domain-specific rules when working in the relevant subdirectory. Root keeps universal rules (commands, architecture, style, testing, setup wizard, enterprise).
• Rule wording is preserved verbatim — this is pure relocation, no semantic changes.
• Adds empty stubs for proxy sub-domains (auth/, guardrails/, hooks/, spend_tracking/, pass_through_endpoints/) so future rules land in the right place.

Why

Per Claude Code memory docs: CLAUDE.md files in ancestor directories load at launch, but subdirectory files load lazily when Claude reads files inside them. Splitting by domain keeps the initial context lean and scopes guidance to where it applies.

File map

Path	Content
CLAUDE.md (root)	Universal: commands, templates, architecture, code style, testing, setup wizard, enterprise + index of nested files
ui/litellm-dashboard/CLAUDE.md	antd component library, browser storage safety, UI↔backend consistency, MCP UI bits
litellm/proxy/CLAUDE.md	Proxy DB access rules, migrations, schema-out-of-sync troubleshooting
litellm/proxy/management_endpoints/CLAUDE.md	MCP credential storage, MCP OAuth backend
litellm/caching/CLAUDE.md	HTTP client cache safety
.circleci/CLAUDE.md	CI supply-chain safety
litellm/proxy/{auth,guardrails,hooks,spend_tracking,pass_through_endpoints}/CLAUDE.md	Empty stubs

Test plan

• No code changes — nothing to test functionally
• Verify root CLAUDE.md still renders correctly on GitHub
• Spot-check that each nested file contains the rules moved out of root

[greptile-apps]

Greptile Summary

This PR splits the monolithic root CLAUDE.md into domain-scoped nested files so Claude Code lazy-loads only the rules relevant to the directory being edited. Rule wording is preserved verbatim — this is pure relocation with no semantic changes, plus stub files for five proxy sub-domains to anchor future guidance.

Confidence Score: 5/5

Safe to merge — documentation-only change with no code or test modifications.

All changes are pure documentation relocation. The only finding is a P2 duplicate of the Database Migrations section across root and proxy CLAUDE.md, which does not affect runtime behavior.

No files require special attention.

Important Files Changed

Filename	Overview
CLAUDE.md	Root file trimmed to universal rules + nested-file index; Database Migrations block duplicated verbatim in litellm/proxy/CLAUDE.md
litellm/proxy/CLAUDE.md	New file with proxy DB access rules, N+1/batch/pagination guidance, schema-sync troubleshooting, and duplicated Database Migrations section
ui/litellm-dashboard/CLAUDE.md	New file with antd migration guidance, browser storage safety (sessionStorage), MCP OAuth UI-side rules; content correctly split from root
litellm/proxy/management_endpoints/CLAUDE.md	New file with MCP credential storage and OAuth backend rules relocated from root; correctly scoped to management endpoints
litellm/caching/CLAUDE.md	New file with HTTP client cache safety rule (no close() on eviction); correctly relocated from root
.circleci/CLAUDE.md	New file with CI supply-chain safety rules (checksum verification, pinned versions); correctly scoped to CI directory
litellm/proxy/auth/CLAUDE.md	Stub file for future auth-specific rules
litellm/proxy/guardrails/CLAUDE.md	Stub file for future guardrails-specific rules
litellm/proxy/hooks/CLAUDE.md	Stub file for future proxy hooks rules
litellm/proxy/spend_tracking/CLAUDE.md	Stub file for future spend tracking rules
litellm/proxy/pass_through_endpoints/CLAUDE.md	Stub file for future pass-through endpoint rules

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    ROOT["CLAUDE.md (root)\nUniversal: commands, arch, style, testing, setup, enterprise"]
    ROOT --> UI["ui/litellm-dashboard/CLAUDE.md\nantd, browser storage, UI↔backend, MCP OAuth UI"]
    ROOT --> PROXY["litellm/proxy/CLAUDE.md\nDB access, migrations, schema sync"]
    ROOT --> CACHING["litellm/caching/CLAUDE.md\nHTTP client cache safety"]
    ROOT --> CI[".circleci/CLAUDE.md\nCI supply-chain safety"]
    PROXY --> MGMT["management_endpoints/CLAUDE.md\nMCP credential storage, MCP OAuth backend"]
    PROXY --> AUTH["auth/CLAUDE.md\n(stub)"]
    PROXY --> GUARD["guardrails/CLAUDE.md\n(stub)"]
    PROXY --> HOOKS["hooks/CLAUDE.md\n(stub)"]
    PROXY --> SPEND["spend_tracking/CLAUDE.md\n(stub)"]
    PROXY --> PASS["pass_through_endpoints/CLAUDE.md\n(stub)"]

Loading

Comments Outside Diff (1)

1. CLAUDE.md, line 134-138 (link)

   Duplicated Database Migrations section

   The "Database Migrations" block (lines 134–138 of the root CLAUDE.md) is identical to the one added in litellm/proxy/CLAUDE.md. Keeping both in sync doubles the maintenance burden; the two can silently drift apart over time. Since the proxy-level file is the natural home for this guidance, consider removing or reducing the root copy to a one-liner pointer (e.g. "See litellm/proxy/CLAUDE.md for Prisma migration details").

_{Reviews (1): Last reviewed commit: "chore: split CLAUDE.md by domain for laz..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing litellm_chore-split-claude-md (30a5541) with main (850fe59)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!