Overview

Korbit Policies are for where the linters can't go, allowing you to extend Korbit's out-of-the-box comprehensive reviews by specifying rules that are specific to you and your team's way of doing things. Policies are not required to get started with Korbit, but they are a powerful way to enforce your team's standards.

• Turn your team's best practices into code - Capture team guidelines, naming conventions, and workflow expectations in a structured, version-controlled file.

• Enforce standards that linters can't - Go beyond formatting — enforce things like API usage, service boundaries, and process rules at the PR level.

• Accelerate onboarding and reduce review friction - Help new developers follow team conventions from day one, and reduce repetitive back-and-forth in code reviews.

• Continuously improve your codebase - Track which rules are effective, refine unclear ones, and evolve your standards over time with real developer feedback.

Click here to view examples of policies in action: Examples

Key Configuration Options

The configuration file is written in YAML format and should be placed in the root of your repository.

# yaml-language-server: $schema=https://docs.korbit.ai/configuration/korbit-policies-schema.v0.1.json
version: "0.1" # Schema version. Required to ensure compatibility with policy validator
topics:
  - name: "Topic A" # Example topic showing the structure of a policy
    paths:
      - "**/*" # Glob pattern matching all files in the project
    policies:
      - title: Policy A1 Title # First policy in Topic A
        description: |
          Describe what this rule enforces in a clear and specific way.
        impact: |
          Describe why this rule is important for the code base.
        code_examples:
          - non_compliant: |
              # Bad code example for A1
              something_wrong()
            compliant: |
              # Good code example for A1
              something_right()

Schema Validator

How do policy issues show up in reviews?

When Korbit detects a policy violation, it will be included alongside the out of the box Korbit review comments with a category of Policy.

You are also able to filter for policy violations in the Korbit Console's issues tab.

Guidelines for Writing Effective Korbit Policies

Korbit Policies allow you to enforce your team’s unique best practices, design principles, and workflow expectations directly in your code reviews. Well-written policies make it easier for everyone—especially new team members—to contribute high-quality, consistent code.

Where to Start: Identify High-Impact Rules

• Begin with friction points.
  Think about what issues or coding patterns you and your reviewers correct most often. These are great candidates for your first policies.
• Think like a teammate.
  Consider what rules would help new contributors or teammates quickly adapt to your project’s standards. Policies should make the review and onboarding process smoother for everyone.
• Be opinionated.
  Don’t be afraid to encode your team’s unique practices and preferences. Policies work best when they reflect how your team actually wants to work.

To help you create effective Korbit Policies, follow these guidelines derived from our internal policy validation process:

1. Write Clear, Focused Rules

• Each policy should address a single, specific rule.
  Avoid combining multiple requirements into one policy. If you have more than one rule to enforce, create separate policies for each.

• State the rule directly in the description.
  The description should clearly say what is required, without justifying or explaining the rule. Save explanations for the impact section.

  ✅ Good description:

  All API calls must use the ApiService class instead of the FetchWrapper.

  ❌ Bad description:

  All API calls must use the ApiService class in order to make updates easier in the future.

• Keep descriptions concise.
  Limit to four sentences or fewer. Avoid questions in the description.

2. Explain the Impact

• Use the impact section to explain “why.”
  Describe the benefits of following the policy or the risks of not following it.
  Phrases like “to prevent,” “this helps with,” and “in order to” are welcome here.

  Example:

  Using a service class centralizes API logic, making it easier to update authentication and error handling.

3. Provide Complete, Accurate Examples

• Show both compliant and non-compliant code.
  Examples should be clear, correct, and directly related to the policy.
• Avoid incomplete or buggy code.
  Examples should be functional and realistic.
• Compliant and non-compliant examples must be different and not reversed.
  The compliant example should follow the policy; the non-compliant one should break it.
• Write examples in appropriate languages.
  Use the programming languages that match your codebase. For policies affecting multiple languages, provide examples in each relevant language.

4. Use Appropriate Titles

• Make sure each title matches the rule in the description.
  The title should summarize the policy in a few words.

5. Stay Relevant to Source Code

• Write policies that can be enforced by reviewing the source code.
  Don’t include rules about processes outside of code (like ticketing or code review procedures).
• Avoid rules that can be fully handled by standard linters (e.g., formatting, naming conventions, or spacing).

6. Match the Policy to File Types

• Policies should be applicable to the file types listed in the paths section.
  Make sure your rule makes sense for the files it covers.

7. Avoid Duplicates and Contradictions

• Don’t repeat the same rule in multiple policies.
  Check for duplicate or conflicting policies before adding new ones.
• Policies in the same topic or file should not contradict each other.

8. Group Related Policies Under Topics

• Use topics to organize related policies.
  Group policies that enforce similar concepts or affect the same area of code.

• Choose clear, descriptive topic names.
  The topic name should give a good overview of what the policies inside cover.

  ✅ Good topic organization:

  Topic: "API Service Usage"

  • Policy 1: Use ApiService for HTTP calls
  • Policy 2: Handle API errors consistently
  • Policy 3: API response type validation

  ❌ Bad topic organization:

  Topic: "Miscellaneous"

  • Policy 1: Use ApiService for HTTP calls
  • Policy 2: Avoid global state
  • Policy 3: Format SQL queries

Tip:
Before finalizing your policy, review it using the guidelines above, or use our schema validator to check for issues.

By following these guidelines, you’ll help your team enforce clear, actionable standards and make the most of Korbit’s custom policy system.

Testing and Iterating on Policies

1. Create a .korbit-policies.yaml file in a branch, create a pull request, and push code that violates the policy to verify that the policy is working as expected. To trigger a new review you can use the /korbit-full-review command.
2. Once you have verified that the policy is working as expected, remove the code that violates the policy and merge the pull request into your main branch.
3. Every time Korbit reviews your code, it will check for policy violations and report them in the PR comments.

Examples

# yaml-language-server: $schema=https://docs.korbit.ai/configuration/korbit-policies-schema.v0.1.json
version: "0.1" # Schema version. Required to ensure compatibility with policy validator
topics:
  - name: "API Service Usage"
    paths:
      - "**/*"
    policies:
      - title: Deprecated FetchWrapper usage
        description: |
          All API calls must be made through ApiService
          instead of directly using the legacy FetchWrapper.
        impact: |
          Using the service classes instead of direct FetchWrapper calls is crucial
          for maintaining a clean and consistent codebase. When we centralize our
          API logic in these service classes, we make it much easier to update how
          we handle authentication, error cases, or even switch out the underlying
          implementation.
        code_examples:
          - non_compliant: |
              const response = await fetchWrapper<SomeType>({
                path: '/api/some-endpoint',
                options: { method: 'GET' }
              });
            compliant: |
              const response = await apiService.someEndpoint.get();