Refactoring Your Vibe Coded Projects

A Guide to Code Cleanup

One of the most powerful aspects of building with AI is the ability to rapidly create functional software through what we call "vibe coding" - describing what you want to build in natural language and having Memex build it for you. This approach democratizes software development, allowing non-programmers to create working applications without writing code themselves.

But as your projects grow, you may encounter a common challenge: managing the accumulated files, potential duplicates, and maintaining a clean codebase. This guide will walk you through the process of refactoring your vibe coded projects to keep them organized and maintainable.

What is Refactoring?

For those new to software development, "refactoring" means improving your code's structure and organization without changing what it does. Think of it like reorganizing your kitchen cabinets - you're not adding new ingredients, just making everything easier to find and use.

Refactoring is essential for:

• Making your code easier to understand

• Reducing complexity

• Preparing for future enhancements

• Fixing potential issues before they cause problems

Common Challenges with LLM-Generated Code

Before diving into refactoring techniques, let's address some common challenges when building with AI tools like Memex:

1. File Duplication

AI assistants sometimes create new files instead of modifying existing ones, especially when fixing errors. This can lead to multiple versions of similar files in your project, making it hard to know which one is actually being used.

For example, you might find both database.py and database_fixed.py in your project, with small differences between them.

2. Inconsistent Naming Conventions

AI-generated code may use various naming styles across different files, making your codebase less consistent and harder to navigate.

3. Unused Code and Dependencies

As your project evolves through multiple iterations, you may accumulate code that's no longer needed or dependencies that aren't being used.

Part 1: Refactoring Your Projects - A Step-by-Step Guide

Step 1: Set Up Version Control

Before making any changes to your project, set up version control to create a safety net. This allows you to experiment freely, knowing you can always revert to a previous working version if something goes wrong.

Help me set up git for version control in this project. 
Ensure all necessary files are tracked

Memex will initialize a git repository, create an initial commit of your existing files, and explain how to use basic git commands.

Once your git repository is set up, you can use simple natural language prompts to manage your version control throughout the refactoring process:

# To see what you've changed (like checking what you need to save)
Show me the git status to see what files I've changed

# To save your work (like pressing save, but with a note about what you did)
Commit my changes to git with a descriptive message

# To create a separate workspace for trying risky changes (like a super-powered undo)
Create a new git branch where I can try removing files safely

# To see what changed in a file (like comparing document versions)
Show me the diff for login.py to see what changed since my last commit

# To go back to a previous version if something breaks
Revert my last git commit since something broke

# To recover a file you accidentally deleted
Restore the config.py file from git that I accidentally deleted

By using git throughout your refactoring process, you create checkpoints that you can return to if something goes wrong. This is especially important when removing files or making significant structural changes.

Step 2: Perform a Code Audit

The next step is to review your entire project, understanding the purpose of each file and identifying potential issues:

Review all files in this project and explain what each one does. 
Identify any duplicate or unused files.

Memex will analyze your codebase and provide a comprehensive overview of:

• Each file's purpose

• Potential duplicates

• Files that might be obsolete or unused

• Inconsistencies in code style or structure

Step 3: Create a Refactoring Checklist

For anything beyond a small project, you'll want to create a checklist to track your progress. This is especially important since refactoring might span multiple conversations with Memex:

Based on the code audit, create a markdown file called "refactor_checklist.md" that includes:
1. A list of tests that need to be created before removing specific files
2. A list of duplicate or unused files that can be removed after testing
3. Instructions on how to use this checklist

The checklist should look something like this:

# Refactoring Checklist

## How to use this checklist

1. Create tests one-by-one for each item in the "Tests Needed" section
2. Mark tests as complete only when they run successfully
3. DO NOT remove any files until all relevant tests are complete
4. When starting a new conversation with Memex, begin with: "Let's continue the refactoring project. Here's the current checklist: [paste checklist contents]"
5. Commit changes to git after completing each major section

## Tests Needed

