I Gave Claude Code an Empty Folder

Two commands, and nothing else typed by hand:

mkdir gh-os-contri && cd gh-os-contri
claude

Then one instruction — setup project — into an empty directory. What came back was four questions and a laid-out repository. The folders are not the interesting part of that. The file it wrote while answering the fourth one is.

What the four questions actually asked

They were not a wizard. Each one was a decision that would have been made anyway, pulled forward to the point where it is cheapest to change.

The second one is the one worth showing, because it is the shape of all four:

Should I run git init and set up a remote on GitHub?

  1. git init only
     Local repo, no remote yet
> 2. Init and create GitHub repo
     Uses gh CLI to create and push a remote
     (I'll confirm before publishing)
  3. No git
     Skip version control for now

Three options, each with its consequence written underneath, and a parenthetical that matters more than it looks: I’ll confirm before publishing. The tool is telling you, at the moment you choose, that the irreversible half of this choice has its own gate later. That is not a nicety. It is the difference between a setup step and a setup step that can quietly publish an empty repository under your name.

The other three covered what the project was for, how it should be laid out, and what the working rules were. Four answers, then git init, a README, src and tests.

The folders took seconds. The file is the asset

At the end it wrote CLAUDE.md into the project root and told me what was in it:

I created CLAUDE.md in the project root. It covers four things:

— Layout: the tracker, projects/, notes/ and the git-ignored repos/. — Conventions: the status values, the origin and upstream remotes for forks, and that each project’s own CONTRIBUTING.md takes precedence. — Working rules: confirm with you before any public GitHub action (pushes, PRs, issue comments), never commit to an upstream main, and keep secrets out of commits. — Commit style: short imperative subjects.

Read that list as a set of answers to questions nobody would otherwise be asked until the first time one of them was got wrong. Which remote is which on a fork is not a decision anybody writes down on day one. It is a decision that gets rediscovered, usually by pushing to the wrong one.

The reason this file earns its place is not that it documents the project. It is that every later session reads it before doing anything, so the repository stops being something to work out. I have written elsewhere about what actually gets loaded into context before Claude Code answers you — a short instruction set and a ranked handful of skills, scored against the message you just sent. CLAUDE.md is the part of that which you control completely, and setup is the one moment where writing it costs nothing, because the answers are already on screen.

Writing it later is a different job

The alternative is not “no file”. The alternative is writing it in three months, from memory, about a repository that already has habits.

That version is worse in a specific way. By then the conventions exist in the commit history rather than in anybody’s head, so the file gets written by reading back what was done — which records the accidents alongside the decisions. The upstream remote rule above is a decision. Had it been reconstructed later from a log, it would have been indistinguishable from the three times somebody pushed to the wrong place.

What it should not contain is the other half of the story. A rule about how I like to work follows me between projects and does not belong in a repository that other people clone; a rule about this repository’s layout is useless anywhere else. Which rule lives in which file is its own decision, and I have set out both files and the line between them separately. The setup step writes the project one. It should not be writing the personal one, and it did not try.

What this does not do

It does not pick your architecture. Four questions produced a layout, a remote, a README and a conventions file — scaffolding and agreements, not design. Nothing in that sequence decided a data model or a boundary, and a setup flow that claimed to would be making the most expensive decisions in the project from the least information anybody will ever have about it.

It also does not save much time on its own. The folders were perhaps two minutes of typing. The saving is per session afterwards, and it only exists because the file is accurate — which it is because it was written from four answers given deliberately, rather than inferred from a repository later.

So the test of whether this was worth doing is not how the first session went. It is whether the second session had to ask what the project was. Mine did not.

If you are starting something this week, the thing to take from it is narrow: run the setup into the empty folder before you create anything, and read the file it writes before you accept it. Those are the four answers your next six months of sessions will be working from.