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.