Codebase map

Codebase Map

Coding agents have no memory between sessions except what's written to disk. Most tools auto-load a project memory file at session start (AGENTS.md is the cross-tool standard, read natively by most agents; Claude Code reads CLAUDE.md, not AGENTS.md; Cursor reads .cursor/rules, etc.) — that file IS the project memory. Detect which convention the repo/tool uses and target that file; below it's referred to as the memory file. When a repo must serve both conventions, don't duplicate: keep AGENTS.md as the source and make CLAUDE.md a one-line import (@AGENTS.md) or a symlink. This skill generates and maintains them so every future session starts with the codebase already understood, instead of re-discovering it (slower, token-costly, and error-prone).

Guiding principle: a map, not the territory. The agent can read any file on demand with grep/glob — so persistent context must be a compressed, verified map that tells future sessions WHERE to look and WHAT to watch out for. Pasting large code excerpts or exhaustive file listings into the memory file makes every session worse: it burns context on stale information. Short and true beats long and complete.

The two artifacts

1. Memory file (repo root, e.g. AGENTS.md / CLAUDE.md) — loaded every session, keep under ~60 lines

Sections, in order:

# <Project name>
One sentence: what this is and its runtime (e.g. Go 1.23 REST API, deployed on GKE).

## Commands
build / test (full + single-test invocation) / lint / run locally / deploy
(verified — actually run each one before writing it down)

## Architecture (10 lines max)
The mental model: entry points, main flow, key packages and what owns what.
Point to docs/ARCHITECTURE.md for the deep map.

## Conventions
Only the ones that differ from language defaults or that reviewers enforce:
error-handling style, logging, test layout, naming, commit format.

## Gotchas
The expensive-to-rediscover facts: "tests need docker running",
"pkg/legacy is frozen — don't refactor", "config X overrides Y in prod".

## Current focus (optional, dated)
What's actively being worked on; stale entries get deleted, not appended to.

2. docs/ARCHITECTURE.md — read on demand, not auto-loaded

The deep map for when a session needs it: component diagram (mermaid or ASCII), one traced end-to-end flow with file:line references, data model summary, external dependencies and their failure modes, where each cross-cutting concern lives (auth, config, telemetry). Reference it from the memory file so future sessions know it exists.

Generating (new repo)

1. Investigate before writing — use the tracing method (entry points → one flow end-to-end → tests as spec → git log for why). If the deep-reasoning skill is installed, follow its references/code-comprehension.md.
2. Verify every claim: run the build/test/lint commands before recording them; confirm architecture claims by opening the code. A memory file with a wrong test command poisons every future session.
3. Draft both files, then apply the quality bar below.
4. For monorepos / large repos: add short per-directory memory files in major subdirectories (most tools load them when working in that subtree) instead of one giant root file.

Maintaining (existing memory file)

• Update-don't-append. Rewrite the affected section; delete what's no longer true. Append-only memory files rot into contradictions.
• After completing significant work, ask: did this change the architecture, add a convention, or reveal a gotcha? If yes, update the map in the same session while the knowledge is fresh — this is the cheapest moment to persist it.
• On session start in a repo with a memory file older than the recent git activity (git log --oneline -20 shows major changes it doesn't reflect), flag the staleness and offer to refresh.
• If your tool quick-appends memories (a shortcut, or an auto-memory feature writing its own notes), fold durable ones into the right section rather than leaving a pile at the bottom.

Quality bar (apply before writing)

• Every command verified by execution; every architecture claim verified by reading the code this session.
• No large code excerpts, no exhaustive file listings, no generic advice ("write clean code").
• Root memory file ≤ ~60 lines. If it wants to be longer, the overflow belongs in docs/ARCHITECTURE.md or a per-directory CLAUDE.md.
• Would a fresh session, reading only this file, avoid the top 3 mistakes a newcomer makes in this repo? That's the test.

What NOT to do

• Don't build or suggest vector/RAG indexes of the source — agentic search (grep/glob on demand) plus a good map outperforms stale embeddings for codebases that change daily.
• Don't record secrets, tokens, or internal URLs that shouldn't live in the repo.
• Don't duplicate what's already well-covered in the README — link to it.