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
/initin 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:
- Create a starter CLAUDE.md for a JavaScript interpreter project you're about to build
- 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
/initto 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.mdfor 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
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.
Please add to CLAUDE.md that regression tests must always be run after changing code, and that the documentation must be updated.
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
/initis 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
/initin an empty directory and answer the questions. - [ ] If you already have code, run
/initin 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)