Frequently Asked Questions About Priscila Andre's Comprehend-First AI Coding Skill
22 answers covering everything from basics to advanced usage.
// Basics
What is the Comprehend-First AI Coding Skill in simple terms?
It is the practice of using AI to understand code before using AI to write code. Instead of jumping straight to generation, you prompt the AI to explain the codebase's architecture, conventions, features, data flows, tests, and history. You verify its answers, build your own mental model, and only then move to planning and implementation. It was created by Priscila Andre de Oliveira based on her experience at Sentry.
Who created the Comprehend-First AI Coding Skill?
Priscila Andre de Oliveira, a developer at Sentry, created this framework. She presented it at the AI Engineer conference, explaining how she discovered that 67% of her AI usage was comprehension and only 2% was code generation. The skill is built around her 'Catch Me Up' prompt, stored as a reusable Markdown file, with six exploration modes for systematic codebase understanding.
Is the Comprehend-First skill only for senior engineers?
No, it is valuable at every experience level. Junior engineers benefit most because it gives them a structured way to ask questions they might hesitate to ask busy colleagues. The framework treats AI as the cheapest senior engineer available — always on, always patient. Senior engineers benefit by quickly rebuilding context after absences or when reviewing unfamiliar parts of a large codebase.
Should I use Comprehend-First for small scripts or only large codebases?
The skill is calibrated for large or long-lived codebases where context is expensive to acquire. For a 50-line script, you can read it directly. The framework becomes valuable when the codebase is too large to hold in your head, has multiple contributors, follows conventions you're unfamiliar with, or has a history of changes you need to understand. Scale your investment in comprehension to the complexity of the system.
What is the biggest mistake people make when using AI to write code?
Skipping comprehension and jumping straight to code generation. This is the primary source of slop code in AI-assisted workflows. When you prompt an AI to write code without first understanding the codebase's architecture, conventions, and existing patterns, the output may compile but won't be intentional or defensible. The fix: always invoke a comprehension step before any generation step.
// How To
How do I set up the Catch Me Up prompt as a reusable file?
Create a Markdown file in your local project or notes directory. Structure it as a prompt template with placeholders for your role statement, exploration mode(s), and specific question. Include instructions for the AI to output structured formats (tables, Mermaid diagrams, component trees). Save it where your AI tool can access it — as a custom instruction, system prompt, or snippet you paste into conversations.
How do I choose which exploration mode to use?
Match the mode to your gap. Use Architecture when you don't know how components relate. Use Convention when you're unsure about coding standards. Use Feature for end-to-end understanding of a product capability. Use Trace to follow data or execution paths. Use Syntax for unfamiliar language patterns. Use Testing to understand test infrastructure. Use History to track why something changed. Select multiple modes when your gap spans several areas.
How do I get the AI to output diagrams instead of long paragraphs?
Explicitly request the format in your prompt. Say: 'Summarize as a Mermaid flow diagram,' 'Output this as a component tree,' or 'Present your findings as a table with columns for component, responsibility, and dependencies.' If the AI initially produces prose, re-prompt: 'Convert that into a table / ASCII diagram / Mermaid chart.' Visual structures accelerate comprehension significantly over walls of text.
How do I verify the AI's understanding of the codebase is correct?
Cross-reference the AI's output against what you already know, however partial. Ask probing follow-up questions. Look for contradictions or oversimplifications. Test specific claims by checking the actual code. If the AI says a function does X, verify it. Discrepancies between the AI's model and reality are often where bugs, misalignments, or architectural surprises live. Never accept the first response as ground truth.
// Troubleshooting
What if the AI gives me wrong information about my codebase?
This is expected and is exactly why the comprehension gate exists. When the AI misreads complex or legacy code, your follow-up questions catch the error before it propagates into planning or implementation. Surface the discrepancy, provide the correct context, and ask the AI to revise its understanding. This interactive correction process is where the deepest understanding is built — for both you and the AI.
What if the codebase is too large to fit in the AI's context window?
Focus on the subsystem relevant to your task rather than the entire codebase. Use the exploration modes to narrow scope: a Feature trace only needs the files involved in that feature. Paste specific files, directory structures, or README excerpts. Some AI tools support repository indexing. If context is limited, run multiple focused Catch Me Up sessions — one per exploration mode — and synthesize the results yourself.
I used Comprehend-First but the AI agent still drifted during implementation — what went wrong?
Drift during implementation means you may not be actively steering with your mental model. Comprehension is not a one-time step — it's your continuous reference point. When the agent proposes something that contradicts your model, stop and resolve the conflict before continuing. Also check whether you moved to implementation too early, before your mental model was truly aligned. If in doubt, return to the comprehension phase.
Can I use Comprehend-First with any AI model or does it require a specific tool?
It works with any conversational AI model — ChatGPT, Claude, Gemini, Copilot Chat, Cursor, or local models. The skill is prompt-based and tool-agnostic. The Catch Me Up prompt is a Markdown template you adapt to whatever AI interface you use. Models with larger context windows and code understanding perform better for architecture-level questions, but the framework applies universally.
// Comparisons
What is the difference between Comprehend-First and just reading the code yourself?
Reading code yourself is still essential, but AI accelerates comprehension by summarizing architectures, tracing execution paths, explaining conventions, and surfacing historical context from commit history in seconds rather than hours. The skill doesn't replace reading code — it structures your investigation so you ask the right questions and get organized, visual answers that build your mental model faster.
How does Comprehend-First compare to using GitHub Copilot for code generation?
GitHub Copilot focuses on inline code generation and autocomplete. Comprehend-First addresses the step that should happen before generation: understanding what exists and why. They are complementary. Use Comprehend-First to build your mental model, plan your approach, and only then use Copilot or similar tools for implementation — steering them with the context you've already built.
How does this compare to traditional code review practices?
Traditional code review assumes the reviewer already has sufficient codebase context. Comprehend-First adds a preparation step: before reviewing a PR, invoke Catch Me Up to understand the feature, data paths, and conventions being touched. This turns rubber-stamp approvals into genuine, contextual reviews. The PR author doesn't need to be interrupted for a walkthrough.
How does the four-phase model differ from the three-phase Research-Plan-Implement model?
The common three-phase model (Research, Plan, Implement) assumes you automatically understand the research output. Priscila Andre's four-phase model (Research → Comprehend → Plan → Implement) inserts a mandatory personal comprehension gate between research and planning. The AI does the research. You must comprehend its findings — verify, interrogate, and internalize them — before proceeding. This prevents planning based on misunderstood context.
// Advanced
How do I track my own AI usage like Priscila Andre did?
Review your recent AI conversation history and categorize each prompt as comprehension, planning, generation, debugging, or other. Tally the percentages. You may find, as Priscila did, that comprehension dominates your usage at 67% while generation is only 2%. Knowing your actual distribution lets you invest in better comprehension prompts and tools rather than optimizing for generation, which may be a small fraction of your workflow.
What does 'agent manager' mean in the Comprehend-First framework?
Agent manager is Priscila Andre's self-assigned role descriptor — a developer who primarily orchestrates and steers AI agents rather than writing code directly. It reflects the shift in senior engineering work toward comprehension, direction-setting, and quality control. Your job becomes ensuring the agent has correct context, its research is accurate, and its output meets the 'keynote code' standard of being intentional and defensible.
What is keynote code and how is it different from just 'clean code'?
Keynote code is code that is intentional, well-understood, and of a quality you would be proud to present publicly — as if at a conference keynote. It goes beyond clean code's focus on readability and formatting. Keynote code implies that the author deeply understands what the code does, why it exists, and how it fits into the larger system. It is the positive counterpart to slop code in Priscila Andre's framework.
Can Comprehend-First be used for codebases in languages I don't know well?
Yes, this is one of its strongest use cases. The Syntax exploration mode is specifically designed for understanding unfamiliar language patterns and abstractions. Combine it with Architecture or Feature modes to understand both the language-level patterns and the system-level design. AI excels at translating idioms from one language to another and explaining why certain patterns are used in a given ecosystem.
How do I use Comprehend-First for incident investigation?
Select the Trace and History exploration modes. Invoke Catch Me Up with your role (e.g., 'on-call engineer investigating a regression'), and ask the AI to trace the execution path of the failing behavior and surface recent changes via commit history. The AI can correlate recent PRs with the regression timeline. Verify its findings against logs and metrics. Build your mental model of the failure before attempting a fix.