The difference between a migration that finishes on time and one that doesn’t often comes down to decision quality under pressure. When a developer hits a fork in the road — migrate this in place, or rewrite? Use Block List or Block Grid for this content type? How should this custom property editor map to the new architecture? — the speed and quality of that decision matters.
AI doesn’t replace the judgment needed to make those decisions. But used correctly, it compresses the research-and-deliberation cycle significantly, and ADRs preserve the decision record for the next time the same question comes up.
This post covers the AI-and-ADR workflow we use in Umbraco migration projects: how Umbraco 17’s built-in Developer MCP changes what AI can do directly, the prompt patterns that work, and the ADR templates that make migration decisions durable.
Umbraco 17’s Developer MCP: What It Changes
Umbraco 17 ships with a built-in Model Context Protocol (MCP) server for developers. This is the same protocol that Claude, GitHub Copilot, and other AI tools use to connect to external data sources.
What this means in practice: your AI assistant can directly query your Umbraco instance during development. Not just read your source code — it can read your actual running Umbraco site’s schema, content types, properties, and media structure.
What the Developer MCP exposes:
- All document types and their properties
- Data type configurations
- Content tree structure
- Member types
- Routes and URL mappings
- Settings and configuration
Enabling the Developer MCP:
// appsettings.Development.json
{
"Umbraco": {
"CMS": {
"Global": {
"McpConfiguration": {
"Enabled": true,
"ApiKey": "your-development-mcp-key"
}
}
}
}
}Connecting Claude Desktop to Umbraco Developer MCP:
// claude_desktop_config.json
{
"mcpServers": {
"umbraco": {
"url": "http://localhost:5000/umbraco/api/mcp",
"apiKey": "your-development-mcp-key"
}
}
}Once connected, you can ask Claude questions about your live Umbraco site:
“What document types currently use the Block List editor? For each one, what element types are configured as allowed blocks?”
“Generate a strongly typed model extension for the ArticlePage document type using the exact property aliases and types from the connected Umbraco instance.”
“I need to add a hero block to the LandingPage document type. What block element types are reused across other document types that I should consider for consistency?”
This is a qualitative shift from AI working with code — it’s AI working with your live content model.
The AI Champion Workflow for Umbraco Teams
On a migration project with 3–10 developers, having everyone prompt AI independently creates inconsistency. The AI Champion model addresses this.
The AI Champion Role
One developer per project takes on the AI Champion responsibility:
- Owns the prompt library for the project (a living document, versioned in git)
- Evaluates AI output quality and updates prompts when output quality degrades
- Identifies new high-value AI tasks as migration work reveals them
- Serves as the review point for any AI-generated code before it merges
The Champion doesn’t write all the AI prompts — they manage the system so that AI assistance is multiplied across the team, not idiosyncratic per developer.
The Prompt Library Structure
/docs/
/ai-prompts/
assessment/
01-version-env-audit.md
02-content-type-inventory.md
03-template-audit.md
migration/
04-usync-migration-report.md
05-nested-content-converter.md
06-surface-controller-conversion.md
07-template-conversion.md
review/
08-block-list-review.md
09-ci-validation.md
README.mdEach prompt file contains:
- The prompt template (with
[PLACEHOLDER]variables) - A description of what it produces
- Example output for calibration
- Known limitations and when not to use it
High-Value Prompt Patterns for Umbraco Migration
1. Document Type Analysis (Assessment Phase)
You are analyzing an Umbraco content type structure for migration complexity.
Here is the uSync export XML for our document types:
[paste XML]
For each document type, provide:
1. Name and alias
2. Properties and their data types
3. Whether it uses Nested Content, Grid, or any deprecated editors
4. Inheritance chain (if any)
5. Estimated migration complexity: Low / Medium / High / Requires Custom Work
6. Recommended action: Direct migrate / Convert properties / Rebuild
Format as a markdown table.2. Nested Content to Block List Map Generator
I need to create a Block List migration plan for these Nested Content elements from our
Umbraco project.
Nested Content document types and their properties:
[paste doc type list with properties]
For each Nested Content element type:
1. Suggest an equivalent Block List element type structure
2. List any properties that map 1:1 vs. properties that need transformation
3. Identify any properties that were stored as JSON sub-properties inside Nested Content
that need to become first-class properties in Block List
4. Suggest the uSync Migrations configuration for this mapping
Output as a migration mapping table followed by the uSync migration config YAML.3. Surface Controller Batch Conversion
Convert these Umbraco 8 / .NET Framework Surface Controllers to Umbraco 17 / .NET 10.
Rules:
- Use constructor dependency injection for all services
- Replace all static helper calls (ApplicationContext, UmbracoContext.Current) with injected equivalents
- Use async/await on all I/O operations
- Add ILogger<T> for all logging (remove LogHelper)
- Preserve all business logic and form handling — only modernize the framework layer
- Output each converted controller in a separate fenced code block
[paste controllers]4. CI Validation Report Prompt
This prompt runs against the build log after a migration step:
Here is the build output and test results from our Umbraco 17 migration step.
Build output:
[paste dotnet build output]
Test results:
[paste test output]
Please:
1. Identify any build errors related to deprecated APIs (list them in priority order)
2. Identify any test failures with likely root cause
3. For each issue, suggest the specific code fix
4. List any warnings that may become errors in future .NET versions5. Umbraco Developer MCP Prompt (v17 only)
When connected via MCP to a running Umbraco 17 instance:
Using the connected Umbraco instance:
1. List all document types that have Block List properties and their configured element types
2. Find any document types using composition document types — list the compositions
3. Generate a Mermaid class diagram showing the document type inheritance tree
4. For the LandingPage document type, show all properties with their types and aliases —
then generate the complete Model Builder extension partial class for itADR-Driven Migration Governance
Architectural Decision Records solve a specific problem on migration projects: the same architectural question gets asked multiple times, by different developers, and gets answered inconsistently.
“How do we handle multilingual fallback when a property isn’t translated?” asked on day 3 gets a different answer than the same question asked on day 15 by someone who wasn’t on the day 3 call. Without ADRs, the codebase silently accumulates inconsistent decisions.
ADRs create a single, versioned, searchable record of every significant architectural decision. They live in the repository:
/docs/
/adr/
0001-use-block-list-over-block-grid.md
0002-usync-migrations-over-manual-conversion.md
0003-strongly-typed-models-sourcecodmanual.md
0004-multilingual-culture-fallback-strategy.md
0005-custom-property-editor-migration.mdADR Template for Umbraco Migrations
# ADR-[NUMBER]: [Decision Title]
**Date:** [date]
**Status:** Proposed | Accepted | Superseded
**Decider:** [name/team]
## Context
What is the architectural question we're facing? What is the specific Umbraco
migration scenario that prompted this decision? Include version context.
## Decision
What did we decide?
## Rationale
Why did we choose this option? What alternatives did we consider?
### Options Considered
| Option | Pros | Cons |
|--------|------|------|
| [Option A] | ... | ... |
| [Option B] | ... | ... |
## Consequences
**Positive:**
- [Expected benefits]
**Negative / Trade-offs:**
- [Costs, risks, or constraints]
## Implementation Notes
Specific code patterns, NuGet packages, or configuration that implements this decision.
## References
- [Links to Umbraco docs, GitHub issues, community posts]Three ADRs Every Umbraco Migration Should Have
ADR-0001: Migration approach selection (direct upgrade vs. fresh instance)
This is the foundational decision. Document which path was chosen (Path A, B, or C from Part 3), why, and what migration tools handle the data transformation. Once this is decided, all subsequent work depends on it.
ADR-0002: Block List element type reuse strategy
When you have multiple document types that could share the same block elements (e.g., a heroBlock used on both LandingPage and ArticlePage), document whether you’ll use shared element types or per-document-type copies. Shared is more efficient; per-doc-type is more flexible for per-context customization.
ADR-0003: Model Builder mode and model location
Decide on SourceCodeManual vs. InMemoryAuto. SourceCodeManual gives you generated model files you can extend with partial classes; InMemoryAuto generates in memory at startup (faster iteration but no IDE type support). Document the chosen mode and the convention for partial class extensions.
AI-Generated ADR First Draft
I need to write an ADR for the following Umbraco migration architectural decision:
Topic: Whether to use uSync Migrations or Umbraco Deploy artifact migrators to handle
Nested Content to Block List conversion on our project.
Project context:
- Umbraco 8 → 17 migration
- Site has 12 document types with Nested Content
- 2 document types use custom Nested Content implementations
- Team has existing uSync setup on source site
- No current Umbraco Deploy license
Please draft an ADR using the standard template covering:
1. Context of the decision
2. Both options (uSync Migrations vs Deploy migrators)
3. Recommended decision with rationale
4. Implementation notes for the chosen approachThe Weekly AI Review Loop
During active migration sprints, running a weekly AI review prevents technical drift:
Every Friday:
- Run the build with full warnings visible
- Feed build output to AI with the CI Validation Report prompt
- AI identifies patterns in the warnings (e.g., consistently using a deprecated API across multiple files) that would be missed in normal review
- Champion creates tickets for recurring issues
Every sprint:
- Review the prompt library — are the conversion prompts still producing good output?
- Review the ADR log — any decisions documented verbally that should be written up?
- Review test coverage trend — are we testing what AI generates?
This is Part 5 of 8 in the Umbraco AI-Powered Migration Playbook.
Series outline: