DEV Community: yureki_lab

How I Gave Claude Code a Long-Term Memory: 5 Lessons from State Persistence

yureki_lab — Sun, 05 Jul 2026 14:33:06 +0000

TL;DR

I run a fully autonomous implementation system built on Claude Code that works on my projects around the clock. The single biggest upgrade I ever made to it wasn't a smarter prompt or a better model — it was giving it a file-based long-term memory. This post covers the state persistence design that turned my agent from a goldfish into a coworker, and the 5 lessons I learned getting there. 💡

The Problem

Every Claude Code session starts with total amnesia.

That's fine when you are the memory. You sit there, you remember that yesterday you decided to use SQLite instead of Postgres, you remember that the flaky test is a known issue, and you steer accordingly.

It falls apart the moment you take the human out of the loop. My system launches Claude Code sessions on a schedule, with nobody watching. Early on, the transcript of any given night looked like this:

Night 1: Agent investigates a failing build, figures out the root cause is a version mismatch, patches it. Great.
Night 2: New session, zero context. Agent sees a related warning, re-investigates the same dependency tree from scratch, and "fixes" it a second time — differently. Now I have two conflicting fixes.
Night 3: Agent reverts night 2's change because it looks wrong. Which it is. But so was doing the work three times.

The model wasn't dumb. It was stateless. Every session re-derived the world from the repo, and anything that wasn't in the repo — decisions, dead ends, "we tried this and it broke" — evaporated at session end.

The constraint that made this interesting: I wanted persistence without adding infrastructure. No vector database, no memory service, no external API. The whole system runs on a single Mac mini (macOS 15, Claude Code, launchd for scheduling), and I wanted memory to survive anything short of disk failure.

How I Solved It

The answer turned out to be embarrassingly boring: Markdown files, read at session start, written at decision time.

The three-file core

My persistence layer is built around three files per project, each with exactly one job:

project/
├── CLAUDE.md        # HOW to work: rules, conventions, scope (rarely changes)
├── state/
│   ├── memo.md      # WHERE we are: current status, next action (changes every session)
│   └── tasks.md     # WHAT remains: task list with a status per item
└── decisions.md     # WHY we chose things: append-only decision log

The separation matters more than the format:

The project spec file (CLAUDE.md) holds durable rules — coding conventions, what the agent must never touch, how to report results. Claude Code loads it automatically at session start, which makes it the natural home for anything that should apply to every session forever.
The state memo is the handoff note. It answers one question: if a new session starts right now with zero context, what does it need to know to continue? Current phase, last completed step, next step, any active weirdness.
The task file is a checklist with statuses (todo / doing / done / blocked). Sessions pick up the first non-done item instead of inventing work.
The decision log is append-only. Every entry gets an ID (D-001, D-002, …), a date, the decision, and — critically — the reason. You never edit old entries; you supersede them with new ones.

The write rules

Files alone do nothing. The behavior comes from two rules baked into the agent's instructions:

Rule 1: Read before work. Every session starts by reading the spec file, the state memo, and the task file, in that order, before touching any code. Non-negotiable. A session that skips this is a session that repeats last week's mistakes.

Rule 2: Write at decision time, not session end. My first version said "update the state memo before you finish." Terrible idea. Sessions die — context fills up, the process gets killed, the machine reboots. Anything buffered for "the end" is exactly what gets lost. Now the rule is: the moment something is decided or discovered, it gets written. The state memo is updated mid-session, every time reality changes.

flowchart LR
    A[Session start] --> B[Read spec + memo + tasks]
    B --> C[Do work]
    C --> D{Decision or discovery?}
    D -- yes --> E[Write memo / decision log immediately]
    E --> C
    D -- no --> C
    C --> F[Session ends - even abruptly]
    F --> G[Next session starts with full context]

The conflict rule

Once you have multiple files, they will contradict each other. An old strategy note says "we're doing X", the state memo says "we pivoted to Y". An agent without a tie-breaker will pick whichever it read last — or worse, try to satisfy both.

So there's an explicit priority order written into the spec file:

state memo  >  strategy doc  >  project spec  >  decision log  >  everything else

The state memo — the most recently updated, most operational file — always wins. The decision log is deliberately near the bottom: it's history, and history explains the present but doesn't override it. When the agent changes course, it overwrites the current-state file and appends a new decision entry, so the old reasoning survives without ever being mistaken for the current plan.

What it looks like in practice

A real (lightly genericized) state memo from my system:

# State memo — updated 2026-07-04 23:10

## Current phase
Trial run of the nightly build-repair loop (day 12 of 14).

## Last completed
Migrated scheduled jobs to the new machine; all paths rewritten.
Verified one full unattended cycle end-to-end.

## Next action
Watch tonight's run. If the headless timeout recurs, apply D-029
(switch to the local integration instead of the cloud connector).

## Active issues
- Cloud connector times out under headless runs (~30% of nights).
  Hypothesis and fix candidates recorded in D-028 / D-029.

