Prompt Engineering

Architecture Cleanup Prompt — Boundaries Without a Redesign

Dependency cycles, leaky modules, misplaced responsibilities — cleaned up within the existing design. Explicitly not an invitation to invent a new architecture.

Open in Refactor Prompt Builder

Overview

Architecture refactors attract scope explosions: asked to break one dependency cycle, the model proposes a hexagonal rewrite. This prompt uses the architecture cleanup goal with its built-in fence — straighten boundaries and dependencies within the existing design; do not invent a new architecture, introduce new layers, or redesign the system. The priorities are practical: modules expose purpose not internals, high-level policy stops depending on low-level detail, cycles get broken, misplaced responsibilities move to the module that owns the concept. An aggressive risk profile allows real restructuring — staged, verifiable, and traceable to the goal.

How to use this resource

Fence the scope

Cleanup within the existing design — the contract names the redesign temptation and forbids it.
Fix direction and ownership

Dependencies point from policy to detail, cycles break, responsibilities move to their owning module.
Verify at the seams

Module moves change visibility and initialization order — every consumer must still get the same contract.

Why This Works

The explicit no-redesign fence prevents the scope explosion these refactors are famous for
Dependency direction is checkable — vibes-based "cleaner architecture" is not
Integration-level validation catches what unit-level checks miss in module moves

Best for

Codebases where module boundaries eroded gradually
Restructuring that must stay shippable at every stage
Teams that want cleanup, not an architecture pitch

Not for

Designing a new system architecture from requirements — out of scope by the contract's own rules
Documenting the existing architecture — that's the Markdown Output Builder's space

Use cases

Breaking a dependency cycle between two packages
Moving misplaced responsibilities to the module that owns them
Narrowing a module interface that leaks internals

FAQ

Will this prompt propose a rewrite when I ask it to break one dependency cycle?

That's exactly what the built-in fence prevents. The TRANSFORMATION GUIDANCE states this is "cleanup within the existing architecture — do not invent a new architecture, introduce new layers, or redesign the system." So a request to break the reporting-package cycle stays scoped to boundaries and dependency direction, not the hexagonal rewrite these refactors usually attract.

The risk level is set to Aggressive — does that mean it can change behavior?

Aggressive applies only to the SIZE of the change, never its safety: no behavioral assumptions, no feature invention, no guessed requirements. The BEHAVIOR PRESERVATION requirements keep outputs, business rules, side-effect ordering, and public contracts identical, and if the goal and preserving behavior ever conflict, behavior wins and the model stops to explain.

How does it check that moving a module didn't quietly break a consumer?

The VALIDATION STRATEGY validates at the integration level, because "a module move preserves behavior only if every consumer still gets the same contract." It asks for a before/after verification plan, a behavior comparison per changed unit, and integration checks on every external touchpoint — since moving code across boundaries shifts visibility and initialization order.

Customize This Resource

Opens this setup in Refactor Prompt Builder. Generate to get the full refactoring contract — then adjust the goal, risk level, and validation strategy.

Open in Refactor Prompt Builder

Prompt Template

Copy it as-is, or use Open in Refactor Prompt Builder to load it pre-filled and customize it with your own context.

REFACTORING OBJECTIVE
Straighten the module boundaries in the reporting package: break the dependency cycle between data access and formatting.
Refactoring goal: architecture cleanup — straighten boundaries and dependencies within the existing design.
Change how the code is built — never what the code does. If a transformation cannot be made safely with the available information, leave that code unchanged and say why.

EXISTING CODE CONTEXT
Code context: none specified — treat unknown consumers as possible and unstated requirements as existing.
Language: not specified — infer it from the code and stay consistent with it.
Code to refactor:
```
[Paste the code to refactor here]
```

REFACTORING GOAL
Primary goal: Architecture Cleanup.
Transformation priorities for this goal:
1. Clarify module boundaries: each module exposes a purpose, not its internals.
2. Fix dependency direction: high-level policy should not depend on low-level detail, and cycles must be broken.
3. Relocate misplaced responsibilities to the module that owns the concept.
4. Reduce coupling at the seams: narrow interfaces and explicit contracts between modules.

RISK PROFILE
Risk level: Aggressive.
- Larger restructuring is allowed: reorganize units, modernize patterns, and restructure flow where it serves the goal.
- Aggressive applies to the SIZE of the change, never to its safety: no behavioral assumptions, no feature invention, no guessed requirements.
- Every restructuring must still trace back to the stated goal — ambition is not a license to rewrite unrelated code.
- Sequence large changes into verifiable stages; an aggressive refactor that cannot be verified in steps is a rewrite, not a refactor.

