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—think of a wildly talented management trainee showing up, except I’ve already put him through a detailed onboarding built for this 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. A waste of time.
• Sometimes a change that looks tiny 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, on two axes.

Two axes: uncertainty × risk

Axis 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?

Axis two, risk. If it goes wrong, how much does that cost? Does it need testing over and over? Or can we just ship it and see whether it’s fine?

Judge on those two axes 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, the risk tier decides how hard I check it, including a dedicated “poke holes in it” pass and a re-check afterward. 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 makes the instructions more stable. Claude was trained on huge volumes of those English technical terms—commit, push, all of it in English—so using the “native” word makes its reading 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 rules. 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 actually go about it. So let’s look at this thing up close. 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 that’s the case where it actually should look into things first before it starts—and it doesn’t, it just dives straight in. And that gives you a pile of bugs. So how do you fix 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 digging, I cut that difficulty grading down to just two levels: low and high. And how did I split it? It starts by thinking about two things. The first one 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 side. The second one is risk: if this change goes wrong, how much does that mistake cost? Is it going to mean testing it over and over, or can I just ship it—

[02:31] and see if it’s okay? So by weighing those two things, it sorts changes into two buckets: simple changes and complex changes. Simple changes, it just goes ahead and does them. 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 counts as done 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 it’s done executing, 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 ahead of time so things move faster. I’ll put this file up. There’s one more detail worth calling out on its own. 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 words in their original English here makes it read the config more reliably. And the reason the skeleton is in Chinese is, first off, my English just isn’t as good as my Chinese. And this config file—

[04:40] is something I can tweak faster that way. Same thing with a Chinese prompt—I can tell right away whether it’s both rigorous and tight, whether the wording is lean enough to still get the config across. That pays off for me down the road too. Of course, if your English is better, then writing the whole doc in English—

[05:05] would probably make it more robust, meaning it runs more reliably. One last thing, off topic. The weather in Beijing has been bad lately, there’s a lot of dust in the air, so my allergies have been acting up and I’ve been coughing nonstop. Ugh, I feel—how do I put this—part of why I put time into these videos is 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 putting it that way, even if the advice is fair, 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 put out is worth something, and you want to be friends with me—then as a friend, wouldn’t you ask if I’m feeling all right, right? What’s actually causing it, is there something I could do about it? That’s when I start feeling like some people are worth spending my time on, worth making these for and talking to.

[06:22] But some people, honestly—you get all kinds, I guess. Including people who DM me just to cuss me out. Can you imagine—like, what kind of crap is this you’re talking about. It’s… ugh, I just feel—of course, there are also plenty of viewers who write in saying they learned a ton, and who go out of their way to tell me where they’ve put all this experience of mine to use,

[06:47] and what they got out of it. And that makes me really happy. It makes me feel like my time wasn’t wasted, right? Even shooting ten-plus minutes a day in one take, no edits, that still takes 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 like these videos are worth something. So yeah, I think I’m going to keep making them. 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.