A fresh session reading this needs zero archaeology. It knows the phase, the last verified state, the exact next action, and the known failure mode with a pointer to the reasoning. That last line is the goldfish-to-coworker moment: the agent doesn't re-diagnose the timeout from scratch — it recognizes it.

Lessons Learned

1. Session memory is the bottleneck, not model intelligence. I spent weeks tuning prompts to make sessions "smarter" when the actual failure was that each session was brilliant and blind. Claude Code (I'm on the 2026 releases) is easily capable of multi-week projects — if and only if context survives between sessions. Fix memory before you touch the prompt.

2. Write-on-decision beats write-on-exit, every time. Sessions end abruptly more often than you think: context limits, crashes, machine restarts. Across six months of 24/7 operation, mid-session persistence has saved me from replaying lost work dozens of times. If your agent buffers its learnings for a final summary step, you have a memory system that fails exactly when you need it most.

3. Separate "how", "where", and "why" into different files. My first attempt was one giant NOTES.md. It became a swamp — 700 lines where stale plans sat next to current status, and the agent couldn't tell which was which. Splitting by rate of change (rules change rarely, status changes hourly, decisions only append) fixed it. Each file gets one job and one update pattern.

4. An explicit priority order is not optional. Contradictions between files aren't an edge case; they're the steady state of any project that pivots. The single line "state memo always wins" has resolved more agent confusion than anything else in my setup. Without it, your agent averages your old plan and your new plan into something that is neither. ⚠️

5. Persist decisions and dead ends — not transcripts. My instinct was to keep everything. Wrong. Full session logs are write-only garbage: no future session will ever read 40k tokens of history. What's worth its weight in gold is tiny: what we decided, why, and what we tried that didn't work. "The obvious refactor breaks the release script — see D-014" is one line and saves an entire wasted night. Compression is the feature, not a compromise.

What's Next

The current design is deliberately low-tech, and I'm keeping it that way — but two upgrades are on my list:

Memory review passes: a periodic session whose only job is pruning the state files — merging duplicates, deleting stale entries, flagging contradictions before they bite.
Cross-project memory: my agents work across several codebases, and lessons learned in one ("this library's v3 API silently changed behavior") currently don't transfer. A shared, read-mostly lessons file is the next experiment.

I'll write both up once they've survived a few weeks of unattended runs — I only publish patterns after they've been through real nights, not demos.

Wrap-up

If your Claude Code sessions feel like hiring a genius with amnesia every morning, the fix probably isn't a better prompt. It's three Markdown files and two write rules.

If this was useful: follow me here on Dev.to — I'm documenting the whole journey of running a fully autonomous implementation system, war stories included. And if you've built agent memory a different way (vector stores? SQLite? something weirder?), I genuinely want to hear about it in the comments. 🚀

How I Built My First MCP Server for Claude Code (4 Lessons)

yureki_lab — Wed, 17 Jun 2026 14:33:31 +0000

TL;DR

I built my first Model Context Protocol (MCP) server to give Claude Code read access to a local project knowledge base — and the first version was bad in ways I didn't expect. Here's the minimal TypeScript skeleton that actually works, plus 4 lessons about tool design that I wish someone had told me on day one.

The Problem

I use Claude Code (v2.x) as my daily driver, and most of the time the built-in file and shell tools are enough. But I had one recurring annoyance: a pile of internal docs — design notes, decision logs, runbooks — scattered across a directory that the agent kept re-reading from scratch every session. It would grep, open three files, lose the thread, and grep again.

I wanted the agent to ask one focused question — "what did we decide about retries?" — and get back the relevant note, not a directory listing.

That's exactly what MCP is for. MCP is an open protocol that lets you expose tools (callable functions), resources, and prompts to an LLM client over a standard interface. Claude Code speaks it natively. So instead of teaching the model to navigate my files, I could hand it a search_notes tool and a get_note tool and let it do the obvious thing.

The interesting constraint: the model only uses a tool well if the schema tells it exactly when and how. A tool the model calls with garbage arguments is worse than no tool at all. That's where the real work was.

How I Solved It

The whole thing is a small Node.js server (Node 22.x) using the official @modelcontextprotocol/sdk. Here's the architecture — it's deliberately boring:

flowchart LR
    A[Claude Code] -- stdio / JSON-RPC --> B[MCP Server]
    B --> C[search_notes]
    B --> D[get_note]
    C --> E[(Local notes dir)]
    D --> E

The server talks to Claude Code over stdio (standard in/out), which is the simplest transport — no ports, no auth, no network. The client launches your server as a subprocess and pipes JSON-RPC over the pipe. For a local, single-user tool this is exactly what you want.

The minimal skeleton

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "notes-server", version: "0.3.0" },
  { capabilities: { tools: {} } },
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "search_notes",
      description:
        "Search the project knowledge base by keyword. Returns up to 5 " +
        "matching note titles with a one-line snippet. Use this FIRST to " +
        "find a note before fetching its full text.",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "Keyword or phrase to search for" },
        },
        required: ["query"],
      },
    },
    {
      name: "get_note",
      description:
        "Fetch the full Markdown of one note by its exact id, as returned " +
        "by search_notes. Do not guess ids.",
      inputSchema: {
        type: "object",
        properties: {
          id: { type: "string", description: "The note id from search_notes" },
        },
        required: ["id"],
      },
    },
  ],
}));

