I learn codebases faster by giving AI better context

The biggest improvement I made to my contribution cycle was not a better prompt. It was giving the AI better artifacts to reason from.

This shows up in two places for me: reviewing code changes, and landing in codebases I do not know well yet.

Reviewing code changes

For a while, my workflow for exploring pull requests in unfamiliar codebases looked like this: I checked out the PR locally, asked an assistant to explain the change, then kept asking follow-up questions until I felt oriented.

It only worked up to a point.

The assistant was often exploring the codebase in the same messy way I would. It searched files, inferred patterns, guessed intent from names, and stitched together an explanation. That was useful, because it was still faster than manually browsing everything myself. But it was also hit and miss. It gave me a narrative, not necessarily a reliable model of the system.

What changed for me was combining AI with Swamp reports.

A Swamp report is a repeatable artifact generated from project data. It can summarize code structure, activity, dependencies, runtime assumptions, or review-specific signals.

Instead of asking an AI to rediscover the same facts every time, the artifact captures what matters for the review: call paths, dependency management, runtime assumptions, drift, recent activity, or whatever else the report is designed to expose.

As an example, for PRs, I have a report showing the declared linked issues, a recap of the conversations, the full call paths and stack affected, the tests related to those paths, and the dependency changes. It saves me opening GitHub, running grep searches, and browsing the IDE just to reconstruct context.

In other words, I start my review by understanding the context without leaving my terminal. I can even stay inside my agent session, because displaying the Swamp report does not consume many tokens.

I also record my findings and comments in the Swamp report. That means I can come back to the same PR a week later and remember where I was. The context lives in the swamp, not in a chat window.

The next step is to enrich that report with more historical context: previous PRs, issue discussions, and decision records connected to the files being changed. If a file was shaped by an earlier decision, I want that decision to show up during review.

That turns the AI from an explorer reconstructing context on demand into a review assistant working from a stable map.

The important part is that this can happen asynchronously. The report can be generated before I sit down to read the pull request. When I start reviewing, I already have a consistent artifact that helps me build a mental model of what should change and what actually changed.

That shifts my attention. I spend less time reconstructing mechanical context and more time asking higher-level questions. Does this change fit the architecture? Does it move risk into a hidden place? Does the implementation match the intent? Are the tests exercising the important or risky behavior, or only the easy path?

The consistency matters. If every review starts from a slightly different AI exploration, my brain has to normalize the result each time. If every review starts from a report with the same shape, I can compare faster and notice the strange parts sooner.

Landing in new codebases and projects

The same pattern helps when I land in a new codebase.

I do not want a file-by-file tour. I want to answer sharper questions quickly. What are the important moving parts? How is the community behaving? Who is active on the project? How are dependencies managed? What are the indirect security implications of the architecture? Which parts look actively maintained, and which parts look suspiciously quiet? Where are the operational edges?

Raw source code can answer those questions, but not directly. You have to read through conventions, framework noise, generated files, and historical accidents. AI helps compress that reading, but only if the input has enough shape.

Swamp reports give me that shape.

The useful pattern is simple. I use Swamp to extract and normalize the facts I know I will ask about repeatedly. Then I use AI to interrogate those facts, connect them back to the source, and challenge my assumptions.

That separation matters.

Reports are deterministic enough to trust as a baseline. They do not get tired, skip files because the context window is full, or change their mind because I phrased a question differently. AI is good at synthesis. It can explain why two facts matter together, compare a current implementation with a likely design intent, or point out the strange part of a system that a table will not highlight.

The combination is much stronger than either side alone.

For infrastructure projects, this lets me ask sharper questions: Which secrets or permissions are implied but not documented? Is there an explanation for why this component exists, or only evidence that it was added at some point?

A generic AI pass often gives me a pleasant overview. Sometimes it gives me confident guesses. A report-backed AI pass gives me a sharper mental model, because the conversation starts from facts that were extracted consistently. It changes the questions I ask.

Instead of asking, “What does this repo do?”, I can ask, “Given this report, what are the three riskiest assumptions for code sustainability?” Or, “What is missing from the code to make that implementation match current reality?” Or, “Which part of the system should I inspect first if I care about what happens when one active maintainer disappears?”

Those are better questions. Better questions produce better learning.

Project memory, not just chat memory

The other benefit is memory. Not AI memory, but project memory.

A report can be rerun after changes. It can be compared. It can be shared with another person or another assistant. If my understanding depends only on a chat transcript, it starts decaying as soon as the conversation ends. If it depends on a report, I can refresh it and keep using it as a stable reference point.

That makes the learning loop tighter.

I used this, for example, to analyze people risk in the External Secrets Operator project. I looked at maintainer activity beyond commits, including issue comments and reviews, to estimate the impact of a maintainer leaving the project.

That analysis had a practical goal, but it also gave me an unexpected personal benefit. It helped with my imposter syndrome. On the months where I was active, the report showed that I was often the second contributor, or very close to third, by issue and review activity. Not by vibes, not by memory, but by data. That matters when your internal story is noisier than the facts or your confidence is low.

The actual acceleration

I still read the code. I still check the implementation. I do not want an assistant to replace that part.

What I want is to spend less time building the first rough map in my head, especially when the codebase mixes application logic, infrastructure, security policy, and operational glue.

AI helps me move faster through unfamiliar terrain. Swamp reports make sure the terrain is described in a form that survives past one conversation.

That is the real acceleration for me: not skipping understanding, but reaching the interesting questions sooner.