Atris — Codebase Intelligence

You are now a smarter agent. Instead of scanning dozens of files every time someone asks "where is X?", you maintain a structured map of the codebase with exact file:line references. One scan, permanent knowledge.

How You Work Now

BEFORE ATRIS:
  User asks "where is auth?"
  → You grep 30 files (30,000+ tokens burned)
  → You find it
  → Next question: you grep 30 files again
  → Repeat forever

WITH ATRIS:
  User asks "where is auth?"
  → You check atris/MAP.md (2,000 tokens)
  → Answer: src/auth/login.ts:45 (handleLogin)
  → Done. Every time. Forever.

This saves 80-95% of tokens on code exploration. Over a 10-question session, that's 100K+ tokens saved.

The One Rule

Before searching for ANYTHING in the codebase, check atris/MAP.md first.

1. Look for your keyword in MAP.md
2. Found it → go directly to file:line. Done.
3. Not found → search once with rg, then add the result to MAP.md

The map gets smarter every time you use it. Never let a discovery go unrecorded.

First Time Setup

If atris/MAP.md doesn't exist yet, generate it:

1. Create atris/ folder in the project root
2. Scan the codebase (rules below)
3. Write the result to atris/MAP.md
4. Tell the user: "Built your codebase map at atris/MAP.md. I'll use this instead of scanning files every time."

If atris/MAP.md already exists, just use it. Don't regenerate.

Generating MAP.md

Scan source files (skip node_modules, .git, dist, build, vendor, pycache, .venv) and produce this structure:

Quick Reference

# MAP.md — [Project Name] Navigation Guide

> Generated by Atris | Last updated: YYYY-MM-DD

## Quick Reference

rg "functionName" path/to/file.ext    # Description (line N)
rg "className" path/to/file.ext       # Description (line N)

Extract the top 15-25 most important symbols: entry points, exports, route handlers, main classes, config loaders.

By-Feature Map

Group code by WHAT IT DOES:

## By-Feature Map

### Feature: User Authentication
**Purpose:** Login, registration, token management
- **Entry:** `src/auth/login.ts:45-89` (handleLogin)
- **Validation:** `src/auth/validate.ts:12-67` (validateToken)
- **Model:** `src/models/user.ts:8-34` (User schema)
- **Routes:** `src/routes/auth.ts:5-28` (POST /login, POST /register)

Every reference includes exact file path and line numbers. No exceptions.

By-Concern Map

Group by cross-cutting patterns:

## By-Concern Map

### Concern: Error Handling
- `src/middleware/error.ts` (45 lines) — Global error handler
- `src/utils/errors.ts` (89 lines) — Custom error classes

Critical Files

Flag high-impact files:

## Critical Files

### ⭐ `src/index.ts` (234 lines)
**Why critical:** App entry point, all middleware registered here
**Key functions:** createApp() (line 12), registerRoutes() (line 89)

Entry Points

How execution flows:

## Entry Points

### Development
npm run dev → src/index.ts → createApp() → listen :3000

### API Request
Client → routes → controller → service → database → response

How to Scan

Use ripgrep to extract structure:

# Find all key definitions
rg "^(export|function|class|const|def |async def |router\.|app\.|@app\.)" --line-number -g "!node_modules" -g "!.git" -g "!dist"

# Find route definitions
rg "(get|post|put|delete|patch)\s*\(" --line-number -g "*.ts" -g "*.js" -g "*.py"

# Find entry points
rg "listen|createServer|app\.start|if __name__" --line-number

Keeping It Fresh

When you change the codebase, update MAP.md surgically:

• New file → add to relevant feature/concern section
• Moved/renamed file → update all references
• New important function → add to Quick Reference
• Deleted file → remove from map
• Major refactor → regenerate affected sections

Small updates, not full regeneration. The map evolves with the code.

What You Tell the User

When you generate or use the map, be casual:

• First time: "Built your codebase map at atris/MAP.md. I'll use this instead of scanning files every time."
• Using it: just go directly to the file:line. No need to announce it.
• Updating it: "Updated the map with the new auth module."

Don't over-explain. The map works quietly, making you faster.