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 rulesStored in .zencoder/rules/*.md files in your repository. Applied conditionally based on file patterns or always when specified.

Instructions for AI

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

Repo Info

Generated contextCreated 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/:GitHub commit showing files moved from .zencoder/docs to .zencoder/rules during migration

​
2. Create Your First Rule

Create a new markdown file in the rules directory. Here’s an example using the actual markdown-writing-styles.md rule from this repository: 
---
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 (-)

​
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: Zen Rules mentioning interface showing @ dropdown with Zen Rules option and 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.

​
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

FieldRequiredDescription
descriptionYesBrief 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"
globsNoArray of file patterns that trigger this rule. Rule is automatically included when working with matching files. Examples: ["*.ts", "*.tsx"], ["src/**/*.js"], ["*.md", "*.mdx"]
alwaysApplyNoBoolean (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:

​
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

​
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.