Codebase Mapping
Produce an evidence-backed map that helps another engineer navigate and change the system. This is read-only unless the user separately asks for implementation or documentation edits.
Scope
Resolve the question the map must answer: system overview, one feature flow, a migration target, security boundaries, deployment topology, or likely change surface. Read repository instructions first and preserve the distinction between source, generated code, vendored dependencies, tests, and deployment artifacts.
Investigate
Use fast repository search and manifests before broad file reading. Trace:
- runtime and build entrypoints;
- packages, modules, layers, and dependency direction;
- primary user/request/event flows and state transitions;
- schemas, persistence, queues, caches, and migrations;
- external APIs, authentication, secrets, and trust boundaries;
- configuration, feature flags, environments, CI/CD, and deployment units;
- tests, observability, ownership signals, and operational runbooks;
- coupling, fan-in/fan-out, compatibility boundaries, and change hotspots.
Validate inferred relationships through imports, registrations, call sites, tests, configuration, or runtime evidence. Label uncertainty instead of presenting guesses as architecture.
Deliver the Map
Tailor the output to the task. Include:
- a concise system summary;
- a component or directory map with responsibilities;
- the relevant data/control-flow sequence;
- key contracts and external boundaries;
- likely files and tests affected by the proposed change;
- risks, unknowns, and recommended next inspections;
- file and line references for consequential claims.
Use a small diagram only when it makes dependencies or flow materially clearer. Do not turn the map into an implementation plan unless the user asks for one.
1---2name: codebase-mapping3description: Map an unfamiliar repository's architecture, entrypoints, flows, persistence, integrations, ownership, and change hotspots before consequential work.4---56# Codebase Mapping78Produce an evidence-backed map that helps another engineer navigate and change the system. This is read-only unless the user separately asks for implementation or documentation edits.910## Scope1112Resolve the question the map must answer: system overview, one feature flow, a migration target, security boundaries, deployment topology, or likely change surface. Read repository instructions first and preserve the distinction between source, generated code, vendored dependencies, tests, and deployment artifacts.1314## Investigate1516Use fast repository search and manifests before broad file reading. Trace:1718- runtime and build entrypoints;19- packages, modules, layers, and dependency direction;20- primary user/request/event flows and state transitions;21- schemas, persistence, queues, caches, and migrations;22- external APIs, authentication, secrets, and trust boundaries;23- configuration, feature flags, environments, CI/CD, and deployment units;24- tests, observability, ownership signals, and operational runbooks;25- coupling, fan-in/fan-out, compatibility boundaries, and change hotspots.2627Validate inferred relationships through imports, registrations, call sites, tests, configuration, or runtime evidence. Label uncertainty instead of presenting guesses as architecture.2829## Deliver the Map3031Tailor the output to the task. Include:3233- a concise system summary;34- a component or directory map with responsibilities;35- the relevant data/control-flow sequence;36- key contracts and external boundaries;37- likely files and tests affected by the proposed change;38- risks, unknowns, and recommended next inspections;39- file and line references for consequential claims.4041Use a small diagram only when it makes dependencies or flow materially clearer. Do not turn the map into an implementation plan unless the user asks for one.
egeetas