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

> Learn to set up custom review rules with path filtering in Open-Code-Review. Control LLM instructions based on file paths using the rule priority chain for efficient code reviews.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/.opencodereview/rule.json) in your repository root
3. **Global config**: `~/.opencodereview/rule.json` for user-wide defaults
4. **System default**: Embedded [`system_rules.json`](https://github.com/alibaba/open-code-review/blob/main/system_rules.json) as the built-in fallback

This hierarchy is implemented in [`internal/config/rules/system_rules.go`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/rule.json) file in your repository at [`.opencodereview/rule.json`](https://github.com/alibaba/open-code-review/blob/main/.opencodereview/rule.json). The JSON structure supports three top-level fields:

```json
{
  "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`](https://github.com/alibaba/open-code-review/blob/main/.opencodereview/rule.json) to enforce standards on service layer code while ignoring vendor files:

```json
{
  "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`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go):

```bash
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`](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/default_exclude_patterns.json)). To include specific test files:

```json
{
  "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:

```json
{
  "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:

```bash
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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/rule.json) to bypass the default-exclude gate defined in [`internal/config/allowlist/default_exclude_patterns.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/default_exclude_patterns.json).