From 42cfe186f5091cc62a786c8581669e04d69b0e52 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Thu, 7 Aug 2025 22:26:08 +0000 Subject: [PATCH 1/2] docs: update Repo Rules docs for automatic rule files (CLAUDE.md, AGENTS.md) and 25k global budget; add AgentTrace visibility notes\n\nCo-authored-by: Jay Hack --- docs/settings/repo-rules.mdx | 10 ++++++++-- docs/settings/repo-rules.tsx | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/docs/settings/repo-rules.mdx b/docs/settings/repo-rules.mdx index cfacab723..2c79b5cd6 100644 --- a/docs/settings/repo-rules.mdx +++ b/docs/settings/repo-rules.mdx @@ -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 @@ -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 @@ -94,7 +100,7 @@ Prefer functional components over class components in React - 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. ## Common Use Cases and Examples diff --git a/docs/settings/repo-rules.tsx b/docs/settings/repo-rules.tsx index a78f4726c..8f2c49920 100644 --- a/docs/settings/repo-rules.tsx +++ b/docs/settings/repo-rules.tsx @@ -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. + + + Automatic rule files are merged with manual Repository Rules to give the agent repository-specific context. + + + + If discovered rule files exceed the global 25,000 character budget, content will be truncated. Keep files concise or split by area of concern. + + ## 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. From fffa7e6e1edf8b1984d570ca778e1e386eb29539 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Thu, 7 Aug 2025 22:43:25 +0000 Subject: [PATCH 2/2] docs: add Rules Overview (User/Org/Repo) with precedence; clarify hierarchy on Org + Repo pages; update nav\n\nCo-authored-by: Jay Hack --- docs/docs.json | 7 ++- docs/settings/organization-rules.mdx | 15 +++--- docs/settings/repo-rules.mdx | 2 +- docs/settings/rules-overview.mdx | 74 ++++++++++++++++++++++++++++ 4 files changed, 90 insertions(+), 8 deletions(-) create mode 100644 docs/settings/rules-overview.mdx diff --git a/docs/docs.json b/docs/docs.json index f5d8f21a6..7342075ef 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -57,7 +57,12 @@ }, { "group": "Settings", - "pages": ["settings/repo-rules", "settings/model-configuration"] + "pages": [ + "settings/rules-overview", + "settings/organization-rules", + "settings/repo-rules", + "settings/model-configuration" + ] } ] }, diff --git a/docs/settings/organization-rules.mdx b/docs/settings/organization-rules.mdx index 681be60bc..eee76a63f 100644 --- a/docs/settings/organization-rules.mdx +++ b/docs/settings/organization-rules.mdx @@ -19,13 +19,17 @@ When you define Organization Rules, they are automatically applied to every agen ## Rule Hierarchy -Organization Rules work in conjunction with Repository Rules to provide flexible rule management: +Organization Rules work in conjunction with User Rules and Repository Rules to provide flexible rule management: -1. **Organization Rules** are applied first as the baseline for all repositories -2. **Repository Rules** can override or extend Organization Rules for specific repositories -3. If both are defined, Repository Rules take precedence for conflicting instructions +1. **Repository Rules** (most specific) take precedence over Organization and User Rules for that repository +2. **Organization Rules** apply across the org and override User Rules +3. **User Rules** (personal prompts) apply by default, unless overridden by Org or Repo rules -This hierarchy allows you to set organization-wide defaults while still maintaining repository-specific customizations when needed. +This hierarchy allows you to set organization-wide defaults while still maintaining repository-specific customizations when needed, while preserving user preferences where they don't conflict. + + +For a complete overview of rule types and examples, see [Rule Types & Precedence](/settings/rules-overview). + ## Setting Up Organization Rules @@ -115,4 +119,3 @@ If the agent isn't following your rules as expected: - **[Model Configuration](/settings/model-configuration)**: Configure which AI model the agent uses Organization Rules provide a powerful way to maintain consistency across your entire organization while still allowing flexibility for individual repositories. Use them to establish your organization's coding culture and ensure all agent interactions align with your standards. - diff --git a/docs/settings/repo-rules.mdx b/docs/settings/repo-rules.mdx index 2c79b5cd6..d14e5f86b 100644 --- a/docs/settings/repo-rules.mdx +++ b/docs/settings/repo-rules.mdx @@ -130,5 +130,5 @@ Repository rules are flexible and can be used for various purposes: - Both manual repository rules and automatic rule files are applied *in addition* to any global prompting strategies or agent capabilities. They provide a repository-specific layer of instruction that helps ensure consistent behavior across your codebase. + For how Repository Rules interact with Organization and User Rules, see [Rule Types & Precedence](/settings/rules-overview). {" "} diff --git a/docs/settings/rules-overview.mdx b/docs/settings/rules-overview.mdx new file mode 100644 index 000000000..4c13d9747 --- /dev/null +++ b/docs/settings/rules-overview.mdx @@ -0,0 +1,74 @@ +--- +title: "Rules Overview" +sidebarTitle: "Rule Types & Precedence" +icon: "layers" +--- + +Codegen supports three levels of rules that guide how the agent behaves. These rules are merged for every run and can override one another based on a clear precedence order. + +## The three rule types + +### 1) User Rules (Personal Prompts) +- Where: Managed by each user at https://codegen.com/personal/prompts +- Scope: Apply to runs initiated by that user, across all organizations and repositories they work on +- Purpose: Personal preferences, style, and reminders (e.g., preferred commit style, tone for PR descriptions) + +### 2) Organization Rules +- Where: Organization settings at https://codegen.com/settings/organization-rules +- Scope: Apply to every repo and run in the organization +- Purpose: Governance, security, and team-wide standards (e.g., no force-push, testing/coverage requirements) + +### 3) Repository Rules +- Where: Repo settings at your repo page (e.g., https://codegen.com/repos/cloud/repo-rules) +- Scope: Apply only to that repository +- Purpose: Project- or repo-specific conventions and constraints (e.g., language choices, directory layout, commit prefixes) + + + In addition to manual Repository Rules, Codegen auto-discovers rule files in the repo (e.g., `.cursorrules`, `.clinerules`, `.windsurfrules`, `**/*.mdc`, `.cursor/rules/**/*.mdc`, `CLAUDE.md`, `AGENTS.md`, `AGENT.md`). These are included with a global 25,000-character budget and are visible in AgentTrace under the SetActiveCodebase tool as "Repository Rules (Filesystem)". + + +## Precedence (who wins on conflict?) +When rules conflict, the more specific layer wins. + +1. Repository Rules (most specific) +2. Organization Rules +3. User Rules (least specific) + +This means: +- Repo Rules can override Org Rules and User Rules +- Org Rules can override User Rules +- User Rules provide defaults and personal preferences, but will not override Org/Repo mandates + + + This precedence ensures company-wide standards remain enforceable (Org Rules), while still allowing repositories to refine their own specific conventions (Repo Rules). User Rules help maintain personal productivity and consistency without breaking org or repo policies. + + +## Examples + +- Example A: Commit messages + - User Rules: "Use short, descriptive commit subjects." + - Org Rules: "Follow Conventional Commits." + - Repo Rules: "Prefix commits with the service name (e.g., api:)." + - Result: The agent uses Conventional Commits with the repo-required prefix; the user’s personal preferences apply where they don’t conflict. + +- Example B: Force pushing + - User Rules: none + - Org Rules: "Never use git push --force." + - Repo Rules: none + - Result: The agent will not force push, even if asked in a user prompt. + +- Example C: Language choice + - User Rules: "Prefer TypeScript." + - Org Rules: none + - Repo Rules: "Write backend in Python (FastAPI)." + - Result: For this repo, the agent writes backend code in Python per repo policy; the user preference applies elsewhere. + +## Where to configure +- User Rules: https://codegen.com/personal/prompts +- Organization Rules: https://codegen.com/settings/organization-rules +- Repository Rules: Your repo page, e.g., https://codegen.com/repos/cloud/repo-rules + +## Related docs +- [Organization Rules](/settings/organization-rules) +- [Repository Rules](/settings/repo-rules) +