DEV Community: Sungsoo Youn

First Setup: What Changes with a Single CLAUDE.md

Sungsoo Youn — Sat, 05 Sep 2026 04:10:03 +0000

This is chapter 2 of my book **Building Autonomous AI Agents with Claude Code* — a field guide to turning Claude Code from a coding assistant into an agent that remembers, verifies its own work, and knows when to stop. Everything below is from a system I actually run every day on one Windows PC.*

1. CLAUDE.md Is a "Contract Read Every Time"

Every time Claude Code starts a session, it injects the global settings (~/.claude/CLAUDE.md) and the project's
CLAUDE.md into the system context. In other words, every sentence written here is a standing instruction that
automatically attaches to every conversation. This property is both the strength and the trap.

The strength is clear. You gain "things you no longer have to say every time."
The trap is this: every sentence written here competes with every other one, every turn.

2. Shorter Gets Followed — A Fact Confirmed by Measurement

There is a common failure path. Rules pile up one by one past 1,000 lines, and at some point the AI
starts missing the most important rules. Inside a long document, instructions bury each other.

In actual operation, when we removed a general-purpose rule set that had grown past 1,300 lines and cut the injected volume by about 89%,
compliance with the core rules went up noticeably. The attempt to raise compliance by adding
more rules had itself been the cause.

Keep only "things that cause real damage when violated" in CLAUDE.md, and move everything else out.

One counterintuitive case is worth adding. We once listed the "expressions not to use" in the rules —
and then removed the list. Showing those words every turn was actually producing an imprinting effect.
The list now lives in a separate file, and a checker filters output just before it is sent.
Writing something in the rules and blocking it with a system are different things.

3. Split into a Three-Layer Structure

Layer	File	What it holds	Size guideline
Global	`~/.claude/CLAUDE.md`	Identity, tone, security, prohibitions common to all projects	Under 100 lines
Rule fragments	`~/.claude/rules/*.md`	Rules by topic (encoding, paths, DB)	Under 30 lines per file

The reason for splitting off rule fragments is to load them only when needed. The DB rules only
need to be present when you touch the DB. If they are always injected, they take up space that other rules need.

4. Three Traits of a Well-Written Rule

① It can be verified through behavior.

"Be careful" cannot be verified. The AI cannot judge whether it was careful, either.

② It carries a one-line reason.

When the AI knows the reason, it keeps the intent even in situations the rule didn't anticipate. A rule
without a reason gets dismissed as "doesn't apply in this case" the moment the situation shifts slightly.

③ It states a replacement behavior, not just a prohibition.

With only a prohibition, the AI improvises a creative workaround at the blocked spot. That workaround is
usually worse.

5. What Must Go into the Project CLAUDE.md

The global file differs from person to person, but there are things every project file should share.

The "confirmed facts (do not ask again)" section is surprisingly effective. If you have been asked the same
question three times, write the answer here. Then there is no fourth time.

6. Signals When Rules Keep Growing

If your rule file is growing, check the following.

Signal	Response
Three or more rules on the same topic are scattered around	Bundle them into a rule fragment file and move them out
A rule contains "as an exception"	That rule is already wrong — rewrite its condition
A rule keeps being ignored	Don't rewrite the sentence — turn it into a hook (Chapter 4)

The last row is the key. If saying it three times doesn't work, build it into the structure. Rewriting a rule
in a stronger tone almost never works.

Want the whole system? The book has 10 chapters plus 4 ready-to-use templates (CLAUDE.md starter, memory files, auditor checklist, measurement guide) and a hands-on section for every chapter. It's $9.99 as a PDF: https://dbsoul.gumroad.com/l/autonomous-ai-agents-claude-code

Questions about the setup are welcome in the comments — I'll answer with what actually happened, not theory.

Why an "Autonomous Agent" — The Decisive Difference from a Coding Assistant

Sungsoo Youn — Fri, 04 Sep 2026 11:02:38 +0000

This is chapter 1 of my book **Building Autonomous AI Agents with Claude Code* — a field guide to turning Claude Code from a coding assistant into an agent that remembers, verifies its own work, and knows when to stop. Everything below is from a system I actually run every day on one Windows PC.*

1. Most People Use AI as a "Typewriter"

When you first use an AI coding tool, everyone falls into the same pattern. You assign one function, check the result, and assign the next function. It's clearly faster, yet strangely exhausting. Why?

Because a human is still making every judgment. The AI is only lending its hands.
Even if your typing speed increases tenfold, if the bottleneck is in your head rather than your hands, the overall speed stays the same.

This book deals with the opposite side. You wake up in the morning and the AI has already collected information overnight, screened candidates, and prepared a report. The human intervenes only at the points where judgment is needed.

2. Diagnosing Where You Are Right Now

If this describes you	Your current stage
You explain the project structure from scratch every time	Typewriter
You have a rules file, but it gets ignored often	Assistant
The AI checks yesterday's records first before starting	Early agent
You can trust a "done" report without verifying it	Agent
In the morning, you just pick from a candidate list the AI made	Autonomous agent

Most people are on the second row. And what it takes to move from the second to the third is
not a better model, but a few files. That is this book's claim.

3. The 3 Conditions of an Autonomous Agent

Condition 1 — Memory

When a session ends, the AI forgets everything. Yesterday's work, last week's mistakes, even the project's context — all of it. So it trips in the same place, in the same way, again.

The solution is surprisingly simple. Build a file-based memory structure that the AI reads and writes.
A handoff note (HANDOFF), a work journal (diary), a mistake log (mistakes), a core index (MEMORY) —
four markdown files are the starting point. In Chapter 3, we build this structure from scratch.

Condition 2 — Verification

When AI verifies its own output, it inevitably becomes lenient. Just like humans.
And AI has one more thing on top of that — the habit of treating what it just said as evidence.
Once it says "the tests passed," its next judgment gets built on top of that sentence.

So what's needed is not self-confidence but structural verification.

① Tests come first (TDD)
② A separate auditor agent judges from the filesystem alone (Ch. 6)
③ A different AI model cross-reviews

This triple structure changes how much you can trust the words "I'm done."

Condition 3 — Boundary

Autonomy is not "do whatever you want." What can be undone, the AI does on its own;
what cannot be undone (payment, publishing, deletion) must be approved by a human.

The moment you write this boundary down explicitly, two things improve at once.
The human delegates with peace of mind, and the AI moves without hesitation inside the boundary.
When the boundary is blurry, the AI asks about trivial things — and just goes ahead and does the dangerous ones.

4. Why Now — The Bottleneck Is Structure, Not Tools

The models are already good enough. The reason many people still use AI as a typewriter is
that there is no structure wrapped around the model.

Give the same model the same task, and the results differ between the side with memory and the side without.
Memory is not a feature of the model — it is a file we create. The same goes for verification and boundaries.
None of the mechanisms in this book will be replaced by improvements in model performance.

5. Where This Book Ends Up

When you finish all the chapters, the following will be up and running.

A pipeline that collects and analyzes information on its own at a fixed time every day
A hook gate that blocks the AI's repeated mistakes through structure
A quality system that requires a PASS from an independent auditor before declaring "done"
An operating routine where human intervention is compressed to 10 minutes a day

And along the way, you will see that every mechanism in this book came from a real incident.
Almost none of the rules here were designed from the start.
Every one of them was created after getting burned badly, once each.

Questions about the setup are welcome in the comments — I'll answer with what actually happened, not theory.