autobe system prompt

# Agent System Prompts ## Critical Importance System Prompt editing is **the most critical and sensitive task** in AutoBE development. System Prompts define AI agent behavior and directly determine generated code quality. Poor prompts cause compilation errors, logical bugs, and architectural inconsistencies. **Absolute Rule**: User instructions are absolute. If unclear, ask questions. If clear, execute exactly as specified. Never modify, reduce, or omit user commands based on your own judgment. **CRITICAL - Scope Limitation**: When user asks to edit system prompts, do ONLY the editing. Do NOT: - Run `pnpm run build:prompt` unless explicitly requested - Run `pnpm run build`, `pnpm run test`, or ANY other commands - Execute `git commit` or any git operations - Perform ANY actions beyond the editing itself The user will decide when to build, test, and commit. Your role is to edit ONLY. When editing System Prompts, you must: 1. **Completely** read and understand the target prompt file 2. Review related Orchestrator, Tool, and History code 3. Integrate changes naturally into the existing storyline 4. **STOP** after completing the edit - do not proceed with any other actions 5. Let the user decide whether to validate in actual pipeline ## Prompt Architecture AutoBE's System Prompts are hierarchically structured. ### Common Prompt `COMMON.md` defines the foundational identity shared by all agents. It begins with "You are an integral part of AutoBE" and explains the agent's role, principles, and architectural context. The Common Prompt provides **context**. It makes agents aware they are not operating alone, but as members of a team of 40+ agents. This helps agents understand that their output becomes input for other agents, maintaining consistent formats. The Common Prompt emphasizes **principles**. It codifies principles like Production-First, Compiler-Driven, and Single-Pass Excellence, ensuring agents maintain high quality standards. The message "you must produce perfect results in one attempt" encourages agents to work carefully. The Common Prompt handles **multilingualization**. Messages are localized according to user locale, but code and documentation are written in English. This maintains international compatibility and industry standards. ### Stage-Specific Prompts Each pipeline stage has specialized prompts: `ANALYZE_WRITE.md`, `DATABASE_SCHEMA.md`, `INTERFACE_OPERATION.md`, `TEST_WRITE.md`, `REALIZE_WRITE.md`, etc. Stage-Specific Prompts build upon the Common Prompt. They inherit general principles from Common and add stage-specific requirements. For example, `REALIZE_WRITE.md` includes specific instructions like "generate NestJS Controllers", "use Prisma for database access". Stage-Specific Prompts provide **rich examples**. They show examples of good code, bad code, and edge case handling. Since LLMs excel at few-shot learning, more examples improve output quality. Stage-Specific Prompts codify **conventions**. They precisely specify naming rules (PascalCase, camelCase), file structure, import order, and comment style. This ensures generated code maintains consistent style. ### Review and Correction Prompts Review and Correction tasks use special prompts: `ANALYZE_REVIEW.md`, `DATABASE_CORRECT.md`, `REALIZE_CORRECT.md`, etc. Review Prompts demand **critical thinking**. They include instructions like "don't just approve - actually find problems", "verify that requirements match implementation". This prevents Review Agents from becoming rubber stamps. Correction Prompts specialize in **compiler error interpretation**. They guide agents to understand TypeScript error messages, identify root causes, and fix with minimal changes. The principle is emphasized: "don't rewrite everything - fix only the error". Correction Prompts encourage **learning**. They promote analyzing error patterns to avoid repeating the same mistakes, maximizing compiler feedback to make accurate corrections. ## Prompt Design Principles Effective System Prompts follow these principles. ### Clarity and Specificity Prompts must be clear and specific. Ambiguous instructions produce inconsistent output. Instead of "write good code", say "generate a NestJS controller class with @Controller() decorator, where each method has HTTP method decorators like @Get(), @Post()". Specify numbers and constraints. Instead of "brief description", write "description under 200 characters". Instead of "some examples", write "3-5 examples". Clear constraints help the LLM understand expectations precisely. Prioritize positive directives. Instead of "don't do X", say "do Y". Negative commands are often missed by LLMs, but positive commands are more effective. For example, instead of "don't use `any` type", say "specify explicit types for all variables and parameters". ### Contextual Awareness Prompts must be designed with understanding of the context agents will receive. Since Realize Agents receive Prisma schema and OpenAPI documents, use expressions like "referring to the provided Prisma schema". Referencing non-existent context confuses agents. Collaborate with History Transformers. Design prompts so History Transformers provide the context structure the prompt expects. If the prompt expects a "Requirements Analysis Report" section, the History Transformer must generate a section with that exact name. Explain before-and-after context. Describe where the current task sits in the overall pipeline, what was completed in previous stages, and how the current output will be used in next stages. This helps agents understand their role precisely. ### Example-Driven Learning Good examples beat a thousand words of description. Include rich examples in prompts to help LLMs learn patterns. Show both normal cases and edge cases. Provide not just simple CRUD API examples, but also examples with complex relationships, conditional logic, and exception handling. Agents learn diverse scenarios and apply them to similar situations. Use Before/After examples. Show "don't do this" (Before) and "do this" (After) side by side. Clearly contrast the problems with bad code and the benefits of good code. Reference actual production code. Find good examples from AutoBE's own codebase and include them in prompts. Agents learn AutoBE's coding style and generate consistent code. ### Iterative Refinement Prompts cannot be perfect on first try. They must be refined iteratively. Collect user feedback. Identify problems that frequently appear in generated code and update prompts to prevent them. For example, if agents frequently use `any` type, emphasize "never use any type, always specify explicit types". Analyze error logs. When compilation errors or schema validation errors repeat, codify them in prompts. Add "common errors from previous versions" to prompts so agents avoid the same mistakes. Perform A/B testing. Quantitatively measure the impact of prompt changes. Use metrics like compilation success rate, retry count, and user satisfaction. Apply changes when improvement is confirmed, rollback when performance degrades. Maintain rigorous version control. When changing prompts, specify the reason and expected effect in commit messages. This enables easy rollback to previous versions if problems occur. ## Prompt Components Effective System Prompts consist of multiple components. ### Identity and Role Prompts clearly define agent identity. Declare roles like "You are a Requirements Analysis Specialist", "You are a NestJS API Implementation Expert". Agents recognize themselves as experts and apply domain best practices. Specify scope of responsibility. Clarify what to do and what not to do. Draw boundaries like "you are responsible only for API implementation, do not modify database schema". This prevents agents from overstepping their domain. Emphasize expertise. Set agent capability high with phrases like "You are a world-class expert", "You have decades of experience". Research shows assigning expert roles to LLMs improves output quality. ### Task Description Describe tasks concretely. Instead of "implement API endpoints", write in detail: "implement the given OpenAPI Operation as a NestJS Controller method, process business logic in the Service layer, and perform database access using Prisma". List steps. Break complex tasks into sequential steps. Guide the process like "1. Analyze OpenAPI Operation, 2. Define DTO types, 3. Write Controller method, 4. Implement Service logic, 5. Verify compilation". Specify output format. Precisely define JSON structure, file paths, naming rules. Write to match Function Calling schemas so agents output in correct format. ### Constraints and Requirements Specify constraints. List rules like "all types must be explicit", "any type prohibited", "all public methods require JSDoc comments". More constraints mean more consistent output quality. Distinguish required vs. optional requirements. Use "MUST", "SHOULD", "MAY" to indicate priority. Agents satisfy required requirements first, then apply optional ones when possible. Use negative commands when necessary. Explicitly list "things you must never do". Prevent critical mistakes like "never leave console.log in production code", "never include hardcoded passwords". ### Examples and Templates Provide rich code examples. Include diverse examples from simple to complex. Agents find similar patterns and apply them. Provide templates. Abstract recurring structures as templates and have agents fill in concrete values. For example, provide Controller class structure as a template and have agents populate methods. Show anti-patterns. Include "don't do this" examples so agents learn patterns to avoid. Highlight frequently occurring mistakes. ### Context References Specify context for agents to reference. Include instructions like "refer to the Prisma Schema below", "base on the provided Requirements Analysis Report". Describe context structure. Specify JSON paths, field meanings, value ranges. Help agents interpret context correctly. Establish context priority. When multiple contexts conflict, specify which takes precedence. For example, clearly state "OpenAPI specification is the source of truth, follow OpenAPI when there are discrepancies". ## Domain-Specific Guidelines Each domain requires special guidelines. ### Requirements Analysis Analyze agents transform natural language into structured documents. They clarify ambiguous requirements, infer missing parts, and organize into consistent format. Prompts provide analysis framework. Guide the sequence of actor identification, use case definition, and feature specification. Present questions to consider at each step. Encode domain knowledge. Include best practices for common web application patterns, authentication/authorization mechanisms, CRUD operations in prompts. Agents reference these to perform professional analysis. ### Database Schema Design Database agents design data models. They define table structure, relationships, indexes, and constraints, considering normalization and performance. Prompts emphasize data modeling principles. Explain normalization rules, relationship types (1:1, 1:N, N:M), and index strategies. Agents generate optimized schemas based on these. Provide Prisma-specific knowledge. Guide in detail on using `@relation` attributes, `@@unique` constraints, and `@@index` definitions. Ensure compliance with formats expected by Database Compiler. Handle edge cases. Provide guidance for complex scenarios like self-referential relationships, circular references, and composite foreign keys. Enable agents to handle difficult cases correctly. ### API Specification Interface agents generate OpenAPI documents. They define endpoint paths, HTTP methods, parameters, and response schemas. Prompts emphasize RESTful principles. Guide resource-centric design, semantic use of HTTP methods, and status code selection. Agents design APIs following REST best practices. Explain OpenAPI 3.0 spec in detail. Specify structures like `paths`, `components/schemas`, `security`, `tags`. Ensure agents generate valid OpenAPI documents. Emphasize alignment with Prisma schema. All fields referenced by APIs must actually exist in Prisma schema. Referencing non-existent fields causes errors in Realize stage. ### Test Generation Test agents write E2E test code. They generate Jest-based tests that actually call API endpoints for verification. Prompts guide test strategy. Explain Arrange-Act-Assert pattern and Given-When-Then structure. Emphasize that each test verifies only one scenario. Provide test data generation methods. Guide on inserting test data into actual database and cleaning up after tests. Maintain independence between tests. Emphasize edge case testing. Require testing not just normal cases, but also exceptional situations like invalid input, insufficient permissions, and missing resources. ### Implementation Realize agents write actual API implementation code. They generate NestJS Controller, Service, Repository and implement business logic. Prompts explain NestJS architecture. Guide Controller-Service-Repository layer separation, dependency injection, and decorator usage. Agents follow NestJS best practices. Explain Prisma usage in detail. Provide examples of using `prisma.model.findUnique()`, `create()`, `update()`, `delete()` methods. Cover relationship data loading (`include`, `select`). Maximize type safety. Require explicit types for all variables, parameters, and return values. Utilize Prisma-generated types to ensure type consistency between database and code. Make error handling mandatory. Require `try-catch` blocks, appropriate HTTP exception throwing (`NotFoundException`, `BadRequestException`), and clear error messages. ## Prompt Maintenance Prompts are living documents requiring continuous maintenance. ### Version Control All prompt changes are managed with Git. Commit messages specify reason for change and expected effect. Write concretely like "Fix: Resolve issue where Realize Agent frequently uses any type - add emphasis on explicit type specification". Correlate prompt versions with agent output quality. Track compilation success rate and retry count for code generated with specific prompt versions. When quality degradation is detected, identify the relevant commit and diagnose the problem. ### Testing Always test after prompt changes. Run actual pipeline to verify agents behave as expected. Test with multiple scenarios to detect regressions early. Build automated prompt tests. Verify that agent output is consistent for fixed inputs. Confirm that prompt changes didn't break existing functionality. ### Documentation Prompts themselves are documentation, but meta-documentation is also needed. Record each prompt's purpose, usage location, and dependencies separately. Enable new developers to understand quickly. Maintain prompt change history. Record chronologically when, why, and what changed. Understand prompt evolution process and reference for future changes. ### Performance Monitoring Quantitatively measure prompt effectiveness. Use metrics like compilation success rate, average retry count, LLM call time, and token usage. Measure impact of prompt changes through A/B testing. Compare output of previous prompt vs. new prompt for identical input. Apply when improvement is confirmed, rollback when degraded. Optimize prompt length. Too short means insufficient instructions, too long means LLM might miss the point. Find optimal length through experimentation. ## Common Pitfalls Common mistakes when writing prompts and their solutions. ### Ambiguity Ambiguous instructions produce inconsistent output. Avoid expressions like "appropriate", "if necessary", "when possible". Provide clear criteria and constraints. **Before**: "Add appropriate error handling" **After**: "Wrap all Prisma calls in try-catch blocks and throw appropriate NestJS HTTP exceptions on error. Use NotFoundException when data is missing, BadRequestException for invalid input" ### Over-Specification Excessively detailed instructions are also problematic. They limit LLM creativity and make prompts unnecessarily long. Specify only essential constraints and leave details to the LLM. **Before**: "Variable names use camelCase with first letter lowercase, second word onwards capitalize first letter, use meaningful names and..." **After**: "Name variables in camelCase with names that clearly convey meaning" ### Inconsistency Inconsistency between prompts creates conflicts between agents. Problems arise if Database Agent uses snake_case while Realize Agent uses camelCase. Maintain consistency across all prompts. Define common conventions in `COMMON.md` and have all Stage-Specific Prompts reference it. Changes in one place reflect across all agents. ### Neglecting Context Agents fail when context expected by prompts differs from actual provided context. When writing prompts, review History Transformers together and accurately understand provided context structure. If prompt says "refer to the Prisma Schema below", History Transformer must generate a section titled "Prisma Schema". Agents can't find context when they don't match. ### Ignoring Feedback Prompts don't improve when user feedback and error logs are ignored. Regularly collect feedback and resolve recurring problems through prompt improvements. Analyze error logs to find patterns. When specific types of compilation errors occur frequently, add preventive instructions to prompts. Include "common errors from previous versions" section in prompts. ## Best Practices Summary Core principles for effective System Prompts: 1. **Clarity**: Eliminate ambiguity and provide concrete criteria 2. **Context**: Accurately understand and reference context agents will receive 3. **Examples**: Use rich examples to help LLM learn patterns 4. **Constraints**: Specify required requirements and prohibitions 5. **Consistency**: Ensure all prompts follow the same conventions 6. **Iteration**: Collect feedback and continuously improve 7. **Testing**: Validate in actual pipeline after changes 8. **Documentation**: Record reasons for changes and effects Prompts are AutoBE's brain. Good prompts produce good code, bad prompts produce bad code. Design carefully, improve continuously, and always listen to user feedback.

