Stop AI Code Changes From Blowing Up — One change-workflow Config

Two days ago I posted an episode called “our Claude Code is different,” about how its harness configuration is different — like a wildly talented management trainee showing up, and I’ve already put him through a detailed onboarding tailored to the company. That one got tens of thousands of views, and a lot of people kept asking: could you share something concrete?

Today I’m sharing one of those files.

change-workflow, inside the rules folder

Go into the Claude config folder and there’s a rules folder holding nothing but “principles” — a behavioral guide, a set of process standards Claude Code follows whenever it does anything.

What I’m sharing today is one of those files, called change-workflow: how it should think and how it should execute when it changes code.

The most maddening problem

The most maddening thing about having Claude Code write code is that it treats every change the same way:

• Sometimes a tiny change — tweak the frontend, reword a line of copy — and it still runs a whole round of deliberation before touching anything. Very inefficient.
• Sometimes a change that looks tiny actually pulls in a bunch of modules, pipelines, and backend data, so it should research first and act second — and instead it dives straight in. Result: a pile of bugs.

How do you fix that?

Version one failed: don’t grade by difficulty

My first thought was to grade changes by difficulty into high, medium, and low, have it judge which one applies, then follow different processes.

But in practice, three levels didn’t work, because it can’t judge task complexity accurately — estimating from “how many files got touched,” for instance, doesn’t hold up: plenty of files can change without the task being complex.

So after a round of research, I compressed difficulty grading from three levels down to two, low / high. And the real split happens earlier, by thinking along two dimensions.

Two dimensions: uncertainty × risk

Dimension one, uncertainty. Before you start, is there already a clear plan? Can this change be described in a single sentence? Is what needs changing clear enough?

Dimension two, risk. If it goes wrong, how much does that cost? Do I need it tested repeatedly? Or can we just ship it and see whether it’s fine?

Judge on those two dimensions and changes fall into two buckets: simple changes and complex changes.

• Simple change → execute directly.
• Complex change → run four stages.

The four stages for a complex change

1. Clarify — get an objective acceptance standard first: what does “done” actually look like? It’ll come back to me with clarifying questions.
2. Research — search for technical approaches, see whether the community already has a best practice, borrow from anyone who’s done it, don’t reinvent the wheel.
3. Plan — go into planning mode, compare approaches, make technology choices, and produce a pre-execution review checklist.
4. Approve — only after I sign off does it actually start work.

Once the work is done, it also runs validation at a level determined by the risk tier, with a dedicated “poke holes in it” pass, then re-checks after. On top of that, an acceptance gate: follow another document for the git deployment steps, decide which memory files need updating, all spelled out. It also works out ahead of time which tasks can run in parallel, to save time.

A detail: why the file mixes Chinese and English

The file is written in mixed Chinese and English — Chinese for the narrative and the judgment logic, but I keep all the technical terms in English.

That isn’t for show, it’s to make the instructions more stable. Because Claude was trained on huge volumes of those English technical terms — commit, push, all trained in English — and using the “native” English word makes its understanding of the config more reliable.

I use Chinese for the skeleton because my Chinese is better than my English — I can tune a config file faster, and judge faster whether it’s both rigorous and concise, saying what needs saying in few enough words. That said, if your English is better than your Chinese, writing the whole thing in English would probably make execution even more robust.

One last aside. I share my time for free partly because I want to make some friends on a bigger platform and pass on what I’ve learned. Someone commented, “fix your cough before you come back to teach” — fair advice, but between friends, the first question is usually whether you’re feeling all right. And plenty of people go out of their way to tell me where they’ve applied this and what came of it, and in those moments I figure the dozen-plus minutes I record every day, unedited, aren’t wasted. So I’ll keep sharing.

Source: EP0025_audio.mp3 · ASR model gemini-2.5-pro (chunked parallel) · full text of the roughly 7-minute original recording

[00:00] A couple of days ago I made some videos about how our Claude Code is actually different, because the harness config is different. It’s like a genuinely brilliant management trainee joining the company, and I put him through detailed training tailored to how the company works first. That episode has tens of thousands of views already, and a lot of people have been pressing me to share something concrete. So today I’m going to share the part of it about getting Claude Code to write code more efficiently — this —

[00:25] config file. So once we go into the Claude folder, you’ll see there’s a rules folder in there. What’s stored in there is all the principles — it’s like a guide to how things get done. When Claude Code goes to do something, it follows the principles in here, this set of process standards, when it executes. And in there I have one file, the one I’m sharing today: change-workflow. It’s about what kind of —

