Code & Comprehension, Part 7: The Agent Prompts

How each of the nine agents in the Codebase MOOC was designed to think — the specific prompt decisions that make the difference between curriculum that builds genuine comprehension and curriculum that produces the illusion of it.

Part 6 described what each agent does. This article explains how.

Every agent in the plugin is a Markdown file in agents/. Each file is both the documentation and the system prompt — Claude Code reads it when running as that agent. The design of each file reflects specific decisions about how to produce reliable, high-quality output for that agent's particular task.

This article opens each file and explains the decisions.

The Archaeologist: Three Levels for a Reason

The Archaeologist builds Codebase Memory — the structured JSON graph that every downstream agent reads. The most important decision in its design is the three-level chunking strategy, and the most critical detail within that is what happens at Level 3.

The agent is explicitly instructed to read from memory at Level 3 rather than re-reading source files:

## Level 3 — Cross-Component Synthesis
Read the graph you have built so far from:
  .codebase-mooc/memory/codebase/graph.json
Do not re-read source files. Reason from what you have already built.

This is not primarily for context window management, though that helps. It is for quality. When the Archaeologist synthesises cross-component relationships from a structured representation rather than raw source, it reasons about the system as a whole rather than being distracted by implementation detail. The synthesis — architectural_philosophy, significant_seams, systemic_failure_modes, dependency_insights, evolution_trajectory — is richer and more accurate when produced this way.

The instruction to preserve the reasoning trace is equally deliberate:

Preserve your complete reasoning in synthesis_reasoning. Downstream
agents read this to understand not just the structure but why it is
structured this way.

The Historian benefits from this most directly. When it reasons about why a component’s code looks the way it does — what decision it reflects, what constraints shaped it — it reads synthesis_reasoning to understand the architectural context. Without this trace, the Historian's INFERRED decisions are less grounded. With it, inferences are anchored in documented reasoning rather than floating speculation.

The write-incrementally instruction matters in production:

Write each component to memory as you finish it. Do not wait until all
components are done — write incrementally so progress is not lost.

A large codebase Level 2 pass can run for minutes. If it fails partway through due to a timeout or context limit, an incremental write strategy means completed components are preserved and only remaining ones need re-running. The difference between a five-minute partial failure and a twenty-minute full restart.

The Architect: Altitude and Format Discipline

The Architect takes Codebase Memory and produces the architecture curriculum layer. Two prompt decisions define its character.

First, it reads cross_component_synthesis and synthesis_reasoning before writing about any individual component:

Read cross_component_synthesis and synthesis_reasoning first. This gives
you the system-level understanding you need before writing about components.

This produces architecture documentation grounded in the system’s actual design philosophy. An architecture layer written without this context tends to describe what components do. An architecture layer written with it tends to explain why they exist and how they fit together — which is what a new developer actually needs.

Second, the file format is specified precisely and includes worked examples:

## Where it fits
{Its position in the system. What calls it. What it calls.
Include a simple ASCII diagram showing the data flow around it.
Example:
  order-service → payment-service → ledger-service
                        ↓
                  fraud-service
}

This specificity matters because vague format instructions produce inconsistent output. The ASCII diagram requirement is particularly important — it forces the Architect to reason spatially about the component’s position rather than describing it in prose, which produces understanding more reliably than text alone.

The Boundaries section instruction carries the most weight:

## Boundaries
{What this component owns exclusively and what it does not touch.
Where responsibility transfers to another component.
This is often the most important thing a new developer needs to know.}

That final line is a prompt to the agent, not to the reader. By telling the Architect that boundaries are the most important thing a new developer needs, the instruction shapes how it reasons about what to emphasise. Agents respond to explicit priority signals. This one reliably produces boundary documentation that is substantive rather than formulaic.

The Domain Analyst: A New Kind of Layer

The Domain Analyst is the newest agent in the plugin. It fills a gap that the others leave: none of them explain why the code has to work a certain way from a business perspective. The Architect explains structure. The Historian explains decisions. The Instructor explains implementation. The Domain Analyst explains the domain.

Its search targets are specified precisely:

Look for: validation rules, business state machines, pricing logic,
permission models, compliance checks, regulatory constraints, domain
events, entity lifecycle rules, invariants enforced in code.

