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
- Open Settings → Review.
- In Review Instructions, select an accessible repository.
- Edit the supported guidance in the visual editor or YAML view.
- Choose Save Instructions and check the success or validation message.
- 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:
.codity/review-instructions.yaml.codity/review-instructions.yml.github/codity-instructions.yaml.github/copilot-instructions.mdreview-instructions.yamlCLAUDE.md.claude/CLAUDE.md.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. |

