> ## 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 **Platforms supported:** GitHub You must [enable a Wiki](/v1/configuration/enabling-a-wiki) to use this feature. Auto best practices is a Qodo capability that: 1. Identifies recurring patterns from accepted suggestions. 2. **Automatically** generates [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](/v1/configuration/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 ``` ### Example ## Custom best practices **Platforms supported:** GitHub, GitLab, Bitbucket ### Local best practices file For basic usage, create a `best_practices.md` file in your repository's root directory containing a list of best practices, coding standards, and guidelines specific to your repository. Qodo will use this `best_practices.md` file as a reference. In case the PR code violates any of the best practices guidelines, Qodo will create additional suggestions, with a dedicated label: `Organization best practices`. ### Writing effective best practices files The following guidelines apply to all best practices files: * Write clearly and concisely. * Include brief code examples when helpful with before/after patterns. * Focus on project-specific guidelines that will result in relevant suggestions you actually want to get. * Keep each file relatively short, under 800 lines, since: * AI models may not process effectively very long documents. * Long files tend to contain generic guidelines already known to AI. * Use pattern-based structure rather than simple bullet points for better clarity. ### Example `best_practices.md` #### Error handling You can create a `best_practices.md` file in your repository root with content like: ```bash theme={null} Add proper error handling with try-except blocks around external function calls. ``` Example code before: ```bash theme={null} # Some code that might raise an exception return process_pr_data(data) ``` Example code 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 like: ```bash theme={null} Add defensive null/empty checks before accessing object properties. ``` Example code before: ```python theme={null} def get_pr_code(pr_data): if "changed_code" in pr_data: return pr_data.get("changed_code", "") return "" ``` Example code 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. **Supported scenarios:** 1. **Standalone repositories**: Individual repositories can have their own specific best practices tailored to their unique requirements 2. **Groups of repositories**: Repositories can be mapped to shared group-level best practices for consistent standards across similar projects 3. **Monorepos with subprojects**: Large monorepos can have both repository-level and subproject-level best practices, with automatic path-based matching **Setting 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:** In this structure, `pr-agent-settings`, `codebase_standards`, `global`, `groups`, `metadata.yaml`, and `best_practices.md` are hardcoded names that 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. Group them by purpose, programming languages, or other categories 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 Qodo loads all configured best practices sources independently and sends them to the LLM together. There is no override. If both local and global best practices are configured, the LLM sees both. Qodo combines sources 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 own `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 the global system, 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, modify it in your configuration file: ```bash theme={null} [best_practices] organization_name = "..." ``` And the label will be: `{organization_name} best practice`. ## How it works #### 1. **Exploration phase** – Finding code issues The `improve` tool scans PR code changes for potential issues, not minor formatting errors, but real problems like bugs, logic flaws, or anti-patterns. This phase is exploratory by design, helping surface meaningful suggestions beyond predefined categories. #### 2. **Tracking implemented suggestions** Qodo automatically tracks accepted AI-generated suggestions. When PR authors apply a suggestion, it’s logged in the `.pr_agent_accepted_suggestions` Wiki page. This tracking provides the foundation for learning what works. #### 3. **Learning from accepted patterns** Once a month, Qodo analyzes accepted suggestions to generate a custom `.pr_agent_auto_best_practices` Wiki file. These patterns represent practices that your team implicitly approves through repeated adoption. #### 4. **Applying best practices in reviews** During the next use of the `improve` tool: * The tool checks code changes against these learned patterns. * If a suggestion matches a learned best practice, it’s clearly labeled with **“Learned best practice.”** * This creates a two-phase analysis: * **Exploratory**: Surfaces general issues without restrictions * **Targeted**: Checks for violations of established, successful patterns Keeping both phases separate allows Qodo to stay innovative while building on your team’s real-world feedback.