SAFETY RULES
These rules apply to every transformation, at every risk level:
1. Identify behavior assumptions before changing code — list every assumption you rely on.
2. Flag uncertain behavior instead of deciding it: if you cannot tell what a branch does or why it exists, ask — do not guess.
3. Do not remove functionality. Code that looks redundant may be load-bearing.
4. Do not invent requirements. Refactor toward the stated goal, not toward an imagined better product.
5. Do not rewrite unrelated code. Touch only what the goal requires.
6. Explain why each change exists — every transformation traces to the stated goal or to a named problem in the code.
7. Preserve public contracts — signatures, return types, error types, serialized shapes — unless explicitly instructed otherwise.

TRANSFORMATION GUIDANCE
Known failure modes of this goal — watch for:
- This is cleanup within the existing architecture — do not invent a new architecture, introduce new layers, or redesign the system.
- Moving code across boundaries changes visibility, lifetimes, and initialization order — verify each move individually, not just the end state.

BEHAVIOR PRESERVATION REQUIREMENTS
- Preserve observable behavior: the same inputs produce the same outputs, including error cases.
- Preserve business rules: every condition, threshold, and special case survives the refactor exactly.
- Preserve outputs: formats, ordering, precision, and encodings stay identical unless the goal explicitly targets them.
- Preserve side effects: writes, emitted events, log lines other systems consume — and their relative order.
- Preserve integrations: API shapes, serialized payloads, database access patterns, and external call sequences.
- These requirements hold unless the instructions explicitly say otherwise — and any knowingly behavior-affecting change must be flagged, never silent.
- If achieving the goal and preserving behavior conflict, behavior wins: stop and explain the conflict instead of compromising it.

VALIDATION STRATEGY
Goal-specific validation: validate at the integration level — a module move preserves behavior only if every consumer still gets the same contract.
- Provide a before/after verification plan: the specific inputs to run against both versions and the outputs that must match.
- Provide a behavior comparison: for each changed unit, the observable behaviors it had before and the evidence each is intact after.
- Provide regression validation: the existing tests that must pass, and the missing tests that should exist before this refactor ships.
- Provide integration verification: every external touchpoint — API consumers, database, events, files — and how to confirm each still sees identical behavior.

ASSUMPTIONS
- List every assumption made about the code's behavior, inputs, or environment.
- Mark each assumption VERIFIED (with its evidence) or UNVERIFIED (with the question that would resolve it).
- Any transformation that depends on an UNVERIFIED assumption must be flagged as conditional on it.

NON-GOALS
- Do not invent requirements.
- Do not redesign the entire system.
- Do not remove behavior without justification.
- Do not introduce new features.
- Separate assumptions clearly from facts.
- Flag uncertainty instead of resolving it silently.
- Explain the tradeoffs of any change that has them.

OUTPUT REQUIREMENTS
- Return the refactored code, complete — no elided sections, no "rest unchanged" placeholders inside changed units.
- Follow it with a change list: for each change — what changed, why it serves the goal, and its behavior impact (expected: none).
- Flag any change that could plausibly alter behavior, with the reason it might and the check that would confirm it does not.
- Where a worthwhile transformation was skipped for safety, list it under "Suggested but not applied" with what information would unlock it.

More resources from Refactor Prompt Builder

Resource

Refactor Prompt — the Behavior Preservation Contract

"Refactor this code" invites silent behavior changes. The refactoring contract preserves business rules, outputs, and side effects — and flags uncertainty instead of deciding it.

Prompt Engineering

Resource

Safe Refactoring Prompt — Zero Regression Tolerance

For code that ships weekly: a refactoring prompt where regression avoidance outranks improvement depth, log lines stay intact, and every step is rollback-friendly.

Prompt Engineering

Resource

AI-Generated Code Cleanup — Deflate the Generated Bloat

Generated code duplicates instead of extracting, wraps without deciding, and defends against impossible states. This prompt hunts those exact failure modes — without preserving bugs as behavior.

Prompt Engineering

Resources that pair well

Resource

Code Review Prompt — the Review Contract

"Review this code" gets shallow comments. The review contract gets findings with severities, a checklist, and a verdict.

Prompt Engineering

Resource

Playwright Test Prompt

getByRole over CSS chains, auto-wait over sleep, web-first assertions — Playwright tests written the way Playwright wants.

Engineering

Resource

Debugging Prompt — the Investigation Contract

"Fix this error" gets guesses. The investigation contract gets a ten-stage diagnosis: facts separated from assumptions, alternatives weighed, fixes justified.

Prompt Engineering

Related tools

Tool

Refactor Prompt Builder

Build behavior-preserving refactor prompts — goal, risk level, and code context turn into a safe refactoring contract.

Coding Workflows

Tip: Save time by exploring related resources and tools that integrate with this resource.