[00:50] thinking it should use when it changes code, and how it should execute. So let’s look at this thing specifically. When you have Claude Code write code, honestly the most annoying thing is that sometimes it’s a tiny change — say a frontend tweak or a copy change — and it goes to enormous trouble doing a whole chain of thinking, right, before it makes the change. Very inefficient. Or the other way: the change is a small functional tweak but it touches a lot of modules, a lot of pipelines, and a lot of backend data,

[01:15] and it really should do research first before acting — and it doesn’t, it just dives straight in. Which then produces a pile of bugs. So how do you solve this? At first what I wanted to do was split the work into three tiers by difficulty — high, medium, low — and have it make a judgment call and then run a different process for each. But in practice I found that three tiers isn’t a particularly good approach, because it can’t —

[01:40] judge task complexity well. For example, if you go by the number of files changed, it might change a lot of files and still not be a complex task, right? So after a bunch of research, I turned that difficulty grading into just two levels: low and high. And how did I split it? It actually starts by thinking along two dimensions. The first dimension is uncertainty — for this change, this piece of code, before you start, do you —

[02:06] already have a clear plan? Or: can you describe the change clearly in one sentence, and is it perfectly clear what exactly needs to change? That’s the uncertainty dimension. The second dimension is risk: if this change goes wrong, how big is the cost of that error? Will it mean I have to test repeatedly, or can I just ship it —

[02:31] and see if it’s okay? So by judging along those two dimensions, it sorts changes into two categories: simple changes and complex changes. Simple changes it can just execute directly. Complex changes have to go through a four-stage process. And those four stages: first it does a clarification pass, to get an objective acceptance standard — what does “done” look like for this thing.

[02:57] It’ll use clarifying questions to talk it through with the user. Then the second stage is research. It goes and searches for technical solutions, checks whether the community already has best practices — if someone’s already done it we can borrow from that instead of reinventing the wheel. Then the third stage is going into planning mode, comparing approaches, making the technical choice, and producing a pre-execution review checklist. And finally it asks the user to sign off on that review before it touches anything.

[03:23] Then once execution is done, it also runs different levels of verifi— verification depending on the risk tier. There’s a dedicated nitpicking step in there. And after the nitpicking it runs the checks again, including the acceptance gate — meaning it follows another doc to handle the git deployment, including which memory files need updating. All of that is spelled out in here.

[03:48] And which tasks can run in parallel — it thinks that through in advance to boost efficiency. I’ll share this file. There’s one more detail worth calling out separately. You can see this file is written in a mix of Chinese and English — Chinese for the narrative, for the judgment logic, but I keep all the technical terms in English. That’s not showing off. It’s to make the instructions more stable,

[04:15] because when Claude was trained, it saw these technical words heavily in English — things like commit, like push, all trained in English. So keeping those native English terms here makes its understanding of the config more stable. And the reason the skeleton is in Chinese is, first, my English isn’t as good as my Chinese expression. And this config file —

[04:40] is something I can adjust faster that way. Likewise with a Chinese prompt I can quickly judge whether it’s both rigorous and concise — whether the description is tight enough to explain the config clearly. That helps me later on too. Of course, if your English is better, then writing the whole doc in English —

[05:05] would probably make it more robust, meaning more stable in execution. One last aside. Lately the weather in Beijing has been bad, and there’s a lot of dust in the air, so I’ve had allergy symptoms and I’ve been coughing nonstop. Ugh, I feel — how do I put this — the reason I spend time sharing is partly to make some friends on a bigger —

[05:30] platform, right, to give away some of my own experience for free. But I’ve also seen a lot — a lot of people commenting saying stop coughing, get it cured and then come back and talk, right, it’s really ruining the… the viewing experience. And I think an expression like that, even if it’s fair advice, honestly doesn’t feel great to hear. I mean, we’re doing this as friends, right?

[05:55] If you value my content, if you think what I share is worth something, and you want to be friends with me — then from a friend’s perspective, shouldn’t you ask whether I’m feeling okay, right? What’s actually causing it, what could I do about it? That’s when you start feeling like some people are worth spending my time sharing with and talking to.

[06:22] But some people, really — you get all kinds, I guess. Including people who DM me just to hurl abuse. Can you imagine — what kind of garbage is this you’re talking about. It’s… ugh, I just feel — of course, there are also plenty of viewers sharing that they learned a lot, and who’ll proactively tell me where they applied all this experience of mine,

[06:47] and what they got out of it. And that makes me really happy. It makes me feel my time wasn’t wasted, right? Even recording ten-plus minutes a day in one continuous take, no edits, still costs time, right? I could be doing something else with that time, couldn’t I? But it’s exactly because those people are out there that I feel my sharing has value. So I think I’m going to keep sharing. If you like what I do, remember to hit all three buttons, and drop what you want to hear about in the comments.

[07:12] I’ll keep sharing with you going forward. See you next episode, bye-bye.