How to Organize Your Claude Projects

Why structure matters

Claude is a probabilistic AI. If you give it a messy folder with no context, it will produce messy, inconsistent results. But if you give it a clean structure -- files that tell it exactly what the project is, what it should do, and how it should behave -- it becomes reliable.

This lesson shows the structure used by the HivePowered team. It's designed specifically for non-developers who want AI to do serious work.

---

The 3-layer architecture

Every project follows the same pattern:

Layer	Folder	What it does
Directives	directives/	SOPs and instructions in Markdown -- tells Claude what to do
Orchestration	(Claude itself)	Claude reads directives, makes decisions, calls scripts
Execution	execution/	Deterministic scripts that actually do the work

Why this works: Claude is great at reading instructions and making decisions. Scripts are great at doing the same thing the exact same way every time. This structure lets each do what it's good at.

---

Standard project folder structure

your-project/
|- CLAUDE.md               # What Claude needs to know about this project
|- .env                    # API keys and secrets (never commit this)
|- .env.example            # Template showing what keys are needed (safe to commit)
|- .gitignore              # Prevents secrets and exports from going to GitHub
|
|- directives/             # Your SOPs and context documents
|   |- learnings.md        # Bug fixes, quirks, lessons learned (grows over time)
|   |- security_checklist.md  # Rules for handling sensitive data
|   |- [workflow-name].md  # One file per repeatable workflow
|
|- execution/              # Scripts that do the actual work
|   |- [script-name].py    # One script per task
|
|- .tmp/                   # Scratch space for intermediate files (gitignored)

---

What each file does

CLAUDE.md
The most important file. Claude reads this automatically at the start of every session. Put your project overview, rules, key contacts, and file organization here. (Full guide: Lesson 3 in this module.)

directives/learnings.md
This is your error log and lesson book. Every time you hit a bug, a quirk, or find a better way to do something -- write it here. Claude reads it and won't repeat the same mistakes.

Format entries like this:

### Short title (date)
- Problem: what went wrong
- Root cause: why it happened
- Solution: what fixed it
- Impact: what to watch for going forward

directives/[workflow].md
A step-by-step SOP for one repeatable workflow. Examples: email-outreach.md, monthly-report.md, client-onboarding.md.
Claude reads this when you tell it to run that workflow. The SOP tells it exactly what to do.

execution/[script].py
A Python script that does one specific task. Claude can write these for you. Once written, they run the same way every time.
Examples: send-emails.py, generate-report.py, sync-to-notion.py.

.tmp/
A scratch folder for intermediate files. Never committed to git. Claude puts working files here. Anything here is disposable -- Claude can regenerate it.

---

Memory files (cross-session context)

Claude Code saves cross-session memory in a separate location:

~/.claude/projects/[your-project-slug]/memory/
|- MEMORY.md          # The main index -- Claude loads this at session start
|- [topic].md         # Overflow detail for specific topics

MEMORY.md is like a living briefing document. Claude updates it when it learns something new about your project. You can also write to it directly.

Keep MEMORY.md under 200 lines -- Claude Code only loads the first 200 lines. Put overflow detail in separate topic files and link to them from MEMORY.md.

What to put in MEMORY.md:
- Current project status
- Key decisions and why they were made
- Important contacts and their roles
- Any constraints or blockers Claude needs to know about

What NOT to put in MEMORY.md:
- Step-by-step procedures (put those in directives/)
- Bug fixes (put those in learnings.md)
- Temporary status ('currently running X') -- this will be stale next session

---

Skills storage

Skills are stored in your global Claude Code folder:

~/.claude/skills/[skill-name]/SKILL.md

Each skill is a folder with one markdown file. The file contains instructions and context that Claude follows when you invoke that skill.

Skills are global -- they're available in every project. They add about 10-100 KB each depending on how detailed they are.

A full skill library (20-30 skills) adds roughly 50-200 MB to your storage, but makes Claude dramatically more effective at specialized tasks without having to re-explain everything each session.

---

Quick setup for a new project

When you start a new project with Claude Code, run through this checklist:

1. Create the folder structure above
2. Write CLAUDE.md (or use /init to auto-generate it)
3. Create .gitignore before your first git commit
4. Create .env.example with placeholder values
5. Create directives/learnings.md (can start empty)
6. Tell Claude: 'Read CLAUDE.md and tell me what you know about this project'

That last step is the handshake -- Claude confirms it understood the setup, and you can correct anything before you start working.

---

The rule that makes this work

Files over conversation. Every input, decision, and output lives in a file.

• Task brief -> write it to input/ or a directives/ SOP
• Intermediate results -> write them to .tmp/
• Final output -> write them to output/ or sync to Google Docs, Notion, etc.
• Lessons learned -> write them to directives/learnings.md

If you hold information in a chat conversation, it disappears when the context compresses. If you write it to a file, it lives forever and can be picked up by any future session, any team member, or any AI tool.

---

Next: Skills, hooks, and MCP -- the features that let Claude automate without being told every time.

HivePowered AI — AI Like a Pro Training