- [ ] Test database connection functionality (database.py)
- [ ] Test user authentication (auth.py, login.py)
- [ ] Test data validation functions (validation.py)

## Files to Remove or Consolidate

- [ ] database_fixed.py → merge with database.py
- [ ] db_connection.py → merge with database.py
- [ ] old_login.py → can be removed after auth tests pass

Note: Refactoring larger projects may require multiple conversations with Memex. When starting a new conversation, make sure to reference your checklist by saying something like: "Let's continue refactoring my project. Here's my current checklist: refactor_checklist.md". This ensures Memex has the context needed to continue where you left off.

Step 4: Implement Testing

Before removing any files or making significant changes, it's crucial to ensure you can verify your application still works correctly:

Help me create tests that verify the core functionality of my application.
Reference refactor_checklist.md for a list of test to perform.
Choose a testing framework that is lightweight and easy to implement, but ensures coverage of the core functionality.

These tests provide an objective way to confirm that your refactoring doesn't break existing features. For a web application, Memex might create tests like:

Create tests that check if:
1. The login page opens correctly
2. A user can log in with the right password
3. A user can't log in with the wrong password

Memex will create the technical test code for you behind the scenes. The important part is that these tests automatically verify if your app is working correctly.

After implementing tests, you can run them to establish a baseline:

Run the authentication tests

Throughout your refactoring process, you'll use these tests to ensure your changes don't break existing functionality. If a test fails after making changes, you'll know exactly what stopped working and can fix it (or revert to your previous git commit).

Step 5: Clean Up Duplicate Files

Now that you have version control and tests in place, you can start cleaning up your project:

Let's consolidate the duplicate files you identified earlier. 
For each pair of duplicates, help me determine which one to keep and update any references to the removed file.

Memex will help you:

1. Compare duplicate files to identify the most complete/correct version

2. Update any imports or references to the removed files

3. Commit these changes to git

4. Run your tests to ensure everything still works

Step 6: Final Verification and Documentation

Once your refactoring is complete, verify everything works and document your project:

Run all tests to verify the application works correctly. 
Update .memex/rules.md to ensure it documents the project structure, tests, and how to run them.

A good README file makes your project more accessible, both for others and for your future self.

Part 2: Preventing File Duplication and Other Common LLM Issues

To avoid dealing with these issues in future projects, here are some preventive measures:

1. Use the @obey Command Pattern

One common practice among Memex users is to use a "magic" command syntax. E.g.

<magic_syntax>
The user can invoke "magic" commands using the following syntax
@magic_cmd ..
Here are the built-in magic commands:
@note <user_note> - "Take a note of user note, and update the .memex/rules.md"
@enhance - "Take the user prompt and enhance it to be more comprehensive and detailed so you can understand the user intent better. Ask the user any questions that may help clarify the intent"
...
</magic_syntax>

Then, you can add one for "@obey"

@obey <prompt> - "let's review the custom rules and then execute the actions requested on the <prompt> taking the custom rules by the book"

This reminds Memex to adhere strictly to your custom rules before taking action.

2. Establish Clear Custom Rules

Create specific custom instructions for your projects:

<MUST FOLLOW RULES>
1) When asking about something and/or you have a doubt that needs clarification, DO NOT infer what are the next steps and DO NOT take any further actions unless clearly answered and/or ordered to do so.

2) Before creating new files or components be sure the project does not have the functionality and/or need already implemented on other components. If so, reuse, adapt or upgrade the currently implemented functionality.

3) You are FORBIDDEN to even consider the alternative of creating a new file in order to update an existing one. You MUST edit and update the existing document.

4) Do not overthink and do not be so proactive. Keep your actions under the immediate scope of the prompt given to you.

3. Regular Housekeeping

Incorporate regular cleanup sessions into your development process. One approach is creating custom commands for this purpose:

@doHouseKeeping - "The main objective here is to clean-up the project in order to prepare a detailed documentation and delete obsolete / unnecessary files. To start, review the project and check what every file does. After presenting this, get authorization to remove all outdated, obsolete and/or unnecessary files from the project."

