DEV Community

Tetsuo TANAKA
Tetsuo TANAKA

Posted on Edited on

The First Step Was CLAUDE.md: How I Start a Project with Claude Code

This is part 2 of My First Agentic Coding: Field Notes, a series about the five months I spent growing software through instructions to Claude Code alone, without writing a line of code myself. Each part covers one topic.

In short:

  • "What should I do first?" In the three projects I started from an empty directory, the first step was always CLAUDE.md.
  • I created the first version in three different ways: writing the requirements myself over about four hours, running /init in an empty directory and answering four questions, and leaving it to Claude.
  • None of those first versions was finished. Even a carefully written spec got overturned in use, and I added rules as I went.

Introduction

When I started using Claude Code, my first thought was "What should I do first?"

Looking back, in the three projects I started from an empty directory, CLAUDE.md (the project guide Claude Code reads at the start of a session) always came before the code. But I created it in a completely different way each time.

Project When How it started First version
A web app for an experiment May 15, 2026 I wrote the requirements and had Claude review them 178 lines
JSInterpreter May 23, 2026 I ran /init in an empty directory and answered four questions 75 lines
JSVisualizer May 25, 2026 Claude wrote it along with the design documents 154 lines

The experiment web app at the top of the table is the earliest agentic coding project I have records of. In this post, I go through these three in order, then cover what to do when you already have code. Part 1 describes how I ran the projects as a whole.

The quotes from my sessions below are translated from Japanese, except where Claude answered in English.

Writing out the requirements: the experiment web app

The first thing I built was a small web app for an experiment comparing sounds by ear. On the evening of May 15, I ran /init and immediately asked:

Please create a CLAUDE.md for a Node application. It will use Firebase.

From there, I added requirements one sentence at a time: the purpose of the experiment, the features, the screen layout, the list specification. For example:

New entries and updates shall use the same screen layout, and an update shall show the registered data.

Along the way, I caught one of my own wrong assumptions: "It's not a Node.js application. It's a web application." With no code yet, only the text had to change.

Once the requirements were written, I asked Claude for a review:

Please review CLAUDE.md. Point out anything missing, anything ambiguous, and anything that should be improved.

I fixed what it pointed out (I believe I had Claude do most of the fixing) and said "Please review it again." We went around several times. Where I didn't know something, I said so and left it to Claude:

I don't really know about the detailed frontend stack, so please recommend something suitable.

The finished 178-line CLAUDE.md was essentially a requirements document. It took about four hours. I remember working hard on it.

Today I might keep the requirements in a separate document, but at the time I put everything in CLAUDE.md. This article isn't a guide to how CLAUDE.md should be structured; it's a record of how I actually started using it.

That file was the only thing in the first commit. Five days later, on May 20, my only instruction was "Implement it."

Even a careful spec gets overturned in use

The CLAUDE.md I had worked so hard on became the foundation of the implementation, but what I wrote wasn't always right.

For audio playback, I had written in CLAUDE.md that sound would be "processed using the Web Audio API." Once the app was working, I asked Claude where the code that played the sound was. After seeing the answer, I asked:

Shouldn't it use the HTML audio element?

Claude's reply began with "The CLAUDE.md spec says this." It went on to explain that changing the length with the <audio> element's playbackRate would also change the pitch, so the app used the Web Audio API instead. My own spec was being used to argue against me.

But that explanation was wrong.

Changing the length with the audio element's playbackRate doesn't change the pitch. The current implementation seems to sound much worse than the audio element. Please change it to use the audio element.

On the <audio> element, the preservesPitch property controls whether the pitch is kept when playbackRate changes. It defaults to true, so normally the pitch stays the same when you change the playback speed. Meanwhile, the Web Audio API implementation at the time sounded noticeably worse to me, so I had Claude switch to an implementation that uses the <audio> element.

I took three things from this:

  • Even a spec you wrote yourself can feel wrong once you use the result.
  • "It's in CLAUDE.md" is strong evidence as far as Claude is concerned.
  • Claude's explanations need checking too.

There was one more trap. The implementation moved to the <audio> element, but CLAUDE.md still said "Web Audio API" right up to the last commit. Changing the implementation doesn't change CLAUDE.md by itself, and I hadn't asked for that.

/init in an empty directory: JSInterpreter

The next project, a JavaScript interpreter called JSInterpreter, started in a completely different way.

On the night of May 23, I ran /init in an empty directory. Claude noticed the directory was empty and offered two options:

  1. Create a starter CLAUDE.md for a JavaScript interpreter project you're about to build
  2. Wait until you've added some source files, then re-run /init

I answered "1," and four multiple-choice questions followed.

Question My answer
What language to write it in JavaScript
How much of the syntax to cover Modern ES6+
How to execute programs Tree-walk interpreter
Which test framework Jest

About three minutes later, Claude had finished writing CLAUDE.md. All I did afterward was ask Claude to translate it into Japanese. The CLAUDE.md in the first commit is exactly that translation.

It's easy, but because it's written before the code, the first version is a prediction of what you're about to build. Sure enough, it mentions a name, LoxClass, that doesn't exist in the finished code, and it says nothing about the debugger I built later. Claude itself hinted at this when it finished:

As you start adding source files, re-run /init to refine this with specifics from the actual code.

Three days later, in 42e4873, CLAUDE.md was rewritten into a 146-line version that matched the implementation.

Leaving it to Claude: JSVisualizer

