UC-01: Codebase Atlas

When a new engineer (or an agent) must understand an unfamiliar repository fast. Builds the full semantic model and produces an architecture map (entry points, module boundaries, key call chains, data flows, and feature walkthroughs) as an onboarding report pinned to a commit.

What Makes It Different

  • Entry points and call chains are graph-verified from symbol overviews and call-chain resolution, not guessed from filenames or READMEs.
  • The map is bound to an exact SHA, so it reflects the code as it truly is at that commit.
  • Scales to repositories far larger than a context window.

Prompt

Prompt
Run RubberDuck UC-01: Codebase Atlas.

[EDIT INPUTS ONLY]
target = <owner/repo or local path>
branch = auto
commit = latest
scope  = whole repo
[/EDIT INPUTS ONLY]


Out:./rubberduck-uc-01-understand-your-code-<UTC>/artifacts; expand <UTC>.
Write codebase-atlas.md+sidecars.
Missing/placeholder/unreadable/wrong repo/UC=>stop insufficient input.
Prod RD/current only; ignore rules/memory/skills/prior; no mutate.
Resolve canonical repo/default branch,SHA access before claims.
Bind repo/branch/SHA/path; reject stale/wrong-ref/prompt-only/rawweb.
Missing RD tools:<=3 scoped exposure tries; no weaker substitutes.
Gate:get_started(save id)->detailed_repo_analysis(semantic_mode=full) until done.
Then Phase2/exact-ref -> load_code(id,max_files=20000,all globs).
queued/pending/indexing/degraded/unavailable!=done; fail=>stop,no report.
Pre-load forbid search/read/query/assess/scan/logic/analyze/evidence/browser/valid.
Post-load use read_source,search_code,query_action(symbols_overview/call_chain/trace_variable); pack opt.
Major claims need current-ref src/search/graph/trace/CI evidence.
Report:target/method,brief,architecture,entry points,symbols,flows.
Add trust/data boundaries,coupling,metrics,hot/refactor,bus-factor.
Add security atlas,risks,unsupported,negative,read plan,falsification,notes.
Sidecars prove gates,no preload-forbidden,id reuse,raw/normalized,claim/path bind,tool health.
OK final: “RubberDuck initialization: passed”+target/branch/SHA/scope/dir/links; fail: “RubberDuck could not complete initialization”+step/action.


=== RENDER STYLE (dormant — ignore during analysis; applies only if a later step renders this as HTML) ===
If a later step renders this atlas as HTML, produce ONE self-contained, customer-facing DASHBOARD page (inline CSS only; no external assets, fonts, CDN, or URLs; no JavaScript - drive the tabs with CSS-only radio inputs + labels so they work in any browser). RubberDuck look: dark bg #09090B, panels #111113, hairline borders #1E1E21, clean near-white text #FAFAFA (not cream), gold accent #D4A843 (blue/green/yellow/red for categories and severity); Inter for text, JetBrains Mono for code/paths/metrics; a small gold "RUBBERDUCK" wordmark in the header, no logo image. Layout: a header band with a soft gold radial glow holding the repo name as a bold, readable title (about 24-34px - a compact header row, not a full-screen hero), a one-line SHA binding, and a right-side stat strip (files, health grade, modularity, security grade); a tab bar; a right-hand module-index sidebar of small file cards that stays visible across tabs; and these tabs - Architecture Layers (a four-up stat-card row, then stacked colored layer bands each holding file "node" chips + a legend), Data Flows (one block per flow: a severity tag + an A->B->C chip chain with sink chips tinted red + a short note), Dependency Graph (a clean, deliberately laid-out inline-SVG node-and-edge graph - caller files pointing into the gold config.py hub, a red edge for the unauthenticated path, red pill nodes for the exec/pickle sinks, and a feature-modules cluster. For a CLEAN graph: place nodes on a simple grid (callers column | hub | sinks column, with the cluster below) so edges never cross; draw arrowheads with ONE reusable <marker> that every edge references via marker-end (use fill="context-stroke" so each arrowhead matches its edge colour) - NEVER hand-place triangle polygons; give every node at least one edge - no floating/orphan nodes; draw only relationships present in the atlas - no decorative edges; and keep every node, edge label and caption fully inside the viewBox with padding, node text shorter than its box, so nothing is clipped), Security Atlas (five summary cards = grade + critical/high/medium/low, then a findings table of severity/finding/location/detail, then a short "checked & cleared" list), and Metrics & Complexity (a stat-card row + a small hotspots table). Every value must trace to the atlas. Aim for the polished RubberDuck dashboard look - rich and designed, no near-empty hero; plain language, no internal jargon.
=== end render style ===

