How Agent Rules Work
When an agent starts working, it receives all applicable rules as text prompts in its context:- User Rules - Your personal coding preferences and style
- Organization Rules - Organization-wide standards and conventions
- Repository Rules - Project-specific requirements and guidelines
Rules are text prompts, not strict settings. Agents use them as guidance
alongside the specific task you’ve given them.
Codegen automatically detects
AGENTS.md
and other rules files. Learn
moreAutomatic Rule File Detection
In addition to manual repository rules, Codegen automatically discovers and includes agent rule files from your repository when the agent starts working on it. This happens automatically whenever theset_active_codebase
tool is used.
Supported Rule File Patterns
Codegen automatically searches for the following types of rule files in your repository:You can customize which rule file patterns to match by configuring glob
patterns in your repository settings at
codegen.com/repos (select your repository, then
configure rule file patterns).
AGENTS.md
- preferred default. Learn moreCLAUDE.md
- Claude assistant rules.cursorrules
- Cursor AI editor rules.clinerules
- Cline AI assistant rules.windsurfrules
- Windsurf AI editor rules**/\*.mdc
- Markdown files with.mdc
extension anywhere in the repository.cursor/rules/**/\*.mdc
- Markdown files in the.cursor/rules/
directory structure
How Automatic Detection Works
- File Discovery: When you switch to a repository, Codegen uses
ripgrep
to search for files matching the supported patterns - Content Extraction: The content of discovered files is read and processed
- New: The content is encoded to preserve formatting during transport, then decoded before being presented to the agent
- Size Limitation (25k global budget): All rule files combined are truncated to fit within a 25,000 character global budget to ensure optimal performance
- Context Integration: The rule content is automatically included in the agent’s context alongside any manual repository rules
Example Rule Files
Here are examples of how you might structure agent rules in your repository:AGENTS.md
example:
Visibility in UI
When rules are discovered, they are displayed in the AgentTrace under theSetActiveCodebase
tool card as “Repository Rules (Filesystem)”. You can expand each entry to preview the content and open the source file on GitHub.
Benefits of Automatic Rule Files
- Version Control: Rule files are committed with your code, ensuring consistency across team members
- Repository-Specific: Different repositories can have different rule files without manual configuration
- Developer-Friendly: Developers can manage rules using familiar file-based workflows
- Editor Integration: Many AI-powered editors already support these file formats
Automatic rule files work alongside manual repository rules. Both types of
rules are combined and provided to the agent for maximum context.
If your rule files exceed the global 25,000 character budget, they will be
truncated per-file and/or at the aggregate level. Keep rule files concise or
split them into focused files.
Common Use Cases and Examples
Agent rules are flexible and can be used for various purposes across different levels:User-Level Rules Examples
Perfect for personal preferences that should apply across all your work:- Personal Coding Style:
- “I prefer functional programming patterns over object-oriented when possible.”
- “Always include detailed JSDoc comments for functions with more than 2 parameters.”
- Workflow Preferences:
- “Include performance considerations in code reviews for any loops or database queries.”
- “Prefer explicit error handling over try-catch blocks when the error is expected.”
- Tool Preferences:
- “Use my preferred linting configuration and code formatting style.”
- “Always suggest using TypeScript strict mode for new projects.”
Organization-Level Rules Examples
Perfect for organization-wide standards that should apply to all repositories:- Coding Standards:
- “All code must follow our organization’s style guide. Use Prettier for JavaScript/TypeScript formatting.”
- “All API endpoints must include proper error handling and logging.”
- Security Requirements:
- “Never commit API keys, passwords, or other secrets to the repository.”
- “All database queries must use parameterized statements to prevent SQL injection.”
- Process Requirements:
- “All commit messages must follow the Conventional Commits specification.”
- “Every PR must include tests for new functionality.”
Repository-Level Rules Examples
Perfect for repository-specific requirements that may override organization defaults:- Technology-Specific Rules:
- “This is a Python project. Use
black
for formatting andpytest
for testing.” - “This legacy repository uses JavaScript instead of our organization’s TypeScript standard.”
- “This is a Python project. Use
- Project-Specific Information:
- “All new backend code should be in the
/server/src
directory.” - “Avoid using deprecated function
old_function()
. Usenew_function()
instead.”
- “All new backend code should be in the
- Build and Deployment:
- “Run
npm run build
before committing to ensure the build passes.” - “This repository deploys automatically on merge to main - ensure all tests pass.”
- “Run