This article was originally written in Japanese and translated into English with AI assistance. Please note that some expressions may carry nuances from the original Japanese.
🇯🇵 日本語版はこちら / Japanese version
Series: DataMigrator Development Journal (Part 5)
By the end of last time, requirements and design were done. Up to this point, I’d been proceeding with the Claude I normally use (the chat screen in a browser or app). But once I was finally about to enter the stage of actually writing code, one more preparation was needed: the work of introducing a type of Claude that runs inside the terminal, called “Claude Code.”
Honestly, until I introduced it, “what do you mean there are two kinds of Claude?” hadn’t really clicked for me. This time, I’ll write the record of the introduction, up to the point where that question got resolved.
What’s the Difference Between the Chat Version and the Code Version?
There are, broadly, two ways to use Claude. One is “Claude.ai,” used in the chat screen of a browser or app. This is what I’d been using for requirements and design up to now. You write a question in the input field, and a reply comes back. You can also attach files. The UI is nearly the same as a typical chat app.
The other is “Claude Code.” This is a Claude that lives in the Mac’s terminal (that thing where you type characters with the keyboard on a black screen), and the biggest difference is that it “can directly read and write files” and “can directly execute commands.”
To put this in my own metaphor, which I arrived at by hearing it out with Claude Code — the chat version of Claude is “a consultant who gives instructions over the phone from outside the room,” while Claude Code is “a pair programmer who comes into the room and hits the keyboard together with you.” The former is excellent as someone to consult, but the one actually doing the hands-on work is you. The latter writes the code and creates the files directly, but in exchange, if you don’t keep a proper watch on what’s being written, there’s a possibility of unintended changes creeping in. They’re each good at different roles.
For DataMigrator’s implementation, I decided to use these two with a division of roles. I’d have Claude.ai handle the roles of “design consultant,” “someone to talk to when I’m unsure of a decision,” and “recorder of blog material,” while I’d ask Claude Code for “the actual implementation work.” The practice is to develop while going back and forth between the two windows.
The Install Was Anticlimactically Easy
The actual install work finished so smoothly it was anticlimactic. The flow is: put in Node.js via the macOS package manager called Homebrew, and install Claude Code from there. I don’t think it took even ten minutes in total.
When I launched it, Claude’s logo was displayed in ASCII art inside the terminal, I was made to choose a theme (color scheme), I was asked to authenticate, and it safely reached a usable state. When “Welcome back, Satoshi!” appeared, I had a somehow strange feeling. The me logged in via the browser and the Claude inside the terminal are connected by the same account. Obvious if you call it obvious, but when the kind of screen changes, the same partner feels like a different person.
That said, in contrast to the speed of the install, “understanding the security side” afterward took a little time.
A Three-Layer Security Setup
Claude Code can read and write files and can also execute commands. In other words, it also means that, in a worst case, it could do whatever it likes inside my Mac. Using it without understanding this point felt frightening.
So for a while, I spent time hammering the Claude on the Claude.ai side with questions like “can Claude Code be used safely?” to understand the mechanism. As a result, I learned that Claude Code has a three-layer set of safety measures.
The first layer is the “capability scope.” Claude Code basically works within the directory (folder) it was launched in, and going outside that requires an explicit instruction. This is like a building’s “off-limits area” — the image of places it can’t access being decided from the start.
The second layer is a file called “CLAUDE.md.” This is, so to speak, a “house rulebook” that Claude Code reads if you place it inside the project. If you write rules in natural language — “do not use sudo (escalation of administrator privileges),” “do not touch this directory,” “do not commit while tests aren’t passing” — Claude Code acts in accordance with them. As I’ll describe later, in DataMigrator’s CLAUDE.md I also wrote in the project-wide philosophy of “never delete.”
The third layer is something called the “Allow flow”: when Claude Code is about to do something with side effects (rewrite a file, execute a command, access something external), it asks for permission just beforehand — “may I do this?” It isn’t executed until the human presses “Yes.” The more dangerous the operation, the more carefully this permission dialog comes up.
After understanding this three-layer setup, I came to hold the sense that “Claude Code is convenient, but a tool not to let your guard down with.” Rather than going straight to “leave everything to it,” I decided to engage with it, at least at first, with the stance of properly reading the contents at each Allow.
Failing Small in a Practice Project
Before jumping straight into DataMigrator’s production project, I made a practice directory and tried “Hello World.” It’s the standard ritual when starting programming.
When I asked Claude Code, in Japanese, “please write a Python script that displays ‘hello,’ and run it,” it created a file, wrote the code, tried to run it — and there, an error came out. The Python that comes standard with macOS (the python command) couldn’t be invoked, for version-related reasons.
Normally this would be the point of “oh, an error came out, I’ll have to look it up myself,” but Claude Code read the error message on its own, judged that “we should use python3 rather than python,” rewrote the code, ran it once more, and this time it succeeded. I just watched this exchange. This “recovers on its own even when an error comes out” behavior was a big source of reassurance for someone with no programming experience. The sense is that you can take errors as a given and entrust the handling of them after they happen.
Getting carried away, I next tried asking, “please write a program that displays a window with PySide6.” This failed spectacularly. The standard macOS Python was old, so PySide6 wouldn’t run; switching next to Tkinter, that wouldn’t run either; and finally, judging that “we need to start by updating the Python version,” Claude Code itself proposed suspending the work.
This failure was frustrating, but at the same time it was also useful, because I could understand — not in my head but in my body — the reality that “to run a GUI app properly, you need a proper Python environment.” This also became foreshadowing for the later introduction of uv (I’ll touch on uv in the next article).
Preparing the Production Project — An Alias Called dm
Once the practice was at a stopping point, I finally prepared the directory for DataMigrator.
I put it at ~/dev/datamigrator. Until then, I’d been gathering Soul Resonant Works—related files in a folder called ~/Documents/SRW, but I decided to separate development projects into their own dedicated directory. The reason is that when “development projects” and “documents” get mixed in the same folder, finding things gradually becomes a pain. Anticipating that several development projects with uncertain futures would line up, I made a policy of creating a new directory, ~/dev/, and gathering development projects there.
Next, I set up a terminal alias (a shortcut command). Concretely, I added the following one line to a file called .zshrc.
alias dm="cd ~/dev/datamigrator && claude"
With this, just by typing dm in the terminal, it moves to the DataMigrator directory and launches Claude Code. It’s a simple contrivance that combines two commands into one. Once I started using it, this was unexpectedly pleasant, and the action of “type dm and you enter the project” became a little ritual.
As an aside, I got a little confused trying to do this setup from inside Claude Code. I rewrote .zshrc from inside Claude Code and then tried to run dm within it, but I was gently admonished: “you’re already inside a Claude session, so a new session can’t be launched.” “The dm alias is meant to be used from a normal terminal.” Claude Code senses the human’s confusion and guides you politely.
Once I exited Claude Code with /exit, returned to a normal terminal, and typed dm again, Claude Code safely launched in the DataMigrator directory. It felt like “a password to enter the house,” and I remember getting a little happy about it.
Placing CLAUDE.md and .gitignore, and Pushing to GitHub
What remained was to create DataMigrator’s CLAUDE.md (the project’s rulebook), a journal template, and a .gitignore (a list of files you don’t want managed by Git), initialize it as a Git repository, and push it to GitHub.
I asked Claude Code for this whole series of work all at once, in a single compound instruction: “please create CLAUDE.md, place a template in docs/dev-journal/, create .gitignore, make the first commit, and create a private repository on GitHub and push to it.” Claude Code created the files in order, interjecting “may I run this?” confirmations along the way when necessary, and completed all of it.
Just once, for GitHub authentication, I needed to pass through browser authentication using gh auth login --web. The flow is: a one-time code is displayed in the terminal, and you enter it into the browser to approve. After this authentication finished, things moved all at once, from creating the repository to the first push.
By the time all the work was done, the DataMigrator project was in the following state. Locally there was a directory ~/dev/datamigrator, with CLAUDE.md, .gitignore, and the journal template inside; it was managed by Git; and the same thing was up on GitHub. And by typing dm, I could resume work in Claude Code anytime. I hadn’t written a single line of code yet, but I’d arrived at “a state where development can happen.”
Next Time
Next time is finally the implementation of M1 (the first milestone). I hand the design documents to Claude Code and have it build the project’s framework and the database part. What surprised me most in this session was that “without being instructed, Claude Code wrote the test code itself.” The sense that “if the design documents are solid, you can entrust the implementation to a fair degree” begins here. At the same time, I ended up building the Python environment using a different tool called uv rather than pyenv, and I was impressed by uv’s speed, too. Look forward to the curtain-raiser on the implementation phase.
About Soul Resonant Works
Soul Resonant Works is a solo venture developing seven local AI systems. Starting from zero programming experience, the development is progressing through collaboration with AI.
🌐 Soul Resonant Works:
→ https://sr-works.net/en/index.html
📝 This blog publishes the entire development process as a serialized journal.
If you found this article useful, please share it.
Leave a Reply