Skip to content

3.2 Files, Folders, and Paths

Everything on your computer — every photo, app, website, and AI project — is a file in a folder, and every file has an address called a path. This sounds too basic to be a lesson until you realize: paths are how you and your agent point at the same thing. Half of all beginner agent confusion is really path confusion. Thirty minutes here saves hours later.

What you will learn

  • Read any path and know exactly where it points.
  • Use absolute vs. relative paths and know when each is right.
  • Understand what a "project" is — the unit your agent thinks in.

Builder principle

When you and your agent share precise addresses, ambiguity dies. "The file" is a guess; src/index.html is a fact.

The tree

Your computer's storage is one big upside-down tree. On a Mac it starts at / (the root) and branches down:

/
└── Users
    └── jordan          ← your home folder, aka ~
        ├── Desktop
        ├── Documents
        └── builds       ← your course workspace
            └── candle-site
                ├── index.html
                └── images
                    └── logo.png

(WSL/Linux is the same shape with /home/jordan; native Windows says C:\Users\jordan — same idea, different costume.)

A path is directions through the tree, folders separated by /:

/Users/jordan/builds/candle-site/images/logo.png

Read it left to right: root → Users → jordan → builds → candle-site → images → logo.png. Every file on the machine has exactly one such address.

Absolute vs. relative

Absolute paths start from the filesystem root or your home folder. They work from anywhere:

$ cat ~/builds/candle-site/index.html

Get-Content (Join-Path $HOME "builds\candle-site\index.html")

Relative paths start from where you're standing (your pwd):

$ cd ~/builds/candle-site
$ cat index.html
$ cat ../terminal-drill/log.txt

Set-Location (Join-Path $HOME "builds\candle-site")
Get-Content .\index.html
Get-Content ..\terminal-drill\log.txt

The two special names: . means "right here," .. means "one level up."

Rule of thumb: inside a project, use relative paths (they're what your agent uses in its reports). Jumping between projects, use absolute ones. When a "file not found" error strikes, first show the current location, then list what is there: pwd and ls in Bash, or Get-Location and Get-ChildItem -Name in PowerShell.

The project: your agent's intended workspace

A project is one folder holding the files for one build. When you start Claude Code inside ~/builds/candle-site, that folder becomes its intended workspace and primary context. It is not automatically an operating-system security boundary: an approved command or connected tool may reach files, credentials, networks, or services outside it.

This is why the course insists on structure:

~/builds/                  ← everything you make lives here
├── candle-site/           ← one project, one folder
├── weekly-report-bot/     ← another project, another folder
└── terminal-drill/        ← even practice gets a folder

One project per folder buys you three things:

  1. Scope — requests, diffs, and path rules can target one clearly named workspace. Use tool sandboxing, permission policy, scoped credentials, and backups for actual security and recovery boundaries.
  2. Clarity — every path in a session means one unambiguous thing.
  3. Portability — a self-contained folder can be backed up, shared, or published as a Git repository in one move. (Next lesson.)

A few file-name habits that pay forever

  • Lowercase, hyphens, no spaces: candle-site, not Candle Site (FINAL) 2. Spaces in names force quoting everywhere and trip up tools.
  • Extensions tell the truth: .html is a web page, .md is formatted text (this entire course is .md files), .txt is plain notes. Your agent reads extensions as meaning — so should you.
  • README.md at the top of every project: the note that says what this folder is. Future-you forgets; README remembers. (In Chapter 5, its big sibling CLAUDE.md becomes the agent's briefing document.)

Try it now

Build your first properly structured project skeleton by hand:

$ cd ~/builds
$ mkdir -p quick-win/notes
$ cd quick-win
$ echo "# Quick Win" > README.md
$ echo "brief lives here soon" > notes/brief.txt
$ ls
$ cat notes/brief.txt
$ cat ./notes/brief.txt
$ cd notes
$ cat ../README.md

Set-Location (Join-Path $HOME "builds")
New-Item -ItemType Directory -Force -Path .\quick-win\notes
Set-Location .\quick-win
Set-Content -Path .\README.md -Value "# Quick Win"
Set-Content -Path .\notes\brief.txt -Value "brief lives here soon"
Get-ChildItem -Name
Get-Content .\notes\brief.txt
Set-Location .\notes
Get-Content ..\README.md

In Bash, mkdir -p creates nested folders in one command. In PowerShell, New-Item -ItemType Directory -Force does the equivalent. This folder is where your Lesson 1.4 quick win will actually get built in Chapter 4.

Check your understanding

  • Read this path out loud and name every hop: ~/builds/quick-win/notes/brief.txt
  • What do . and .. mean? When would you use ../?
  • Your agent says it edited src/app.js but you "can't find it." What two inspection commands diagnose this in your shell, and in what order?
  • Why use one project per folder, and which additional controls create real security and recovery boundaries?