Notice the descriptions read like instructions to a teammate, not API docs. That's the single highest-leverage thing in this file. More on that below.

The call handler

The handler is where I learned to be careful about failure. The first version threw exceptions on a missing file. Bad idea — a thrown error reads to the agent like the tool is broken, so it gives up instead of correcting course.

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  const { name, arguments: args } = req.params;

  try {
    if (name === "search_notes") {
      const hits = await searchNotes(String(args?.query ?? ""));
      if (hits.length === 0) {
        return {
          content: [{
            type: "text",
            text: "No notes matched. Try a broader single keyword.",
          }],
        };
      }
      return { content: [{ type: "text", text: formatHits(hits) }] };
    }

    if (name === "get_note") {
      const note = await loadNote(String(args?.id ?? ""));
      if (!note) {
        return {
          content: [{
            type: "text",
            text: `No note with id "${args?.id}". Call search_notes to get a valid id.`,
          }],
          isError: true,
        };
      }
      return { content: [{ type: "text", text: note.body }] };
    }

    return {
      content: [{ type: "text", text: `Unknown tool: ${name}` }],
      isError: true,
    };
  } catch (err) {
    return {
      content: [{
        type: "text",
        text: `Tool failed: ${err instanceof Error ? err.message : String(err)}`,
      }],
      isError: true,
    };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

The key move: errors come back as content with isError: true, with a sentence telling the model what to do next ("call search_notes to get a valid id"). The agent reads that and self-corrects, usually on the very next turn.

Wiring it into Claude Code

One line in the MCP config registers it:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/abs/path/to/dist/index.js"]
    }
  }
}

Restart Claude Code, and search_notes / get_note show up as callable tools. That's the whole loop.

Lessons Learned

1. The tool description IS the prompt — write it for the model, not for humans

My first search_notes description was literally "Searches notes." The model called it with full sentences, paragraph queries, sometimes the entire user message as the query. Garbage in, garbage out.

When I rewrote the description to say what it returns, when to use it, and what to do next ("Use this FIRST… then get_note"), the call quality jumped immediately. Treat every description field as a mini system prompt. The model has no other signal about your intent.

If you find yourself debugging "why won't the agent use my tool right?", the answer is almost always in the description, not the code.

2. Return structured errors, never stack traces

A raw exception bubbling up makes the agent think the tool is dead. A short, actionable error message makes it a recoverable hiccup. isError: true + "here's the valid next step" turned my flakiest tool into the most reliable one. Think of error messages as instructions for recovery, because to the model, that's exactly what they are.

3. Scope tools narrowly — two small tools beat one clever one

I was tempted to build a single notes(action, ...) mega-tool with an action enum. Don't. The model reasons about distinct tools far better than about a polymorphic one with conditional arguments. Two tools with clear names and required fields gave me dramatically more predictable behavior than one tool with five optional params. Narrow tools are also easier to grant or withhold — a real win when you care about what the agent can touch.

4. Version-stamp the server and the schema

I bumped version: "0.3.0" and added a stable id contract to get_note ("ids come from search_notes, don't guess"). When I later changed the search output format, the explicit contract meant I knew exactly what the model depended on. Schemas rot the same way APIs do — the model has memorized your old shape from earlier in the session. A version field and an explicit contract make breaking changes visible instead of mysterious.

A few smaller things that bit me:

stdio means stdout is sacred. Anything you console.log to stdout corrupts the JSON-RPC stream. Log to stderr (console.error) or a file. This cost me an hour of "why is the connection dropping?"
Keep tool count low. Every tool you expose is tokens in the model's context on every turn. I capped myself at the two tools I actually needed, and the agent's reasoning stayed tight because of it.
Make required fields actually required. Marking query and id as required in the JSON Schema stopped the model from calling tools with empty arguments "just to see what happens." The schema is a contract the client enforces before your code ever runs — lean on it.
Test the server by hand before wiring it in. You can pipe a JSON-RPC tools/list request straight into the process over stdin and eyeball the response. Doing that once saved me from chasing a config problem that was actually a serialization bug in my own formatHits.

What's Next

Three directions I'm exploring:

A list_recent_notes resource so the agent can browse without searching first.
Swapping the keyword search for a small embedding index — same two-tool interface, smarter matching underneath.
An HTTP transport version so the same server can back a shared team setup instead of a local subprocess.

