Home Optibot Config Crafting effective optibot guidelines

Crafting effective optibot guidelines

Last updated on Dec 09, 2025

What are optibot guideline files?

Optibot guidelines are context-engineering documents that enhance your agentic code reviews for your team. Our sweet spot target for the length of the file is between 1200-2,200 words. We suggest prioritizing high-signal rules over comprehensive coverage, and structure content for optimal performance of your optibot agent. Think "high-impact heuristics" rather than a "complete rulebook."

How guideline files contribute to Optibots context budget:

Optibot uses AI models with large context windows for its code reviews. The default optimization for optibot is to use its context budget on collecting code context and reading files. While theres no limit to how long an optibot guideline file can be, during our evals and research we tend to see a degradation in attention as guideline files get longer. This is typical across models as it tends to cloud the judgement of the model and its effective use of its thinking budgets.

The Attention Budget Problem

LLMs operate with an "attention budget" similar to human working memory. To put things into perpsective, theres limited context you can hold on to when carrying out a code review. Even if multiple agents are involved, the pass through of information across expert reviewers can result in the following deficiencies:

  • Context rot: Accuracy decreases as context length increases

  • n² complexity: Transformers create pairwise relationships between tokens—more tokens means thinner attention spread across all information

  • Diminishing returns: Every additional token competes for the model's limited attention

In Optibot your guidelines compete with: patch content, file context, conversation history, system prompts, and tool outputs. Therefore we highly recommend that every token counts.

The Goldilocks Zone: Right-Sizing Your Guidelines

Too Short (<200 words)

  • Vague guidance. For example "Write clean rails code"

  • Lacks project-specific context

  • Forces model to rely on generic patterns

  • Misses critical architectural decisions

Too Long (>3,000 words)

  • Dilutes high-priority rules with noise

  • Creates context rot—critical rules get lost

  • Repeats and enforces obvious patterns models already know

  • Wastes thinking budget on redundant info

Just Right (1,200-2,200 words)

  • Clear, enforceable heuristics

  • Project-specific architectural patterns. Highly enforceable shared values amongst internal engineering teams.

  • Prioritized by impact (security > style). For example inserting linting guidelines in the reviewer vs running the linter in a check suite

  • Focuses on what's unique to your codebase

  • Highly useful when tackling infrastructure as code, microservices or external patterns not present in the repo itself.

Rule of thumb: If your guideline would apply to 90% of projects, optibot probably knows it already. Focus on what makes your codebase unique.

What to Include: High-Signal Rules

1. Architecture-Specific Patterns (Highest Priority)

Define patterns unique to your system architecture. Highly specific, enforceable, this is proven to prevent actual bugs in your architecture based on our evals and testing. Here are some commonly seen examples across our customer base.

Example for a microservices architecture:

### Service Communication**
- All inter-service calls MUST use the message queue, not direct HTTP
- Service responses must include correlation IDs for tracing
- Timeout all external service calls at 5 seconds with a circuit breaker pattern

Example for a monolithic application:

### Database Transaction Pattern**
- Always use transaction wrappers for multi-table operations
- Never instantiate database connections directly—use the connection pool
- All data access must go through the repository layer

2. Security & Compliance Requirements

Non-negotiable rules with concrete criteria that pertain to internal security practices. Optibot already enforces its own high security policies based on the OWASP 10 out of the box. We suggest adding any standards outside of that in your guidelines file.

### Multi-Tenant Data Isolation
- All database queries MUST include tenant_id in WHERE clause
- Cross-tenant data access requires explicit audit logging
- Admin operations must validate tenant context before execution
- Data exports must be scoped to single tenant with verification step

### PCI Compliance for Payment Data
- Payment card data never stored in application database
- Tokenized references only—tokens must expire after 15 minutes
- All payment processing logs must exclude card details (mask to last 4 digits)
- Failed payment attempts trigger security review after 3 failures

3. Technology-Stack Conventions

Any specific rules that are unique to your tools and frameworks. We highly recommend setting this up if you use internal packages, forked and unsupported libraries that you self maintain or even large utility and helpers that are a core part of your tech stack.

