Zen Rules

Create custom context and instructions for your AI agents with project-specific markdown rules that enhance code understanding and consistency.

New Feature: Zen Rules were introduced in VS Code version 2.16.0 and JetBrains version 2.7.0. Make sure you’re running the latest version to access this functionality.

Rules Organization and Hierarchy

Zencoder uses a hierarchical system of rules and instructions to provide the most relevant context. Understanding this hierarchy helps you choose the right approach for your needs:

Zen Rules

Project-specific rules

Stored in .zencoder/rules/*.md files in your repository. Applied conditionally based on file patterns or always when specified.

Instructions for AI

Personal preferences

Global instructions stored locally on your machine. Applied to all projects and conversations automatically.

Repo Info

Generated context

Created by running the Repo Info Agent to provide comprehensive understanding of your project structure and workflows.

How Each Level Works

• Zen Rules: Project-based markdown files that provide custom context to Zencoder’s AI agents. Unlike global AI instructions, they’re committed to your codebase for team sharing and can be applied always (alwaysApply: true) or conditionally based on glob patterns. Perfect for team standards, architecture guidelines, and project-specific conventions.

• Instructions for AI: Your personal, global preferences managed through Zencoder’s three-dot menu → Instructions for AI. These apply across all your projects and are ideal for general coding style preferences or tone of voice the agent is using to respond to you.

• Repo Info: Generated context about your repository structure, technologies, and patterns (requires running the /repo-info agent). This runs with alwaysApply: true to help all agents understand your project better.

Getting Started

1. Locate the Rules Directory

Your Zen Rules live in the .zencoder/rules directory at your project root. When you upgrade to the latest version of Zencoder, this directory is created automatically with proper migrations handled for you.

You might notice a repo.md file already present in your .zencoder/rules directory. This file is created by the Repo Info Agent and provides project context. Learn more about working with repo.md in the Repo Info Agent documentation.

Since repo.md and custom Zen Rules serve different purposes, check out our quick guide on choosing the right approach to understand when to use each one.

If you had rules in the previous .zencoder/docs location, we’ve migrated them to the new .zencoder/rules structure. The old .zencoder/docs location is now deprecated for rules.

If you check your git commit history after upgrading, you’ll see the migration reflected as file moves from .zencoder/docs/ to .zencoder/rules/:

2. Create Your First Rule

To create a new Zen rule, you can use the built-in rule creator directly from the chat interface:

1. Click the @ sign in the chat input box
2. Select Zen Rules from the dropdown menu
3. Click on + New rule... at the top of the rules list

This will open a template with the proper markdown structure for you to fill in. The template includes the necessary frontmatter and placeholders for your rule content.

Rule Template Structure

When you create a new rule, you’ll work with this template structure:

---
description: "Brief description of what this rule covers"
globs: ["*.md", "*.mdx"]  # Optional: file patterns where this rule applies
alwaysApply: false         # Optional: set to true if rule should always be active
---

# Your Rule Title

## Section 1

Your guidelines, instructions, and examples go here.

## Section 2

Additional context, best practices, or specific requirements.

Example Rule

Here’s an example of a complete rule for markdown writing styles:

---
description: "Markdown writing style"
globs: ["*.md", "*.mdx"]
alwaysApply: false
---

# Markdown Style Guide

## Formatting Rules

- Use ATX-style headers (# ## ###) instead of underline style
- Separate headers from content with one blank line
- Use **bold** for emphasis, *italic* for subtle emphasis
- End files with a single newline

## Best Practices

- Keep line length under 100 characters when possible
- Use meaningful link text instead of "click here"
- Include alt text for all images
- Use consistent bullet point style (-)

After creating a rule through the UI, it will be automatically saved to your .zencoder/rules directory as a markdown file. You can then commit it to your repository to share with your team.

3. Reference Rules in Chat

You can manually include any rule by @mentioning it in your chat. Type @ and then select Zen Rules from the dropdown, then choose from the list of available rules:

This allows you to apply specific rules on-demand, in addition to rules that are automatically applied based on alwaysApply: true or matching glob patterns as described earlier.

4. View Applied Rules

You can now see which rules are currently active in your chat by clicking on the rules icon in the toolbar. The icon displays a badge showing the number of applied rules, and when clicked, reveals a panel listing all currently applied rules:

The rules icon provides instant visibility into which rules are influencing the AI’s responses, including both auto-applied rules (based on your current file context or alwaysApply settings) and manually referenced rules from your @mentions.

Rule File Format

Each rule file follows this structure:

---
description: "Brief description of what this rule covers"
globs: ["*.ts", "*.tsx", "src/**/*.js"]  # Optional: file patterns
alwaysApply: false                        # Optional: default is false
---

