Custom Rules

Custom rules provide a powerful way to define project-specific and global behaviors and constraints for the Kilo Code AI agent. With custom rules, you can ensure consistent formatting, restrict access to sensitive files, enforce coding standards, and customize the AI's behavior for your specific project needs or across all projects.

Overview

Custom rules allow you to create text-based instructions that all AI models will follow when interacting with your project. These rules act as guardrails and conventions that are consistently respected across all interactions with your codebase. Rules can be managed through both the file system and the built-in UI interface.

Rule Format

Custom rules can be written in plain text, but Markdown format is recommended for better structure and comprehension by the AI models. The structured nature of Markdown helps the models parse and understand your rules more effectively.

• Use Markdown headers (#, ##, etc.) to define rule categories
• Use lists (-, *) to enumerate specific items or constraints
• Use code blocks ( ) to include code examples when needed

Rule Types

Kilo Code supports two types of custom rules:

• Project Rules: Apply only to the current project workspace
• Global Rules: Apply across all projects and workspaces

Rule Location

// kilo.jsonc
{
  "instructions": [".kilo/rules/formatting.md", ".kilo/rules/*.md"],
}

project/
├── .kilo/
│   ├── rules/
│   │   ├── formatting.md
│   │   ├── restricted_files.md
│   │   └── naming_conventions.md
├── kilo.json
├── src/
└── ...

Managing Rules Through the UI

// kilo.jsonc
{
  "instructions": [
    ".kilo/rules/formatting.md",
    // ".kilo/rules/experimental.md"  -- temporarily disabled
    ".kilo/rules/naming_conventions.md",
  ],
}

Rule Loading Order

Creating Custom Rules

// kilo.jsonc
{
  "instructions": [".kilo/rules/my-new-rule.md"],
}

Example Rules

Example 1: Table Formatting

# Tables

When printing tables, always add an exclamation mark to each column header

This simple rule instructs the AI to add exclamation marks to all table column headers when generating tables in your project.

Example 2: Restricted File Access

# Restricted files

Files in the list contain sensitive data, they MUST NOT be read

- supersecrets.txt
- credentials.json
- .env

This rule prevents the AI from reading or accessing sensitive files, even if explicitly requested to do so.

Use Cases

Custom rules can be applied to a wide variety of scenarios:

• Code Style: Enforce consistent formatting, naming conventions, and documentation styles
• Security Controls: Prevent access to sensitive files or directories
• Project Structure: Define where different types of files should be created
• Documentation Requirements: Specify documentation formats and requirements
• Testing Patterns: Define how tests should be structured
• API Usage: Specify how APIs should be used and documented
• Error Handling: Define error handling conventions

Examples of Custom Rules

• "Strictly follow code style guide [your project-specific code style guide]"
• "Always use spaces for indentation, with a width of 4 spaces"
• "Use camelCase for variable names"
• "Write unit tests for all new functions"
• "Explain your reasoning before providing code"
• "Focus on code readability and maintainability"
• "Prioritize using the most common library in the community"
• "When adding new features to websites, ensure they are responsive and accessible"

Best Practices

• Be Specific: Clearly define the scope and intent of each rule
• Use Categories: Organize related rules under common headers
• Separate Concerns: Use different files for different types of rules
• Use Examples: Include examples to illustrate the expected behavior
• Keep It Simple: Rules should be concise and easy to understand
• Update Regularly: Review and update rules as project requirements change

Limitations

• Rules are applied on a best-effort basis by the AI models
• Complex rules may require multiple examples for clear understanding
• Project rules apply only to the project in which they are defined
• Global rules apply across all projects

Troubleshooting

Related Features

• Custom Modes
• Custom Instructions
• Settings Management
• Auto-Approval Settings