This list is instructive because these patterns are often invisible at first glance. A validation rule that rejects amounts above a threshold looks like a conditional. Its significance is that it enforces a business rule — possibly a regulatory one — that must not be violated under any circumstances. Without being told to look for these patterns specifically, an agent reads them as implementation detail rather than domain knowledge.

The vocabulary table requirement is the most distinctive design choice in the agent:

## The domain vocabulary
| Term | What it means in this codebase | Where it appears |
{Include terms where the codebase uses domain-specific language that
a new developer would not know. Also include terms where the codebase
uses a common word with a specific meaning different from its usual one.}

The second instruction is the one that catches the most dangerous category of vocabulary misunderstanding. When a codebase uses “event” to mean something specific to its domain rather than the general software engineering sense, a developer who does not know this will make mistakes that look correct technically but violate domain constraints. Naming this category explicitly ensures the Domain Analyst surfaces it.

The compliance section ends with an honest fallback:

If none are apparent, say: "No regulatory constraints identified.
A domain expert should verify this assessment."

This is a deliberate choice about handling uncertainty. Rather than letting the agent speculate or leave the section empty, the instruction provides a specific thing to say when evidence is insufficient. Curriculum that is honest about its own limits is more valuable than curriculum that confidently fills gaps with plausible-sounding content.

The Historian: The Evidence Tagging Discipline

The Historian is the hardest agent to get right. Its job is to produce the decision log — the most valuable curriculum layer and the one most vulnerable to confabulation. A Historian that invents plausible-sounding decision rationale with false confidence is worse than no decision log at all. It does not just fail to inform — it actively misinforms.

The evidence tagging rules are the core of the agent’s design:

CITED — direct evidence from a commit message, PR description, or code
comment. Always include the commit hash or file:line reference.

INFERRED - reasoning from code shape, patterns, or architectural context.
Always include confidence (0.0–1.0) and the specific observation.
Mark the decision heading with ⚠ INFERRED.

Never present an inference as a citation.
Never fabricate a commit hash.
Mark gaps explicitly - they become review prompts, not excuses to confabulate.

The instruction “Mark gaps explicitly — they become review prompts, not excuses to confabulate” is doing important work. It reframes incomplete evidence as valuable rather than as a deficiency to hide. An “Open questions” section at the bottom of a decision log file with specific questions for senior engineers is genuinely useful curriculum. An INFERRED decision dressed up as CITED is a liability that erodes trust in the whole curriculum.

The aggregate warning is equally important:

If more than 50% of decisions are INFERRED, add this callout at the top:
> ⚠ Most decisions in this file are inferred. A senior engineer
> familiar with this component should review and fill the gaps.

This produces self-aware curriculum. A developer reading a decision log knows immediately whether it is well-evidenced or speculative. The Reviewer agent checks CITED entries against actual commit hashes, but this callout gives human reviewers an immediate signal about where to focus their attention before they read a single word.

The Instructor: Teaching vs Describing

The Instructor is most responsible for whether the curriculum builds genuine comprehension or merely familiarity. The distinction is in how it is prompted.

The file format requires actual code to be pasted in alongside the explanation:

### Step 1 — {Short title}
```python
# paste the relevant code here

What is happening: {Plain explanation of what this code does.} Why this way: {Why it is written this way and not another way.} What breaks if you change this: {The specific consequence. Not "things might break" - what specifically breaks and how.}

The rejection of vague explanations — “Not ‘things might break’ — what specifically breaks and how” — is a prompt that produces concrete, testable statements rather than hedged generalities. A developer reading “if you remove the idempotency key check, the payment provider charges for duplicate requests” understands the constraint in a way they cannot from “removing this may cause issues.”

The non-obvious parts section is the most distinctive element:

The non-obvious parts

These are the places that look simple but are subtle. Developers unfamiliar with the constraints will make mistakes here.

This section is designed to surface the tacit knowledge that experienced engineers hold — the things they tell a new developer in a code review or a pairing session but would never put in a README. By naming this category explicitly and asking the Instructor to populate it, the agent is prompted to reason about what a developer would assume versus what is actually true, rather than just describing what the code does.

The seams table is similarly precise:

The seams

| Connects to | Where | Contract | Violation consequence |

The “Violation consequence” column is what makes this useful rather than decorative. A table that names the connection and the location without specifying what breaks when the contract is violated tells a developer where things connect but not why those connections matter. The column forces the Instructor to complete the reasoning.

**The Pathologist: The 3am Heuristic**

The Pathologist writes failure mode entries. The most important prompt decision is a single phrase in the “What happens” section:

Written as if you are describing it to an on-call engineer at 3am.

This heuristic reorients the entire failure mode entry. An on-call engineer at 3am needs observable symptoms in plain language, not architectural analysis. They need to know what they see, not what caused it. The symptoms lead them to the diagnosis; the diagnosis leads them to the resolution. The analysis comes later.

Without this heuristic, failure mode documentation tends to be written from the perspective of someone who already knows the cause — which makes it useless for diagnosis. With it, the entry describes what a developer actually experiences when the failure occurs. The difference is between “occurs when the outbox publisher worker fails to acquire a database lock during high contention” and “the payment service stops publishing events to the message broker — orders appear stuck and the ledger service falls behind.” One is accurate. The other is actionable.

The DOCUMENTED/SPECULATIVE distinction is enforced as a hard rule:

Set all proactive entries to SPECULATIVE.

All proactive entries — failure modes identified through analysis rather than from actual incidents — are SPECULATIVE, and all SPECULATIVE entries require human review. The curriculum is read by developers who trust it. A speculative failure mode presented as a known failure mode erodes that trust when it turns out to be wrong. The marker is not optional.

**The Examiner: Operationalising the Cognitive Science**

The Examiner operationalises Part 4’s cognitive science directly into the exercise format. Three prompt decisions matter most.

The first is the framing at the top of the agent file:

Every exercise must require the learner to produce something — code, an explanation, a design decision, a diagnosis. If a learner can pass by pattern-matching to content they have read, the exercise has failed.

This is not an instruction about format. It is an instruction about the cognitive process the exercise must engage. By stating the failure condition explicitly, the agent is prompted to evaluate every exercise it generates against that condition before writing it out.

The second is the evaluation criteria format:

A passing response demonstrates:

• {Specific thing 1 that shows genuine understanding}
• {Specific thing 2}

A pattern-matched response will:

• {What a surface-level answer looks like - what to watch for} Common mistake: {The most frequent wrong approach and why it is wrong.}

The “pattern-matched response” section is the most important part of the evaluation criteria. It forces the Examiner to reason about what a learner who does not actually understand would produce — and by reasoning about that, the Examiner is prompted to ensure the task itself cannot be completed by surface-level pattern-matching.

The third is the abstraction prompt requirement:

## Abstraction prompt
{A question that asks the learner to name the general principle behind
this specific instance.}

This is the transfer prompt from Part 4. Every exercise generates one. It is the mechanism by which the curriculum builds far transfer rather than near transfer — the ability to apply knowledge to genuinely new situations rather than to situations that resemble the training examples. A developer who can only explain the authorization/capture split in the context of the payment service has near transfer. A developer who can identify the “reserve now, commit later” pattern and recognise it in distributed systems, database transactions, and hotel booking flows has far transfer. The abstraction prompt is what produces the latter.

The Reviewer: Four Checks in a Deliberate Sequence

The Reviewer validates everything before it reaches human reviewers. Its four checks are specified in a deliberate order: factual accuracy, confabulation, pedagogical quality, exercise integrity.

The order matters because the checks have different costs. Factual inaccuracy and confabulation are largely binary — the content is either accurate or it is not, and the Reviewer can verify against source files and git history. Pedagogical quality and exercise integrity require judgment. Running the binary checks first catches clear errors quickly and cheaply. The judgment calls are made only on content that has passed factual validation.

The confabulation check for the decision log is the most specific:

For CITED entries: does the cited commit hash actually exist?
Run: git show {hash} --stat and verify it touches the relevant files.

This is an active verification step. The Reviewer runs git commands to check that cited commit hashes are real and that they actually relate to the relevant files. A Historian that produces a plausible-sounding but fabricated commit hash will be caught here before the content reaches any human.

The annotation output stays JSON even though everything else is Markdown:

## Where to write review annotations
.codebase-mooc/memory/review_annotations/{component}_{layer}.json
Keep this as JSON - it is machine-read by the review CLI, not
human-read directly.

The review CLI reads these annotations to surface flags alongside Markdown content. The human reviewer sees the Markdown file and the parsed, formatted flags. Keeping annotations as machine-readable JSON means the CLI can filter by severity, sort by recommendation, and present structured information rather than raw text. The format serves its purpose — human eyes never need to read raw review annotation JSON.

The Tutor: Continuity as the Core Design Principle

The Tutor is what learners experience. Every other agent exists to build what the Tutor delivers. Its central design principle is continuity — every session is a continuation of a long pedagogical relationship, never a cold start.

The learner state JSON file is read before every single interaction:

## Step 1 — Read learner state (JSON)
Read:
  .codebase-mooc/memory/learners/{learner_id}.json

A developer who started a learning session three weeks ago and returns today resumes exactly where they left off. The Tutor knows which competencies have been mastered, which are in progress, which concepts are due for spaced repetition today, and what arc the developer is currently in. This is not a session state — it is a persistent model of a specific developer’s relationship with this specific codebase.

The competency mastery rule is precise:

Mastered = true after 3 consecutive passes on that competency.

Three consecutive passes, not three total. This prevents a developer from passing two exercises, failing several, passing one more, and being counted as having mastered the competency. The consecutive requirement means mastery must be demonstrated reliably, not just occasionally.

The response evaluation instruction defines what genuinely passes:

A correct answer with wrong reasoning is a flag, not a pass.
A wrong answer with correct reasoning: acknowledge it and guide them.
A correct answer with correct reasoning: genuine pass.

This is the cognitive science from Part 4 operationalised directly. The Tutor evaluates reasoning, not answers. A developer who gives the right answer by pattern-matching has not demonstrated the competency. A developer who gives a wrong answer but reasons correctly about why the code works the way it does is closer to genuine understanding than one who guesses correctly. The Tutor knows the difference and acts on it.

The spaced repetition calculation is specified numerically:

Next review = today + (2 ^ attempt_count) days. Cap at 64 days.

First review: tomorrow. Second: in 2 days. Third: in 4 days. Fourth: in 8. This is the forgetting curve intervention from Part 4 implemented as a specific algorithm. The cap at 64 days prevents concepts from drifting out of regular contact entirely, which matters for a developer who is actively working on a codebase and needs working knowledge rather than archival recall.

The tone instruction is last and brief:

## Tone
Patient. Clear. Curious about the learner's thinking. Never condescending.
Honest about what is hard. Encouraging without being hollow.
You genuinely want this person to understand this codebase deeply enough
to onboard the next developer who comes after them.

The final sentence is not motivational phrasing. It is a goal specification. The Tutor’s purpose is not to help the learner pass exercises or complete arcs — it is to produce an engineer capable of teaching the next person. That is a meaningfully higher bar than comprehension alone, and stating it explicitly shapes every pedagogical decision the Tutor makes throughout every session.

What These Decisions Share

Reading across all nine agents, a pattern emerges in the prompt decisions that work.

Explicit failure conditions outperform positive instructions. Telling the Examiner “if a learner can pass by pattern-matching, the exercise has failed” is more effective than telling it to “create challenging exercises.” The Historian’s “never fabricate a commit hash” is more effective than “be accurate.” Negative constraints narrow the space of bad outputs more reliably than positive descriptions of good ones.

Format specificity produces consistency. The Architect’s ASCII diagram requirement, the Instructor’s code-paste requirement, the Historian’s CITED/INFERRED tagging with required fields — these produce consistent output that downstream systems and human reviewers can rely on. Vague format instructions produce output that varies in structure, which makes it harder to validate and harder to display reliably.

Honest uncertainty beats confident speculation. The Domain Analyst’s compliance fallback, the Historian’s open questions section, the ⚠ INFERRED marker — all of these are prompts that produce curriculum honest about its own limits. Curriculum that confidently fills gaps with plausible-sounding content fails in the worst possible way: it produces false confidence in learners who trust it.

Goal specification shapes every decision in an interaction. Telling the Tutor that its goal is to produce an engineer capable of onboarding the next developer is not an inspirational statement. It is a constraint that makes the Tutor more demanding about genuine understanding and less satisfied with surface familiarity. Every prompt decision that specifies the ultimate purpose of the output shapes how the agent reasons about intermediate decisions.

Code & Comprehension is a series on AI, engineering knowledge, and the responsibility we carry toward the developers who come after us. The plugin is live at github.com/psreek-ai/codebase-mooc. Part 8 covers the hooks and coordinator in depth — how the three-outcome significance classifier handles real commit patterns, why ambiguous commits are deferred rather than forced, and how the coordinator’s pure-Python zero-API-call architecture is the decision that makes the whole system work without any infrastructure beyond Claude Code itself.