# Agent Histories ## History Philosophy AutoBE agents need context to perform their tasks. This context is provided through message history - the sequence of messages sent to the LLM before the agent's actual task instruction. History is not just "previous conversation". It's carefully curated context that gives the agent exactly what it needs to succeed, nothing more, nothing less. Too little context and the agent lacks information. Too much context wastes tokens and dilutes important information. History Transformers are functions that construct optimal message histories for each agent. They analyze the current state, extract relevant information, and format it into clear messages. This is a critical optimization point - good history design dramatically improves output quality and reduces costs. ## History Transformation Each agent has a dedicated History Transformer function that builds its context. **Input**: Current AutoBE state (analysis results, Prisma schema, OpenAPI doc, test results, compilation diagnostics, etc.) **Output**: Array of messages in Claude API format (`{role: 'user' | 'assistant', content: string}`) **Location**: `packages/agent/src/orchestrate/*/histories/*` - colocated with orchestrators The transformer selects what information to include based on the agent's task. An agent generating Prisma schema needs the requirements analysis but doesn't need test results. An agent fixing TypeScript errors needs the code and error messages but doesn't need the original requirements. Transformers use intelligent filtering and summarization to keep context lean while preserving essential information. ## Message Types Histories consist of different message types, each serving a specific purpose. ### Context Messages Context messages provide background information that doesn't change across similar tasks. They're perfect for Prompt Caching. **Examples**: - Requirements analysis report - Prisma schema - OpenAPI specification - Project structure and conventions Context messages go early in history to maximize cache reuse. They're marked with `cache_control` to signal Claude to cache them. ### Task-Specific Messages Task-specific messages vary per task. They contain the specific input for this particular agent invocation. **Examples**: - "Generate implementation for the `getUser` operation" - "Fix the following TypeScript errors: ..." - "Review this analysis report for completeness" Task messages go after context messages. They're short and specific, building on the cached context. ### Example Messages Example messages show the agent "how to think" through concrete demonstrations. They're especially powerful for few-shot learning. **Pattern**: User provides example input, assistant provides example output. This shows the exact transformation the agent should perform. Example messages are included in context (for caching) since they don't change across tasks. The actual task message then follows the same pattern. ### Correction Feedback When an agent's output fails compilation or review, correction feedback explains what went wrong. **Contents**: - Compiler error messages - Diagnostic locations and severity - Suggested fixes - Previous attempt for reference Correction agents receive this feedback as their primary input. They analyze errors and produce fixes. ## Content Formatting History content is formatted for maximum clarity and LLM comprehension. ### Structured Sections Large content is divided into named sections with clear headers: ``` ## Requirements Analysis [analysis content] ## Prisma Schema [schema content] ## Your Task Generate API specifications based on the above. ``` Sections make content scannable. The LLM can quickly locate relevant information. ### Code Blocks All code is wrapped in markdown code blocks with language tags: ```` ```typescript function example() { return "code here"; } ``` ```` This improves LLM comprehension and output formatting. The LLM learns to format its own code output similarly. ### JSON Formatting Structured data is formatted as readable JSON with proper indentation: ```json { "entity": "User", "fields": [ {"name": "id", "type": "string"}, {"name": "email", "type": "string"} ] } ``` Pretty-printed JSON is easier for LLMs to parse and understand. ### Clarity Over Brevity Histories prioritize clarity over token conservation (up to a point). Clear explanations and well-formatted content help the LLM understand context accurately. However, irrelevant verbosity is removed. Don't include information the agent won't use. ## Optimization Strategies Effective history optimization balances context quality and token efficiency. ### Selective Inclusion Only include information the agent actually needs. Ask: "Will the agent use this to perform its task?" **Example**: Realize Write agent generating controller code needs: - ✅ OpenAPI operation specification - ✅ Prisma schema (to understand available data) - ✅ DTO type definitions - ❌ Original user requirements (too abstract) - ❌ Test code (not relevant to implementation) This keeps context focused and reduces token usage. ### Summarization Long documents are summarized to essential points. Full details are included only when necessary. **Example**: Requirements analysis might be 5000 tokens. For Prisma Schema generation, summarize to key entities and relationships (500 tokens). Include full details only if the agent needs them. Summarization is lossy but intentional. Include what matters for the task. ### Reference Instead of Repeat When the same information appears in multiple contexts, reference it instead of repeating. **Example**: If Prisma schema is cached, don't include it again in every message. The LLM retains context across messages. However, critical information is repeated if it ensures the agent doesn't miss it. ### Incremental Context For iterative tasks (like error correction), provide incremental context showing progression. **Example**: Correction agent receives: - Original code (context) - First error and fix attempt (context) - Current error (task) This shows the agent what's been tried and prevents repeating failed approaches. ## Prompt Caching Strategy Prompt Caching is critical for cost optimization in AutoBE. History design directly impacts cache effectiveness. ### Cache Block Design Cache blocks are ~1024 tokens. Structure history so stable content aligns with cache block boundaries. Messages sent with `cache_control: {type: "ephemeral"}` are cached. Subsequent requests with identical prefix reuse the cache. **Strategy**: 1. Put stable, reusable content first (requirements, schemas, examples) 2. Mark these messages for caching 3. Put task-specific content last (varies per request) This maximizes cache hits since the prefix is consistent. ### Cache Reuse Patterns **Sequential Pattern**: First task in a batch runs cold (no cache), establishing cache. Subsequent tasks reuse cache, running fast and cheap. AutoBE exploits this by processing similar tasks in batches. First Realize Write operation caches the Prisma schema and OpenAPI spec. Remaining operations reuse this cache. **Parallel Pattern**: Multiple concurrent tasks use the same cache if they share history prefix. All tasks benefit from caching immediately. However, parallel tasks must be careful not to invalidate each other's caches by varying the prefix. ### Cache Invalidation Cache is invalidated when the prefix changes even slightly. A single character difference breaks the cache. **Avoid**: - Timestamps in context - Random IDs or ordering - Conditional content that varies unpredictably **Maintain**: - Deterministic message ordering - Stable content formatting - Consistent schema representations ### Cache Monitoring Monitor cache hit rates to verify optimization effectiveness. Low hit rates indicate prefix instability. Metrics to track: - Cache hit rate percentage - Cache read tokens vs. new tokens - Cost savings from caching High cache hit rates (>80%) confirm good history design. ## Stage-Specific Patterns Different pipeline stages have characteristic history patterns. ### Analyze Stage Analyze agents receive user requirements as primary input. History is minimal: - System prompt with analysis framework - User requirements - Examples of good analysis No prior artifacts exist yet, so history is short. Cache benefit is small since requirements vary per project. ### Database Stage Database agents receive requirements analysis. History includes: - Requirements analysis (cached) - Data modeling principles and examples (cached) - Specific generation task (not cached) Cache reuse is high since analysis is the same for all schema generation tasks in a project. ### Interface Stage Interface agents receive both requirements and Prisma schema. History includes: - Requirements analysis (cached) - Prisma schema (cached) - API design principles and examples (cached) - Specific operation to implement (not cached) Heavy caching since multiple operations share the same context. ### Test Stage Test agents receive all prior artifacts. History includes: - Requirements summary (cached) - Prisma schema (cached) - OpenAPI specification (cached) - Testing guidelines and examples (cached) - Specific test to generate (not cached) Maximum cache reuse - test generation benefits heavily from caching. ### Realize Stage Realize agents receive complete context for implementation. History includes: - Prisma schema (cached) - OpenAPI operation (cached) - DTO types (cached) - Implementation guidelines and code examples (cached) - Specific file to generate (not cached) Realize stage processes dozens of files with shared context. Caching is critical for performance and cost. ### Correction Stages Correction agents receive error diagnostics. History includes: - Original artifact (context) - Error messages (task-specific) - Correction guidelines (cached if reused) Correction history is smaller since it focuses on specific errors rather than full project context. ## History Debugging When agent output is wrong, history is often the culprit. Debug systematically. ### Verify Context Availability Check that the agent receives all information it needs. Print the actual history and verify required context is present. **Symptom**: Agent produces generic/wrong output. **Diagnosis**: Missing context - agent is guessing instead of using facts. **Fix**: Update History Transformer to include missing information. ### Check Context Clarity Verify that context is formatted clearly and unambiguously. Is the Prisma schema valid? Are examples correct? **Symptom**: Agent output is confused or contradictory. **Diagnosis**: Ambiguous or incorrect context. **Fix**: Improve formatting, fix errors in context. ### Detect Context Overload Too much context dilutes important information. The LLM might miss key details buried in noise. **Symptom**: Agent ignores important constraints or makes basic mistakes. **Diagnosis**: Critical information lost in large context. **Fix**: Summarize or remove less important context. Put critical info near the end (recency bias). ### Alignment with Prompts History must align with System Prompts. If the prompt says "refer to the Prisma Schema below", the history must actually include a section titled "Prisma Schema". **Symptom**: Agent seems confused about task or context structure. **Diagnosis**: Prompt-history mismatch. **Fix**: Coordinate prompt and history transformer changes. ## Best Practices ### Provide What's Needed, Nothing More Include exactly what the agent needs. More context isn't always better - it can be worse. ### Format for Clarity Use headers, code blocks, and structure. Make content scannable and clear. ### Cache Aggressively Design history for maximum cache reuse. Stable prefix, consistent formatting. ### Test with Real Data Don't assume history is correct - test it. Run agents with the actual history and verify output quality. ### Iterate Based on Failures When agents fail, check if history can be improved. Add missing context, clarify ambiguities, provide better examples. ### Document History Logic Explain why each piece of context is included. Future maintainers need to understand the reasoning. --- History Transformers are unsung heroes of AutoBE. They quietly ensure agents have perfect context, enabling high-quality output with minimal cost. Invest time in history design - it's as important as prompt design.

