Organize Your Claude Code Projects

Organizing Your Projects

You've built a few automations. You have CLAUDE.md files, input folders, output files, maybe some intermediate data. It's starting to get messy.

This lesson is about keeping things organized so you can find what you need, run your automations reliably, and not drown in random files.

The basic folder structure

Here's a pattern that works for most projects:

~/my-automation/
  CLAUDE.md           # Project context and rules
  /input/             # Raw files you're processing
  /output/            # What Claude generates
  /archive/           # Old inputs after processing
  README.md           # Notes for future you

That's it. Four folders and two files. Let's break down why each matters.

The input folder

This is where you drop files before processing. Keep it clean:

/input/
  sales_march_2026.csv
  sales_april_2026.csv

Don't mix input files with outputs. Don't leave files here after they're processed. The input folder should only contain "stuff waiting to be processed."

The output folder

Everything Claude generates goes here:

/output/
  report_2026-03-09.md
  cleaned_sales_march.csv
  cleaned_sales_april.csv

Use consistent naming. Include dates when relevant. Your future self will thank you when searching for "that report from two weeks ago."

The archive folder

After processing, move input files here instead of deleting them:

/archive/
  2026-03/
    sales_march_2026.csv
  2026-04/
    sales_april_2026.csv

Organize by month or week, depending on volume. This way you can always go back and reprocess if something was wrong.

The README

A simple text file explaining:

• What this automation does
• How to run it
• Any quirks or gotchas

Example:

# Weekly Sales Report Automation

## What it does
Processes sales CSVs and generates a markdown report with 
week-over-week comparisons.

## How to run
1. Drop CSV export in /input/
2. Run: claude
3. Say: "Process this week's sales report"
4. Output appears in /output/

## Notes
- CSV must have columns: date, rep, amount, status
- Expects fiscal year starting April 1 (configured in CLAUDE.md)

Takes 2 minutes to write. Saves 20 minutes of confusion when you come back to this in 3 months.

Naming conventions

Pick a pattern and stick to it:

Files:

• report_YYYY-MM-DD.md for dated outputs
• [type]_[source]_[date].csv for data files
• Lowercase, underscores, no spaces

Folders:

• Lowercase
• Descriptive but short: sales-reports, expense-tracking, client-data

Bad: New Folder (2), stuff, FINAL_final_v3.csv

Good: sales_report_2026-03-09.md, expenses_march_2026.csv

One project, one folder

Resist the urge to dump everything in one mega-folder. Each distinct automation gets its own project folder:

~/automations/
  /sales-reports/
    CLAUDE.md
    /input/
    /output/
  /expense-tracking/
    CLAUDE.md
    /input/
    /output/
  /client-invoices/
    CLAUDE.md
    /input/
    /output/

Each CLAUDE.md is specific to that project. Each has its own input/output folders. No confusion about which files belong where.

Version control (optional but recommended)

If you're comfortable with Git, version control your automation folders:

cd ~/automations/sales-reports
git init
git add CLAUDE.md README.md
git commit -m "Initial setup"

Don't commit data files (add /input/ and /output/ to .gitignore). Just track the CLAUDE.md and README. This gives you history of how your automation evolved.

If Git sounds scary, skip it. The folder structure alone is a huge improvement over "everything in Downloads."

Cleaning up regularly

Set a monthly reminder to:

1. Move processed files to archive
2. Delete old outputs you don't need
3. Update README if anything changed
4. Check if CLAUDE.md needs tweaks based on recent issues

15 minutes of maintenance prevents hours of archaeology later.

Example: setting up a new project

Let's say you want to automate invoice processing. Here's the setup:

mkdir -p ~/automations/invoice-processing/{input,output,archive}
cd ~/automations/invoice-processing

Create the CLAUDE.md:

# Invoice Processing

Read PDF invoices from /input/ and extract:
- Invoice number
- Vendor name  
- Date
- Line items
- Total

## Rules
- Save extracted data to /output/
- Name files: invoice_[vendor]_[date].csv
- After processing, move PDFs to /archive/[month]/
- Flag any invoice over $5,000 for review

Create a quick README:

# Invoice Processing

Drop PDF invoices in /input/, run claude, say "process invoices."
Extracted data lands in /output/.

Done. You now have a clean project structure ready to use.

Next up

You've got a clean project structure. Before we cover debugging, there's something important: how to use Claude Code without accidentally deleting your files or exposing sensitive data. Next up — staying safe.