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

Metrics: Usage Analytics

Rules — Usage

As you can see in these screenshots, rule violations surface directly in the PR review comment — labelled, categorised, and linked to the exact rule and code location that triggered them.

---

2. PR Findings Sync

TLDR. Enable findings_sync to store review findings on the Qodo platform. This unlocks incremental reviews, attribution tracking, and workspace-level analytics — all of which depend on findings being persisted.

When Qodo Merge runs /agentic_review, it produces findings: issues, violations, and suggestions across security, performance, correctness, and other categories. By default these are published as PR comments. Enabling findings sync also stores them on the platform with full metadata.

[qodo_platform]
enable_findings_sync = true

[azure_devops_server]
pr_commands = ["/agentic_review"]
push_commands = ["/agentic_review"]

What this unlocks:

Without sync	With sync
Re-reports the same findings on every push	Tracks what's new vs. still open across pushes
Pre-PR findings lost when PR is opened	Surfaced automatically in the PR review
No record of accepted/dismissed suggestions	Tracked per finding; feeds impact metrics
Compliance statistics unavailable	Captured on merge
No workspace analytics	Aggregate trends across repos, teams, and time

What gets stored per finding: title, description, category, severity, diff reference (file + line range), fix suggestion, git metadata (SHA, branch, repo, org), PR URL, author, and attribution status.

Attribution and impact tracking: when a developer applies a suggestion, dismisses it, or defers it, the platform record is updated. This feeds impact metrics — which categories get resolved most often, which teams have the highest fix rates.

Reliability note: if the platform is unreachable, findings sync fails silently — the PR comment is still published normally. Reviews are never blocked by a platform outage.

---

3. Incremental vs. Full Re-Review on Push

TLDR. Use incremental review on push. It focuses on what changed since the last review, cuts noise, and costs less. Full re-review is only warranted when you need a clean audit snapshot.

When a developer pushes new commits to an open PR, you have two options.

Option A: Full re-review on every push

[azure_devops_server]
push_commands = ["/agentic_review"]

[review_agent]
enable_incremental_review = false

Pros: always shows the complete picture of open findings; no dependency on previous review state.

Cons: re-reports everything the developer already saw; noisy on PRs with many small commits; higher LLM cost per push.

Option B: Incremental review (recommended)

[azure_devops_server]
push_commands = ["/agentic_review"]

[review_agent]
enable_incremental_review = true
persistent_comment = true

[qodo_platform]
enable_findings_sync = true

Only reviews what changed since the last completed review. Developers see new findings, not repeats. Lower cost. Requires findings persistence — if a previous review failed, the incremental focus may be incomplete.

Recommendation. Use Option B for daily development. Fall back to Option A when you want a clean audit snapshot on a significant PR.

---

4. Suppress Feedback on Draft PRs

TLDR. Set feedback_on_draft_pr = false if your team treats drafts as genuine WIP. Saves LLM cost and keeps the PR thread clean until the author is ready.

By default, Qodo runs automatically on every PR — including drafts. Setting feedback_on_draft_pr = false disables that trigger, so reviews only fire when a PR is explicitly marked ready. Manual /agentic_review is still available on demand.

[azure_devops_server]
feedback_on_draft_pr = false

Pros: no premature feedback on in-progress code, lower cost, cleaner PR threads.

Cons: developers lose early signal. If a draft PR is never converted to "ready", it never gets reviewed automatically. Manual /agentic_review is still available, but relies on discipline.

Recommendation: enable suppression for teams that use drafts as genuine WIP. If your team uses drafts for early collaboration and expects feedback during drafting, keep it enabled — and pair it with incremental review (see section 3) to reduce noise on subsequent pushes:

[review_agent]
enable_incremental_review = true

---

5. Capture Compliance Statistics at Merge Time

TLDR. Qodo runs a silent compliance-only pass every time a PR merges, capturing a final snapshot of rule pass/fail at the moment code entered the main branch. Zero developer friction. Engineering leadership gets trend data.

When a PR is merged, the git.pullrequest.merged webhook fires. Qodo re-runs a compliance-only pass silently — nothing is posted to the PR. The result is stored as a pr_compliance_statistics object and emitted to the analytics pipeline.

This runs automatically once your pr_commands includes /agentic_review:

[azure_devops_server]
pr_commands = ["/agentic_review"]

The check always runs silently — nothing is posted to the PR at merge time.

What gets captured: number of rules checked, rules passed/failed, per-rule outcomes — attached to the PR's full merge-time statistics.

Who this is for: engineering leadership, not individual developers. It answers: which teams have the lowest compliance rates? Are scores improving over sprints? Which rules are most frequently violated before merge?

Catch 1 — Analytics pipeline dependency: statistics are emitted as log events, not displayed in a built-in dashboard. Your team needs to consume the Qodo analytics pipeline or export logs to a BI tool. Without that, the feature runs but produces no actionable output.

Catch 2 — Rules must be configured: if no YAML rules or platform rules are defined, the compliance pass runs but captures nothing meaningful. Enable this feature after rules are in place, not before.

Recommendation. Enable this once you have compliance rules defined and a way to consume the analytics output. If either is missing, the feature runs silently with zero visible effect — set it up when you're ready to act on the data.

---

6. Verifiable Work Items for Compliance-Driven Reviews

TLDR. Qodo reads linked ADO work items and derives compliance rules from them. The quality of the review is directly proportional to the quality of the acceptance criteria. Vague work items produce nothing useful.

