| name | claude-md-inverted-index |
| description | Inverted index strategy for CLAUDE.md that maps technology keywords to module/package locations.
Reduces AI agent tool calls by 42-68% across all major languages and architectures.
Use when setting up CLAUDE.md for any project with 50+ files, multi-module structure,
or 3+ external technologies. Covers Spring Hexagonal, Python uv, Node.js/TypeScript,
Go, Rust, and polyglot monorepos.
|
| license | MIT |
| metadata | {"version":"2.1.0","author":"jmk","category":"developer-productivity","domain":"ai-agent-optimization","updated":"2026-03-09T00:00:00.000Z","research-basis":"3-phase team research (12 agents, 6 languages, 10+ architectures)","languages":"kotlin, java, python, typescript, javascript, go, rust","frameworks":"spring-hexagonal, fastapi, django, nextjs, nestjs, turborepo, axum, gin"} |
CLAUDE.md Inverted Index Strategy
Map technology keywords to file locations so AI agents find code instantly instead of searching.
When to Apply
Use this skill when:
- Setting up or optimizing CLAUDE.md for a code project
- Project has 50+ files with multi-module or multi-package structure
- 3+ external technologies integrated (DB, cache, queue, search, etc.)
- AI agent repeatedly asks "where is X?" or makes many Glob/Grep calls
- Hexagonal/Clean Architecture with ports and adapters spread across modules
- Monorepo with multiple apps/packages sharing code
Do NOT apply when:
- Convention-over-Configuration framework (Rails, Laravel, small Django)
- Single module project with <50 files
- File-based routing project with no complex lib/ (basic Next.js pages)
- Greenfield project still establishing structure
3-Axis Necessity Score
Calculate before applying:
| Axis | 1 point | 2 points | 3 points | 4 points |
|---|
| Scale (files) | <50 | 50-200 | 200-500 | 500+ |
| Architecture | single, flat | multi-module or layered | hexagonal/clean + multi-module | polyglot monorepo |
| Tech Diversity | 1-2 techs | 3-5 techs | 6-8 techs | 9+ techs |
Sum 3-5: Not needed | 6-8: Recommended | 9-12: Strongly recommended
Core Concept
BEFORE (narrative):
"The evolution directory contains Python scripts for each pipeline phase..."
AFTER (inverted index):
### Kafka
- consumer: inbound-consumer/.../listener/
- producer: outbound-event/.../producer/
- config: inbound-consumer/.../config/, outbound-event/.../config/
Output Architecture: 3-Tier External Reference
All files are project-level (not global ~/.claude/). Each project has its own inverted index.
PROJECT_ROOT/
├── CLAUDE.md # Tier 1: always loaded (30-50 lines)
├── .claude/
│ └── rules/ # Tier 2: auto-loaded on path match
│ ├── kafka.md
│ ├── jpa.md
│ └── redis.md
├── module-a/
│ └── CLAUDE.md # Tier 3: loaded in this module only
└── module-b/
└── CLAUDE.md
Tier 1: PROJECT_ROOT/CLAUDE.md (always loaded, 30-50 lines)
- Module/package list (names only)
- Entry points, Generated files (DO NOT MODIFY)
- "See .claude/rules/ for tech-specific guides"
Tier 2: PROJECT_ROOT/.claude/rules/*.md (auto-loaded on path match)
Tier 3: PROJECT_ROOT/{module}/CLAUDE.md (loaded when working in that module)
- Optional, for complex modules only
Why 3-Tier?
- Root CLAUDE.md stays under 50 lines (always in context, never wasted)
- Tech-specific rules load ONLY when the agent works in matching paths
- Total indexed knowledge can be 10x larger without context overhead
Optimal Granularity
Safe to index | Do NOT index
-----------------------|-----------------
Module structure | Business class filenames
Package paths | Test filenames
Config filenames (few) | DTO/VO class names
Port/Interface names | Implementation file names (many)
Module + Package level is optimal. Agent can ls the package to find specific files.
Effectiveness by Language
| Ecosystem | Tool Call Reduction | ROI | Killer Feature |
|---|
| Rust (Cargo workspace) | ~68% | 5-12x | Trait->Impl mapping, feature flags |
| Polyglot monorepo | ~67% | 8-14x | Cross-service domain mapping |
| Turborepo/Nx | ~63% | 8-14x | Cross-app impact analysis |
| Python uv monorepo | ~62% | 5-12x | Name disambiguation (models/schemas) |
| Go (standard layout) | ~60% | 5-10x | Interface->Impl mapping |
| Next.js App Router | ~58% | 6-12x | 3-way split (app/lib/components) |
| Spring Hexagonal | ~42% | 3-8x | Layer mapping (port/adapter) |
How to Use Templates
Templates in templates/ provide ready-to-use 3-Tier output for each stack.
Each template contains two parts:
- Part 1: Root CLAUDE.md -- Copy to your project's root CLAUDE.md
- Part 2: .claude/rules/ Files -- Create each file in your
.claude/rules/ directory
templates/spring-hexagonal.md -- Kotlin/Java multi-module
templates/python-uv-monorepo.md -- Python uv workspace
templates/turborepo.md -- TypeScript Turborepo/Nx/pnpm
templates/go-standard.md -- Go standard layout
templates/rust-workspace.md -- Rust Cargo workspace
See references/ for detailed per-language guides:
references/lang-kotlin-java.md -- Spring Hexagonal deep guide
references/lang-python.md -- FastAPI/Django/Celery patterns
references/lang-typescript.md -- Next.js/NestJS/Turborepo patterns
references/lang-go.md -- Go standard layout + DDD
references/lang-rust.md -- Cargo workspace + trait system
references/lang-polyglot.md -- Multi-language monorepo
references/maintenance-automation.md -- Auto-generation scripts, CI checks
Key Principles
- Root CLAUDE.md: 30-50 lines max (module names + entry points + generated files)
- .claude/rules/: One file per technology, with
paths: frontmatter for auto-loading
- Module + Package granularity (not individual files)
- Technology-grouped format (not layer-grouped)
- Auto-generate paths, manually curate descriptions
- Validate in CI (check paths still exist)
- Defend against semantic staleness (paths exist but meaning drifted)
Semantic Staleness Defense
Path existence checks catch deleted paths, but NOT semantic drift -- where a path still exists but no longer represents the concept it's mapped to.
The Problem
Index says: Kafka consumer → inbound-consumer/.../listener/
Reality: Listener is now a thin wrapper; real logic moved to event-processor/.../handler/
CI path check: ✅ PASS (folder exists)
Agent result: ❌ Reads wrapper, misses real logic, falls back to Grep
4-Layer Defense
Layer 1: Metadata Tagging (passive, time-based trigger)
Add staleness metadata to .claude/rules/*.md frontmatter:
---
description: "Kafka consumer/producer conventions"
paths: ["**/inbound-consumer/**", "**/outbound-event/**"]
last_reviewed: "2026-03-01"
review_commit: "a1b2c3d"
owner: "@backend-team"
staleness_window: 90
---
CI warns when last_reviewed exceeds staleness_window days.
Layer 2: Generated vs Curated Separation (structural)
Explicitly separate auto-generated paths from human-curated descriptions:
## Kafka
### Location Map (auto-generated, 2026-03-01)
<!-- regenerate: make generate-index -->
- consumer: inbound-consumer/.../listener/
- producer: outbound-event/.../producer/
### Conventions (curated, @backend-team)
<!-- manual review required on structural changes -->
- Event classes live in the domain module
- Consumers call inbound ports after deserialization
Auto-generated sections can be refreshed by scripts. Curated sections require human review.
Layer 3: Structural Change Detection (active, PR-time)
Detect technology markers appearing OUTSIDE indexed paths:
See references/maintenance-automation.md for full detection scripts.
Layer 4: Agent Self-Verification (runtime, zero-cost)
Add to .claude/rules/ files:
## Self-Verification
When landing on an indexed path, verify actual logic exists there.
If only wrapper/delegate found, find real location, complete the task,
then suggest updating the index.
Defense Layer Comparison
| Layer | When | Cost | Catches |
|---|
| Metadata tagging | Time-based | Very low | Unreviewed sections |
| Generated/Curated split | On regeneration | Low | Path drift |
| Structural change detection | PR time | Medium | Tech marker migration |
| Agent self-verification | Runtime | ~Zero | Actual staleness at point of use |
References
- Liu et al., "Lost in the Middle" (TACL 2024) - context middle information ignored
- "Context Length Alone Hurts" (EMNLP 2025) - length itself degrades performance
- Anthropic, "Effective context engineering for AI agents"
- arXiv 2602.11988 - context files can hurt agent performance when overdone
- arXiv 2601.20404 - AGENTS.md reduces runtime by 28.64%
