How to Set Up Custom Review Rules with Path Filtering in Open-Code-Review

Open-Code-Review uses a four-layer priority chain to load rule files, where the first matching glob pattern in an ordered rules array determines which LLM instructions apply to each file.

The Open-Code-Review (OCR) tool from Alibaba enables fine-grained control over AI code reviews through JSON-based rule files. By configuring rule.json files with path filtering, you can specify exactly which review instructions apply to specific files, directories, or file types across your repository.

Understanding the Rule File Hierarchy

OCR resolves rules through a strict priority chain, loading configuration from highest to lowest precedence:

1. CLI flag: --rule <path> overrides all other sources
2. Project config: .opencodereview/rule.json in your repository root
3. Global config: ~/.opencodereview/rule.json for user-wide defaults
4. System default: Embedded system_rules.json as the built-in fallback

This hierarchy is implemented in internal/config/rules/system_rules.go, where the loadProjectRule and loadGlobalRule functions merge configurations according to this precedence order.

Creating Your First rule.json

Place a rule.json file in your repository at .opencodereview/rule.json. The JSON structure supports three top-level fields:

{
  "include": ["src/**/*.go", "src/**/*.{ts,tsx}"],
  "exclude": ["**/*.test.ts", "**/generated/**"],
  "rules": [
    {
      "path": "src/api/**/*.go",
      "rule": "All exported handlers must validate request bodies before use."
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Check SQL for injection risks, parameter errors, and missing closing tags."
    }
  ]
}

• include: Optional glob patterns that bypass the default exclude list. Files matching here are retained even if they match typical test file patterns.
• exclude: Optional glob patterns that always filter out matching files, taking precedence within the filtering stage.
• rules: An ordered array of objects containing path (glob pattern) and rule (LLM instructions). The first matching path determines the rule text for that file.

Path Filtering and Glob Pattern Matching

Before rules are applied, each file passes through a five-gate filter: binary check → exclude patterns → include patterns → extension validation → default-exclude patterns. Only files surviving this filter are matched against your custom rules.

OCR uses the Go library bmatcuk/doublestar/v4 for glob matching, supporting these patterns:

• * – Match any sequence of characters within a single directory
• ** – Match across directory boundaries (recursive)
• ? – Match any single character
• [abc] – Match character classes
• {ts,tsx} – Brace expansion for multiple patterns

All matching is case-insensitive and evaluated relative to the repository root.

Practical Configuration Examples

Targeting Specific Directories

Create .opencodereview/rule.json to enforce standards on service layer code while ignoring vendor files:

{
  "include": ["src/**/*.go"],
  "exclude": ["**/vendor/**", "**/*.test.go"],
  "rules": [
    {
      "path": "src/service/**/*.go",
      "rule": "All exported functions must have proper error handling."
    },
    {
      "path": "**/*handler*.go",
      "rule": "Handlers must validate incoming JSON payloads."
    }
  ]
}

Overriding Rules via CLI

For temporary or experimental rules, use the --rule flag defined in cmd/opencodereview/review_cmd.go:

ocr review --rule /tmp/emergency-rules.json .

This completely overrides project and global configurations for the current run.

Reviewing Test Files Explicitly

By default, OCR excludes test files (defined in internal/config/allowlist/default_exclude_patterns.json). To include specific test files:

{
  "include": ["tests/integration/**/*.test.ts"],
  "exclude": [],
  "rules": [
    {
      "path": "tests/integration/**/*.test.ts",
      "rule": "Integration tests must not contain production secrets."
    }
  ]
}

The include pattern short-circuits the default-exclude gate, allowing rules to apply to normally excluded test files.

Multi-Language Projects with Brace Expansion

Use brace expansion to target multiple file extensions with a single rule:

{
  "rules": [
    {
      "path": "src/**/*.{js,jsx,ts,tsx}",
      "rule": "All UI components must have an associated Storybook entry."
    }
  ]
}

Inspecting and Debugging Rules

Verify which rule applies to a specific file using the diagnostic command:

ocr rules check src/main/java/com/example/UserService.java

This outputs the source layer (project/global/system), the matching glob pattern, and the full rule text that would be sent to the LLM.

The loading logic and merging behavior are validated in internal/config/rules/system_rules_test.go, which handles malformed JSON and precedence edge cases.

Summary

• OCR loads rules through a four-layer priority chain: CLI flag → Project → Global → System
• Rule files use bmatcuk/doublestar/v4 for case-insensitive glob matching with *, **, and brace expansion support
• The include field overrides default exclusions (like test files), while exclude filters files before rule matching
• Rules are evaluated in array order, with the first matching path determining the LLM instructions
• Use ocr rules check <file> to debug which rule applies to specific paths

Frequently Asked Questions

What happens if multiple rule patterns match the same file?

Only the first matching rule in the rules array is applied. OCR evaluates entries sequentially from index 0, so order your rules from most specific to most general.

Can I use absolute paths in my rule.json file?

No. All paths in rule.json are evaluated relative to the repository root. The system normalizes paths to lower-case before matching against your glob patterns.

How do I temporarily disable project rules for a single review?

Pass the --rule flag pointing to a custom JSON file. According to the CLI implementation in cmd/opencodereview/review_cmd.go, this flag overrides both project and global configurations, using only the specified file for that execution.

Why are my test files not being reviewed despite having a rule?

OCR applies a five-gate filter that includes default exclusions for test files. You must explicitly add test file patterns to the include array in your rule.json to bypass the default-exclude gate defined in internal/config/allowlist/default_exclude_patterns.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}