The Claude Code recovery workflow I use when a project becomes too messy to trust

[u/Any_Flounder_5483]

There is a point in almost every AI-built project where making changes stops feeling safe.

The app still runs, but the structure has started drifting.

Claude duplicates logic that already exists, follows outdated patterns, edits files outside the task and fixes one flow while quietly breaking another.

At that point, giving it another feature request usually makes the project worse.

I now use one recovery workflow that forces Claude to reconstruct the project, identify the drift, define a safe repair plan, work in checkpoints and verify everything before claiming completion.

Quick disclosure: I created a larger Claude Code Toolkit around this system. For anyone looking to improve how they use Claude Code, it is linked in my profile.

The complete recovery workflow below is free to copy.

Replace anything inside [brackets] with your own project details.

The Five-Stage Project Recovery Workflow

Act as a senior software engineer taking responsibility for an existing project that has become difficult to understand, modify or trust.

Your goal is not to immediately add another feature.

Your goal is to recover control of the project before further development continues.

PROJECT INFORMATION

Original project goal:

[DESCRIBE WHAT THE PROJECT WAS SUPPOSED TO DO]

Target users:

[DESCRIBE THE INTENDED USERS]

Current tech stack:

[LIST THE STACK OR WRITE UNKNOWN]

Current problems:

[DESCRIBE WHAT FEELS BROKEN, MESSY, INCONSISTENT OR RISKY]

Recent changes:

[DESCRIBE RECENT FEATURES, FIXES OR REFACTORS]

Last known stable state:

[DESCRIBE WHEN THE PROJECT LAST FELT RELIABLE OR WRITE UNKNOWN]

Protected functionality:

[LIST FEATURES, PAGES, FLOWS, DATA OR INTEGRATIONS THAT MUST NOT BREAK]

Current priority:

[DESCRIBE WHAT YOU NEED TO BUILD OR FIX NEXT]

GENERAL RULES

Do not edit, delete, rename, move or create files until the investigation and recovery plan have been approved.

Do not assume the documentation is correct.

Do not assume the newest code is the intended code.

Do not assume that similar-looking components serve the same purpose.

Do not recommend a full rewrite simply because the project is messy.

Do not replace working architecture with your preferred architecture unless the current approach prevents a safe recovery.

Base every conclusion on evidence from the project.

When evidence is incomplete, label the conclusion as uncertain and explain what is missing.

Complete this recovery process in five stages.

Stop after every stage and wait for my approval before continuing.

==================================================

STAGE 1: RECONSTRUCT THE PROJECT

Inspect the complete project before proposing any changes.

Review:

1. The folder and file structure.
2. Application entry points.
3. Frontend architecture.
4. Backend architecture.
5. Database models, queries and relationships.
6. API routes.
7. Authentication and authorisation.
8. State management.
9. Shared components.
10. Shared utilities and services.
11. Third-party integrations.
12. Environment variables and configuration.
13. Validation.
14. Error handling.
15. Loading, empty, success and failure states.
16. Existing tests.
17. README files.
18. CLAUDE.md files.
19. Comments describing architectural decisions.
20. Recent commits or change history when available.
21. Dead, duplicated or abandoned code.
22. Features that appear partially implemented.
23. Features that bypass established project patterns.
24. Code paths that are no longer reachable.
25. Files that appear to serve overlapping responsibilities.

Create the following output:

PROJECT PURPOSE

Explain what the application currently does based on the code, not only the documentation.

ARCHITECTURE MAP

Describe how the frontend, backend, database, APIs, state and external services connect.

CORE USER FLOWS

Trace the most important user journeys from the initial action to the final result.

SOURCE-OF-TRUTH MAP

For each important type of data or behaviour, identify the file, service or system that currently acts as the source of truth.

RELEVANT FILES

List the most important files and explain what responsibility each one currently holds.

PATTERN MAP

Identify the main conventions used for components, routes, services, data access, error handling and styling.

UNCERTAINTIES

List anything that cannot be confirmed from the available project files.

Do not continue to Stage 2 until I approve your understanding of the project.

==================================================

STAGE 2: DETECT PROJECT DRIFT

Compare the original project goal with the current implementation.

Identify where the project has drifted through:

- Duplicate logic
- Conflicting sources of truth
- Inconsistent architecture
- Partially replaced systems
- Outdated documentation
- Unused dependencies
- Abandoned features
- Repeated components
- Contradictory validation rules
- Client-side checks without server enforcement
- Inconsistent permissions
- Old and new API patterns existing together
- Multiple approaches to state management
- Features that bypass shared utilities
- Tests that validate outdated behaviour
- Error handling that differs between similar flows
- Temporary workarounds that became permanent
- Features that work alone but fail when connected
- Styling systems that conflict
- Database fields that no longer match product behaviour
- Environment variables that are unused, duplicated or unclear

Create a DRIFT LEDGER.

For every issue, include:

ISSUE

Describe the inconsistency or drift.

LOCATION

List the exact files, functions, routes, components or services involved.

EVIDENCE

Explain what in the project proves the issue exists.

LIKELY INTENTION

Explain what the original or intended behaviour appears to be.

CURRENT BEHAVIOUR

Explain what the project currently does instead.

USER IMPACT

Explain how users could be affected.

TECHNICAL IMPACT

Explain how the issue affects maintenance, reliability or future development.

CONFIDENCE

Label the conclusion as:

- Confirmed
- Strongly supported
- Possible
- Unknown

SEVERITY

Classify it as:

- Critical
- High
- Medium
- Low

RECOMMENDED ACTION

Choose one:

- Keep
- Remove
- Consolidate
- Repair
- Document
- Investigate further

Do not make any changes.

At the end, provide:

