Qodo Best Practices — Rules, Reviews, and Governance at Scale

1. Rules

TLDR. Define custom coding standards in a YAML file at the repo root. Every PR is then reviewed against your team's requirements — traceability, security, documentation — without writing a single prompt.

Qodo Merge ships with default review heuristics, but the most durable value comes from rules you define. Rules encode your organization's standards into the review process: mandatory work item links, no hardcoded secrets, XML doc comments on public APIs.

There are two sources of rules: the repo-level YAML file, and platform-level rules configured through the Qodo console. Both compose.

Repo rules — the YAML file

Create .qodo/rules.yaml at the repo root:

- title: "All Azure DevOps work items must be linked in the PR description"
  objective: "Ensure every PR is traceable to a work item"
  success_criteria: "PR description contains a work item reference like AB#1234"
  failure_criteria: "No AB# reference found anywhere in the PR description"
  compliance_label: true
  category: "traceability"
  external_id: "ORG-POLICY-001"

- title: "No secrets or connection strings in committed code"
  objective: "Prevent credentials from leaking into source control"
  success_criteria: "No hardcoded passwords, tokens, or connection strings in changed files"
  failure_criteria: "A changed file contains a string matching patterns like 'password=', 'AccountKey=', or similar"
  compliance_label: true
  category: "security"
  severity: "critical"
  external_id: "ORG-POLICY-002"

- title: "Public APIs must have XML documentation comments"
  objective: "Ensure public surface area is documented for consumers"
  success_criteria: "All new or modified public methods/classes have <summary> XML doc comments"
  failure_criteria: "A new or modified public method/class is missing XML documentation"
  compliance_label: false
  category: "documentation"
  severity: "medium"

Then tell Qodo Merge to pick it up. In .pr_agent.toml:

[config]
add_repo_metadata = true
add_repo_metadata_file_list = [".qodo/rules.yaml"]

That's it. On the next PR, Qodo reads the file, evaluates each rule against the diff, and reports violations in the review comment. No LLM step is needed to parse the rules — they are applied directly.

Key constraints to know:

Constraint	Detail
File must end in .yaml or .yml	.json, .toml, .md are not picked up
YAML list at the top level	A dict at root will be skipped with a warning
title is the only required field	All other fields default
compliance_label: true adds a blocking label	Defaults to false
Max lines per file defaults to 1500	Configurable via max_lines_per_repo_metadata_file

Platform rules

Org wide governance

A select few — engineering leads, compliance officers — manage platform rules through the Qodo Console. Those rules then apply automatically to every PR across all repositories in the workspace.

flowchart LR
    subgraph Org["Engineering Org"]
        Devs["Developers\n(all)"]
        A1(["Engineering Leads"])
        A2(["Security + Compliance"])
    end

    Console[("Qodo Console\nPlatform Rules")]

    subgraph Repos["All Repositories"]
        R1["Repo A"]
        R2["Repo B"]
        R3["Repo C"]
    end

    A1 -->|"define & manage"| Console
    A2 -->|"define & manage"| Console
    Console -->|"enforced on every PR"| R1
    Console -->|"enforced on every PR"| R2
    Console -->|"enforced on every PR"| R3

    classDef admin fill:#6b21a8,stroke:#4c1d95,color:#fff
    classDef dev fill:#e2e8f0,stroke:#94a3b8,color:#334155
    classDef console fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef repo fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f

    class A1,A2 admin
    class Devs dev
    class Console console
    class R1,R2,R3 repo

Rules via platform

Metrics: Rules & Findings