Inheritance Chains & Resolution Order

The GEMINI.md cascade is a three-tier inheritance chain: global (~/.gemini/GEMINI.md), project (./GEMINI.md at repo root), and subdirectory (nested GEMINI.md files in any directory). Resolution follows deepest-wins semantics — when two tiers define conflicting instructions, the more specific file takes precedence. This is not a merge. The deeper instruction replaces the shallower one for that specific rule. Understanding this distinction is critical: if your global file says "always write tests" and a subdirectory file says nothing about tests, the global rule still applies. But if the subdirectory file says "skip tests for generated code," that overrides the global rule within that directory scope only.

The resolution order has a subtle implication that trips up experienced users: settings.json and GEMINI.md cascade independently. A project-level settings.json does not override a global GEMINI.md instruction — they are parallel tracks. GEMINI.md carries intent (rules, conventions, architecture context). settings.json carries mechanics (model, tools, MCP servers). Both cascade from global to project to subdirectory, but a mechanical override in settings.json never silences a rule in GEMINI.md. Treat them as two independent inheritance chains that happen to share the same scoping system.

Circular or contradictory inheritance is silent. If a global file says "prefer functional patterns" and a project file says "use class-based architecture," the project rule wins with no warning. Gemini CLI does not flag conflicts because intent is context-dependent — what looks like a contradiction to a linter is often a legitimate project-specific override. The responsibility for coherence falls on you. Audit your hierarchy periodically by checking effective configuration at each directory level.

1. Map your active hierarchy List every GEMINI.md and settings.json file across global, project, and subdirectory scopes. Document which topics each file addresses. Identify overlapping topics where override behavior will kick in.
2. Test resolution at each level Start Gemini CLI sessions in different directories and ask it to describe its active instructions. Compare the responses across scopes to verify inheritance is working as intended.
3. Document override intent When a subdirectory GEMINI.md overrides a global or project rule, add a comment explaining why. Future maintainers (including future you) need to understand whether the override is intentional or accidental.