module 12 folder structure

When to reorganise

System Text-to-Speech Ready
Slide: 0:00 / 0:00
Slide 1 of 0Interactive Deck

Full Lesson Reference

Your Claude Code structure should evolve as your work evolves. But reorganising costs time - files move, paths break, memory references go stale. Know when it's worth the cost and how to do it without breaking things.

Signs it's time to reorganise

  • Finding files takes more than 30 seconds on average
  • Same content exists in multiple places (you can't remember which is current)
  • CLAUDE.md files are bloated because they're trying to cover too much
  • Claude is mixing context from different projects (cross-contamination)
  • You've hit the 16K skill budget because skills aren't scoped per project
  • Your current pattern was set when you had fewer clients/projects + doesn't fit now
  • You keep meaning to create a sub-folder for X and haven't

Any of these = time to tidy. Two or more = priority.

Signs you shouldn't reorganise yet

  • Current structure is messy but you can still find things
  • You're in the middle of active work that would be disrupted
  • You're tempted to over-engineer a structure for a speculative future
  • You've only been using the current structure for a few weeks

Wait until real pain forces it. Premature reorganisation is procrastination.

Minor reorganisations (anytime)

Small changes that don't break paths

  • Moving a finished project to archive/
  • Creating a sub-folder for existing scattered files
  • Splitting a bloated CLAUDE.md into a shorter main + @file refs
  • Renaming a folder to follow your naming convention
  • Adding _shared/ and moving reusable assets in

Do these any time. Low cost, immediate benefit.

Major reorganisations (plan it)

Big changes that affect memory, GitHub, or multiple projects:

  • Switching from agency to in-house pattern (or vice versa)
  • Restructuring how clients are nested
  • Moving skills between global and project-scoped
  • Renaming the top-level Claude Code folder
  • Consolidating multiple GitHub repos

These need a plan (Module 11)

Brainstorm a reorganisation. Current structure is [describe]. I want to move to [describe]. What breaks if I just move files? What order should I do things in to minimise pain?

Claude identifies impact + proposes a migration plan. Execute in chunks across sessions.

What breaks when you move files

Things that reference paths

  • CLAUDE.md @file references
  • Supabase memory records with project_path
  • GitHub links + hardcoded URLs in deliverables
  • Skills that hardcode folder paths
  • Backup scripts
  • Your muscle memory for cd commands

Audit before moving

Search all my CLAUDE.md files, skills, and memory records for references to [old path]. Show me what would need to update if I rename that folder to [new path].

Claude finds all the dependencies. Decide whether to update references first or move first.

Migration pattern

Safest way to do a major reorganisation

  1. Plan it (session 1)

Help me plan a reorganisation from [current] to [new]. What files move where? What references need updating? What's the risk order?

Save the plan to notes.md.

  1. Update references first (session 2)

Update CLAUDE.md @file refs, skill paths, and memory project_path values to point to the NEW locations - before moving the files.

When files then move, they're already expected at the new location.

  1. Move files (session 3)

Move [old location] to [new location]. Use git mv so history is preserved. Commit the move with a descriptive message.

  1. Verify + fix breakage (session 4)

Scan for any remaining references to the old paths. Test Claude Code in the new structure - does /startup still find the project? Are skills still registered? Does memory still connect? Fix whatever broke.

  1. Clean up (session 5)

Remove any empty folders or stale backups left behind. Update this module's notes with what you learned.

Memory layer migration

If the reorganisation includes moving projects between folders, your session_memories table has project_path values pointing to old locations. Update them:

In my session_memories and projects tables, update any project_path values from [old] to [new]. Show me what would change before applying.

Claude previews, you approve, it applies. Search across past sessions still works.

Quarterly mini-audit

Once a quarter, 30 minutes

Audit my Claude Code folder structure. Flag

  • Folders that haven't been touched in 3+ months (archive candidates)
  • Similar content in multiple places (merge candidates)
  • CLAUDE.md files over 60 lines (consolidation candidates)
  • Any pattern mismatch vs my current work style
  • Things I keep meaning to organise better

Give me a prioritised list.

Keeps drift in check without major surgery.

Power-user tips

  • Archive instead of delete - cheaper to keep than to regret deleting
  • Git history survives folder renames - use git mv not delete + create
  • Update references BEFORE moving files - safer than fixing breakage after
  • Don't reorganise during busy work periods - schedule it for lighter days
  • Take a backup snapshot first - tell Claude to create a zip of the whole Claude Code folder before major surgery

Action items

☐ Add a quarterly folder audit to your calendar (30 min)

☐ If you have an obvious reorganisation need, plan it across multiple sessions (don't do it all in one)

☐ Always update references before moving files

☐ Archive finished projects the day they finish (prevents buildup)

Module complete. Next: Module 13 - Manage tokens and performance.

Exercises

  1. Review the concepts covered in this lesson: When to reorganise.
  2. Write down your key takeaway from this lesson.
  3. Practice running any commands or prompts mentioned above inside your terminal.