Overview

​

How to use Kody Rules

​

Create Custom Rules

​

Variables, File References & MCP Functions

• File-Level:
  • fileDiff - The specific changes made to the individual file being analyzed
• PR-Level:
  • pr_title - The title of the Pull Request
  • pr_description - The description/body of the Pull Request
  • pr_total_additions - Total number of lines added
  • pr_total_deletions - Total number of lines deleted
  • pr_total_files - Total number of files changed
  • pr_total_lines_changed - Total number of lines modified
  • pr_files_diff - Complete diff of all changes across the entire Pull Request
  • pr_tags - Tags associated with the Pull Request
  • pr_author - Author of the Pull Request
  • pr_number - Pull Request number

• @file:path/to/file.ts - Reference files in the same repository where you’re editing the rule
  • Use when referencing templates, examples, or configuration files within your current repository
  • Example: @file:src/services/userService.ts
• @repo:org/project - Reference files in another repository or when configuring rules outside a repo context
  • Use when enforcing consistency across multiple repositories or referencing shared standards
  • Example: @repo:team/api-standards

• Kody identifies file references automatically when you save a rule
• References are resolved in the background—watch the status indicator next to the editor to confirm completion
• Use accurate blob-style paths (e.g., src/utils/helpers.ts) instead of placeholders
• File contents are injected into the rule context, allowing Kody to compare, validate, or enforce patterns
• Works in both File-Level and Pull Request-Level rules

• Repository operations: List repositories, get repository files, content, and languages
• PR analysis: Get pull request details, list commits, analyze PR file content
• File content retrieval: Fetch file contents and diffs
• Cross-file validation: Perform advanced analysis across multiple files
• Custom integrations: Any MCP server you’ve connected as a plugin (Jira, custom tools, etc.)

• Use specific file paths rather than generic placeholders
• Reference stable files that represent your team’s standards
• Test file references exist before saving rules to avoid resolution errors
• Combine variables, file references, and MCP functions for comprehensive validation

​

File-Level Rules

• Compare against reference files using @file or @repo
• Fetch related files or repository data using MCP functions
• Combine variables, file references, and MCP functions to validate patterns, check consistency, or enforce architectural rules

• Rule name: Clearly define the rule purpose
• File Paths: Limit rules to specific files or directories using glob patterns
• Severity: Set to Critical, High, Medium, or Low
• Detailed Instructions: Use fileDiff, reference files with @file/@repo, and call MCP functions to compose powerful rules with rich context

// Risk of infinite loop if increment is not exactly 1
for (let i = 0; i != 10; i += 2) {
  console.log(i); // Will print 0, 2, 4, 6, 8, 10, 12, 14... forever
}

// Risk if array is modified during iteration
let items = [1, 2, 3, 4, 5];
for (let i = 0; i != items.length; i++) {
  if (items[i] === 3) {
    items.push(6); // Modifies length, can cause infinite loop
  }
}

// Safe: loop will always terminate
for (let i = 0; i < 10; i += 2) {
  console.log(i); // Will print 0, 2, 4, 6, 8 and stop
}

// Safe even if array is modified
let items = [1, 2, 3, 4, 5];
for (let i = 0; i < items.length; i++) {
  if (items[i] === 3) {
    items.push(6); // Loop will still terminate safely
  }
}

​

Pull Request-Level Rules

• Validate PR metadata using variables like pr_title, pr_description, pr_author
• Reference configuration files or templates using @file or @repo
• Fetch additional context using MCP functions (e.g., check if related files exist, validate against repository structure)
• Combine PR variables, file references, and MCP functions to create comprehensive validation rules

• Every service file must have a corresponding test file
• PR description must be complete, clearly stating what was added or removed
• When a new route is created in a controller, it must be registered in routes.json
• Use pr_total_lines_changed to flag PRs exceeding size limits
• Combine pr_files_diff with MCP functions to validate cross-file dependencies
• Reference @file:routes.json to ensure new routes are registered
• Use MCP functions to check if test files exist for modified service files

​

Composing Powerful Rules

• Use fileDiff to analyze the specific changes in a file
• Reference related files with @file:path/to/template.ts to compare against patterns
• Call MCP functions to fetch repository data or check if related files exist
• Example: “Analyze fileDiff and ensure it follows the pattern in @file:src/utils/example.ts. Use MCP to verify related test files exist.”

• Use PR variables (pr_title, pr_description, pr_files_diff, etc.) to validate PR metadata and size
• Reference configuration files with @file:config.json or @repo:org/shared-config to enforce consistency
• Call MCP functions to perform cross-file validation, check repository structure, or fetch commit history
• Example: “If pr_files_diff contains new routes, verify they’re registered in @file:routes.json. Use MCP to check if corresponding test files exist for all modified service files.”

• Reference files from other repositories with @repo:org/project to maintain consistency across projects
• Combine with MCP functions to validate against shared standards or templates
• Example: “Ensure API endpoints follow the pattern defined in @repo:org/api-standards. Use MCP to fetch the latest standards document.”

• MCP functions execute during rule evaluation, enabling rules that adapt to current repository state
• Fetch real-time data about files, commits, or repository structure
• Example: “Use MCP to check the current repository structure and ensure new files follow the existing directory patterns.”

​

Import from Rules Library

• Navigate to Discovery Rules in your Kodus dashboard.
• Filter rules by severity, language, or tags.
• Import and activate rules with a single click.

• Security: “Disallow use of insecure MD5 hashing.”
• Maintainability: “Limit React components to less than 150 lines.”

​

Next Steps