Start Here: Your First Hypothesis, in One Sitting

Every guide we have written about hypothesis-driven development starts in the same place: "write down your hypothesis."

That is not where you are. You are one step before that, and nobody wrote that step down. This is it.

By the end of this page you will have done hypothesis-driven development once, for real — a claim written down, a target set before you looked at any results, and a timestamp that proves you did it in that order. That last part is the whole trick, and you will see why.

It takes about half an hour. You need no programming experience. You install the coding agent, and your Mac may ask once to install its own developer tools.

This guide assumes a Mac. Windows and Linux work the same way, but the menus differ and I have not walked those, so I am not going to pretend otherwise.

First, what you are actually doing

Three sentences, so the setup has a point.

Hypothesis-driven development is writing down what you expect before you find out. You state a claim and a number that would settle it, you save that somewhere you cannot quietly edit later, and only then do you go look.

The value is in the order. If you write the target first, a result that misses it is information. If you write it after, you will — without meaning to, and without noticing — remember your target as whatever you got.

That is not a character flaw, it is how memory works. Researchers have a name for the paper version of it: HARKing, hypothesizing after results are known. The fix is not willpower. The fix is a timestamp.

Before you start — two things to know

This guide assumes a Mac. The ideas are the same everywhere; the exact commands are not.

One of the steps costs money, and you should hear that now rather than at minute twelve. Step 2 installs a coding agent, and signing in to it needs a paid Claude plan. The entry tier — around twenty US dollars a month as of August 2026 — is enough for everything in this guide.

That figure is dated on purpose: check claude.ai for what it actually costs today. But "it costs money, go and find out how much" is not a helpful thing to tell someone deciding whether to spend their morning, so: roughly twenty dollars, monthly, cancellable.

Everything else is free. GitHub is free, git is free, the folder is a folder. If a paid plan is not something you want, stop here rather than partway through — you can still read the method and run the whole loop with a text file and a date, which is chapter 2's point.

Step 1 — Get a GitHub account (5 minutes)

What GitHub is, for our purposes: a website that stores folders of files and remembers every change ever made to them, with the date and time of each one. That memory is what makes it useful here. It is where your timestamp comes from.

  1. Go to github.com/signup.
  2. Enter an email, a password, and a username. The username is public; your own name is fine.
  3. Verify the email they send you.

That is all. You do not need to pay, and you do not need to understand anything else about GitHub today.

A word you will see: "repository", usually shortened to "repo". It means one project's folder. That is genuinely all it means.

Step 2 — Install the coding agent (5 minutes)

This is the thing you install on purpose. One more may install itself; that is Step 2b and it takes no work from you.

A coding agent is a program you talk to in plain English, which then does the computer parts for you — creating folders, saving files, recording changes. You are not going to learn commands. You are going to ask.

⚠ This is the step that needs the paid plan. When it asks you to sign in, it is asking for a Claude account with an active subscription. If you do not have one yet, set it up first — being sent to a pricing page halfway through a terminal command is a miserable way to find out.

Open Terminal. It is on your Mac already:

  • Press ⌘ + Space, type Terminal, press Return.

A window opens with some text and a blinking cursor. This is Step 3's subject; for now just use it.

Copy this line, paste it into that window, and press Return:

curl -fsSL https://claude.ai/install.sh | bash

It will print progress for a minute or two.

Then close the Terminal window and open a new one — this matters, because the new window is the one that knows the agent exists. Now type:

claude

The first time, it will ask you to sign in. Follow the prompts; it opens a browser.

If claude says "command not found": you are almost certainly in the Terminal window that was open during the install. Close it, open a fresh one, try again. This catches nearly everyone once.

Step 2b — Git housekeeping (2 minutes, or ~15 if your Mac fetches its developer tools first — it probably will)

Later steps use git, the thing that records your history. Two small surprises live here, and both are much less annoying now than in the middle of Step 5.

First, check whether you have it. Type:

git --version
  • A version number (like git version 2.50.1) — you are done, skip to Step 3.
  • A dialog box offering to install "command line developer tools" — click Install and let it run. It is a few minutes and a large download, it is Apple's own, and it is safe. macOS ships a placeholder for git that fetches the real one on first use, so this is the moment it happens. The agent's installer does not bring git with it.

Second, tell git who you are. Otherwise it invents an identity from your computer's name and quietly stamps every entry with something like [email protected]. It will not stop you — it will just record the wrong thing forever, which is worse. Run these two, with your own details:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Use the same email as your GitHub account from Step 1. That is what links what you do here to your account there.

Step 3 — About that terminal window (3 minutes)

Skip this if you are comfortable already. If you are not, it is worth three minutes, because the terminal is the thing that makes people stop.

What it is: a window where you type an instruction and press Return, instead of clicking. That is the entire concept.

You will not break your computer. Nothing in this guide deletes anything. The commands here create a folder and write text files in it.

Three things worth knowing:

  • Where you are matters. The terminal is always "inside" some folder, the way a Finder window is showing some folder. pwd prints which one.
  • Nothing happens until you press Return. A typo is not a problem before then; use Backspace.
  • Errors are text, not alarms. When something goes wrong it prints a sentence. Read the sentence. Usually it says what it wanted.