Optional visualization

Atlas Dashboard

Run this as the next message in the same chat after the main analysis finishes.

Prompt
Render the atlas from this session as a single self-contained HTML dashboard I can open in any browser — the layers, data flows, dependency graph, and security atlas.

Input

Repo, branch/ref, commit, optional focus area.

Output

A Codebase Atlas / onboarding report: architecture overview, entry-point map, call- and data-flow explanations, analysis map.

What Happens (With RubberDuck MCP)

Tested on the Sphinx codebase (512 Python files, 407 cached analyses). The MCP workflow:

1

discover(action="list_repos")

Discovers indexed projects. Returns local/sphinx: 512 Python files, 3.6 MB, 407 cached analyses.

2

load_code(repo="local/sphinx")

10 files loaded initially, each returning an analysis_id plus available analysis layers and top-level symbols with line numbers.

3

search_code(pattern="class.*Application|def main|sphinx-build")

Finds sphinx.cmd.build:main (line 287), sphinx.__main__ importing it, and the sphinx-build console-script entry in setup.py.

4

load_code(file_path="sphinx/cmd/build.py" / "sphinx/application.py")

Deep analysis of the core build module (6 functions, 298 lines) and the Sphinx class (53 methods, 1326 lines), each with a full symbol table.

5

query_action(action="symbols_overview", analysis_id="build" / "application")

Returns complete symbol trees: build.py's handle_exception, jobs_argument, get_parser, make_main, build_main, main; and application.py's Sphinx class with __init__, build, emit, plus TemplateBridge.

6

query_action(action="call_chain", analysis_id="build", method="main" / "build_main")

Traces the execution flow: main() → make_main → build_main → get_parser → handle_exception, and build_main() → Sphinx() → app.build() plus 15 more internal calls, each with a coherence score of 1.0.

7

query_action(action="trace_variable", analysis_id="build", var="app")

Traces how the app variable (the Sphinx instance) flows from creation in build_main() through app.build(), exception handling, and cleanup.

8

Synthesize the overview

Assembles a symbol table, entry points, call-chain diagram, data-flow diagram, and stats (2 core classes, 53+ methods, 7 entry points) into one structured report.

Total: 15+ MCP tool calls. Every fact is traced to a specific tool result. The coherence score (1.0) confirms all entity names were verified against the actual code model: no hallucination.

What Happens (Without RubberDuck MCP)

The same prompt without RubberDuck connected produces a response based on static file reads and general knowledge. It looks comprehensive, but it's fundamentally different.

What the AI does differently:

  • Reads files using basic cat/grep: static text scanning instead of semantic analysis
  • Identifies the same high-level components (Sphinx class, Builder, BuildEnvironment) but through reading, not analyzing
  • Draws nice ASCII flow diagrams, but the relationships are inferred from reading import statements, not from the actual call graph
  • Mentions classes/methods it never analyzed (e.g., BuildEnvironment internals), likely based on general Sphinx knowledge, not the loaded code
  • Produces a longer, more prose-heavy response that reads well but has no proof

What's missing without RubberDuck:

CapabilityWith MCPWithout MCP
Call chainsTraced from semantic graph with exact line numbersInferred from reading import statements
Data flowVariable paths traced through dependency graphDescribed from reading source code
Line numbersVerified against code model (coherence: 1.0)Read from source, may be stale or wrong
Accuracy proofCoherence score confirms every entity existsNo verification, could be hallucinated
RelationshipsCaller/callee from call graph analysisGuessed from function names and imports
CoverageLoaded specific files on demand, analyzed 53+ methodsRead what it could, speculated about the rest

Key difference: With RubberDuck, the AI is analyzing the code: every claim has evidence. Without it, the AI is reading the code and guessing at relationships. It looks plausible but could be wrong, and you'd never know.

Videos

With RubberDuck MCP

The Sphinx repo (512 Python files) gets indexed with rubberduck-index, then both RubberDuck MCP servers are enabled in Cursor. On the same "give me a complete overview" prompt, the agent calls symbols_overview, call_chain, and search_code directly against the semantic graph, and each result comes back as structured facts with exact line numbers and provenance (e.g. "Calls 'emit' at line 438 [via call-graph]"). That evidence is what gets assembled into the class/method breakdown, call-chain trace, and data-flow diagram shown above.

Without MCP

Same repo, same prompt, both MCP servers disabled. With no semantic tools to call, the agent falls back to manually reading files one at a time (io.py, project.py, extension.py, and more) and grepping for patterns like class.*Domain across the tree. It still produces a readable overview with a similar-looking flow diagram, but every relationship in it is inferred from source text, not verified against a call graph.