The two-tool interface stays stable through all of that, which is the whole point of designing the schema carefully up front.

Wrap-up / CTA

Building an MCP server turned out to be 20% protocol and 80% interface design for a reader who happens to be a language model. The SDK gets you a working server in 40 lines; the lessons are all about making tools the model uses correctly.

If you're already using Claude Code, try writing one tiny MCP server this week — expose one thing you keep re-explaining to the agent and watch how much friction disappears.

💡 If this was useful:

Follow me here on Dev.to for more build logs on agent tooling.
Try Claude Code if you haven't — pairing it with a custom MCP server is where it gets genuinely fun.
Drop a comment with the first tool you'd expose. I'm collecting ideas. 🚀

How I Stopped Babysitting Claude Code: 5 Patterns for 24/7 AI Workers

yureki_lab — Mon, 15 Jun 2026 14:33:34 +0000

TL;DR

I spent a month babysitting Claude Code runs — watching every prompt, every tool call, every "are you sure?" If I stepped away for an hour, things either silently stalled or did something I didn't want. Here are 5 patterns that finally got me to a place where my agent runs unattended for a full day and I'm not nervous about it. The big one is treating the agent like a flaky background job, not a chat partner.

The Problem

When I first started using Claude Code (this was on claude-sonnet-4-6, then claude-opus-4-7), I treated it like an ultra-fast pair programmer. I'd kick off a task, watch it tear through files, and step in whenever it got weird. That's fine for 20-minute sessions.

It falls apart fast when you want the agent to run for hours.

The specific failure mode I kept hitting: I'd start a long task, walk away for 30 minutes, and come back to one of three states:

Silent stall. A tool call was waiting on a permission prompt I never approved. Nothing was happening. The clock was burning.
Wrong direction. The agent had decided — totally reasonably from its point of view — to refactor a directory I didn't want touched. The diff was huge. Reverting was annoying.
Lost state. The session had been compressed or context-trimmed, and the agent had forgotten which step we were on. It cheerfully started over from a stale assumption.

None of these are bugs in Claude Code. They're consequences of treating an autonomous agent like an interactive REPL. I was the bottleneck because I was the supervisor. So I tried to stop being the supervisor.

This is the build log of how I did that. The goal: a Claude Code worker I can leave alone for a full workday, that either does the right thing or fails loudly enough that I don't waste a day of compute on garbage.

How I Solved It

Five patterns. Each one came out of a specific thing breaking. They compose.

1. Idempotent restart from a state file

The single biggest unlock. The agent should be able to re-read its own state file and pick up where it left off, without remembering anything from the previous session.

I keep a STATE.md in the repo root. It's plain markdown, three sections:

## Current goal
<one sentence>

## Next concrete action
<one specific verb-led step>

## Notes
<anything load-bearing that isn't in the code yet>

The agent reads this on every startup. Every time it finishes a meaningful step, it rewrites it. If the run dies mid-task, the next invocation reads the same file and resumes.

The key word is idempotent. The agent shouldn't care whether this is the first run, the fifth, or the recovery after a crash. The state file is the source of truth; the chat history is just working memory.

# pseudo-runner
while ! task_done; do
  claude --read STATE.md --do-next-action
done

What surprised me: once the state file existed, I stopped needing to scroll the chat to remember what we were doing. I just opened STATE.md. The discipline forced clarity.

2. Journal every external action

The second pattern: write an append-only log of anything the agent does that touches the outside world.

2026-06-10T09:14Z run-id=a3f committed=feat: add retry to fetcher
2026-06-10T09:18Z run-id=a3f pushed=origin/main
2026-06-10T09:22Z run-id=a3f opened-pr=#412

Pure text, one event per line, timestamp + run-id + what happened. No JSON, no nested structure, no schema migrations later. I keep this in a journal.log at the repo root and grep it when I'm trying to figure out what the agent did overnight.

The boring format is the feature. When something goes wrong at 3am and I want to know which commit was the agent's last sane state, I'm not parsing JSON in my head — I'm just reading lines.

This is also how I caught the "wrong direction" failures earlier. Reading two days of journal entries is way faster than diffing the repo.

3. Narrow tool grants by default, escalate by exception

I used to give my agent every tool. Read, Write, Bash, Web — all on, all the time. I figured "smart agent, smart enough not to do anything dumb."

It was dumb. Not because of the agent — because the blast radius of any single tool call was the entire filesystem and the entire internet.

Now I scope tools per task. A "review the diff" task gets Read + Grep. No Write. No Bash. A "run the test suite" task gets Bash but only with a whitelist of commands. A "post a comment to a PR" task gets the GitHub MCP server and that's it.

When the agent needs something not in scope, it stops and asks. I'd rather have it pause and request a tool than improvise around the missing one. The pause is recoverable. Improvising on a file you didn't want it to touch is not.

# Bad: agent has Bash with no constraints
# Good: agent has Bash restricted to: pytest, ruff, mypy

