Custom rules | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions GitLab Duo Agent Platform Getting started Tutorials Availability Agentic Chat AI Catalog Agents Flows Sessions Customization Custom rules AGENTS.md Agent Skills Custom review instructions Code Suggestions Models Contextual awareness Composite identity Authentication Security threats Model Context Protocol Semantic code search Troubleshooting GitLab Duo Non-Agentic Data usage * GitLab Docs / * GitLab Duo / * GitLab Duo Agent Platfor… / * Customization / * Custom rules Help us learn about your current experience with the documentation. Take the survey . Custom rules * Tier : Premium, Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated History * Custom rules added in GitLab 18.2. * Introduced in GitLab for VS Code 6.32.2. * Introduced in the GitLab Duo plugin for JetBrains IDEs 3.12.2. * Introduced in GitLab for Visual Studio 0.60.0. * Introduced in GitLab Duo CLI 8.43.0. * User-level custom rules added in GitLab 18.7. * Generally available in GitLab 18.8. * Support for GitLab UI introduced in GitLab 18.11. You can use custom rules in the GitLab Duo Agent Platform to ensure that generated output (for example, code or documentation) aligns with your specific instructions, or any other requirements such as development style guides. The following Agent Platform features support custom rules: * GitLab Duo Agentic Chat in the GitLab UI and your local environment. * Foundational and custom agents . * Foundational and custom flows , excluding Code Review Flow. Create custom rules You can create custom rules at two levels, depending on how you use GitLab Duo: Level GitLab UI Editor extensions GitLab Duo CLI User-level: Apply to all of your projects No Project-level: Apply only to a specific project If you use a multi-root workspace in your IDE, you can create project-level custom rules for each project in the workspace. If both user-level and project-level rules exist, GitLab Duo Chat applies both to conversations. Prerequisites: * Meet the Agent Platform prerequisites . * For GitLab Duo in your local environment, install and configure one of the following: * GitLab for VS Code 6.32.2 or later. * GitLab Duo plugin for JetBrains IDEs 3.12.2 or later. * GitLab for Visual Studio 0.60.0 or later. * GitLab Duo CLI 8.43.0 or later. Conversations that existed before you created any custom rules do not follow those rules. Create user-level custom rules User-level custom rules apply to all of your projects in your local environment. * Create a custom rules file in your home directory: * On Linux or macOS, create the file at ~/.gitlab/duo/chat-rules.md . * On Windows, create the file at %APPDATA%\GitLab\duo\chat-rules.md . * Add custom rules to the file. For example: - Don't put comments in the generated code - Be brief in your explanations - Always use single quotes for JavaScript strings * Save the file. * To apply the new custom rules, do any of the following as appropriate: * Start a new GitLab Duo Chat conversation. * Use an agent in a Chat conversation, discussion, issue, or merge request. * Trigger a flow. If you have set a specific environment variable, then you create the custom rules file in a different location: * If you have set the GLAB_CONFIG_DIR environment variable, create the file at $GLAB_CONFIG_DIR/chat-rules.md . * If you have set the XDG_CONFIG_HOME environment variable, create the file at $XDG_CONFIG_HOME/gitlab/duo/chat-rules.md . Create project-level custom rules Project-level custom rules apply only to a specific project. You can use this method to apply a set of custom rules to the project for your team. For example, you can apply a set of development style guides that your team uses. * In the root of your project, create a custom rules file: .gitlab/duo/chat-rules.md . * Add custom rules to the file. For example: - Don't put comments in the generated code - Be brief in your explanations - Always use single quotes for JavaScript strings * Save the file. * For a project: Add the .gitlab/duo/chat-rules.md file to the Git repository. Chat, agents, and flows then automatically read the custom rules from the repository into context. * To apply the new custom rules, start a new GitLab Duo conversation. You must do this every time you change the custom rules. For more information, see the Custom rules in GitLab Duo Chat tutorial blog . Update custom rules To update your custom rules, edit and save the custom rules file. Then, start a new GitLab Duo conversation to apply the updated rules. You cannot use Chat to edit your custom rules file directly. To manage who must approve any changes to custom rules, use Code Owners . Related topics * AGENTS.md customization files * Agent Skills * Create custom rules * Create user-level custom rules * Create project-level custom rules * Update custom rules * Related topics * Facebook * LinkedIn * Twitter * YouTube Company * About GitLab * View pricing * Try GitLab for free Feedback * View page source * Edit in Web IDE * Contribute to GitLab * Suggest updates Help & Community * Get certified * Get support * Post on the GitLab forum Resources * Terms * Privacy statement * Use of generative AI * Acceptable use of user licenses *