From 5d78f4882bf68948e6ce1f5506fbd5443990b047 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Sun, 14 Sep 2025 22:22:54 +0000 Subject: [PATCH 1/2] Update repo rules docs to include organization rules and rule hierarchy - Renamed from 'Repository Rules' to 'Agent Rules' to reflect broader scope - Added comprehensive explanation of organization rules vs repository rules - Documented rule hierarchy: repository rules override organization rules - Added detailed configuration instructions for both rule types - Included practical examples showing rule hierarchy in action - Updated use cases to show organization-level vs repository-level examples --- docs/settings/repo-rules.mdx | 127 +++++++++++++++++++++++++---------- 1 file changed, 93 insertions(+), 34 deletions(-) diff --git a/docs/settings/repo-rules.mdx b/docs/settings/repo-rules.mdx index 2c79b5cd6..bce6c9431 100644 --- a/docs/settings/repo-rules.mdx +++ b/docs/settings/repo-rules.mdx @@ -1,39 +1,80 @@ --- -title: "Repository Rules" -sidebarTitle: "Repo Rules" +title: "Agent Rules" +sidebarTitle: "Agent Rules" icon: "shield-check" --- -Repository Rules in Codegen act as a persistent set of instructions or a "system prompt" for the AI agent whenever it operates on a specific repository. These rules guide the agent's behavior by enforcing coding standards and repository-specific conventions through automated reminders to the language model (LLM) during each task. +Agent Rules in Codegen act as persistent instructions or "system prompts" for the AI agent, guiding its behavior by enforcing coding standards, conventions, and preferences. These rules are automatically included in the agent's context during each task to ensure consistent behavior across your organization and repositories. -Codegen supports two types of repository rules: -1. **Manual Repository Rules** - configured through the web interface -2. **Automatic Rule File Detection** - automatically discovered from your repository files +## Rule Hierarchy + +Codegen supports a hierarchical rule system with two levels: + +1. **Organization Rules** - Apply to all repositories within your organization +2. **Repository Rules** - Apply to a specific repository and override organization rules when conflicts exist + + + **Rule Precedence**: Repository rules take precedence over organization rules when conflicts exist. This allows you to set organization-wide defaults while customizing specific repositories as needed. + + +## Types of Rules + +Each level supports two types of rule configuration: + +### Manual Rules +Rules configured directly through the Codegen web interface at [codegen.com/repos](https://codegen.com/repos) (for repository rules) or organization settings (for organization rules). + +### Automatic Rule File Detection +Rules automatically discovered from files in your repository (repository level only). -## How Repository Rules Work +## How Agent Rules Work + +When an agent is assigned a task, all applicable rules are automatically included in the agent's context as "Mandatory User Rules." The agent sees these rules alongside the actual task or prompt it receives, ensuring consistent behavior. + +**Rule Resolution Process:** +1. **Organization Rules** are loaded first (if configured for your organization) +2. **Repository Rules** are loaded next (if configured for the specific repository) +3. **Repository rules override organization rules** when conflicts exist +4. **Automatic rule files** are discovered and included (repository level only) +5. All rules are combined and presented to the agent as mandatory constraints -When an agent is assigned a task on a repository with defined rules, those rules are automatically prepended or made available to the LLM as part of its context. This means the agent "sees" these rules alongside the actual task or prompt it receives. +For example, if your organization has a rule "Use TypeScript for all new code" and a specific repository has a rule "Use JavaScript for this legacy project," the repository rule takes precedence for that specific repository. -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. +## Configuring Agent Rules -## Accessing and Configuring Repository Rules +### Organization Rules -You can typically find and configure Repository Rules within the settings page for each specific repository in the Codegen web UI. +Organization rules apply to all repositories within your organization and serve as default behavior guidelines. -1. Navigate to [codegen.com/repos](https://codegen.com/repos). -2. Select the repository for which you want to set rules. -3. Look for a section titled "Repository rules" or similar in the repository's settings. +**To configure organization rules:** +1. Navigate to your organization settings in the Codegen web interface +2. Look for the "Organization Rules" section +3. Enter your organization-wide rules in the text area +4. Click "Save" to apply them to all repositories in your organization + + + Organization rules are perfect for setting coding standards, commit message conventions, or testing requirements that should apply across all your repositories. + + +### Repository Rules + +Repository rules apply to a specific repository and override any conflicting organization rules. + +**To configure repository rules:** +1. Navigate to [codegen.com/repos](https://codegen.com/repos) +2. Select the repository for which you want to set rules +3. Look for the "Repository Rules" section in the repository's settings +4. Enter your repository-specific rules in the text area +5. Click "Save" to apply them -In the text area provided (as shown in the image), you can specify any rules you want the agent to follow for this repository. Click "Save" to apply them. - ## 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 happens automatically whenever the `set_active_codebase` tool is used. @@ -105,30 +146,48 @@ When rules are discovered, they are displayed in the AgentTrace under the `SetAc ## Common Use Cases and Examples -Repository rules are flexible and can be used for various purposes: +Agent rules are flexible and can be used for various purposes across different levels: + +### Organization-Level Rules Examples + +Perfect for organization-wide standards that should apply to all repositories: -- **Enforcing Linting/Formatting:** - - "Remember to run the linter with `npm run lint` before committing." - - "Ensure all Python code follows PEP 8 guidelines. Use `black` for formatting." -- **Specifying Commit Message Conventions:** +- **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." - - "Prefix commit messages with the related Linear issue ID (e.g., `ENG-123: ...`)." -- **Highlighting Project-Specific Information:** - - "This repository uses TypeScript. All new backend code should be in the `/server/src` directory." + - "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 and `pytest` for testing." + - "This legacy repository uses JavaScript instead of our organization's TypeScript standard." +- **Project-Specific Information:** + - "All new backend code should be in the `/server/src` directory." - "Avoid using deprecated function `old_function()`. Use `new_function()` instead." -- **Code Style Preferences:** - - "Don't write super long strings, as this will break pre-commit. Do triple-quoted strings with newlines, non-indented, instead!" (As seen in your example image) - - "Prefer functional components over class components in React." -- **Reminders for Testing:** - - "Ensure all new features have corresponding unit tests." - - "Run integration tests with `npm run test:integration` after significant changes." +- **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." + +### Rule Hierarchy in Action + +Here's how organization and repository rules work together: + +**Organization Rule:** "Use TypeScript for all new code" +**Repository Rule:** "This legacy project uses JavaScript - do not convert existing files" +**Result:** The agent will use JavaScript for this specific repository while using TypeScript for all other repositories in the organization. - Keep your repository rules concise and clear. Overly complex or numerous rules - might confuse the agent or lead to suboptimal performance. Focus on the most - critical guidelines for each repository. + Keep your rules concise and clear. Overly complex or numerous rules might confuse the agent or lead to suboptimal performance. Focus on the most critical guidelines for your organization and repositories. - 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. + All agent rules (organization, repository, and automatic rule files) are applied *in addition* to any global prompting strategies or agent capabilities. They provide a hierarchical layer of instruction that helps ensure consistent behavior across your organization and codebases. {" "} From 570b4facd8f029c74122f81877b1a35570eeb9f9 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Sun, 14 Sep 2025 23:18:43 +0000 Subject: [PATCH 2/2] Add user rules to agent rules documentation - Added user rules as the first level in the three-tier hierarchy - Updated rule precedence: Repository > Organization > User - Added user rules configuration section with 'Coming Soon' note - Included user-level rule examples for personal preferences - Updated rule resolution process to include all three levels - Enhanced hierarchy examples to show user, org, and repo rules working together Co-authored-by: Jay Hack --- docs/settings/repo-rules.mdx | 61 ++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 13 deletions(-) diff --git a/docs/settings/repo-rules.mdx b/docs/settings/repo-rules.mdx index bce6c9431..000d47d59 100644 --- a/docs/settings/repo-rules.mdx +++ b/docs/settings/repo-rules.mdx @@ -8,13 +8,14 @@ Agent Rules in Codegen act as persistent instructions or "system prompts" for th ## Rule Hierarchy -Codegen supports a hierarchical rule system with two levels: +Codegen supports a hierarchical rule system with three levels: -1. **Organization Rules** - Apply to all repositories within your organization -2. **Repository Rules** - Apply to a specific repository and override organization rules when conflicts exist +1. **User Rules** - Personal preferences that apply to all your work across organizations +2. **Organization Rules** - Apply to all repositories within your organization +3. **Repository Rules** - Apply to a specific repository and override higher-level rules when conflicts exist - **Rule Precedence**: Repository rules take precedence over organization rules when conflicts exist. This allows you to set organization-wide defaults while customizing specific repositories as needed. + **Rule Precedence**: Repository rules take precedence over organization rules, which take precedence over user rules when conflicts exist. This allows you to set personal defaults, organization-wide standards, and repository-specific customizations. ## Types of Rules @@ -36,16 +37,35 @@ Rules automatically discovered from files in your repository (repository level o When an agent is assigned a task, all applicable rules are automatically included in the agent's context as "Mandatory User Rules." The agent sees these rules alongside the actual task or prompt it receives, ensuring consistent behavior. **Rule Resolution Process:** -1. **Organization Rules** are loaded first (if configured for your organization) -2. **Repository Rules** are loaded next (if configured for the specific repository) -3. **Repository rules override organization rules** when conflicts exist -4. **Automatic rule files** are discovered and included (repository level only) -5. All rules are combined and presented to the agent as mandatory constraints +1. **User Rules** are loaded first (if configured in your personal settings) +2. **Organization Rules** are loaded next (if configured for your organization) +3. **Repository Rules** are loaded next (if configured for the specific repository) +4. **Higher-level rules override lower-level rules** when conflicts exist (Repository > Organization > User) +5. **Automatic rule files** are discovered and included (repository level only) +6. All rules are combined and presented to the agent as mandatory constraints -For example, if your organization has a rule "Use TypeScript for all new code" and a specific repository has a rule "Use JavaScript for this legacy project," the repository rule takes precedence for that specific repository. +For example, if you have a user rule "Always use semicolons in JavaScript," your organization has a rule "Use TypeScript for all new code," and a specific repository has a rule "Use JavaScript for this legacy project," the repository rule takes precedence, followed by the organization rule, then your personal user rule. ## Configuring Agent Rules +### User Rules + +User rules are personal preferences that apply to all your work across organizations. These are perfect for setting your individual coding style, preferred tools, or workflow preferences. + +**To configure user rules:** +1. Navigate to your personal settings in the Codegen web interface +2. Look for the "User Rules" or "Personal Agent Rules" section +3. Enter your personal preferences and coding standards +4. Click "Save" to apply them across all organizations and repositories you work with + + + User rules are ideal for personal preferences like "Always include detailed commit messages," "Prefer functional programming patterns," or "Use specific linting configurations." + + + + **Coming Soon**: User-level rules are currently being implemented and will be available in an upcoming release. The infrastructure is in place, and this feature will allow you to set personal coding preferences that follow you across all organizations. + + ### Organization Rules Organization rules apply to all repositories within your organization and serve as default behavior guidelines. @@ -148,6 +168,20 @@ When rules are discovered, they are displayed in the AgentTrace under the `SetAc 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: @@ -178,16 +212,17 @@ Perfect for repository-specific requirements that may override organization defa ### Rule Hierarchy in Action -Here's how organization and repository rules work together: +Here's how user, organization, and repository rules work together: +**User Rule:** "I prefer detailed error messages with context" **Organization Rule:** "Use TypeScript for all new code" **Repository Rule:** "This legacy project uses JavaScript - do not convert existing files" -**Result:** The agent will use JavaScript for this specific repository while using TypeScript for all other repositories in the organization. +**Result:** The agent will use JavaScript for this specific repository (repository rule wins), but will still include detailed error messages (user rule applies) since there's no conflict. Keep your rules concise and clear. Overly complex or numerous rules might confuse the agent or lead to suboptimal performance. Focus on the most critical guidelines for your organization and repositories. - All agent rules (organization, repository, and automatic rule files) are applied *in addition* to any global prompting strategies or agent capabilities. They provide a hierarchical layer of instruction that helps ensure consistent behavior across your organization and codebases. + All agent rules (user, organization, repository, and automatic rule files) are applied *in addition* to any global prompting strategies or agent capabilities. They provide a hierarchical layer of instruction that helps ensure consistent behavior across your personal work, organization, and codebases. {" "}