How to Onboard to a New Codebase Fast with AI
For Engineers onboarding to a new codebase · Based on Priscila Andre's Comprehend-First AI Coding Skill
// TL;DR
New to a repository and expected to contribute within days? The Comprehend-First skill lets you use AI to build an accurate mental model before touching code. Declare yourself a 'new contributor', pick the Architecture and Testing exploration modes, and ask a specific question like how the system handles test payloads. Demand a flow diagram, interrogate the answer, and only start coding once you can explain the system in plain language. This is how you ship keynote code as a new joiner instead of slop code you can't defend in review.
Why is onboarding to a large codebase so slow without AI?
Joining an unfamiliar repository mid-sprint is one of the hardest moments in engineering. Docs are stale, the people who wrote the code are busy or in other time zones, and you're expected to contribute within days. Traditionally you'd spend weeks reading files, tracing flows, and asking hesitant questions. The Comprehend-First skill collapses that timeline by treating AI as the cheapest senior engineer available — one who never gets tired of your questions and answers at any hour.
The core insight: the biggest unlock from AI in a large codebase is comprehension, not generation. An audit of real prompt history showed ~67% of prompts were comprehension and only ~2% were generation. Onboarding is comprehension work by definition, so this is exactly where the skill pays off most.
How do I use Catch Me Up on my first day?
Invoke the Catch Me Up skill with three ingredients. First, declare your role: 'I am a new contributor to this repository.' This calibrates the depth and vocabulary of the response. Second, select your exploration mode — for onboarding, Architecture (overall structure and component relationships) plus Testing (how tests are structured and what they actually simulate versus intercept) is a strong default. Third, ask a specific clarifying question.
A real example: 'I am a new contributor. Catch me up on how this repository works, and clarify whether it simulates external service payloads or intercepts real ones during tests.' The AI produces a structured summary and a flow diagram. In one case, a developer discovered the system intercepts real payloads rather than mocking them — a key architectural fact that completely changed how they wrote their first contribution.
How do I make the output actually usable?
Demand a visual. Ask for a table, an ASCII or Mermaid flow diagram, or a hierarchical organogram of component relationships. Prose summaries are hard to internalize quickly; structure accelerates comprehension. If the AI returns a wall of text, re-prompt: 'Summarise that as a component tree.'
Then interrogate. Don't accept the first response as ground truth — AI can misread complex or legacy code. Ask follow-ups until you can explain, in plain language, what the code does and why. This is the mandatory comprehension gate. If you can't explain it, repeat with a more targeted mode like Trace to follow a specific execution path.
When do I actually start writing code?
Only after your mental model is aligned. Once you can explain the system, instruct the AI: 'Now plan the implementation for my first task.' The comprehension phase feeds directly into planning — don't conflate them. Planning without comprehension produces slop code you'll fail to defend in review. During implementation, your mental model becomes your steering wheel: when the agent drifts or makes a wrong assumption, you catch it because you understand the system.
This is how a new joiner ships keynote code — intentional, well-understood, presentation-quality work — instead of slop code that gets torn apart in review or breaks production.
Next step
Before your next first-day task, save a Catch Me Up prompt as a Markdown file encoding the six exploration modes. On day one, open with your role, select Architecture + Testing, and ask one concrete question about how the repo really works. Don't write a line of code until you can explain the answer out loud.
// FREQUENTLY ASKED QUESTIONS
Which exploration modes are best for onboarding?
Architecture and Testing are the strongest defaults for onboarding. Architecture gives you the overall structure and component relationships, while Testing reveals how tests are set up and what they actually simulate versus intercept — often a key architectural fact. Add Trace if you need to follow a specific data or execution path, and Convention to learn naming and lint standards fast.
How fast can I realistically onboard using this skill?
Days instead of weeks in the documented scenario. A developer joining a test-infrastructure repo mid-sprint used Catch Me Up with Architecture + Testing, got a flow diagram and structured summary, discovered the system intercepts real payloads, and was able to write a correct first contribution — without waiting on busy colleagues in other time zones.
What should I avoid as a new contributor using AI?
Avoid shipping code you don't understand just because the AI wrote it. If the codebase serves real users, you're responsible for what goes in. Also avoid skipping the verification step — AI can misread legacy code, so interrogate its answer until you can explain the system in plain language before you write anything.