Custom Review Instructions

Customize how Codity reviews your code by providing custom instructions that guide the review process. You can define what to focus on, what to skip, and how you want feedback delivered.

Overview

Custom review instructions allow you to:

Set priority areas: Tell Codity what matters most to your team
Skip low-value feedback: Avoid comments on issues already handled by CI or that aren't relevant
Configure confidence thresholds: Only see feedback you trust
Provide project context: Help Codity understand your codebase
Define response format: Control how feedback is presented

How It Works

Custom instructions are loaded in the following priority order:

Dashboard configuration (highest priority) - Settings configured via Codity dashboard
Repository file - Instructions in your repository (.codity/review-instructions.yaml)
Default instructions (fallback) - Codity's default review behavior

Configuration Methods

Method 1: Dashboard Configuration (Recommended)

Configure custom instructions directly in the Codity dashboard for maximum flexibility.

Steps:

Navigate to Repositories in Codity dashboard
Select your repository
Click Settings → Custom Instructions
Enter your custom instructions in YAML format
Click Save

Benefits:

Easy to update without code changes
Immediate effect on new reviews
No need to modify repository
Centralized management across branches

Method 2: Repository File

Store instructions in your repository to version control them alongside your code.

Supported file locations (checked in order):

.codity/review-instructions.yaml
.codity/review-instructions.yml
.github/codity-instructions.yaml
.github/copilot-instructions.md (Markdown format)
review-instructions.yaml (root directory)

Benefits:

Version controlled with your code
Easy to review changes via PRs
Shared across all users
Works offline in repo history

Instruction Format

Custom instructions are written in YAML format with the following structure:

# Confidence threshold (0-100)
# Only show feedback with confidence >= this value
confidence_threshold: 30

# Categories to skip (issues you don't want to see)
skip_categories:
  - "style"
  - "formatting"
  - "minor optimizations"
  - "trivial suggestions"

# Priority areas (what you DO want to see)
priority_areas:
  Security:
    - "SQL injection vulnerabilities"
    - "Authentication bypass"
    - "Sensitive data exposure"
  Performance:
    - "N+1 database queries"
    - "Inefficient algorithms"
    - "Memory leaks"
  Business Logic:
    - "Edge case handling"
    - "Error handling"
    - "Data validation"

# Project-specific context
project_context:
  description: "E-commerce platform with microservices architecture"
  key_files:
    - "src/payment/processor.py - handles all payment transactions"
    - "src/auth/jwt.py - JWT token validation"
  coding_standards: "Follow PEP 8 for Python, ESLint for JavaScript"

# Response format preferences
response_format:
  style: "concise"
  include_examples: true
  include_references: true
  max_suggestions_per_file: 5

# Review philosophy
review_philosophy:
  focus: "Security, correctness, and maintainability over style"
  confidence_policy: "Only show feedback we're >80% confident about"
  tone: "Constructive and educational"

Configuration Options

Confidence Threshold

Set the minimum confidence level for feedback (0-100).

confidence_threshold: 30

Common values:

70 - Very conservative, only highest confidence issues
40 - Balanced (default)
10 - More permissive, catches more potential issues

Skip Categories

Tell Codity what types of feedback to skip.

skip_categories:
  - "style"                    # Code style issues
  - "formatting"               # Whitespace, indentation
  - "minor optimizations"      # Micro-optimizations
  - "naming conventions"       # Variable naming
  - "comment suggestions"      # Documentation suggestions
  - "trivial suggestions"      # Low-impact changes

File-specific skipping:

skip_categories:
  - "ruby files"      # Skip all Ruby files
  - "javascript"      # Skip all JavaScript files
  - ".go"             # Skip all Go files

Why skip categories?

CI already handles these (linting, formatting)
Low value for your team
Too noisy or distracting
Not relevant to your tech stack

Priority Areas

Define what you want Codity to actively look for.

priority_areas:
  Security:
    - "SQL injection in database queries"
    - "XSS vulnerabilities in templates"
    - "Hardcoded secrets or API keys"
    - "Insecure authentication logic"

  Performance:
    - "N+1 query problems"
    - "Inefficient loops or algorithms"
    - "Missing database indexes"
    - "Memory leaks"

  Data Integrity:
    - "Missing input validation"
    - "Incorrect data transformations"
    - "Race conditions"

  Error Handling:
    - "Unhandled exceptions"
    - "Missing error logging"
    - "Silent failures"

Important: Priority areas are actively checked, Codity will explicitly look for these patterns in every review.

Project Context

Provide background information about your project.

project_context:
  description: "Real-time analytics platform using Kafka and PostgreSQL"

  architecture: "Microservices with event-driven communication"

  key_services:
    - "ingestion-service: Receives and validates incoming events"
    - "analytics-service: Processes and aggregates data"
    - "api-service: Serves dashboard queries"

  critical_files:
    - "src/streaming/kafka_consumer.py - Must be thread-safe"
    - "src/core/aggregator.py - Performance critical"

  coding_standards:
    - "PEP 8 for Python"
    - "Use type hints everywhere"
    - "Maximum function length: 50 lines"

  security_requirements:
    - "All user input must be validated"
    - "SQL queries must use parameterization"
    - "Authentication required for all API endpoints"

Response Format

Control how Codity presents feedback.

response_format:
  style: "concise"                    # "concise" or "detailed"
  include_examples: true              # Show code examples
  include_references: true            # Link to docs/standards
  max_suggestions_per_file: 5         # Limit feedback per file
  prioritize_critical: true           # Show critical issues first
  group_by_category: true             # Group similar issues

Review Philosophy

Set the overall approach to code review.

review_philosophy:
  focus: "Security and correctness over style"

  confidence_policy: "Only show issues we're >80% confident about"

  tone: "Constructive and educational, not critical"

  priorities:
    - "1. Security vulnerabilities"
    - "2. Correctness and bugs"
    - "3. Performance issues"
    - "4. Maintainability"

  avoid:
    - "Style nitpicking"
    - "Personal preferences"
    - "Bikeshedding"

Updating Instructions

Via Dashboard

Go to Repositories → Settings → Custom Instructions
Modify the YAML configuration
Click Save

Via Repository File

Create/edit .codity/review-instructions.yaml
Commit and push changes
Open a new PR to test
Instructions apply to that PR and future PRs

Note: Dashboard instructions override repository file instructions.

Precedence Rules

When multiple instruction sources exist:

Dashboard Instructions (Priority 1)
    ↓ (overrides)
Repository File (Priority 2)
    ↓ (overrides)
Default Instructions (Priority 3)

Testing Your Instructions

Verify Instructions Are Loaded

Look for these indicators in review comments:

✅ Custom review instructions loaded
Source: Dashboard

Additional Resources

Auto Review Configuration - Enable/disable reviews
Security Scanning - Security scan features
Organizations and Teams - Org settings
YAML Syntax: https://yaml.org/