This is one of those things that sounds fussy until the first time it saves you from a rm -rf node_modules you didn't want.

4. An explicit error budget per run

Long-running agents fail. Sometimes a tool call times out. Sometimes a flaky test fails. Sometimes a fetch returns 502. The question isn't whether — it's how the agent reacts.

The old default: retry forever, gradually descend into nonsense. By turn 30, the agent is tilting at the windmill, convinced the problem is somehow with the test runner.

I now give every run a hard budget:

3 retries per tool call, then escalate
2 unrelated errors in a session, then halt and write a state-dump
No silent backoff loops

When the budget is blown, the agent writes the partial state to STATE.md, leaves a note in journal.log, and exits non-zero. The next scheduled run reads the state and either retries the same step (if I haven't intervened) or skips it (if I marked it dead).

This pattern is borrowed wholesale from how SREs run flaky services. AI agents are flaky services. Treat them like flaky services.

5. Dry-run wrappers for anything destructive

The last pattern is the cheapest and the one I should have started with. Anything that mutates external state — git push, posting to an API, sending an email — goes through a wrapper that supports a --dry-run flag.

def publish_post(payload, dry_run=False):
    if dry_run:
        print(f"[DRY] would POST {len(payload['body'])} chars to {URL}")
        return {"id": "dry-run", "url": "https://example.com/dry"}
    return real_post(payload)

The agent runs with DRY_RUN=1 by default during development. I flip it off when I trust the run. This means the entire pipeline is exercised end-to-end on every change, but nothing actually ships until I unlock it.

You'd think this is obvious. It was not obvious to me until I had the agent send three identical messages to a Slack channel because of a retry loop.

Lessons Learned

Five takeaways, written so I'd quote them at past-me.

The agent isn't the worker — the state file is. The chat session is ephemeral. Anything load-bearing has to live in a file the next invocation can read. Treat the agent as a stateless function over (STATE.md, repo).
Loud failures beat quiet ones, every single time. I used to tune my agent toward "don't crash." Wrong goal. The right goal is "crash visibly the moment the situation gets unfamiliar." A crash leaves a tombstone. A drift leaves a mess.
Tool surface = risk surface. Every tool you give the agent is a thing it can do without asking. Default to narrow. Expand by exception, with a reason. This is the same logic as Unix permissions and the same logic as IAM. It applies to agents too.
Budget the failure modes, not the work. Don't tell the agent "do this task." Tell it "do this task, but stop if you've retried 3 times or hit 2 unrelated errors." The work limit doesn't matter — the failure limit does.
Dry-run mode pays for itself in one incident. If you're shipping anything destructive, build the dry-run path first. Then make DRY_RUN=1 the default in your shell profile and forget about it.

The meta-lesson behind all five: stop thinking of the agent as a smarter you, and start thinking of it as an unsupervised intern with root. The interventions that work are the same ones you'd use on a junior engineer running their first on-call shift: a clear handoff doc, an append-only log of what they did, scoped permissions, a stop rule, and a sandbox for the scary stuff.

The agent is good at the work. It is not good at noticing it's lost. Your job is the noticing.

What's Next

Two things I'm playing with now:

Cross-run learning. Right now each run reads STATE.md and starts fresh. I want a longer-lived LESSONS.md the agent writes to when it discovers something durable about the codebase (a flaky test, an undocumented constraint). The next run reads it as context. Early experiments suggest this is a big lever — if the agent doesn't have to rediscover every quirk every session, runs get a lot cheaper.
A "second opinion" reviewer agent. Before any destructive step, a separate Claude instance with read-only access reviews the planned action and either approves or vetoes. This is overkill for small changes, but for the dangerous 5% of operations it's worth the extra tokens. I'm specifically interested in whether two independent reviewers catch more than one — the multi-perspective verify pattern in disguise.

If either of those goes somewhere interesting, I'll write it up.

Wrap-up / CTA

If you're using Claude Code and the run-time is starting to creep past "one focused session" — start with the state file pattern. It's the cheapest one on this list and it unblocks all the others. Everything else is a refinement.

If you found this useful:

Follow me on Dev.to — I'm writing up more build-in-public posts on running Claude Code in production
Try Claude Code if you haven't — it's free to get started and the agent-loop UX is genuinely different from a chat window
Drop a comment with the pattern you're using to keep your own agent runs honest. I'd love to steal it.

Versions used while writing this: Claude Code v0.x (current as of mid-2026), claude-sonnet-4-6 and claude-opus-4-7. The patterns aren't model-specific — they're about how you wrap the agent, not which model you point it at.

5 Mistakes I Made Designing My First Claude Code Sub-Agent Pipeline

yureki_lab — Sun, 14 Jun 2026 14:33:46 +0000

TL;DR

I spent a weekend wiring up my first multi-agent pipeline with Claude Code, and almost every design choice I made was wrong. Here are the 5 mistakes — one monolithic prompt, free-text returns, eager barriers, ignored concurrency caps, and no dedup — and how I fixed each one. If you're about to fan out sub-agents for the first time, read this before you ship.

The Problem

I wanted to run a "find bugs in this repo" sweep across a medium-sized codebase. The naive version was easy: one Claude Code session, one big prompt, walk the tree. But it was slow, it ran out of context partway through, and the output was a wall of unstructured prose I had to re-parse by hand.

So I rewrote it as a fan-out: spawn N sub-agents, each focused on a slice, collect their findings, verify, dedupe, report. Classic map-reduce on top of Claude Code sub-agents.

The first version "worked" — it produced output. But the wall-clock was almost as bad as the monolith, half the findings were duplicates, and roughly 1 in 5 sub-agent results couldn't be parsed at all. I rebuilt it three times in a week. These are the mistakes I keep seeing in my own code and in other people's.

Versions: Claude Code v2.x, Node.js 22.x. The patterns are general but the API surface I reference is from late 2025/early 2026.

How I Solved It

I'll walk through the 5 mistakes one by one. Each one has the "before" sketch I actually wrote, then the version I landed on.

Mistake 1 — One monolithic prompt for every sub-agent

My first fan-out gave every sub-agent the same prompt and just varied the input slice:

const findings = await Promise.all(
  slices.map(slice =>
    runAgent(`Find bugs in this code. Look for correctness issues,
              security holes, performance problems, dead code,
              and missing error handling. Be thorough.\n\n${slice}`)
  )
)

This looks tidy. It's also why my outputs were noisy. Every agent tried to be a generalist, every agent re-discovered the same shallow issues (unused variables, missing null checks), and nobody went deep on anything.

The fix was to give each agent a single lens. Same input, different prompts:

const LENSES = [
  { name: 'correctness', prompt: 'Find logic bugs. Ignore style.' },
  { name: 'security',    prompt: 'Find injection, auth, secret-handling bugs.' },
  { name: 'concurrency', prompt: 'Find race conditions and ordering bugs.' },
]
const findings = await Promise.all(
  LENSES.flatMap(lens =>
    slices.map(slice => runAgent(`${lens.prompt}\n\n${slice}`, { label: lens.name }))
  )
)

Same agent count, vastly better signal. Diversity beats redundancy when you're searching for something you can't fully specify upfront.

Mistake 2 — Free-text returns

I let agents return prose, then tried to regex out the findings. Roughly 20% of returns had a header I didn't anticipate, or a numbering scheme that broke my parser, or a "By the way…" tail that polluted the next stage.

The fix: enforce a schema at the tool layer. Most agent frameworks now support forcing the agent to call a structured-output tool. In Claude Code's workflow primitives this looks like:

const FINDING_SCHEMA = {
  type: 'object',
  required: ['findings'],
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        required: ['file', 'line', 'severity', 'description'],
        properties: {
          file:        { type: 'string' },
          line:        { type: 'integer' },
          severity:    { enum: ['low', 'medium', 'high'] },
          description: { type: 'string' },
        },
      },
    },
  },
}

