Architecture maps that coding agents read first

The step before the code

Coding agents write good code once they are looking at the right files. Most of the variation in what they produce comes from the step before that: working out where a feature lives, what depends on it, and what the last person to touch it already knew. A fresh session does that research from a cold grep, and two sessions given the same task often start from different places. That is a large part of why quality from agentic development is uneven.

Feature Map gives every session the same starting point. The skill thatinit installs tells the agent to run list andshow before feature work, debugging or planning, and to patch the map after it ships. Research becomes a lookup with a consistent answer, and the map is corrected in the same pull request as the code it describes. The guide lists the exact instructions agents follow.

How an agent looks up a feature

# names only, a few dozen tokens
feature-map list

# slugs and short snippets, not whole documents
feature-map search billing

# one key from one file
feature-map show billing --section entry_points

# which maps reference the file you are about to change
feature-map impact api/src/billing/invoice.go

The agent then opens the code at those paths. It does not read a two-thousand-word page and grep the tree anyway.

• AddressableThe CLI works as an index. list, search, find and impact return names, so an agent reads only the map it needs.
• Bounded readsStructured keys and --section cap how much context a lookup costs. A wiki has no way to say "give me only the files".
• Checkablevalidate catches missing fields and unresolvable links. check reports entry points that no longer exist on disk.
• Stable over timeYAML fields do not pick up a new introduction every time an agent updates the docs, so maps stay about the same size.

What a map looks like

A map needs a feature_name, a one-sentence purpose and real entry_points. The rest is optional. Entry points are the ways into a feature, such as the HTTP handler, the page a user lands on and the job that runs afterwards, and not every file the feature touches.

.features/signup.yamlfeature_name: signup
purpose: "How a new account is created and reaches the first authenticated screen."

entry_points:
  - api/src/signup/handler.go
  - web/src/routes/signup/+page.svelte
  - api/src/jobs/welcome_email.go

apps:
  - api
  - web

user_flow:
  primary: "Visitor submits email → API creates user + session → redirect to /app"
  error: "Duplicate email → 409 → form shows sign-in link"

related_features:
  - billing (free plan attached on first login)
  - auth (session issued here, refreshed there)

notes: >
  Confirm the Stripe webhook path before changing plan assignment.

related_features starts each entry with a slug, which is whatgraph and impact --transitive follow. The note in parentheses is for the human reader.

What feature-map init sets up

1. Creates .features/ for your maps
2. Installs the agent skill in .agents/skills/feature-map/, mirrored into .claude/skills/ or .grok/skills/ if the repo already uses them
3. Writes .feature-map.yaml with defaults, if it is missing
4. Appends a block to AGENTS.md that points agents at the skill
5. Adds a repo-local shim at bin/feature-map
6. Offers to launch your agent to read the repo and draft the first maps

Agents it can launch to draft maps:

• claude
• cursor-agent
• opencode
• grok
• codex
• gemini
• pi

To skip the prompt and pick one directly: feature-map init -y -h claude. For a codebase that already exists, the guide walks through writing the first maps.

A backlog that lives in the repository

feature-map idea writes a product idea to a dated markdown file indocs/ideas/, creating the folder the first time. Pass the text as an argument, pipe it in, or run it bare to type several lines. It takes a few seconds, so the idea gets written down while you still remember it.

# one line from the terminal
feature-map idea "let users export invoices as CSV"
Saved docs/ideas/2026-09-26-let-users-export-invoices-as-csv.md

# or omit the text to type several lines, ending with an empty line
feature-map idea

The ideas are committed with the code, so a cloud agent that checks out the repository can read them too. Point one at an idea file, and it can uselist and show to find the features it touches, build it, and add or update the map in the same pull request.

Commands

list

All feature slugs

show <name>

Print a map, or one --section

search <query>

Full-text search across maps

find <path>

Reverse lookup by path fragment

impact <file>

Which maps reference a file

graph [name]

related_features as mermaid, json or dot

validate

Structural checks, --strict for CI

check

Stale entry_points and core_components paths

stats

Coverage by app

viewer

Read-only local browser view for humans

init <name>

Scaffold a map from the template

idea [text]

Save an idea to docs/ideas/ for later

update

Upgrade via pip, npm, brew, pipx or uv

Every command accepts --json. Exit codes are 0 for success,1 for user error and 2 when validate --strict fails. See the full command reference for every flag.

Frequently asked questions

Does this replace PRDs or documentation?

No. PRDs and plans describe what to build. A map records where a feature lives and what it touches, and keeping the two apart keeps both short. A wiki is still a fine place for history, vision and runbooks.

Are maps generated from the code?

No. There is no AST generator, because a generated map would list every file instead of the few that matter. Maps are authored. feature-map init can launch your agent to read the repository and write first drafts, which you then review like any other change.

Which agents does it work with?

Any agent that reads skills or AGENTS.md. init can launch claude, cursor-agent, opencode, grok, codex, gemini or pi directly. For other harnesses, add a directory with --skill-dir or skill_dirs: in .feature-map.yaml.

Why is the package called feature-map-cli?

pip install featuremap is an unrelated biology project, and PyPI blocks feature-map as too similar to it. The installed command is still feature-map.

What does it need to run?

Python 3.8 or later and PyYAML. The npm package installs the PyPI CLI into a local virtualenv, so it needs Python too.

How do I upgrade?

Run feature-map update, then feature-map init --upgrade-skill to refresh the agent skill in every location it was installed.