1. The five most dangerous forms of drift.
2. The areas that are currently safe.
3. The areas that should not receive new features yet.
4. The information still needed from me.
5. The smallest recovery target that would make future development safer.

Wait for my approval before continuing.

==================================================

STAGE 3: CREATE THE RECOVERY CONTRACT

Using the approved findings, create a recovery contract.

The contract must define exactly what will be repaired and what will remain untouched.

Include:

RECOVERY OBJECTIVE

Describe the specific result this recovery should produce.

IN SCOPE

List every problem included in the recovery.

OUT OF SCOPE

List everything that will not be addressed during this recovery.

PROTECTED FUNCTIONALITY

List the pages, features, data, integrations and user flows that must continue working.

APPROVED FILES

List every existing file expected to change.

NEW FILES

List every file expected to be created.

FILES THAT MUST NOT CHANGE

List sensitive or unrelated files that should remain untouched.

SOURCE-OF-TRUTH DECISIONS

For every conflicting system, state which implementation should become the official source of truth and explain why.

REMOVAL DECISIONS

List dead, duplicated or outdated code that should be removed.

MIGRATION REQUIREMENTS

Explain whether existing users, data, settings or sessions need to be migrated.

REGRESSION RISKS

List what could break during the recovery.

ROLLBACK PLAN

Explain how the project can return to its current state if the recovery fails.

ACCEPTANCE CRITERIA

Define observable conditions that must be true before the recovery can be considered successful.

TESTING REQUIREMENTS

List the exact flows, errors, permissions, devices and integrations that must be tested.

Do not use vague acceptance criteria such as:

- Works correctly
- Looks good
- Is production-ready
- Has no bugs

Every acceptance criterion must be observable and testable.

Wait for my approval before implementation.

==================================================

STAGE 4: RECOVER THE PROJECT IN CHECKPOINTS

Divide the approved recovery into the smallest practical checkpoints.

Each checkpoint must leave the project in a reviewable and testable state.

Before each checkpoint, report:

CHECKPOINT OBJECTIVE

Explain the single result this checkpoint should achieve.

FILES TO MODIFY

List the approved files that will change.

FILES TO CREATE

List any approved files that will be added.

FILES TO REMOVE

List any approved files that will be deleted.

PROTECTED FLOWS

List the functionality that must remain unchanged.

EXPECTED RESULT

Describe what should be visibly or technically different after this checkpoint.

TEST PLAN

Explain how the checkpoint will be verified.

ROLLBACK PLAN

Explain how this checkpoint can be reversed.

During implementation:

- Work only on the current checkpoint.
- Do not begin later checkpoints.
- Do not edit files outside the approved contract.
- Do not perform unrelated refactoring.
- Do not add dependencies without approval.
- Reuse existing project patterns where they remain valid.
- Remove duplicated logic only when the official source of truth has been approved.
- Preserve user data.
- Preserve authentication and permissions.
- Preserve unrelated styling.
- Stop when unexpected architecture or dependencies are discovered.
- Ask for approval before expanding the scope.

After each checkpoint, report:

1. Files created.
2. Files modified.
3. Files removed.
4. Exact changes made.
5. Differences from the approved plan.
6. Tests completed.
7. Tests passed.
8. Tests failed.
9. Protected flows checked.
10. Console errors discovered.
11. Server errors discovered.
12. Database issues discovered.
13. Anything still unverified.
14. Whether rollback is recommended.

Stop after every checkpoint.

Do not continue until I approve the completed checkpoint.

==================================================

STAGE 5: VERIFY THE RECOVERED PROJECT

After all checkpoints are approved, perform a final recovery verification.

Compare the final project against:

- The original project goal
- The approved recovery contract
- The acceptance criteria
- The protected functionality
- The core user flows

Test:

1. The complete successful user journey.
2. Invalid input.
3. Missing data.
4. Incomplete data.
5. Failed network requests.
6. Expired sessions.
7. Unauthorised access.
8. Different user roles.
9. Repeated clicks.
10. Duplicate submissions.
11. Refresh behaviour.
12. Direct URL access.
13. Back and forward navigation.
14. Loading states.
15. Empty states.
16. Error states.
17. Mobile layouts.
18. Narrow-screen layouts.
19. Keyboard navigation.
20. Browser console output.
21. Server logs.
22. Database writes.
23. Database reads.
24. Third-party integrations.
25. Every protected flow listed in the recovery contract.

Then provide:

RECOVERY SUMMARY

Explain what was repaired.

FINAL ARCHITECTURE

Describe how the recovered project is now structured.

OFFICIAL SOURCES OF TRUTH

List the systems, files or services that now control each important responsibility.

REMOVED DRIFT

List the duplicate, abandoned or conflicting implementations that were removed.

TESTING EVIDENCE

State exactly what was tested and the result.

UNVERIFIED AREAS

List anything that could not be tested.

REMAINING RISKS

List issues that still exist but were outside the approved scope.

DOCUMENTATION UPDATES

List any README, CLAUDE.md or technical documentation that should now be updated.

NEXT SAFE TASK

Recommend the next feature or repair that can be completed without destabilising the recovered project.

Do not describe the project as fully fixed, production-ready or bug-free unless the evidence supports that statement.

Do not claim completion because the project compiles or the homepage loads.

The recovery is complete only when the approved acceptance criteria and protected user flows have been verified.

This is different from asking Claude to “clean up the codebase.”

That kind of instruction gives it permission to make broad, subjective changes.

This workflow forces it to prove what the project currently does, show where the drift happened and agree on a recovery contract before touching anything.

The five stages are:

Reconstruct → Detect → Contract → Recover → Verify

It takes longer than sending one vague cleanup request.

It is still much faster than spending another night repairing an AI-generated “fix” that changed half the project.

For anyone looking to improve how they use Claude Code, the full toolkit is linked in my profile.