const result = await runAgent(prompt, { schema: FINDING_SCHEMA })
// result is already a typed object — no parsing

The agent retries internally on schema mismatch, so by the time I get the object back, it's valid. This single change cut my downstream code in half and eliminated the parse-error tax.

Mistake 3 — Eager barriers between stages

My original pipeline looked like this:

const reviews  = await Promise.all(items.map(reviewAgent))  // BARRIER
const verified = await Promise.all(reviews.map(verifyAgent)) // BARRIER

Looks clean. It also means the verify stage cannot start until every review finishes. If one slow reviewer takes 3x the median, the verifier sits idle for that whole stretch.

The fix is to pipeline: each item flows through all stages independently. Item A can be in verify while item B is still in review.

async function pipeline(items, ...stages) {
  return Promise.all(items.map(async (item) => {
    let cur = item
    for (const stage of stages) cur = await stage(cur)
    return cur
  }))
}

const results = await pipeline(items, reviewAgent, verifyAgent)

Wall-clock dropped from "sum of slowest per stage" to "slowest single-item chain." On a 12-item run that's the difference between ~90s and ~35s for me.

A barrier is only correct when stage N actually needs all of stage N-1 (dedup across the full set, early-exit if zero findings, cross-item comparison). Otherwise: pipeline.

Mistake 4 — Ignoring the concurrency cap

I gleefully shoved 80 items into Promise.all. The runner happily accepted them, then quietly queued 70 of them while running 10 at a time. My logs showed "80 agents started" — but only 10 were actually doing work, and I had no idea why my wall-clock was so bad.

Two fixes, depending on the situation:

Know your cap. Most agent runners have a concurrency cap (often min(16, CPU - 2)). Anything above that queues. If you want to reason about wall-clock, treat the cap as your effective batch size.
Right-size the fan-out. I now scale fan-out to the work budget, not "as wide as possible":