For JSVisualizer, a visualization tool built on JSInterpreter, I left CLAUDE.md to Claude. At ea3d857 (May 25), there wasn't a single line of code, yet the README and design documents were already there alongside CLAUDE.md.

From the first version, it had a section on key design decisions and assumed JSInterpreter's API. I think having that foundation in place is why the first version was so substantial.

The wording of my instruction can't be verified because the session log no longer exists. My only evidence that Claude wrote it is my memory and the Co-Authored-By line.

If you already have code, start there

So far, I've been talking about empty directories. But I suspect many people starting out already have code. In that case, I think the easiest first step of all is to run /init in that directory. Claude can read the real thing, so mismatches with a prediction, like LoxClass, should be less likely.

It doesn't matter if you didn't write the code yourself. Both of my examples began with a different AI.

  • Code and nothing else (October 2026): a small browser-based tool for measuring sound. As I remember it, the code came from Gemini. I created CLAUDE.md with /init, then asked "First, please run git init." Claude wrote the README too. So even code that isn't under version control yet can be set up this way.
  • A settings file from another agent (June 2026): a web app that supports oral exams in my classes. It already had a GEMINI.md for Gemini. The CLAUDE.md that appeared the next day has the same headings and looks like it was carried over and extended. So you don't have to throw that file away. You can build on it.

Keep in mind, though, that code only shows how things are now. What you want to build and what you want protected are things you'll need to add yourself. The rules in the next section are examples of that.

How CLAUDE.md grew

JSVisualizer's CLAUDE.md went through 48 updates and roughly tripled in a little over five months.

Date Size What happened
May 25 154 lines / 6.9 KB First version
June 3 331 lines / 21 KB Updated along with new features
July 23 431 lines / 38 KB Updated to match the actual code
September 29 451 lines / 47 KB Fixed outdated descriptions of the Lifetime view
November 2 452 lines / 51 KB "Key design decisions" reached 47 items

Most of this came from me saying "Document this and commit." Claude wrote the content.

Working rules were a different story: I added them myself whenever I ran into a problem or noticed something. On May 24, in JSInterpreter, I asked:

Please add to CLAUDE.md that regression tests must always be run after changing code, and that the documentation must be updated.

Claude wrote this rule (excerpt, translated):

## Required steps when changing code

When you change source code (under `src/`), **always do both of the following**.

### 1. Run the regression tests

Confirm that all 185 tests pass before committing. If a test fails, do not commit.

### 2. Update the documentation
Enter fullscreen mode Exit fullscreen mode

In JSVisualizer, on November 2, I added a commitment not to delete or rename files that my article series links to. Doing so would break the links in published articles.

That said, CLAUDE.md doesn't have to keep growing. JSInterpreter's has stayed at 146 lines since May 26, and the only changes since then have been to the test count.

I'll cover what happens when CLAUDE.md gets long in part 4.

If I were starting tomorrow

I can't tell you which approach is best. Here is what I would do in each situation.

Situation First step
You can describe what you want to build Give the requirements as a list and ask for a review
It's still vague Run /init in an empty directory and answer the questions
You have a related project Have Claude read it and write CLAUDE.md
You already have code Run /init in that directory
You have another agent's settings file Have Claude write CLAUDE.md based on it

Here are two instructions you can use as they are. I sent both myself (translated here).

Please review CLAUDE.md. Point out anything missing, anything ambiguous, and anything that should be improved.
Enter fullscreen mode Exit fullscreen mode
Please add to CLAUDE.md that regression tests must always be run after changing code, and that the documentation must be updated.
Enter fullscreen mode Exit fullscreen mode

In part 1, I said not to try to write a perfect specification up front, so the experiment web app may look like the opposite. The difference is how settled the work was. The requirements were clear, so I could write them all out first. JSInterpreter was something I was exploring, and four answers were enough to begin with.

The three starts were different, but they had one thing in common: the first CLAUDE.md was never finished. Whether I spent four hours writing it, made it in three minutes, or left it to Claude, I had to rewrite it once implementation got going. How much detail you put in at the start may matter less than whether you keep fixing it as you go.

Limits

  • I can't rank these approaches. The projects differ, and so did my experience at the time. The effort may have dropped simply because I was getting used to it.
  • "First" means first on record. I may have tried it before then, but I don't remember.
  • Some logs no longer exist. I can't verify the text of Claude's review comments on May 15, the wording of my instructions for JSVisualizer's first version and for 42e4873, or the instruction that created the oral exam app's CLAUDE.md.
  • The behavior of /init is as of May 2026. The current version may not ask the same questions.

Checklist

  • [ ] If you can describe what you want to build, write it in CLAUDE.md before the code.
  • [ ] If it's hard to describe, run /init in an empty directory and answer the questions.
  • [ ] If you already have code, run /init in that directory.
  • [ ] When you don't know which technology to choose, say so and ask for a recommendation.
  • [ ] Ask for a review of CLAUDE.md before implementation.
  • [ ] Once code exists, have the first version's predictions corrected to match the implementation.
  • [ ] When the implementation departs from the spec, ask for CLAUDE.md to be updated too.
  • [ ] Add working rules you want followed every time to CLAUDE.md.

Next time

Next time: "I let the AI decide whether to write an ADR." I'll cover what happened when I left the decision about what to record to the AI, and how the ADRs it wrote recorded the implementation rather than my intent.

The May exchanges in this post used Claude Sonnet 4.6.

Top comments (0)