Keep Your AI Project Organized: A Simple Folder Plan

Keep your AI project organized by giving every kind of thing one home: game rules, pictures, sounds, notes and one short instruction file. One tidy-up session usually does it, as long as the AI only moves things and changes nothing about how the game behaves.

What does a messy project look like?

Here is the folder of Fog Bell Fort, an invented defence game, after three weeks of work:

game.js
game_final.js
game_final_v2_REAL.js
index-old.html
index.html
player.png
player (1).png
notes.txt
todo new.txt

A mess like this costs you more than tidiness. Your AI cannot tell which of the three game files is the real one, so it may change the wrong one, and you see no difference and ask again. Your notes sit in two places, and neither gets read.

What does a tidy one look like?

fog-bell-fort/
  CLAUDE.md
  index.html
  game/
    player.js
    enemies.js
    levels.js
  assets/
    images/
    sounds/
  docs/
    design.md
    decisions.md

This is an example for a small browser game, not a rule. Your engine may want something else, and your AI will tell you if so.

Which rules keep it that way?

• One home for each kind of thing. A picture never lives next to a rule.
• No old copies. "Final", "v2" and "old" are jobs for Git, which keeps every saved version, so the folder only needs today's. If you are not using it yet, start here.
• One file per topic. The AI then reads only what a change needs. Small files also help with your AI's working memory.
• Plain, lower-case names. That avoids trouble on servers later.
• One short instruction file. Claude Code reads CLAUDE.md at the start of every session, or AGENTS.md if there is no CLAUDE.md. Other tools have their own.

What goes in the instruction file?

Less than you would think. The Claude Code docs suggest keeping each CLAUDE.md under 200 lines, because longer files take up more space and get followed less. They also say there is no need to describe your file layout: the AI reads your project itself, so "only write down what isn't in there".

For Fog Bell Fort, that comes to six lines: how to start the game, where decisions live, what must never change, and three habits you want from your AI. It does not include a list of folders.

Paste this to your AI

Tidy up my project without changing how the game behaves.

1. Save the current version first, so we can come back. Show me that it is saved.
2. Before you move anything, draw a Mermaid diagram of what uses what: which file loads which, and where each picture and sound is used. Check each arrow against the real files. Mark any file that nothing uses.
3. If several files look like the real one, such as game_final and game_final_v2, do not guess. Show me what you found that tells you which one the game really loads.
4. From that drawing, propose a folder plan and a list of every move. Wait for my yes.
5. Move things in small steps, and update every place that points to a moved file. Do not rewrite or improve anything while you are at it.
6. Delete nothing that has not been saved. Ask me about each file you want to remove.
7. Write a short CLAUDE.md or AGENTS.md: how to start the game, where decisions live, what must never change.

Afterwards, tell me what you tried to see that the game still starts and plays the same, and what you could not try.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

How to check it worked

• Play for five minutes. Everything should look, sound and behave as it did.
• Look at the top of your folder. You should be able to say what each item is.
• Start a new chat. Ask where enemy speed is set. It should find it at once.
• Ask about one deleted file. Your AI should be able to bring it back from a saved version.
• Read the instruction file. If you find a line you do not understand, ask what it is for, or cut it.