Claude AI Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Claude AI integration serves as the cognitive backbone of the Abee platform, leveraging Anthropic's Claude models (specifically claude-sonnet-4-20250514) to handle complex reasoning tasks throughout the synthetic testing pipeline. This integration is responsible for interpreting raw user descriptions into structured data, synthesizing agent behavior logs into actionable UX reports, and analyzing source code to propose site optimizations.
By utilizing Claude's vision and extended thinking capabilities, the system moves beyond simple pattern matching to perform "aggressive inference," allowing it to fill gaps in persona profiles and understand the underlying reasons behind user friction. Sources: README.md:32-42, src/engine/interpreter.ts:161.
System Architecture and Model Usage
The project utilizes the @anthropic-ai/sdk to communicate with Claude. The primary model used across all modules is claude-sonnet-4-20250514, chosen for its balance of reasoning speed and capabilities, including vision-based website navigation via the Browser Use SDK. Sources: package.json:20, README.md:162-164.
The diagram shows how Claude is integrated into three distinct stages of the Abee pipeline: Persona Interpretation, Report Generation, and Code Analysis. Sources: src/engine/pipeline.ts, src/engine/optimizationLoop.ts.
Functional Modules
1. ICP Interpretation
The interpreter.ts module uses Claude to transform natural language or website URLs into a structured PersonaConfig. If a URL is provided, Claude first summarizes the website's content to infer the ideal customer profile (ICP). Sources: src/engine/interpreter.ts:50-101.
Key characteristics of this integration include:
- Aggressive Inference: Claude is instructed to infer missing traits (e.g., a "busy executive" implies high income and low patience) rather than using neutral defaults. Sources: src/engine/interpreter.ts:40-42.
- Strict Output Control: The system uses a comprehensive system prompt to ensure Claude returns only valid JSON matching a 19-trait schema. Sources: src/engine/interpreter.ts:16-36.
2. Report Generation and Synthesis
The reportGenerator.ts module aggregates raw event streams from browser agents—including URL visits, "confusion" flags, and "frustration" events—into a human-readable report. Sources: src/engine/reportGenerator.ts:108-115.
| Feature | Claude's Role | Description |
|---|---|---|
| Friction Analysis | Severity Ranking | Claude identifies specific URLs and ranks friction as Low, Medium, High, or Critical. |
| Persona Narratives | 1st-Person Perspective | Claude writes 2-3 sentence summaries of the agent's journey in that persona's "voice". |
| Recommendations | Actionable Strategy | Claude suggests specific UI/UX changes (e.g., "Add plain-language descriptions"). |
Sources: src/engine/reportGenerator.ts:15-32.
3. Code Failure Analysis
In the codeAnalyzer.ts module, Claude acts as a UX engineer. It receives the source code of the target website along with the narratives of failed personas to propose minimal, targeted code modifications. Sources: src/engine/codeAnalyzer.ts:18-20.
The sequence shows the validation loop used to ensure Claude's code proposals are technically applicable to the current source files. Sources: src/engine/codeAnalyzer.ts:122-137.
Implementation Details
JSON Enforcement and Validation
Because Claude is used to drive automated downstream logic (like the PopulationGenerator or CodeModifier), the system uses specific prompt engineering to ensure parseable JSON. Sources: src/engine/interpreter.ts:38, src/engine/codeAnalyzer.ts:32.
// Example of how Claude is called for code analysis
const response = await client.messages.create({
model: "claude-sonnet-4-20250514",
max_tokens: 4096,
system: CODE_ANALYSIS_SYSTEM_PROMPT,
messages: [{ role: "user", content: prompt }],
});
// Error handling includes regex-based JSON extraction if Claude includes preamble
let proposals = JSON.parse(block.text);
Sources: src/engine/codeAnalyzer.ts:106-120.
Prompt Structure
Prompts are dynamically constructed to provide Claude with maximum context while staying within token limits:
- Context Cap: Website text content is capped at 8,000 characters to avoid exceeding window limits during interpretation. Sources: src/engine/interpreter.ts:74.
- Friction Grouping: Failure data is grouped by "friction type" before being sent to Claude to help the model identify patterns across different personas. Sources: src/engine/codeAnalyzer.ts:50-60.
Summary
Claude AI integration is central to Abee's ability to automate the entire testing-to-optimization loop. By acting as a researcher, an analyst, and an engineer, Claude allows the system to not only identify where users struggle but also to understand the psychological "why" and generate the technical "how" for fixing it. Sources: README.md:12-28, plan.md:12-30.