Project Files

Written & tested for accuracy by a developer (not AI) · Updated November 2026

What's in a Project Folder?

What's in a project folder? Explains odd files like .gitignore, .env and CLAUDE.md. Learn about hidden files that advanced users add, and files your software creates.

A project folder is any ordinary folder you've created on your Mac for something you're working on. A project could be a report, writing, research analysis, or a website you're building. For a software developer, it holds the code, its settings, and the documents that guide development. If you work with an AI agent such as Anthropic Claude or ChatGPT Codex, the project folder contains instructions and rules to guide the agent and provide context for its working memory.

Open a project folder for the first time and you'll find files with odd names that software created. Many of them are hidden and only visible in a terminal window or with an option in the Finder.

If you want to really know how to use your Mac, learn what these files are for. Then, if you want to get the most out of work with AI, learn about the files that guide AI agents.

Knowing your way around a project folder is part of setting up a Mac for coding. See the Mac development setup guide for the rest.

A sample project folder

Here is a project set up for work with AI agents. No real project has every item shown here. Most people start with three or four files and add others as they need them. Programming languages and software tools add a few more files of their own. The Finder hides any file or folder whose name starts with a dot.

Take a look and see if you already know what each file or folder is for.

my-project/
├── README.md              the project's purpose and how to run it
├── AGENTS.md              instructions for AI agents
├── CLAUDE.md              one line to redirect Claude to AGENTS.md
├── CHANGELOG.md           a record of what changed, newest first
├── LICENSE                how others are allowed to use the project
├── .gitignore             files to exclude from version control
├── .env                   secrets such as API keys
├── .DS_Store              the Finder's view settings for this folder
├── .claude/               project settings and skills for Claude
├── .codex/                project settings for ChatGPT Codex
├── .agents/               skills for Codex and other AI tools
├── .github/               settings and automation for collaboration
├── work-ledger/           handoff notes between AI sessions
├── 0-project-management/  … 8-archive/   plans and specs to guide AI
├── src/                   code for a software project
├── tests/                 automated tests for a software project
├── docs/                  documentation
└── scripts/               helper scripts

What each item does

Here is a brief explanation with a link to an article that describes the file or folder in more detail:

  • README.md - describes the project's purpose and how to run it, both for people and AI agents. It is intended to be the first file anyone opens.
  • AGENTS.md and CLAUDE.md - the instructions an AI agent reads at the start of every session. CLAUDE.md often holds the single line @AGENTS.md, so Claude and ChatGPT Codex read the same instructions.
  • CHANGELOG.md - a dated list of what changed, newest first, which you update, or ask an AI agent to update, when a task is done.
  • LICENSE - the terms under which other people may use the project if it is shared. Without one, the author keeps all rights, so others may not reuse it. For software, the license indicates if the code is open source and the conditions that allow copying.
  • .gitignore - the list of files and folders Git will leave out of the project's history, such as secrets and folders that software creates.
  • .env - settings and secrets, such as API keys, that a program reads when it starts. Be sure to keep this file out of Git history.
  • .DS_Store - a file the Finder makes to remember how a folder looks. It is the one Mac-only item here.
  • .claude/, .codex/, and .agents/ - the project's settings and skills for Claude, Codex, and other AI coding tools.
  • .github/ - files that GitHub reads from your project, such as workflows that run automated software tests.
  • work-ledger/ - short handoff notes an AI agent writes at the end of a session, so the next session gets context for the next task.
  • 0-project-management/ to 8-archive/ - nine numbered folders for the plans, research, decisions, and specifications behind the code. Not a universal convention, but a recommendation I give beginners.
  • Language files - each programming language will add its own. A JavaScript project has package.json. A Python project has pyproject.toml and a .venv/ folder.

The folders src/, tests/, docs/, and scripts/ don't have articles of their own. They are explained in "Typical code folders" below.

Hidden files in a project folder

Any file or folder whose name starts with a dot is hidden in the Finder. That includes .gitignore, .env, and the AI agents' folders, so a project folder can look nearly empty even when it holds many files. Press Command + Shift + . (period) in a Finder window to show hidden items. Press it again to hide them. Show Hidden Files on Mac explains more ways to see them.

Even with hidden files shown, the Finder keeps its own .DS_Store files out of sight. To see everything in a project folder, open a terminal application, move into the folder with cd, and list its contents with the -a option, which includes hidden names:

$ ls -a

You can't create a hidden file in the Finder. If you rename a file to a name that starts with a dot, the Finder shows an error, because macOS reserves those names for the system. Tools create them, or you can create one with a terminal command or a code editor.

Files you write and files created by software

Some project files are written by people (or by an AI agent, at your request). Others are made by software tools. Do what you want with the files you've created. Leave the tool files alone. If you delete them, configuration settings may disappear. A software tool may also make them again automatically.

  • Written by you - README.md, AGENTS.md, CHANGELOG.md, the plans and notes in the numbered folders, and the code in src/.
  • Made by tools, kept out of Git - .venv/, node_modules/, dist/, build/, and .DS_Store. The .gitignore file in the "Set Up Your Mac" example projects lists all of these, along with any .env file.
  • Made by tools, kept in Git - lock files, such as package-lock.json. You don't edit them by hand, but you commit them, so everyone who works on the project installs the same package versions.

Plans and notes for AI agents

When you work with an AI agent, a project folder holds more than code. An AI agent remembers almost nothing from one session to the next, so the plans, decisions, and notes on what was done have to live in the project folder as files. That is why well-planned projects have items such as AGENTS.md, the .claude/ folder, the numbered project folders, and a work ledger. Developer Setup for Starter Projects shows how to set up a project folder of your own. Spec-Driven Development shows how the plans lead to well-designed software code.

Typical code folders

These names are conventions shared by many software projects. A project's settings can specify a different folder name, so look at what a folder holds before you assume its purpose.

src folder

src is short for "source". It is the usual name for the folder that holds code used to build an application.

source folder

source/ is the same thing with the name spelled out. The "Set Up Your Mac" starter projects use it, such as source/hello.py in AI-Coding-Project. The two names mean the same thing, and which one a project uses matters only to the people who read it and to the project's settings.

dist folder

dist is short for "distribution". It holds the finished files a build step produces, ready to install or publish. A software build process makes this folder. A project's .gitignore usually lists it, so a large finished application isn't stored in the Git history. If it takes up too much storage, you can delete it and rebuild your application when you need it again.

build folder

A build tool puts its working files or its output in build/. As with dist/, a software build process makes this folder. Leave it out of Git history. It contains temporary files, so delete it if it takes up too much storage.

lib folder

lib is short for "library", meaning code used by other code, often the project's own building blocks. JavaScript's npm package.json documentation names lib as one of a package's standard folders. In some projects, a build tool fills lib with files it produced, so check what's in it before you edit anything there. Code from other developers' projects usually goes in a separate folder, such as node_modules/ in a JavaScript project.

scripts folder

scripts/ holds small programs that help you work on the project, such as setting it up, building it, or releasing it. They aren't part of the product itself.

tests folder

tests/ (or test/) holds automated tests, small programs that check whether the code works as intended. An AI agent that runs tests can check its own work and fix its mistakes before you see them. You (or AI) can build software without writing tests, but the presence of tests is an indicator that the project is robust and well-designed.

docs folder

docs/ holds documentation for people and AI agents, such as guides longer than a README. GitHub Pages can publish a website straight from a docs folder.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.