Prompts & Context Assembly
Relevant source files
The following files were used as context for generating this wiki page:
The Prompts & Context Assembly system is the core intelligence layer of the AI code reviewer. It is responsible for transforming raw data—such as pull request diffs, repository history, and developer feedback—into structured prompts that guide Large Language Models (LLMs) to perform specialized tasks including code review, intent classification, and knowledge extraction.
The system utilizes a multi-layered Retrieval-Augmented Generation (RAG) architecture to move beyond simple diff analysis. By injecting historical review decisions, similar code patterns from the existing codebase, and specific repository knowledge, the system ensures that AI-generated comments are contextually aware, consistent with existing standards, and grounded in the team's specific engineering culture.
RAG Context Layers
The assembly process gathers information from four distinct "knowledge layers" to enrich the review prompt. This multi-layered approach allows the LLM to act as a senior engineer who is deeply familiar with the specific codebase.
| Layer | Purpose | Retrieval Method |
|---|---|---|
| Layer 1: Codebase Context | Identifies similar functions/classes to flag inconsistencies. | Vector search of AST-parsed code chunks. |
| Layer 2: Review Memory | Recalls past review decisions (accepted/dismissed) to ensure consistency. | Vector search of past ReviewMemory entries. |
| Layer 3: Rules & Knowledge | Injects documentation, coding standards, and learned developer feedback. | Hybrid search of .md files and RepoKnowledge table. |
| Layer 4: Dependency Graph | Understands the "blast radius" and impact of changes (Advanced). | AST import parsing (planned/advanced). |
Sources: CLAUDE.md:43-108, packages/review/src/orchestrator.ts:133-157
Context Retrieval Flow
The orchestrator manages the parallel retrieval of these layers before constructing the final prompt for the LLM.
Prompt Templates & Construction
The system uses specialized prompt builders located in prompts.ts. These functions take structured data and format it into the final string sent to the provider.
File Review Prompt
The most critical prompt, buildFileReviewPrompt, assembles the PR metadata, the diff itself, and the retrieved RAG context. It enforces a strict JSON output format to ensure the response can be programmatically parsed and validated.
- System Role: Expert AI code reviewer focusing on bugs, security, and quality.
- Rules: Only comment on added/context lines, use 1-indexed line numbers, and prioritize high severity.
- Context Components: PR Title/Body, Similar Code patterns, Past Review decisions, and learned Repo Knowledge.
Sources: packages/review/src/prompts.ts:12-30, packages/review/src/prompts.ts:32-75
Interaction Prompts
The system supports two-way interaction through specialized classification and explanation prompts:
- Intent Classification:
buildClassifyDevCommentPromptdetermines if a developer is asking a question, providing knowledge, or accepting/dismissing a finding. - Comment Explanation:
buildExplainCommentPromptinstructs the LLM to provide a detailed technical breakdown of a specific finding when a developer asks for clarification. - Knowledge Extraction:
buildExtractKnowledgePromptidentifies factual statements about the codebase in developer comments to store for future reviews.
Sources: packages/review/src/prompts.ts:110-153, packages/review/src/prompts.ts:157-184
Data Structures and Validation
To maintain reliability, the system uses Zod schemas to validate LLM outputs. This prevents "hallucinated" structures from breaking the orchestration pipeline.
Response Schemas
| Schema | File Path | Purpose |
|---|---|---|
FileReviewOutputSchema | schemas.ts | Validates a list of comments and an optional file summary. |
FileReviewCommentSchema | schemas.ts | Validates individual comment fields (line, side, severity, body, suggestion). |
PrSummaryOutputSchema | schemas.ts | Validates the final 2-4 sentence PR review summary. |
DevCommentClassification | llm-client.ts | Structure for intent, confidence, and reasoning. |
Sources: packages/review/src/schemas.ts:14-38, packages/review/src/llm-client.ts:40-44
Structured Output Logic
The llm-client.ts contains utility logic to handle the transition from raw LLM text to typed objects.
function extractJson(raw: string): string {
const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
if (fenced?.[1]) return fenced[1].trim();
return raw.trim();
}
Sources: packages/review/src/llm-client.ts:31-35
Context Assembly Workflow
The orchestrator integrates retrieval and prompt building into the review loop. For every reviewable file, the system performs the following sequence:
- Vectorization: The diff patch (up to 3000 chars) is converted into a vector embedding.
- Multi-Store Retrieval: Queries are sent to
searchSimilarCode,searchSimilarReviews, andsearchRepoKnowledge. - Context Block Formatting: Raw database results are formatted into human-readable Markdown blocks (e.g., using
buildPastReviewsContext). - Prompt Injection: These blocks are concatenated into the final user prompt.
- LLM Execution: The prompt is sent to the configured provider (OpenAI or Anthropic) with low temperature (0.1) for consistency.
Sources: packages/review/src/orchestrator.ts:133-176, packages/review/src/llm-client.ts:80-92
Developer Comment Processing
When a developer replies to an AI comment, the processDevComment function triggers a sub-flow for context assembly.
Summary
The Prompts & Context Assembly system transforms the AI Reviewer from a generic LLM wrapper into a specialized engineering tool. By strictly separating prompt templates from orchestration logic in prompts.ts and implementing a robust RAG pipeline in orchestrator.ts, the system provides reviews that are consistent with historical decisions and repository-specific standards. The use of structured Zod validation ensures that the results posted back to GitHub remain technically accurate and formatted correctly.