Keeping your Claude Code project organized

A messy project folder wastes time, and Claude has to guess where new files belong. For a small static website, I would start with this structure:

The Basic Structure

Every project needs at least this:

my-website/
  CLAUDE.md
  index.html
  css/
    styles.css
  images/
    profile.jpg
    hero-bg.jpg
  pages/
    about.html
    projects.html
    contact.html

Notice the pattern: each type of file has its own folder. HTML pages in one place, CSS in another, images in a third. Nothing loose in the root except index.html (the home page) and CLAUDE.md.

This isn't the only way to organize a project. It's a good starting point. The specifics matter less than the principle: similar files live together.

The Underscore Convention

I prefix reference folders with an underscore:

my-website/
  _docs/          <-- Planning documents, notes, references
  _debug/         <-- Test files, experiments, scratch work
  CLAUDE.md
  index.html
  css/
  images/
  pages/

The underscore is a visual convention only. It can mark folders that should stay out of the published site, but your deploy configuration, .gitignore, and search tools must exclude those paths explicitly. Test the actual package before relying on the name.

My current deploy script excludes named development paths such as .claude, _debug, docs, and storage/content. It does not exclude every path beginning with _ or ., which is why the explicit list matters.

Keeping Documentation Contained

Without a documented location, Claude may put refactoring notes and explanation files in the project root.

This isn't bad. Documentation is useful. The problem is when it ends up scattered everywhere.

I put the documentation location in CLAUDE.md:

## Documentation
Put all documentation, notes, and planning files in _docs/.
Never create markdown files in the project root.

Now when Claude wants to document something, it has a home for it. Your root folder stays clean, and all your notes are in one searchable place.

The Design Drift Problem

Folder drift can stay hidden for a while. Design drift appears as soon as two pages use different headings, buttons, or spacing.

You ask Claude to create a contact page. It looks great. Then you ask for an about page. Also looks great. But wait. The headings are different sizes. The buttons have different colors. The spacing doesn't match. Each page is fine on its own, but together they look like three different websites.

In the same session, Claude can use earlier conversation and files it has read. A new session loads project instructions, not every design decision hidden in old chat. Put stable choices in the stylesheet and project rules, then compare the rendered pages.

The fix is documenting your design decisions. Even something basic helps:

## Design Rules
- Headings: Use the .heading class, dark gray color
- Buttons: Blue background, white text, rounded corners
- Spacing: 20px padding inside sections, 40px between sections

Better yet, create a reference page. A simple HTML file showing all your styles: headings, buttons, colors, spacing. Tell Claude to check this before creating new pages.

Keep the shared decision in one reference, so changing a button does not become a search across every page.

Naming Files

I use three naming rules:

Keep file names lowercase. Some filesystems and web servers treat capitalization differently, so consistent lowercase names avoid deployment surprises.

Use dashes instead of spaces. Spaces are valid, but they require quoting in terminals and encoding in URLs. Dashes are a simpler default for web filenames.

Use descriptive names such as team-photo.jpg, because IMG_4523.jpg tells you nothing when the folder has dozens of images.

Tell Claude Where to Put Things

When your project has clear structure, be explicit in your instructions:

Good:

Create a new page called services.html in the pages/ folder

Less good:

Create a services page

Both work. The first one puts the file exactly where it belongs. The second one can end up in the root folder, requiring you to move it.

As your project grows, specificity becomes more important. With five files, Claude can figure it out. With fifty files, telling Claude exactly where things go saves time.

When Projects Grow

I reorganize when the same structural problem appears more than once:

• Related files no longer have an obvious home
• Naming becomes inconsistent
• Claude keeps putting new files in the wrong place
• Temporary versions accumulate beside production files

Using search is normal. Unclear ownership is the problem.

When you see these signs, ask Claude to help:

Review my project structure and propose how to reorganize it.
List every file move and every link, import, build entry, and deployment
path that must change. Do not edit anything yet.

Review the plan and commit a restore point. Then move one group and test the site before continuing.

Temporary Files

Failed experiments leave test files behind unless they have a temporary home.

Give them a home: _debug/ or _scratch/. Everything experimental goes there. When you're done experimenting, delete the folder contents. This prevents your project root from filling up with test.html, backup-old.html, final-final-v2.html.

Tell Claude about this in your CLAUDE.md:

## Temporary Files
Put all experimental or test files in _debug/.
Never create test files in the project root or pages/ folder.

Keeping Your Memory Files in Sync

As your project grows, you'll accumulate project instructions in CLAUDE.md, scoped rules in .claude/rules/, and reusable workflows in .claude/skills/. Existing .claude/commands/ files still work, but new workflows belong in skills.

Claude forgets things. It might add a new component but forget to update CLAUDE.md. Create a new controller but not document it in the rules. Over time, your memory files drift out of sync with reality.

I handle this two ways:

Automatic maintenance. My CLAUDE.md includes this instruction:

When you create new controllers, models, or services, update the
relevant documentation in .claude/rules/ to include them.

This helps, but Claude still forgets sometimes.

Periodic sync. I have a command that reviews all my memory files against the actual codebase:

Compare CLAUDE.md, .claude/rules/, and .claude/skills/ with the current
codebase. List stale paths, missing conventions, and conflicting
instructions. Do not edit anything until I approve the findings.

I run this after major structural changes, when the rules are most likely to have drifted from the code.

How I Organize Things

My project uses a more complex structure because it follows an MVC pattern:

• CSS component files in public/css/components/
• Blog views in app/views/blog/
• Project and audit documentation in docs/
• Temporary investigation files in _debug/ when needed

Don't feel like you need to copy this. My structure evolved to fit how this specific project works. Your website might be perfectly fine with the basic structure from the beginning of this article.

This didn't happen on day one. It developed over weeks. Start with the small tree above. When Claude puts something in the wrong place twice, write down the rule and decide whether the folder structure needs to change.