Skip to content

docs: update Repo Rules docs for automatic rule files + 25k budget + AgentTrace visibility #1185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jayhack merged 1 commit into from
Aug 7, 2025
Merged

docs: update Repo Rules docs for automatic rule files + 25k budget + AgentTrace visibility #1185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/settings/repo-rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,14 @@ Codegen automatically searches for the following types of rule files in your rep
- **`.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
- **`CLAUDE.md`**, **`AGENTS.md`**, **`AGENT.md`** - top-level docs commonly used to instruct AI agents

### How Automatic Detection Works

1. **File Discovery**: When you switch to a repository, Codegen uses `ripgrep` to search for files matching the supported patterns
2. **Content Extraction**: The content of discovered files is read and processed
3. **Size Limitation**: All rule files combined are truncated to fit within 3,000 characters total to ensure optimal performance
- **New**: The content is encoded to preserve formatting during transport, then decoded before being presented to the agent
3. **Size Limitation (25k global budget)**: All rule files combined are truncated to fit within a 25,000 character global budget to ensure optimal performance
4. **Context Integration**: The rule content is automatically included in the agent's context alongside any manual repository rules

### Example Rule Files
Expand Down Expand Up @@ -82,6 +84,10 @@ Prefer functional components over class components in React
- Include request/response validation
```

### Visibility in UI

When rules are discovered, they are displayed in the AgentTrace under the `SetActiveCodebase` 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
Expand All @@ -94,7 +100,7 @@ Prefer functional components over class components in React
</Tip>

<Warning>
If your rule files exceed 3,000 characters combined, they will be automatically truncated. Consider keeping rule files concise or splitting them into multiple focused files.
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.
</Warning>

## Common Use Cases and Examples
Expand Down
34 changes: 34 additions & 0 deletions docs/settings/repo-rules.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,40 @@ When an agent is assigned a task on a repository with defined rules, those rules

For example, if you have a rule like "Always use tabs for indentation," the agent will be reminded of this preference before it starts writing or modifying code in that repository.

## Automatic 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 discovery happens whenever the `set_active_codebase` tool initializes work on a repo.

### Supported Rule File Patterns

Codegen searches for the following patterns:

- **`.cursorrules`** (Cursor)
- **`.clinerules`** (Cline)
- **`.windsurfrules`** (Windsurf)
- **`**/*.mdc`** (any `.mdc` file in the repo)
- **`.cursor/rules/**/*.mdc`** (files under `.cursor/rules/`)
- **`CLAUDE.md`**, **`AGENTS.md`**, **`AGENT.md`** (top-level agent instruction docs)

### How it works

1. Discovery via `ripgrep`
2. Content is read and encoded to preserve formatting during transport, then decoded
3. A global size budget of **25,000 characters** is enforced across all discovered files
4. The resulting content is combined with your manual Repository Rules and provided to the agent

### Visibility in the UI

Discovered rule files are rendered in AgentTrace under the `SetActiveCodebase` tool card as "Repository Rules (Filesystem)". Expand entries to preview content and open the source on GitHub.

<Tip>
Automatic rule files are merged with manual Repository Rules to give the agent repository-specific context.
</Tip>

<Warning>
If discovered rule files exceed the global 25,000 character budget, content will be truncated. Keep files concise or split by area of concern.
</Warning>

## Accessing and Configuring Repository Rules

You can typically find and configure Repository Rules within the settings page for each specific repository in the Codegen web UI.
Expand Down