const BATCH = Math.min(items.length, MAX_CONCURRENCY)
log(`Running ${BATCH} concurrent; ${items.length - BATCH} queued.`)

Logging the queued count was the single most useful debug change I made all month. It turned an invisible bottleneck into a number.

Mistake 5 — No dedup before verification

Verification is the expensive stage. Each verifier read files, ran tools, asked Claude to refute the claim. So when my finders surfaced "this function lacks input validation" from three different lenses, I was paying 3x for the same finding.

The fix is dumb-simple — dedup in plain code between fan-out stages:

const seen = new Set()
const fresh = allFindings.filter(f => {
  const key = `${f.file}:${f.line}:${f.description.slice(0, 60)}`
  if (seen.has(key)) return false
  seen.add(key)
  return true
})
const verified = await Promise.all(fresh.map(verifyAgent))

The temptation is to make the dedup itself an agent ("ask Claude to merge similar findings"). Don't. A Set and a stable key are faster, deterministic, and free. Reach for an agent only when the comparison genuinely needs judgment.

The shape I landed on

After all five fixes, the pipeline looks roughly like this:

flowchart LR
    A[Slices] --> B[Lens 1: correctness]
    A --> C[Lens 2: security]
    A --> D[Lens 3: concurrency]
    B --> E[Dedup]
    C --> E
    D --> E
    E --> F[Verify - pipelined]
    F --> G[Report]

Multiple lenses (mistake 1), schema-enforced returns (2), pipelined verify with no barrier (3), batch-aware concurrency (4), dedup before the expensive stage (5).

Lessons Learned

Diversity beats redundancy. If you're spawning N agents on the same problem, give them N different angles. N copies of the same prompt is wasted spend.
Schemas are not bureaucracy — they're a parser. Forcing structured output at the tool layer is the single highest-leverage change you can make to a multi-agent system. Stop regexing prose.
Pipeline by default, barrier only when you must. Most "I'll await everything then start the next stage" code is a wall-clock tax for no reason. The barrier is correct only when stage N needs cross-item context from all of stage N-1.
The concurrency cap is real and silent. If your runner queues, you need to know. Log the queued count. Right-size fan-out to the cap, not your ambition.
Dedup with code, not agents. Cheap deterministic operations (filter, group, dedup, sort) belong in your script, not in an LLM call. Reserve the agents for the judgment calls.

What's Next

The version I have running now still has a verification stage that's overly trusting — if a finder is confidently wrong, a single verifier can rubber-stamp it. I'm experimenting with an adversarial panel: three skeptics per finding, each prompted to refute, kill if a majority refute. Early results look promising but the cost goes up linearly, so I want to measure precision/recall properly before I write that one up.

I'm also tracking how much of the pipeline's wall-clock is the slowest single agent in each stage. If it's consistently one outlier, the right move is probably a timeout-and-retry rather than waiting it out.

Wrap-up / CTA

If you're building anything with Claude Code sub-agents, try the schema fix first — it'll pay for itself within a day. The pipelining change is bigger but invasive; do it once your output is reliable enough to trust.

If this was useful:

Follow me on Dev.to — I'm writing up more agent-design war stories as I hit them.
If you haven't tried Claude Code yet, the sub-agent + workflow primitives are what made all of this even possible.
Hit me up in the comments with your own multi-agent mistakes — I want to collect a "things that bit us all" list.

Build in public, break in private. 🛠️

How I Built a Self-Improving Coding Agent with Claude Code: 5 Lessons After 6 Months

yureki_lab — Fri, 12 Jun 2026 14:47:42 +0000

TL;DR

I spent 6 months building a self-improving coding agent on top of Claude Code — an orchestrator that hands work to sub-agents, persists its own state, and rewrites its own prompts when it gets things wrong. Here are 5 lessons I wish someone had told me on day one, with the war stories that taught me each one.

The Problem

I kept hitting the same wall with single-shot LLM coding sessions.

The model would do great work for 30 minutes, then forget a decision it made 10 minutes earlier. It would happily "fix" the same bug I'd asked it to leave alone. It would invent a function name, call it three times, and only notice it didn't exist when the test runner blew up. Re-prompting helped — for one turn. Then we drifted again.

I wanted an agent that:

Held its own state across long-running work (days, not minutes)
Delegated specialized tasks to sub-agents instead of stuffing one context window
Caught its own mistakes before I had to point them out
Got better over time — not the model, but the system around it

I was already using Claude Code (the CLI, v0.x at the time) and it had the right primitives: sub-agents, tool calls, hooks. So I started building on top of it instead of reinventing the runner.

How I Solved It

The architecture ended up looking like this:

