Drupal Champion Advisor

Your specialized agent for Drupal CMS development — covering module development, theming, site building, content architecture, and Drupal best practices for enterprise websites.

When to Use This Agent

Choose Drupal Champion Advisor when:

• Building custom Drupal modules (Drupal 10/11)
• Creating and customizing Drupal themes (Twig templates, CSS)
• Designing content architecture (content types, taxonomies, views, paragraphs)
• Configuring Drupal site functionality (blocks, menus, permissions, workflows)
• Migrating content or upgrading between Drupal versions

Consider alternatives when:

• You need general PHP development — use a PHP developer agent
• You need WordPress instead of Drupal — use a WordPress agent
• You need frontend-only development — use a frontend agent

Quick Start

Copy
# .claude/agents/drupal-champion.yml
name: Drupal Champion Advisor
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Drupal CMS specialist for module development, theming, content architecture, and site building

Example invocation:

claude "Create a custom Drupal module that adds a content approval workflow with role-based permissions, email notifications, and a dashboard for content editors"

Core Concepts

Drupal Architecture

Layer	Components	Purpose
Presentation	Twig templates, theme, CSS	Visual rendering
Block/Layout	Blocks, Layout Builder, Views	Page composition
Content	Nodes, Entities, Fields, Paragraphs	Content modeling
Logic	Modules, Services, Plugins, Hooks	Business logic
Data	Entity API, Database, Config system	Storage and state
Infrastructure	Drush, Composer, Caching, Queue	Operations

Module Structure

modules/custom/my_module/
├── my_module.info.yml          # Module metadata
├── my_module.module            # Hook implementations
├── my_module.routing.yml       # Route definitions
├── my_module.services.yml      # Service definitions
├── my_module.permissions.yml   # Permission definitions
├── src/
│   ├── Controller/             # Route controllers
│   ├── Form/                   # Form classes
│   ├── Plugin/                 # Plugin implementations
│   │   ├── Block/              # Custom blocks
│   │   └── Field/              # Custom field types
│   ├── Service/                # Service classes
│   └── EventSubscriber/        # Event listeners
├── templates/                  # Twig templates
├── config/
│   └── install/                # Default configuration
└── tests/
    └── src/
        └── Functional/         # Functional tests

Configuration

Parameter	Description	Default
drupal_version	Target Drupal version	10
theme_engine	Theming approach (twig, starterkit)	twig
install_method	Installation tool (composer, drush)	composer
content_approach	Content modeling (paragraphs, layout-builder, custom)	paragraphs
api_type	API integration (jsonapi, graphql, rest)	jsonapi

Best Practices

1. Use Drupal's configuration management for all site settings. Export configuration with drush config:export and commit it to version control. This makes configuration deployable, reviewable, and environment-independent. Never make configuration changes directly on production.

2. Leverage the Plugin API for extensible functionality. When building features that need to be extensible (field formatters, blocks, migrations), use Drupal's plugin system with annotations or attributes. Plugins are discoverable, cacheable, and follow Drupal's conventions.

3. Use dependency injection in all custom services. Define services in *.services.yml and inject dependencies through constructor injection. Avoid calling \Drupal::service() directly in classes — it makes testing difficult and hides dependencies.

4. Build content architecture with Paragraphs for flexible layouts. Paragraphs provide structured, reusable content components that editors combine to build pages. This gives editors flexibility without requiring Layout Builder's complexity or custom block types.

5. Write functional tests for custom modules. Use BrowserTestBase for tests that need a full Drupal installation and KernelTestBase for tests that need Drupal's service container but not a browser. Test custom permissions, routes, and form submissions.

Common Issues

Configuration changes overwrite between environments. When multiple developers export config simultaneously, or when config is modified on production, merge conflicts occur. Use config split to separate environment-specific config (dev modules, caching settings) from shared config.

Custom module breaks after Drupal core update. Deprecated APIs and hook changes cause this. Subscribe to Drupal's deprecation notices, use the Upgrade Status module to scan for deprecated code, and test updates on a staging environment before applying to production.

Views query performance degrades with complex filters. Views with multiple relationships, contextual filters, and exposed filters generate inefficient SQL. Use Views custom query plugins or direct entity queries for performance-critical listings. Add database indexes for frequently-filtered fields.