Ansible Monolith to Roles Refactor Prompt
Break a long monolithic playbook into clean, reusable roles with proper defaults/vars/handlers split and a behavior-preserving migration plan.
- Target user
- Ansible engineers untangling a sprawling single-file playbook into maintainable roles
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior automation engineer who has decomposed many 800-line "god playbooks" into clean role structures without changing what they do. You respect variable precedence and handler scope, and you migrate in steps that can be verified, not in one risky big-bang rewrite.
I will paste a monolithic playbook. Produce a role-based refactor plan plus the role skeletons, preserving behavior exactly.
Steps:
1. **Identify cohesive units**: group tasks by responsibility (e.g. base, packages, app, web, db, monitoring) — each group becomes a candidate role. Note shared tasks that belong in a common/base role.
2. **Map the directory layout**: produce the `roles/<name>/{tasks,handlers,defaults,vars,templates,files,meta}` structure for each role and the slimmed top-level playbook that just lists roles.
3. **Split variables by precedence intent**: move overridable settings to `defaults/main.yml`, fixed internals to `vars/main.yml`, and keep environment-specific values in inventory `group_vars`/`host_vars` — explain each placement so precedence behavior is unchanged.
4. **Relocate handlers correctly**: move handlers into the owning role's `handlers/main.yml` and preserve `notify` names; flag any cross-role handler dependency since handler scope changes when tasks move.
5. **Preserve ordering and conditionals**: keep `tags`, `when`, `become`, and task order intact so the refactor is behavior-preserving. Call out anything that can't move cleanly.
6. **Migration plan**: a step order to extract one role at a time and verify after each, not all at once.
Fill in:
- Monolithic playbook: [PASTE]
- Existing inventory / group_vars layout: [DESCRIBE OR "none"]
- Roles you already have or naming conventions: [LIST OR "none"]
Output format: the proposed role directory tree, the slim top-level playbook, the per-role `tasks/main.yml` (and `defaults`/`handlers` where relevant), a variable-placement table (var | old location | new location | reason), and a step-by-step migration order with a verification step after each role.
Do not run anything. Each extraction must be verifiable with --syntax-check, ansible-lint, and a --check --diff comparison against the original before the next role is extracted. Flag any handler or variable move that could change runtime behavior so I review it.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
Refactoring a monolith into roles is where behavior quietly drifts. The two silent killers are handler scope (a notify that used to fire stops firing once the task and handler land in different roles) and variable precedence (a value moved from inline vars into defaults can now be overridden differently). The prompt makes both explicit — a variable-placement table with reasons and a handler-routing check — so the decomposition stays behavior-preserving instead of mysteriously not restarting a service anymore.
Insisting on one-role-at-a-time extraction with verification after each is what turns a scary big-bang rewrite into a safe sequence. You extract base, prove it with --syntax-check, ansible-lint, and a --check --diff against the original, then move to the next role. Any regression is isolated to the role you just touched.
The output is structured to be directly usable: a directory tree, the slim top-level playbook, and per-role files, plus an ordered migration plan. You are reviewing and approving each step rather than trusting a wholesale rewrite, which keeps a large mechanical change firmly under control.
Related prompts
-
Ansible Undocumented Inventory and Playbook Documentation Prompt
Reverse-engineer an undocumented inventory and playbook set into a clear README, variable reference, and a Mermaid run-flow diagram.
-
Ansible Role Dependencies & meta/main.yml Design Prompt
Design a role's meta/main.yml — dependencies, galaxy_info, platforms, and role_dependencies — so roles compose predictably without hidden ordering surprises.
-
Refactor Ansible Tasks into a Reusable Role Prompt
Extract a sprawling set of inline playbook tasks into a clean, parameterized Ansible role with proper defaults, vars, handlers, and a Galaxy-standard directory layout.
-
Ansible Callback Plugin Authoring Prompt
Draft a custom callback plugin that hooks play/task events for profiling, structured logging, or notifications without changing any playbook.
More Ansible prompts & error guides
Browse every Ansible prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.