On every /agentic_review run, Qodo discovers linked work items from three sources: items linked via the ADO Boards API, references in the PR description (AB#123, full URLs), and the branch name prefix (1234-fix-auth-flow). It fetches the full work item — title, description, acceptance criteria, tags — and an LLM extracts verifiable compliance rules from the content. Those rules are checked against the diff alongside YAML and platform rules.

The Acceptance Criteria field is the highest-signal input. It is read separately from the description.

How to write work items for maximum compliance value

Write criteria as verifiable pass/fail statements

Weak	Strong
"The API should be fast"	"The API must return a response within 200ms under normal load"
"Handle errors properly"	"The endpoint must return HTTP 400 with a structured error body when required fields are missing"
"Make it secure"	"JWT signatures must be validated before granting access to any authenticated endpoint"

One condition per bullet point

Compound criteria are harder to decompose into atomic rules. Keep each bullet to a single, testable concern.

Good:
- The endpoint must return HTTP 404 when the resource does not exist
- The response body must include an error_code field on all failures

Avoid:
- The endpoint must handle errors correctly, return the right status codes,
  and ensure no SQL injection is possible

Include technical constraints, not just business requirements

"Users should be able to log in" is too high-level to verify against a diff. "The login endpoint must validate the JWT signature before granting access" is checkable.

Link work items explicitly

Use the ADO PR interface or branch naming convention ({work-item-id}-description). The Boards API linked path is the most reliable discovery method.

Configuration

The feature is on by default. To verify it is enabled:

[pr_compliance]
require_ticket_analysis_review = true

[review_agent]
requirements_gap_enabled = true

Pitfalls:

Pitfall	Impact
No acceptance criteria and vague description	Zero compliance rules generated
No linked or referenced work item	Ticket compliance pass is skipped entirely
Description longer than 10,000 characters	Truncated — put key constraints in Acceptance Criteria
Ambiguous or compound criteria	Inconsistent rule extraction across reviews

Recommendation. The quality of the AI review is a direct function of the quality of the work item. Fill in the Acceptance Criteria field, write one verifiable condition per bullet, and link work items before requesting review. Teams that do this consistently get the most signal from compliance-driven reviews.

---

7. Auto-Generate PR Descriptions with /agentic_describe

TLDR. Run /agentic_describe on every new PR to give reviewers structured context — a clean title, a summary of what changed and why, and a file-by-file walkthrough — before they read a single line of code.

agentic_describe analyzes the diff and generates a concise PR title, a structured body, and a file walkthrough. The output is published as a persistent bot comment. When the PR is updated and the command runs again, the same comment is updated in place — no comment spam.

This runs automatically on PR open with no extra configuration, as long as pr_commands includes /agentic_describe (the default):

[azure_devops_server]
pr_commands = [
  "/agentic_describe",
  "/agentic_review",
]

To publish to the PR body instead of a comment, set publish_description_as_comment = false — but on Azure DevOps, keep the default (true). ADO has no collapsible sections, so writing to the PR body makes large PRs very long.

Benefits:

Benefit	Detail
Faster reviewer onboarding	Reviewers understand scope and intent before opening the diff
Consistent PR format	Every PR gets a structured title and summary regardless of author habits
Reduced back-and-forth	Context that would otherwise need author clarification is auto-generated
Zero developer overhead	Authors don't need to write detailed descriptions manually

Pitfall: push_commands also includes /agentic_describe by default, so the description updates on every commit push. For large PRs with many files, the persistent comment can become long. If the noise is unwanted, remove /agentic_describe from push_commands:

[azure_devops_server]
push_commands = ["/agentic_review"]

Recommendation. Leave /agentic_describe in pr_commands — the reviewer onboarding value is real and costs nothing to the author. Trim it from push_commands if per-push description updates are too noisy for your team's workflow.

---

8. Enable the Chat Agent (/qodo) for Developer Follow-Up

TLDR. Enable chat_agent.enabled = true so developers can ask follow-up questions on findings without leaving Azure DevOps. One line of config.

The chat agent is disabled by default. Once on, it works in two ways:

1. Inline finding replies — a developer replies to a Qodo finding comment. The agent answers in context, with full awareness of what was flagged and why.
2. General PR chat — a developer posts /qodo <question>. The agent answers questions about the PR diff, the code, or specific findings.

The agent has access to the full PR diff and the findings from the review. It does not have access to external systems (Jira, ADO Boards, etc.).

Configuration

[chat_agent]
enabled = true

That's it for Azure DevOps.

Benefits:

Benefit	Detail
Developer stays in ADO	No need to switch to a chat tool to ask about a finding
Finding-aware answers	Replies have full context of what was flagged and why
Accelerates learning	Junior developers can ask "why is this a problem?" and get a code-level explanation
Reduces false positive friction	Developers can justify or challenge a finding before dismissing it

Pitfalls:

Pitfall	Mitigation
Off by default — easy to miss	Explicitly add chat_agent.enabled = true
Triggered by any reply to bot comments	If reviewers use bot threads for human discussion, the agent may respond unexpectedly
Adds LLM calls per reply	Each chat interaction is a separate LLM call — monitor usage if cost is a concern

> Recommendation. Enable the agent, run /agentic_review, then let developers reply directly to findings they want to discuss or challenge. The agent responds in-thread with reasoning, code references, or suggested fixes. Particularly valuable for teams with junior developers or high finding volume — it reduces the friction of dismissing findings without context.

Baseline .pr_agent.toml

All eight practices combined into a single baseline configuration:

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

[azure_devops_server]
pr_commands = ["/agentic_describe", "/agentic_review"]
push_commands = ["/agentic_review"]
feedback_on_draft_pr = false

[review_agent]
enable_incremental_review = true
persistent_comment = true
inline_comments_severity_threshold = 2

[qodo_platform]
enable_findings_sync = true

[pr_compliance]
require_ticket_analysis_review = true

[chat_agent]
enabled = true