Project Files

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

Numbered Project Folders

Numbered project folders guide AI agents such as Claude or ChatGPT Codex, from 0-project-management to 8-archive. What goes in each and why to use them.

Numbered project folders are not a universal convention, but a recommendation I give beginners who work with Claude or ChatGPT Codex. An AI agent remembers almost nothing from one session to the next. It is up to you and the agent to create files that record research, decisions, specifications, and plans as you work on a project. With sufficient ongoing documentation, the agent stays on track toward your goals, even when the agent's working memory, or context, overflows and new sessions are needed.

When people first work with AI, either in web browser chat, a desktop app, or in a terminal window, there is seldom any planning, just spontaneous prompts and follow-up requests. AI agents are eager to help and compliant with any reasonable request, and rarely suggest ways to organize a project unless you specifically ask. Experienced users, both AI consultants and senior software engineers, know to set up project stages and scaffolding to establish structure and cohesion at the start of a project. A structure for plans and process doesn't consume much time when an AI agent does the work. It also leads to better outcomes.

What's in a Project Folder? explains the other files and folders you'll find beside the numbered folders in a project. Organizing a project folder is one item on the complete Mac setup checklist.

Lessons from software development

Numbered folders can be used for any project, but they are particularly well-suited to software development. They roughly follow the software development life cycle (SDLC), the phases most software engineering teams use to plan, design, build, test, release, and maintain software, using architectural or engineering decision records (ADRs or EDRs) and specifications as product requirements documents (PRDs). As Agile teams have learned, it is best to ask an AI agent to loop in short cycles (sprints), updating research, decisions, and specifications as you iterate on the project.

When you need fewer folders

A small or one-off task needs none of this complexity. Just start with a prompt in chat. Or write a short note about what you are trying to accomplish. Obviously, jumping into a new chat session with a quick question (the "AI for search" habit) doesn't need a project folder with numbered folders.

However, I've found that AI agents eliminate most of the overhead of setting up a project folder. Even small projects benefit from the discipline, and don't need much setup time, even if most folders stay empty.

How to get started

You don't have to create the folders yourself. Ask your AI agent to do it. Open Claude or Codex in your project folder and give it this article to read, along with two others that explain the files that go with the folders: Work Ledger and Agent Instructions.

Here's an example prompt:

Read these articles about organizing a project for work with an AI agent:
https://mac.install.guide/project-files/numbered-folders
https://mac.install.guide/project-files/work-ledger
https://mac.install.guide/developer-setup/agent-instructions

Then set up this project folder the same way. Create the numbered folders 0-project-management to 4-playbooks, each with a .gitkeep file. Add a section to AGENTS.md that names the folders and tells you to read the relevant documents before you act. Ask me about the project, then write a short overview of it in 0-project-management. Show me your plan before you create anything.

Claude and Codex can usually read a web page when you give them its address. If the agent says it can't, open the article in your web browser, copy the text, and paste it into the chat.

The prompt's last line is important. Ask the agent to explain what it will create. That gives you an opportunity to change the plan before any files appear.

If your project already has notes or plans, add "Move my existing notes into the right folders" to the prompt.

If you've used one of my "Set Up Your Mac" apps, you may already have a working example. The app's coding starter project, AI-Coding-Project, comes with folders 0-project-management to 4-playbooks already set up. You can give the agent the example's location, such as ~/Documents/AI-Coding-Project, and ask it to copy the layout for a new project. Developer Setup for Starter Projects explains how to get the examples.

From then on, ask the agent to keep the folders up to date as you work. When you settle a question, ask it to write a decision record. Before you build a feature, ask it to write a spec. Spec-Driven Development shows how one leads to the next.

Why numbered folder names?

The numbers, from 0-project-management to 8-archive, set the order for an AI agent to read the files, establishing a workflow sequence simply from folder names. The numbered stages are also helpful for people, so we proceed step by step without overlooking preliminaries.

Sorted by phase, the numbered folders let any new session, or a different AI agent, read the folders in order and pick up where the last one stopped.

The nine folders