Example for a typed language (TypeScript, Java, C#):

###Types Management
- Place shared type definitions in `/types` or `/models` folder
- Local types stay in the same file where used
- Avoid using `any` or equivalent—prefer strongly typed alternatives
- Enable strict type checking in your configuration

Example for error handling:

### Error Handling Pattern**
- All exceptions must extend our custom ApplicationError base class
- Include error codes for client categorization (AUTH_001, VAL_002, etc.)
- Never expose internal error details to clients—use sanitized messages
- Log full error context server-side for debugging

4. Domain-Specific Logic

These include business rules or domain constraints unique to your application that are not clearly defined in code. This means that within your repo there's no presence of either a data structure, logical readable code optibot can access pertaining to these practices.

This can include requirements of how you conduct business, standardized compliance in your industry or a unique enforcement of processes that need to be represented in code.

Example for a fintech application:

### Transaction Processing Rules
- All financial transactions must be idempotent with unique transaction IDs
- Account balance updates require pessimistic locking to prevent race conditions
- Transactions over $10,000 must trigger AML (Anti-Money Laundering) review workflow
- Failed transactions must maintain full audit trail for regulatory compliance
- Currency conversions must use rates locked at transaction initiation time

### Ledger Integrity
- Double-entry bookkeeping: every debit must have corresponding credit
- Account balances must be calculated from ledger entries, never cached
- Ledger entries are immutable—corrections require new offsetting entries

Example for a healthcare tech system:

### HIPAA Compliance for PHI (Protected Health Information)
- Patient data access must be logged with user ID, timestamp, and reason
- PHI cannot be transmitted without end-to-end encryption (TLS 1.3+)
- All patient records require explicit consent flags before sharing
- Data retention: medical records must be retained for minimum 7 years
- De-identification must remove 18 HIPAA identifiers before using data in analytics

### Clinical Data Validation
- Lab results outside normal ranges must flag for physician review
- Prescription dosages must validate against patient weight and age
- Drug interaction checks required before prescription confirmation
- Allergy checks mandatory before any medication-related operations

What to Exclude: Low-Signal Noise

Optibot already knows alot about generic best practices across different languages and thousands of libraries and frameworks. Its best to avoid reiterating on these in your guideline files. Here are some clear don'ts.

Skip Generic Best Practices and Linting Rules

  • "Use descriptive variable names"

  • "Add comments to complex code"

  • "Write unit tests for business logic"

  • "Use 2 spaces for indentation"

  • "Maximum line length 100 characters"

  • "Add trailing commas in multi-line objects"

Skip Language Basics

  • "Use async/await for asynchronous code"

  • "Avoid deprecated language features"

  • "Close database connections after use"

  • "Handle exceptions properly"

Avoidable Anti-patterns like Meta-Instructions for the AI. Avoid directing the AI's behavior:

  • "Pay special attention to..."

  • "Always check for..."

  • "Remember to consider..."

Structure for Optibot guidelines : optimizing for best results

Structure your guidelines with the most critical rules first. This signals priority and ensures reviewers (both human and AI) immediately understand what matters most to your team. Leading with high-impact rules sets the tone for the entire document.

Recommended Document Structure

# [Your Project Name] Coding Guidelines**

## Critical Architectural Rules
[Top 5-10 most important, non-negotiable patterns]

## Security & Compliance
[Security requirements, auth patterns, data protection]

## Technology Stack Patterns
[How you use your specific frameworks and tools]

## API Design Conventions
[REST patterns, error handling, response formats]

## Domain-Specific Logic
[Business rules unique to your domain]

Writing Style: Be Specific and Actionable

Your guidelines should be concrete enough to catch real issues, but flexible enough to handle legitimate edge cases. This means avoiding both vague language and rigid language. In our tests optibot caught more production issues when optibot's guidelines followed verbiage that was more action based.

❌ Language that results in degraded results and noisier reviews:

Vague Language - covering what models already know

### Code Quality
- Write clean, maintainable code
- Follow best practices
- Ensure proper error handling

Rigid Language - brittle rules with endless exceptions. Optibot will struggle with edge cases you didn't anticipate.

- If a service needs database access, inject DatabaseService in the constructor
- If it needs HTTP calls, inject HttpClient in the constructor
- If it needs both, inject both in the constructor
- Never inject more than 5 dependencies
- If you need more than 5, create a facade service
- Unless it's a utility service, then inject directly
- Except for background jobs, which should use service locator pattern...

✅ Language that resulted in higher code quality and code hygiene

Best Practice is to be specific and Flexible - back your guidelines with code examples or mention internal patterns

### Service Dependencies (Dependency Injection Required)**
- All external dependencies (database, HTTP, cache) must be injected via constructor
- Avoid direct instantiation of services—makes testing impossible
- More than 4-5 dependencies suggests the service has too many responsibilities

### Multi-Tenant Database Queries**
- Every query touching user/customer data MUST filter by tenant_id
- Cross-tenant operations require explicit admin authorization check
- Example violation: `SELECT * FROM orders WHERE user_id = ?` (missing tenant_id)