# Rule Content

Your markdown content here with guidelines, examples, and instructions.

Frontmatter Fields

Field	Required	Description
description	Yes	Brief description of the rule’s purpose. Displayed in chat when @mentioning rules and used by agents to understand rule relevance. Example: "TypeScript coding guidelines and best practices"
globs	No	Array of file patterns that trigger this rule. Rule is automatically included when working with matching files. Examples: ["*.ts", "*.tsx"], ["src/**/*.js"], ["*.md", "*.mdx"]
alwaysApply	No	Boolean (default: false). When true, rule is included in every request regardless of file context. Note: When true, the globs field is ignored

Practical Examples

Here are two complete examples showing different types of rules and how they’re structured:

Markdown Style Guide - Content formatting rules

---
description: "Markdown writing style and formatting guidelines"
globs: ["*.md", "*.mdx"]
alwaysApply: false
---

# Markdown Style Guide

## Formatting Rules
- Use ATX-style headers (# ## ###) instead of underline style
- Separate headers from content with one blank line
- Use **bold** for emphasis, *italic* for subtle emphasis
- End files with a single newline

## Best Practices
- Keep line length under 100 characters when possible
- Use meaningful link text instead of "click here"
- Include alt text for all images
- Use consistent bullet point style (-)

## Code Blocks
- Always specify language for syntax highlighting
- Use descriptive variable names in examples
- Include comments for complex examples

API Development Standards - Backend development guidelines

---
description: "REST API development guidelines and conventions"
globs: ["**/api/**/*.ts", "**/routes/**/*.js", "**/controllers/**/*.ts"]
alwaysApply: false
---

# API Development Standards

## Endpoint Naming
- Use plural nouns for resource endpoints: `/users`, `/products`
- Use kebab-case for multi-word resources: `/user-profiles`
- Version APIs with prefix: `/api/v1/users`

## HTTP Methods
- GET: Retrieve data (no side effects)
- POST: Create new resources
- PUT: Update entire resources
- PATCH: Partial updates
- DELETE: Remove resources

## Response Format
\```json
{
  "success": true,
  "data": {},
  "message": "Optional success message",
  "errors": []
}
\```

## Error Handling
- Use appropriate HTTP status codes
- Include descriptive error messages
- Log errors with request context
- Never expose internal system details

How Zen Rules Work

When you send a message to Zencoder, the system automatically includes relevant rules in the context:

1. Always applied rules are included in every request when you set alwaysApply: true in the frontmatter. That’s the case with repo.md, for example.
2. Pattern matched rules are automatically included when you’re working with files that match their glob patterns
3. Manually referenced rules are added when you @mention them in your chat for that specific request

Rules are added to the LLM context alongside your message, giving the AI agent comprehensive understanding of your project’s requirements and standards.

Why This Matters

This hierarchical system provides essential benefits for modern development workflows.

Team collaboration becomes seamless when consistent coding standards are committed to your repository, ensuring everyone follows the same patterns.

Project-specific context tailors AI responses to your unique codebase and architecture, making suggestions more relevant and accurate.

Conditional logic allows you to apply different rules based on file types or directories, giving you precise control over when and where specific guidelines are enforced.

Choosing the Right Approach

Understanding when to use repo.md (and Repo Info agent) versus custom rules helps you organize context effectively.

repo.md

• Project structure and architecture patterns
• Build commands and development workflows (especially in non-monorepo projects)
• Technology stack and framework configurations
• Dependencies and package management details

Keep repo.md current!

Run the Repo Info Agent whenever you make significant changes like updating dependencies, modifying build systems, adding new architectural patterns, or introducing major framework changes.

This ensures that our agents have the most accurate understanding of your project.

Custom rules

• Coding standards and style guidelines
• File-specific conventions (using globs to target specific file types)
• Team processes and review requirements
• Conditional logic that applies only to certain directories or file patterns

Configuring Rule Folders

Compatible with other AI tools! If you’ve been using AI coding assistants like Cursor, Windsurf, Cline, or Continue, Zencoder can read your existing rules without migration. Simply configure Zencoder to search in their rule folders.

Zencoder always searches for rules in the .zencoder/rules folder by default. However, you can configure additional folders where Zencoder will look for AI rules (*.md and *.mdc files). This is particularly useful if:

• You’re switching from another AI coding tool and want to keep using your existing rules
• Your team has established rules in different locations
• You want to organize rules across multiple directories

Setting Up Additional Rule Folders

VS Code

To configure rule folders in VS Code:

1. Go to the Zencoder ⋯ (three-dot menu)
2. Click on Settings from the dropdown menu
3. In the sidebar, scroll down to find Zencoder: Rule Folders
4. You’ll see predefined folders for common AI tools:
   • .ai/rules
   • .cursor/rules
   • .clinerules
   • .windsurf/rules
   • .continue/rules
5. Click the Add Item button to add custom folders

The .zencoder/rules folder is always included regardless of this setting and cannot be removed.

Why This Matters

Seamless migration in cases where you’re switching from Cursor, Windsurf, Cline, Continue, or other AI tools - you don’t need to move or duplicate your existing rules. Zencoder will read them from their original locations.

Team flexibility matters and different team members might use different AI tools. By supporting multiple rule folders, everyone can contribute rules using their preferred tool’s conventions.

Backward compatibility is made easier if your existing workflows and rule structures remain intact while gaining access to Zencoder’s capabilities.

How It Works

When processing a request, Zencoder:

1. Always includes rules from .zencoder/rules (the default location)
2. Searches all configured additional folders for *.md and *.mdc files
3. Applies rules based on their frontmatter configuration (alwaysApply, globs, etc.)

Best Practices

Good rules are focused, actionable, and scoped to specific concerns. Think of them as internal documentation that guides both your team and the AI.

Writing Effective Rules

Keep it concise and specific. Aim for under 300 lines per rule and avoid broad instructions like “write good code” - the AI already knows general best practices. Instead, focus on your project’s specific requirements and patterns.

Use clear formatting. Structure your rules with bullet points, numbered lists, and markdown headers. This makes them easier for the AI to parse and follow:

# API Standards
- Use plural nouns for endpoints: `/users`, `/products`
- Version with prefix: `/api/v1/users`
- Always return consistent JSON structure

Group related concepts. In addition to markdown headers, HTML-like XML tags can help organize similar rules together:

<error_handling>
- Use appropriate HTTP status codes
- Include descriptive error messages
- Log errors with request context
</error_handling>

Organization Tips

Split large rules into multiple, composable files rather than creating monolithic documents. Use descriptive filenames like typescript-standards.md instead of generic names.

Use globs effectively to target specific directories or file types. This allows you to apply rules only where they are relevant, reducing noise in the AI’s context.

Turn repetitive prompts into rules - if you find yourself writing the same prompts over and over again, consider creating a rule file to capture that knowledge.

For complex workflows, if you’re facing increasingly complex and repeatable prompts that need to use different tools and MCPs, consider exploring Custom Agents for more advanced automation.

Team Workflow

Treat rule changes like code changes with proper review processes. Use clear descriptions in your frontmatter so team members understand each rule’s purpose and scope.

More questions about Zen Rules? Reach out to our community support.