> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qodo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

Best Practices lets Qodo learn from accepted code suggestions and continuously adapt to your team's coding patterns.

## Auto best practices

<Badge color="outline-provider" size="sm" shape="pill" icon="github">GitHub</Badge>

<Note>
  You must [enable a wiki](/code-review/get-started/configuration-overview/enable-a-repository-wiki-for-configuration) to use this feature.
</Note>

Auto best practices is a Qodo capability that:

1. Identifies recurring patterns from accepted suggestions.
2. Automatically generates a [best practices page](https://github.com/qodo-ai/pr-agent/wiki/.pr_agent_auto_best_practices) based on what your team consistently values.
3. Applies these learned patterns to future code reviews.

This creates an automatic feedback loop where the system continuously learns from your team's choices to provide increasingly relevant suggestions.

### How to enable auto best practices

To enable auto best practices, add the following to your [configuration file](/code-review/get-started/configuration-overview/configuration-file):

```bash theme={null}
[auto_best_practices]
# Disable all auto best practices usage or generation
enable_auto_best_practices = true

# Disable usage of auto best practices file in the 'improve' tool
utilize_auto_best_practices = true

# Extra instructions to the auto best practices generation prompt
extra_instructions = ""

# Max number of patterns to be detected
max_patterns = 5
```

## Custom best practices

<Badge color="outline-provider" size="sm" shape="pill" icon="github">GitHub</Badge>
<Badge color="outline-provider" size="sm" shape="pill" icon="gitlab">GitLab</Badge>
<Badge color="outline-provider" size="sm" shape="pill" icon="bitbucket">Bitbucket</Badge>

Custom best practices allow you to define coding standards specific to your repository.

### Local best practices file

Create a `best_practices.md` file in your repository's root directory containing your coding standards and guidelines.

Qodo will use this file as a reference during code review.

If PR code violates these guidelines, Qodo will generate additional suggestions labeled: `Organization best practice`

### Writing effective best practices files

The following guidelines apply to all best practices files:

* Write clearly and concisely.
* Include brief code examples when helpful (before/after patterns).
* Focus on project-specific guidelines that result in relevant suggestions.
* Keep files relatively short (under \~800 lines), since:
  * AI models may not process very long documents effectively.
  * Long files often include generic guidance already known to AI.
* Use a pattern-based structure rather than simple bullet points.

### Example `best_practices.md`

#### Error handling

You can create a `best_practices.md` file in your repository root with content such as:

```bash theme={null}
Add proper error handling with try-except blocks around external function calls.
```

Before:

```bash theme={null}
# Some code that might raise an exception
return process_pr_data(data)
```

After:

```bash theme={null}
try:
    # Some code that might raise an exception
    return process_pr_data(data)
except Exception as e:
    logger.exception("Failed to process request", extra={"error": e})
```

#### Null checks

You can create a `best_practices.md` file in your repository root with content such as:

```bash theme={null}
Add defensive null/empty checks before accessing object properties.
```

Before:

```python theme={null}
def get_pr_code(pr_data):
    if "changed_code" in pr_data:
        return pr_data.get("changed_code", "")
    return ""
```

After:

```python theme={null}
def get_pr_code(pr_data):
    if pr_data is None:
        return ""
    if "changed_code" in pr_data:
        return pr_data.get("changed_code", "")
    return ""
```

### Global hierarchical best practices

For organizations managing multiple repositories with different requirements, Qodo supports a hierarchical best practices system using a dedicated global configuration repository.

#### Set up global hierarchical best practices

1. Create a new repository named `pr-agent-settings` in your organization/workspace.

2. Build the folder hierarchy in your `pr-agent-settings` repository. For example:

```bash theme={null}
pr-agent-settings/
├── metadata.yaml                    # Maps repos/folders to best practice paths
└── codebase_standards/              # Root for all best practice definitions
    ├── global/                      # Global rules, inherited widely
    │   └── best_practices.md
    ├── groups/                      # For groups of repositories
    │   ├── frontend_repos/
    │   │   └── best_practices.md
    │   ├── backend_repos/
    │   │   └── best_practices.md
    │   ├── python_repos/
    │   │   └── best_practices.md
    │   ├── cpp_repos/
    │   │   └── best_practices.md
    │   └── ...
    ├── repo_a/                      # For standalone repositories
    │   └── best_practices.md
    ├── monorepo-name/               # For monorepo-specific rules
    │   ├── best_practices.md        # Root level monorepo rules
    │   ├── service-a/               # Subproject best practices
    │   │   └── best_practices.md
    │   └── service-b/               # Another subproject
    │       └── best_practices.md
    └── ...                          # More repositories
```

<Note>
  `pr-agent-settings`, `codebase_standards`, `global`, `groups`, `metadata.yaml`, and `best_practices.md` are hardcoded names and must be used exactly as shown.

  All other names (such as `frontend_repos`, `backend_repos`, `repo_a`, `monorepo-name`, `service-a`, etc.) are examples and should be replaced with your actual repository and service names.
</Note>

<Accordion title="Grouping and categorizing best practices">
  * Each folder (including the global folder) can contain a single `best_practices.md` file.
  * Organize repository best practices by creating subfolders within the `groups` folder.
  * You can group them by purpose, programming language, or other categories.
</Accordion>

3. Define the metadata file `metadata.yaml` that maps your repositories to their relevant best practices paths. For example:

```bash theme={null}
# Standalone repos
repo_a:
  best_practices_paths:
    - "repo_a"

# Group-associated repos
repo_b:
  best_practices_paths:
    - "groups/backend_repos"

# Multi-group repos
repo_c:
  best_practices_paths:
    - "groups/frontend_repos"
    - "groups/backend_repos"

# Monorepo with subprojects
monorepo-name:
  best_practices_paths:
    - "monorepo-name"
  monorepo_subprojects:
    service-a:
      best_practices_paths:
        - "monorepo-name/service-a"
    service-b:
      best_practices_paths:
        - "monorepo-name/service-b"
```

4. Set the following configuration in your global configuration file:

```bash theme={null}
[best_practices]
enable_global_best_practices = true
```

#### Best practices priority

All configured best practices sources are loaded independently and sent to the LLM together. There is no override. If both local and global best practices are configured, the LLM sees both. Sources are combined in the following order:

1. Organization best practices: Global `best_practices.md` from `codebase_standards/global/` in `pr-agent-settings`
2. Organization repository best practices: Repo-mapped files from `metadata.yaml`, or matched subproject paths for monorepos
3. Local repository best practices: Your repository's `best_practices.md`, always included if present, regardless of whether global best practices are configured
4. Wiki best practices
5. Auto-learned best practices

The only fallback logic is within the global system: if `metadata.yaml` is missing or cannot be parsed, Qodo falls back to the root-level `best_practices.md` in `pr-agent-settings`. This is a fallback within global, not between global and local.

#### Edge cases and behavior

* **Missing paths**: If specified paths in `metadata.yaml` don't exist in the file system, those paths are skipped.
* **Monorepo subproject matching**: For monorepos, Qodo automatically matches PR file paths against subproject paths to apply relevant best practices.
* **Multiple group inheritance**: Repositories can inherit from multiple groups, and all applicable best practices are combined.

#### Best practices suggestions label

Best practice suggestions are labeled as `Organization best practice` by default.

To customize this label:

```bash theme={null}
[best_practices]
organization_name = "..."
```

The label will become: `{organization_name} best practice`

## How it works

#### Exploration phase

PR code changes are scanned for potential issues such as bugs, logic flaws, and anti-patterns.

#### Tracking accepted suggestions

Accepted AI suggestions are tracked in the `.pr_agent_accepted_suggestions` wiki page.

#### Learning from patterns

Qodo analyzes accepted suggestions and generates a `.pr_agent_auto_best_practices` wiki file with recurring patterns.

#### Applying best practices

During code review:

* Code is checked against learned and defined patterns.
* Matching suggestions are labeled as **Learned best practice**.

This creates a continuous feedback loop, combining exploratory analysis with pattern-based enforcement.