Try one now — type this and press Return:

pwd

It prints a path like /Users/yourname. That is your home folder. You are there. That is all pwd does.

Step 4 — Make somewhere to keep your thinking (5 minutes)

Now use the agent instead of learning commands.

In your Terminal, start it:

claude

Then type this to it in plain English — it is a conversation, not a command:

Make me a new folder called hypotheses in my home directory, set it up as a git
repository, and create a README that says it is my hypothesis log. Explain what
you did in plain language as you go.

The agent will create the folder, run the setup, and tell you what it did.

Note where it put things. It makes a folder named hypotheses inside where you are — so the repository is hypotheses/, not the folder you started in. That is why the next step says "in the hypotheses folder". A good agent works this out on its own and will say so; you do not have to manage it.

What a "git repository" is, since it just made you one: a folder that keeps its own history. Every time you save a checkpoint, it records what changed, when, and that it was you. You cannot change a past checkpoint without it being obvious. That property is the only reason we are using it.

A checkpoint is called a "commit". You will see that word constantly. It means: save a snapshot, with a note about what changed.

Step 5 — Your first hypothesis (10 minutes)

Here is the part that is actually the method.

Think of something you currently believe but have not checked. It does not have to be about software. Real examples from people learning this:

  • "Our onboarding email gets opened more when the subject line is a question."
  • "Most of my support tickets come from one feature."
  • "Adding examples to my prompt gets better answers out of the AI."

Pick one where you could actually go and look afterwards.

Now write it down with a number attached — before you look. Tell the agent:

Create a file called my-first-hypothesis.md in the hypotheses folder. Put in it:
my hypothesis, the number that would settle it, how I plan to check, and today's
date. My hypothesis is [YOUR CLAIM]. I will consider it supported if [YOUR
NUMBER]. Then commit it with the message "hypothesis: before looking".

Fill in the two brackets with your own. Be specific about the number. "Better" is not a target. "Under 30% need a correction" is a target.

The trap that catches everyone, including me. Prefer an absolute number — "under 30%" — over a relative one — "20% fewer". A relative target needs a baseline you probably do not have yet, and a target you cannot evaluate is a target you will end up filling in afterwards with whatever makes the result look good. That is the exact hole this whole practice exists to close, reopened by a plausible-sounding number.

If a relative target is genuinely the right one, then measure the baseline first and commit it too — before you change anything.

I wrote a relative target into the first draft of this page and the agent pushed back on it while I was testing these very instructions. It was right.

If you cannot put a number on it at all, that is worth knowing now rather than later — it usually means the claim is not yet sharp enough to test.

Then ask:

Show me the commit you just made, with its timestamp.

It will show you something like commit a3f8b21 and a date and time.

Now put it somewhere you cannot quietly edit

This is the step that makes the rest of it true, and it is why you made the GitHub account in Step 1.

So far everything lives on your own laptop, and a checkpoint on your own laptop is one you can rewrite. Not by accident — you would have to go out of your way — but git will let you change what a past entry says and what time it claims to have happened, and the display will show the new version as though it had always been that way. A record only you control is a record you are trusting yourself not to edit. That is the thing this whole practice exists to avoid, and it does not help to avoid it everywhere except here.

So send a copy somewhere else:

Create a private repository on GitHub called hypotheses and push this to it.
Then show me the link.

The agent will walk you through signing in the first time.

Now the claim is real. GitHub has its own record of when it received this, and that record is not yours to edit. If you later change what is on your laptop, the two copies disagree — visibly, on a page anyone you show it to can read.

Private is fine. "Private" means only you can see it. It still timestamps. You are not publishing your thinking; you are putting it somewhere that will not quietly agree with a later version of you.

That is the whole mechanism. When you go and look — today, next week — the result either clears the bar you set or it does not, and moving the bar now means moving it somewhere a second party can see it move.

What just happened

You did all three parts:

  1. Stated a claim and a target, specifically.
  2. Recorded them before collecting anything, somewhere that remembers when.
  3. Put that record beyond your own reach, so revising the target quietly is no longer something you could do without it showing.

You did not need a kanban board, a project tool, or a programming language. Those come later and only if you want them — a tool makes this cheaper to do fifty times, but it is not what makes it work.

And one thing worth saying plainly: a hypothesis that fails is a good outcome. It is the outcome that taught you something. The one that teaches you nothing is the one you never wrote down.

Where to go next

You are halfway. Your prediction is on the record, timestamped, beyond quiet revision — which is the half almost everyone skips. The other half is going to look, and looking properly turns out to be less obvious than it sounds.

  • Next: Go and Look — about twenty minutes. It closes the loop, and it covers the five-minute check that catches the mistake most first loops make. Do not do this part from memory; it is the one with the trap in it.
  • After that: When a Tool Earns Its Place — when one file per hypothesis starts to feel like too many files, and only then, that is the moment a board is worth having.

You are not behind. You just did the part that most people skip.