Best practices

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

Auto best practices

GitHub

You must enable a wiki to use this feature.

Auto best practices is a Qodo capability that:

Identifies recurring patterns from accepted suggestions.
Automatically generates a best practices page based on what your team consistently values.
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:

[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

GitHub GitLab Bitbucket 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:

Add proper error handling with try-except blocks around external function calls.

Before:

# Some code that might raise an exception
return process_pr_data(data)

After:

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:

Add defensive null/empty checks before accessing object properties.

Before:

def get_pr_code(pr_data):
    if "changed_code" in pr_data:
        return pr_data.get("changed_code", "")
    return ""

After:

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

Create a new repository named pr-agent-settings in your organization/workspace.
Build the folder hierarchy in your pr-agent-settings repository. For example:

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

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.

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.

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

# 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"

Set the following configuration in your global configuration file:

[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:

Organization best practices: Global best_practices.md from codebase_standards/global/ in pr-agent-settings
Organization repository best practices: Repo-mapped files from metadata.yaml, or matched subproject paths for monorepos
Local repository best practices: Your repository’s best_practices.md, always included if present, regardless of whether global best practices are configured
Wiki best practices
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:

[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.

Centralized governance

Review Standards

Auto best practices

How to enable auto best practices

Custom best practices

Local best practices file

Writing effective best practices files

Example `best_practices.md`

Error handling

Null checks

Global hierarchical best practices

Set up global hierarchical best practices

Best practices priority

Edge cases and behavior

Best practices suggestions label

How it works

Exploration phase

Tracking accepted suggestions

Learning from patterns

Applying best practices

​Auto best practices

​How to enable auto best practices

​Custom best practices

​Local best practices file

​Writing effective best practices files

​Example best_practices.md

​Error handling

​Null checks

​Global hierarchical best practices

​Set up global hierarchical best practices

​Best practices priority

​Edge cases and behavior

​Best practices suggestions label

​How it works

​Exploration phase

​Tracking accepted suggestions

​Learning from patterns

​Applying best practices

Auto best practices

How to enable auto best practices

Custom best practices

Local best practices file

Writing effective best practices files

Example `best_practices.md`

Error handling

Null checks

Global hierarchical best practices

Set up global hierarchical best practices

Best practices priority

Edge cases and behavior

Best practices suggestions label

How it works

Exploration phase

Tracking accepted suggestions

Learning from patterns

Applying best practices