# Agent System ## Agent Philosophy AutoBE's agent system employs 40+ specialized AI agents that collaborate to transform requirements into executable code. Each agent is specialized for a specific domain with clear responsibilities and interfaces. The core principle of agent design is **single responsibility**. Each agent performs one clear task. For example, Requirements Analyzer handles only requirement analysis, while Schema Generator handles only Prisma schema generation. This separation keeps each agent's System Prompt simple and makes testing and debugging easier. Agents generate structured output through **Function Calling**. Rather than generating free-form text, they output according to predefined JSON schemas. This eliminates the need for parsing and guarantees type safety. If the LLM generates output outside the schema, it's automatically retried. Agent communication happens through **events**. One agent's output becomes the next agent's input. For example, the analysis report generated by the Analyze agent is used as input for the Database agent, and the Prisma schema becomes input for the Interface agent. This pipeline structure creates clear data flow and enables independent testing of each stage. ## Agent Categories AutoBE's agents are categorized by function. **Planning Agents** handle plan creation. Scenario Agent determines which tasks to perform in what order. In the Analyze phase, it decides which documents to write; in the Interface phase, which APIs to generate; in the Test phase, which tests to write. Planning Agent output becomes the blueprint for subsequent agents. **Generation Agents** create code or documents. Write Agent writes actual code, and Document Agent writes analysis reports. They have very detailed System Prompts and precisely follow coding conventions, naming rules, and architecture patterns. Generated code must be immediately compilable, requiring high accuracy. **Review Agents** perform verification and improvement. Analyze Review Agent reviews written analysis reports and suggests improvements. Correct Agent analyzes and fixes compilation errors. Review Agents apply critical thinking - they actually find and solve problems rather than just approving. **Specialized Agents** perform domain-specific tasks. Authorization Agent designs authentication/authorization logic, and ERD Agent generates entity relationship diagrams. They encode domain expertise in their System Prompts and perform specialized tasks that general agents cannot. ## Agent Lifecycle Agent lifecycle follows clear stages. **Initialization** stage prepares context needed by the agent. System Prompt, Tool definitions, and History are constructed, and the LLM client is initialized. Cache keys for Prompt Caching are also set at this stage. **Execution** stage calls the LLM API to perform actual work. It requests structured output through Function Calling and receives responses via streaming. Progress events are emitted to provide real-time feedback to users. **Validation** stage verifies agent output. It checks if Function Calling responses match the schema and all required fields exist. For Generation Agents, generated code is validated with compilers. On validation failure, retry or invoke Correct Agent. **Completion** stage publishes results as events. Agent output is stored in state and becomes available for the next agent to reference. Completion events are sent to Frontend via WebSocket, updating the UI. Agents have **idempotency**. They should always generate identical output for identical input. While complete idempotency is impossible due to LLM non-determinism, System Prompt design and Temperature settings maintain maximum consistency. ## Context Management Agent performance heavily depends on context management. **History Transformation** is key to context optimization. Raw history is very long with much duplication, but History Transformer extracts and reconstructs only the core information needed by the agent. For example, Realize Agent needs only Prisma schema and OpenAPI document, so the requirement analysis process is omitted. **Prompt Caching Strategy** maximizes efficiency in repetitive tasks. When implementing 40 APIs in the Realize phase, Prisma schema and OpenAPI document are identical across all calls. These are placed as cacheable System Messages, with only API-specific content in User Messages. After the first call, cache hits dramatically reduce response time and cost. **Progressive Context Loading** loads only necessary information step by step. Initial Planning phase provides only requirement summary, while actual Generation phase provides detailed specifications. This prevents unnecessary token usage and helps the LLM focus on core information. **Context Window Management** handles ultra-large contexts. Claude 3.7 Sonnet supports 200K token context, but using it all is inefficient. Select only necessary information and leave the rest as references. For example, when implementing a specific API, provide only that OpenAPI Operation in detail, listing only paths and methods for other Operations. ## Error Handling Agents must handle various error situations. **LLM API Errors** occur due to network issues or rate limits. These transient errors are retried with exponential backoff strategy. Wait 1 second after first failure, 2 seconds after second failure, up to 3 retries maximum. Users are informed of progress even during retries. **Schema Validation Errors** occur when Function Calling responses don't match the schema. Missing required fields, type mismatches, invalid enum values are causes. In this case, feed back the error to the LLM and request regeneration. Add emphasis to System Prompt to "follow schema exactly" to prevent recurrence. **Compilation Errors** occur when generated code doesn't pass the compiler. Correct Agent intervenes to analyze compiler diagnostics and identify error location and cause. Generate corrected code and recompile. Most type errors are resolved in 1-2 iterations, with maximum retry count limited to prevent infinite loops. **Logical Errors** occur when code compiles but is logically incorrect. For example, referencing non-existent tables or setting up wrong relationships. These cannot be detected by compiler alone - Review Agent or Test Agent discovers them. When found, improve that agent's System Prompt to prevent similar errors. ## Agent Communication Patterns Agent communication follows clear patterns. **Sequential Pipeline** is the most basic pattern. Agent A's output becomes Agent B's input, and B's output becomes C's input. The Analyze → Database → Interface → Test → Realize pipeline follows this pattern. Each stage waits for the previous stage to complete and executes sequentially. **Parallel Fan-Out** is a pattern where multiple agents execute one plan in parallel. When 10 document writes are planned in Analyze phase, 10 Write Agents execute simultaneously. Each agent is independent and doesn't affect others' results. When all agents complete, proceed to next stage. **Iterative Refinement** is a pattern of receiving feedback and iteratively improving. When Write Agent generates code, Correct Agent validates, and if errors exist, feeds back to Write Agent. This loop continues until compilation succeeds, with quality gradually improving. **Hierarchical Delegation** is a pattern where upper agents delegate tasks to lower agents. Orchestrator manages overall flow and delegates actual work to specialized agents. For example, `orchestrateRealize` sequentially calls Authorization, Write, Correct agents and aggregates results. ## Agent Observability Tracking and debugging agent behavior is essential. **Event Logging** records all agent activities. Events like agent start, completion, error, retry are stored with timestamps. When issues occur, analyze event logs to identify which agent failed when. **Progress Tracking** shows progress of long-running tasks. When implementing 40 APIs in Realize phase, update progress info like "completed: 15 / total: 40" in real-time. Users can predict completion time and confirm the system hasn't frozen. **Performance Metrics** measure execution time and token usage for each agent. Identify which agents are bottlenecks and which stages consume many tokens to find optimization points. Can also quantitatively measure performance difference before and after applying Prompt Caching. **Error Analytics** analyzes recurring error patterns. If a specific agent fails frequently, there may be issues with System Prompt or Tool definitions. Track frequency by error type to prioritize and continuously improve the system. ## Agent Evolution The agent system continuously evolves. **Prompt Iteration** is the process of improving System Prompts. Analyze user feedback, error logs, and generated code quality to update prompts. Make unclear instructions specific and add rules to prevent frequently occurring mistakes. Prompt changes are version controlled and improvement effects are validated through A/B testing. **Tool Enhancement** is the process of improving Function Calling tools. Add new fields, define schemas more clearly, or add examples. If agents frequently output incorrect formats, strengthen schema constraints or add additional explanations to prompts. **Architecture Refactoring** is the process of improving agent structure. If one agent has too many responsibilities, split into two; conversely, if too fragmented, consolidate. When new features are added, place agents in appropriate locations and integrate with existing pipeline. **Performance Optimization** is the process of optimizing execution time and cost. Remove unnecessary context, expand Prompt Caching application, and find parallelizable parts for improvement. Use profiling to identify bottlenecks and focus on the most effective optimization points.