Custom Review Instructions

Give the reviewer repository-specific context, priorities and response preferences. These instructions guide reviews; they do not change provider permissions or guarantee detection of every issue.

Overview

Use Settings → Review → Review Instructions. Select the repository, enable its instructions and choose the visual editor or YAML view. Save using Save Instructions. The repository picker follows your current account and team scope.

How It Works

Codity loads dashboard instructions first, then supported repository instruction files, then defaults. Dashboard configuration takes precedence over a repository instruction file. Path Rules use their own additive behavior instead.

Configuration Methods

Dashboard Configuration

  1. Open Settings → Review.
  2. In Review Instructions, select an accessible repository.
  3. Edit the supported guidance in the visual editor or YAML view.
  4. Choose Save Instructions and check the success or validation message.
  5. Run an eligible review to check the resulting guidance.

The visual editor covers skip categories, priority areas and review philosophy. For additional fields such as project_context or a structured response_format, edit and save in YAML view. Switching back to visual editing and saving rebuilds the configuration from its supported controls, so additional YAML fields may be dropped. Keep a copy of your YAML and inspect the saved content after changing editor modes.

Repository File

The loader checks these repository files in order:

  1. .codity/review-instructions.yaml
  2. .codity/review-instructions.yml
  3. .github/codity-instructions.yaml
  4. .github/copilot-instructions.md
  5. review-instructions.yaml
  6. CLAUDE.md
  7. .claude/CLAUDE.md
  8. .cursorrules

YAML and Markdown instruction files are interpreted according to their format. The CLAUDE.md and .cursorrules locations supply project context rather than structured review options. For a structured configuration, prefer .codity/review-instructions.yaml.

Use a repository file when the team wants to review instruction changes alongside code. Use dashboard configuration when you need to update guidance without a repository commit. A saved dashboard override can take precedence over the repository file, so choose the source your team intends to maintain.

Instruction Format

For example, the dashboard YAML can express:

skip_categories:
  - style
  - formatting
priority_areas:
  - category: Security
    items:
      - Authentication bypasses
      - Unsafe query construction
project_context:
  description: Billing service; monetary values use integer minor units
response_format:
  style: concise
review_philosophy: Prioritize production correctness and security

The current platform removes the old confidence_threshold field, and the worker ignores it. Do not use legacy examples that promise a user-configured confidence cutoff.

Configuration Options

Use skip categories for low-value suggestions, priority areas for important failure classes, project context for domain assumptions, and response/philosophy fields for guidance. Keep credentials and private operational secrets out of instructions.

The following examples show individual sections. Combine the sections you need into one YAML document; avoid repeating a top-level key.

Skip Categories

Use categories to reduce feedback already handled by other tools:

skip_categories:
  - style
  - formatting

These entries guide review feedback and participate in category/description filtering. They are not a general file-glob exclusion mechanism. For example, excluding generated/** belongs in Path Rules. Path Rules also explains which review outputs exclusions affect; independent scan pipelines have their own configuration.

Priority Areas

Describe concrete failure modes that matter to your application:

priority_areas:
  - category: Security
    items:
      - Every tenant-scoped query must constrain results to the active tenant
      - Authorization must run before reading or changing another user's records
  - category: Data integrity
    items:
      - Retried payment webhooks must not create duplicate credits
      - A failed transaction must not leave a partially updated balance

The reviewer receives these areas as explicit guidance. They help focus the analysis, but do not guarantee that every matching defect will be found. The YAML loader also accepts a mapping of category names to item lists; the example above follows the dashboard's list-based form.

Project Context

Explain assumptions the reviewer cannot reliably infer from a diff:

project_context:
  description: Multi-tenant billing API using PostgreSQL
  architecture: API handlers delegate balance changes to transactional services
  critical_files:
    - src/billing/ledger.ts records immutable balance movements
    - src/auth/tenant.ts resolves the authorized tenant
  coding_standards:
    - Monetary amounts use integer minor units
    - Store timestamps in UTC
  security_requirements:
    - Every ledger read is scoped to an authorized account

Use real paths and current architectural facts. Context is supplied to the model as guidance; writing an invariant here does not install a runtime check or change the application's permissions.

Response Format

Describe how findings should be explained:

response_format:
  style: concise
  include_examples: true
  include_references: true

These preferences become prompt guidance. They do not enforce an exact finding count, word limit or output schema. To select consolidated PR-level findings instead of the usual inline presentation, configure Concise Mode.

Review Philosophy

State the tradeoffs and tone the team expects:

review_philosophy:
  focus: Production correctness, security and recoverability
  tone: Explain the failing scenario and suggest a practical correction
  avoid:
    - Repeating formatting feedback already covered by CI
    - Requesting broad refactors without a concrete defect

Use this field for review priorities. A statement about confidence in prose does not create a numeric confidence filter; the removed confidence_threshold setting is not supported.

Updating Instructions

Update the selected repository's configuration and save. Check which repository is selected before editing. Repository-file changes apply through the repository content read by the review; saving a dashboard setting is not itself proof a new review completed.

Precedence Rules

Dashboard instructions take priority over a supported repository file, which takes priority over defaults. Path Rules are separate and can combine dashboard and repository rules.

Testing Your Instructions

Run a controlled review and inspect its actual output. If guidance appears absent, check repository selection, enabled state, saved YAML and any higher-priority dashboard configuration. There is no requirement that every review prints a fixed “instructions loaded” confirmation.

For example, add a tenant-isolation priority, save it, and request a review of an authorized test change that reads tenant-owned data. Inspect whether the findings address the actual access boundary. A review with no findings alone cannot prove that instructions were ignored or that the code is correct.

Troubleshooting

Symptom What to check
YAML will not save Fix the reported syntax/validation error. Use consistent indentation, lists for skip categories and category/item entries for priority areas.
Repository-file edits seem ineffective Check for a saved dashboard override and whether an earlier supported file is taking precedence. Verify that the reviewed revision contains your edit.
Guidance applies to the wrong repository Confirm the active account/team and the repository selected in Review Instructions before saving.
Files are still present in the review Use Path Rules for path exclusions; a skip category is not a general path filter.
Output is still inline Review response preferences and the separate Concise mode setting.

Additional Resources