How to customize GitLab Duo Agent Platform (opens in new tab)
The GitLab Duo Agent Platform provides a multi-layered framework for customizing AI behavior to align with specific team workflows and coding standards. By leveraging configuration files at the user, workspace, and project levels, teams can ensure that AI-driven assistance remains context-aware and adheres to internal development policies. This extensibility allows organizations to move from generic AI interactions to highly specialized automation that respects unique architectural patterns and security requirements. ### Levels of Customization GitLab offers a hierarchical approach to tailoring agent behavior, ensuring the right balance between global consistency and project-specific flexibility: * **User-level:** Personal preferences and rules applied across all projects, typically stored in the user’s home directory (e.g., `~/.gitlab/duo/`). * **Workspace-level:** Project-specific configurations located in the repository root that override user-level settings for that specific codebase. * **Project-level:** The creation of entirely custom agents and workflows managed within a specific project to handle complex, specialized tasks. ### Custom Rule Configuration Custom rules provide a mechanism to enforce specific coding styles and instructional sets without repeating prompts in every interaction. * **File implementation:** Rules are defined in `chat-rules.md` files located either in the user's home directory for global application or within the `.gitlab/duo/` directory for project-specific application. * **Functional scope:** They are best used for granular instructions such as forcing the use of the Vue 3 Composition API, requiring JSDoc comments for public functions, or mandating single quotes for strings. * **Governance:** Teams are encouraged to use GitLab Code Owners to manage who can approve changes to these rules, ensuring that AI behavior remains aligned with official team standards. ### Architectural Control with AGENTS.md The platform supports `AGENTS.md`, an industry-standard configuration file used to define broader agent personality, tone, and deep repository context. * **Versatility:** Unlike basic rules, `AGENTS.md` is consumed by both foundational and custom flows and can be understood by external agents like Claude Code. * **Contextual Depth:** These files can be placed in subdirectories to provide specific instructions for different parts of a monorepo, helping the agent understand complex folder structures and internal dependencies. * **Key Parameters:** It typically controls high-level preferences such as security protocols (e.g., "never suggest hardcoding secrets"), documentation requirements, and preferred tool usage. ### Technical Requirements and Deployment Implementing these customizations requires specific environment versions to ensure compatibility across the GitLab ecosystem. * **GitLab Version:** Requires GitLab 18.8 or later. * **IDE Support:** For VS Code users, the GitLab Workflow extension must be version 6.60 or later. * **Update Cycle:** Changes to `AGENTS.md` or custom rules generally require starting a new chat session or triggering a new flow to take effect. To achieve the best results, teams should adopt a "standardize-then-specialize" approach: establish global security and documentation rules at the user level, while using workspace-level `AGENTS.md` files to define the unique architectural patterns and tech stacks of individual projects.