@document - "Create a very detailed readme.md file for this project explaining in details this project. Explain all files, their purpose and the main process flow. Document as well all parameters needed and how they are received by the function and from where."

4. Commit Early and Often

Make git commits a regular part of your workflow. After each significant change or milestone, commit your changes with a descriptive message. This creates a safety net and makes it easier to track the evolution of your project.

Real-World Examples

Example 1: Refactoring a Database Project

Let's look at a practical example of applying the refactoring process. Imagine you've built a mobile app connected to a database through vibe coding. After several iterations and fixes, you've noticed multiple database connection files and aren't sure which one is being used.

Here's how you might approach refactoring:

1. Set up version control:

   Help me set up git in this project and make an initial commit

2. Audit the codebase:

   Review all database-related files and explain what each one does

3. Create a refactoring checklist:

   Create a refactor_checklist.md file listing the database files that need tests and which ones to consolidate

   This checklist is crucial if the refactoring spans multiple sessions. You'd refer to it at the start of each new conversation with Memex:

   Let's continue refactoring the database connections. Here's my checklist: [path to checklist]

4. Create tests:

   Help me create tests that verify database connections work correctly

   Memex might respond with tests like these:

   Create tests that check if:
   1. The app can connect to the database
   2. The app can retrieve user information from the database

   Memex will handle the technical details of creating proper tests.

   Running these tests would show results like:

   All tests passed! Your database connection is working correctly.

   These tests establish a baseline of functionality before making any changes.

5. Consolidate duplicates:

   I see we have database.py, database_fixed.py, and db_connection.py. Help me determine which one to keep and update all references

   Memex would analyze each file and might provide a comparison like:

   I found three similar database files:
   
   1. database.py - This is the oldest file and is used by most of your app, but has some issues.
   
   2. database_fixed.py - This looks like a newer version with improvements, but it's not actually being used anywhere in your app.
   
   3. db_connection.py - This is the newest file and is only used by the report feature.
   
   Recommendation: Let's combine the best parts of all three files into one improved database.py file, and update your app to use only this file.

6. Verify functionality:

   Run the tests to make sure database connections still work correctly

   After consolidation, running the tests again ensures nothing broke during the refactoring:

   All tests still pass! Your changes didn't break anything.

   If tests had failed, Memex would help you identify and fix the issues, or you could revert to your previous git commit.

7. Document the changes:

   Update the documentation to reflect our database architecture

Example 2: Preventing Duplication in a New Project

Now, let's see how you might apply prevention techniques to a new project. You're starting to build a web application and want to avoid accumulating duplicate files.

Before beginning development, you create a .memex/rules.md file with clear instructions:

# Memex Project Rules

1. Always edit existing files rather than creating new versions
2. Use git for version control with meaningful commit messages
3. Follow consistent naming conventions (camelCase for variables, PascalCase for components)
4. Keep file organization according to feature/functionality

Then, as you develop, you use the @obey command pattern before significant changes:

@obey Help me implement a login feature for my web application

This reminds Memex to follow your custom rules while implementing the feature. Every few development sessions, you also run a housekeeping check:

@doHouseKeeping

This proactive approach prevents duplicate files from accumulating in the first place, making your project easier to maintain as it grows.

Conclusion

Maintaining clean, organized code is essential for the long-term success of any software project - especially when building with AI assistants like Memex. This guide has provided two complementary approaches:

1. Refactoring existing projects - A systematic process to clean up and organize projects that have accumulated duplicate files and inconsistencies over time.

2. Preventing issues in new projects - Proactive techniques to guide Memex's behavior and avoid accumulating duplicate files in the first place.

Remember that code maintenance is not a one-time task but an ongoing process. For existing projects, schedule regular refactoring sessions. For new projects, implement prevention techniques from the start.

One of the greatest benefits of vibe coding with Memex is the speed of development - you can rapidly bring your ideas to life without writing code. By combining this speed with disciplined maintenance practices, you get the best of both worlds: fast iteration and sustainable code quality.