Here's what goes in each folder, in the order an AI agent reads them:

  • 0-project-management - where you orient the agent and yourself, with an overview of the project, its roadmap and status, and a backlog of bugs and ideas to defer until later.
  • 1-research - notes on what you learned before deciding, such as the options you compared and the sources you read.
  • 2-decisions - one short record for each real choice, such as a language or a software framework, with the reasons and the alternatives you turned down. The AI agent reads them so it doesn't reopen a question you already settled.
  • 3-specifications - one specification (a spec) per feature, saying what to build, why, and how you'll know it is done, without saying how to build it.
  • 4-playbooks - step-by-step instructions for the AI agent, either the tasks for one piece of work or a procedure you repeat, such as implementing a feature or testing or releasing the project.
  • 5-assets - images, media, and drafts staged before you use them and preserved for reuse.
  • 6-outreach - announcements, campaigns, and emails that tell people about the project, as well as feedback from users.
  • 7-performance - analytics and other measurements of how the project is doing.
  • 8-archive - finished and superseded documents, kept out of the way but not deleted.

The work itself, such as the code, goes in a folder without a number, such as source or src for software code or drafts for articles. Anything that isn't the product goes in a numbered folder.

Why the numbers

The folders follow the phases of the work. In logical sequence, you:

  • orient yourself
  • research
  • decide
  • define what to build
  • plan how to build it
  • preserve pieces from what you made
  • tell people about it
  • measure the results
  • archive what is no longer needed

If the sequence doesn't match the way you work, tell your AI agent to change it. Not every project will match these stages, so change what you need. The discipline is what matters.

An AI agent new to the project reads the folders from low to high to catch up. The numbers also keep the folders in sequence on your Mac. Sorted by name, the Finder lists them from 0 to 8, ahead of folders such as source and work-ledger. Their names don't start with a dot, so you see them without having to show hidden files.

The project's AGENTS.md file should name the folders and tell Anthropic Claude or ChatGPT Codex to read the relevant documents before it acts.

Start with 0 to 4

A small project starts with the first five folders, 0-project-management to 4-playbooks, and adds 5 to 8 when it needs them. That is how the example AI-Coding-Project in the "Set Up Your Mac" apps is laid out, with its work ledger of handoff notes inside 0-project-management. Developer Setup for Starter Projects shows how to get it.

My own projects keep all nine numbered folders, even when some are empty, with the work ledger in the project's top folder. Every project then has the same layout, so an AI agent never has to learn a new one. An empty folder shows that a phase was considered and left for later. Spec-Driven Development shows both layouts side by side, and explains how a research note leads to a decision, a spec, a playbook, and finally the code.

Empty folders and .gitkeep

Git doesn't track an empty folder, so a numbered folder with nothing in it is left out of the project's history. Anyone who copies the project from Git doesn't get it. To keep it, put an empty file named .gitkeep inside the folder. The name is a habit developers share. It is just an empty file. Git treats it as any other file.

To add a folder and keep it in Git, open a terminal application and move into your project folder with cd. The first command below creates the folder. The second creates the empty file inside it:

$ mkdir 5-assets
$ touch 5-assets/.gitkeep

The .gitkeep file starts with a dot, so the Finder hides it. The folder will look empty until you add something.

Dates and IDs in file names

In my own projects, files in four of the folders carry a date and a permanent ID in their names, such as 2026-06-02-EDR-001-database-choice.md in 2-decisions. The four are the project-management, decision, specification, and playbook folders. A spec can then say "as decided in EDR-001". The AI agent can find that decision even if its file is later renamed. Each document also starts with a short header that gives its version, date, and author, and lists its source documents.

Similar ways to organize a project

Parts of this layout come from common practice. Many projects keep their documents in a single docs folder. The numbered folders split that material by phase. The 2-decisions folder follows architecture decision records, which Michael Nygard proposed in 2011 as short, numbered records of each decision, kept with the code. Johnny.Decimal also numbers folders, but to give every item a fixed address rather than a reading order.

Now you can open a project with numbered folders and know where to find its plans, decisions, and specs, and where a new document belongs. Start a small project with folders 0 to 4. Ask an AI agent to write each document in its place as you work.

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.