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.
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.