flowchart TD
    User[User prompt] --> Orchestrator
    Orchestrator -->|reads| State[(State files<br/>STATE.md, DECISIONS.md)]
    Orchestrator -->|delegates| SubA[Researcher sub-agent]
    Orchestrator -->|delegates| SubB[Implementer sub-agent]
    Orchestrator -->|delegates| SubC[Reviewer sub-agent]
    SubA --> Orchestrator
    SubB --> Orchestrator
    SubC --> Orchestrator
    Orchestrator -->|writes| State
    Orchestrator -->|updates| Prompts[Prompt files]

Three pieces did most of the work.

1. State as plain Markdown, not a database

I tried a SQLite-backed memory store first. It was technically nicer, but the agent kept misquerying it and producing weird half-correct context. So I ripped it out and replaced it with three plain files the agent reads at the top of every session:

STATE.md — "where am I right now, what's the next concrete step"
DECISIONS.md — append-only log of decisions with IDs (D-001, D-002, …)
MEMORY.md — index of long-lived facts

The agent reads these first, writes to them as it works, and treats STATE.md as the single source of truth when files disagree.

Boring? Yes. But the agent understands Markdown the way it understands prose — and git diff makes every state change human-reviewable.

2. Sub-agents with hard scope contracts

Naive delegation didn't work. If I said "spawn a sub-agent to investigate X," the sub-agent would investigate X and also try to fix it, refactor a neighboring file, and write a new test. The blast radius was unpredictable.

What worked: every sub-agent gets a contract at spawn time.

// pseudo-code, not the real API
spawnSubAgent({
  role: "researcher",
  scope: "READ ONLY. Locate the file that defines X. Return a path + 5-line excerpt.",
  forbidden: ["Edit", "Write", "Bash"],
  returnSchema: { path: "string", excerpt: "string" },
})

Two rules I learned to enforce hard:

Tool allowlists per role. A researcher can't write. A reviewer can't edit. A planner can't execute. This is the single biggest leverage point.
Structured return values. A sub-agent's final message is its return value. If I let it return prose, the orchestrator had to re-parse it and often got it wrong. Forcing a schema cut spurious downstream errors dramatically.

3. Self-correction via a "reviewer pass"

After every non-trivial change, the orchestrator spawns a reviewer sub-agent with one job:

Read the diff. Find anything that looks wrong, incomplete, or contradicts a decision in DECISIONS.md. Return a list of concerns or an empty list.

If the list is non-empty, the orchestrator either fixes it directly or escalates back to me. This caught maybe 30% of the bugs I'd otherwise have shipped — including a memorable case where the implementer happily added a // TODO: handle errors and the reviewer flagged it three seconds later.

The trick was making the reviewer adversarial by prompt, not by hope:

Default to suspicious. If you can't tell whether something is correct, return it as a concern. False positives are cheap; false negatives ship bugs.

Lessons Learned

1. State files beat state stores

For an agent that reads its own context every turn, plain Markdown that you can git diff is more debuggable than any DB. I now reach for SQLite/KV only when the agent needs to query state across thousands of records.

2. Tool allowlists are the load-bearing safety mechanism

Prompts that say "don't edit anything" work about 80% of the time. A forbidden: ["Edit"] list works 100% of the time. Don't rely on the model's discipline when you can rely on the runner's.

3. The sub-agent's return value is data, not a message

Treat sub-agents like RPCs. Define the return schema up front. The orchestrator that parses prose is the orchestrator that breaks on Tuesday.

4. Fail loud, never silent

Early versions would catch errors and "try the next thing." Bugs accumulated invisibly until something visible broke. I rewrote every error path to either succeed cleanly, surface the failure, or stop. A loud failure is worth ten silent retries.

5. Version-stamp your prompts

Prompts that worked on Claude Sonnet 4.5 did not always work the same way on Claude Sonnet 4.6. I now stamp every prompt file with the model + date I last validated it on. When a model upgrade lands, I have a re-validation checklist instead of a mystery.

What's Next

A few things are on my list:

Better reviewer diversity — running 3 reviewers with different lenses (correctness, perf, contract-fit) in parallel and merging their concerns. Early experiments suggest this catches a different class of bug than a single reviewer.
Branch-and-merge planning — letting the orchestrator try N approaches in isolated git worktrees and pick the winner, instead of committing to one path.
Eval harness for the agent itself — a fixed set of tasks I can run after every prompt change to measure regression.

I'll write up each of these as I learn what actually works (and what just looks clever on a diagram).

Wrap-up / CTA

If you're building agents on top of Claude Code or any tool-use LLM, the meta-lesson is: the model is the easy part, the system around it is the hard part. Treat it like the distributed system it actually is — explicit contracts, structured returns, loud failures, persistent state.

If this resonated:

💡 Follow me on Dev.to for more build logs as I push this further
⚙️ Try Claude Code if you haven't — most of these patterns translate to whatever runner you use
💬 Drop a comment with what's broken in your agent setup — I read every reply and I'm collecting failure modes for a follow-up post

What's the most surprising failure mode you've hit running a coding agent?