Give Your AI Agent a Map of Your Codebase (For Free, Locally)

Every time you start a new AI coding session, the first thing the agent does is explore. It reads files, scans directories, traces dependencies, and tries to build a mental model of your codebase. This cold-start exploration eats time, burns tokens, and sometimes leads the agent to wrong conclusions because it didn’t look in the right places.

There’s a better way: give the agent the map before it starts walking.

The Problem

AI agents are powerful, but they’re not omniscient. When an agent opens your repository for the first time (or starts a new session), it has no idea what’s in there. It doesn’t know your architecture. It doesn’t know your naming conventions. It doesn’t know that your controllers follow a specific pattern or that your services have a particular dependency chain.

So it explores. It reads your solution file. It opens a few controllers. It checks your Program.cs. It scans directory names. Maybe it looks at a model or two. And from this partial exploration, it builds an incomplete picture and starts making decisions based on it.

Sometimes it works fine. Sometimes it misses your caching layer entirely. Sometimes it builds a new service that duplicates an existing one because it didn’t scan far enough. Sometimes it follows a pattern from one part of the codebase that’s actually an anti-pattern from a legacy module that hasn’t been refactored yet.

The fix is simple: generate a structured map of your codebase that the agent can read instantly instead of discovering piecemeal.

What a Code Map Contains

A code map is a YAML file (.codemap.yaml) at your repository root that captures everything an AI agent needs to understand your codebase structurally:

• Projects: Every project in the solution with its type, framework, and purpose
• Directories: What each directory contains and why
• API endpoints: Every controller with its routes, HTTP verbs, and what each endpoint does
• Services: Every service class with its purpose and dependencies
• Models: Core domain objects, DTOs, ViewModels, and session state with key properties
• Relationships: The dependency chains (Controller → Service → Repository) so the agent understands how pieces connect
• Cross-cutting concerns: How auth, caching, session management, error handling, and logging work
• Conventions: The patterns your team follows (naming, DI style, async patterns, file organization)

The whole file targets 5,000 to 10,000 tokens. Compact enough to load every session, comprehensive enough to eliminate cold-start exploration.

Why Not Just Use Repomix?

You might have heard of Repomix, a tool that packages your entire codebase into a single AI-friendly file. It’s a solid tool, and I respect what it does. But it solves a different problem.

Repomix gives the AI your entire codebase. Every file, every line. That’s useful for some workflows, but it has trade-offs:

Token cost. A meaningful codebase packaged into one file is massive. You’re burning a huge portion of your context window on raw code before you’ve even asked a question.

Signal-to-noise. The agent gets everything, including the parts that aren’t relevant to the current task. Your logging configuration is in there right next to your core business logic. The agent has to figure out what matters.

External dependency. Repomix is a third-party tool that processes your code.

A code map takes a different approach. Instead of giving the agent all the code, it gives the agent understanding of the code. Structure, not content. Relationships, not implementation details. Enough to navigate intelligently, load specific files when needed, and make decisions that align with your architecture.

Think of it this way: Repomix hands the agent a copy of every book in the library. A code map hands it the card catalog and a floor plan.

How Code Map Works

I built a code-map skill that generates the map by actually reading your codebase. It follows a structured procedure:

1. Discover solution structure. Reads your solution file and lists every project with its type and framework.
2. Map directory purposes. Scans directories and assigns a one-line description to each.
3. Extract API endpoints. Reads every controller, extracts routes, HTTP verbs, and method purposes.
4. Catalog services. Lists every service with its purpose and constructor dependencies.
5. Catalog key models. Identifies core domain objects (not every DTO, just the important ones).
6. Map relationships. Traces dependency chains through DI registrations and constructor parameters.
7. Document cross-cutting concerns. Reads middleware and configuration to identify auth, caching, error handling patterns.
8. Extract conventions. Reviews multiple files of each type to identify consistent patterns.

The result is a .codemap.yaml file at your repo root. It runs locally. It reads your actual files (no guessing). And it’s free.

What It Looks Like

Here’s a simplified example of what a code map produces:

version: 1
overview:
  name: "order-management-api"
  purpose: "REST API for order lifecycle management"
  tech: ["ASP.NET Core 10", "EF Core", "Redis"]
  architecture: "Controller → Service → Repository with cached decorator"

endpoints:
  - controller: OrdersController
    base: "/api/orders"
    methods:
      - "POST / → Create new order"
      - "GET / → List orders with pagination and filters"
      - "GET /{id} → Get order detail with line items"
      - "PUT /{id} → Update order fields"
      - "POST /{id}/cancel → Cancel order"

services:
  - name: OrderService
    purpose: "Order lifecycle operations and business rules"
    depends: ["IOrderRepository", "IPaymentGateway", "IEventPublisher"]

relationships:
  - from: OrdersController
    to: OrderService
    type: depends
    note: "all order operations route through service layer"
  - from: OrderService
    to: CachedOrderRepository
    type: depends
    note: "read-through cache with 5min TTL"

conventions:
  - "Primary constructor injection for all services"
  - "Async/await with CancellationToken on all public methods"
  - "Repository pattern with cached decorator for all entities"

An agent reading this knows the architecture, the patterns, and where everything lives before it touches a single source file. When it needs to add a new endpoint, it knows the pattern. When it needs to create a new service, it knows the dependency style. When it needs to understand how caching works, it’s right there.

When to Regenerate

The code map is structural, not line-level. You don’t need to regenerate it every time you edit a file. Regenerate when:

• You add or remove projects from the solution
• You add new controllers, services, or major models
• You change architectural patterns (new caching strategy, new auth scheme)
• The map feels stale (agent is discovering things that should have been in the map)

For most teams, that’s every few weeks or after any significant structural change.

Getting Started

1. Grab the code-map skill from GitHub
2. Run it against your repository
3. Review the generated .codemap.yaml for accuracy
4. Commit it to your repo
5. Reference it in your AI instructions file so agents load it at the start of every session

The first time you see an AI agent skip the exploration phase and immediately start making architecturally consistent changes, you’ll understand why this matters.

Your agent is going to explore your codebase whether you help it or not. The question is whether it explores efficiently with a map, or inefficiently by wandering. Give it the map.