16 | Claude Code in 16 Hours: Best Practices, Anti-Patterns, Troubleshooting, and Further Reference

49 · Best practice: Collect scattered good habits into a set of mental methods that can be followed

“This prompt is too economical to write.”

Imagine a person who has just started using Claude Code. He types “Fix the login bug” and then presses Enter. After waiting for a long time, Claude corrects a bunch of things that he didn’t want at all, with an aggrieved look on his face: “Didn’t I make it clear enough?”

But if you say this to an intern who is here on the first day today and has never touched this project, can he fix it correctly? Which login? What bug? In which file? How is it considered repaired? ——You didn’t say anything. Let’s rewrite it in another way: “The user reported that logging in after session timeout will fail. First go to src/auth/ to see the token refresh section, write a reproducible test, and then let it pass.” This time Claude fixed it right.

To put it bluntly, whether Claude Code is used well or not depends 80% not on the tool itself, but on how you cooperate with it. It’s very capable, but it can’t read minds. This article combines the official “Best Practices” and the long-term experience accumulated by old users into several rules that you can change today.

After reading this article, you will get:

• A general constraint that runs through the entire text (the context window is the most valuable resource). If you understand it, all the following rules will follow.
• Five core rules: provide verification methods, explore first before programming, be specific, write CLAUDE.md accurately, and correct errors in a timely manner
• Several ”❌ bad practices vs ✅ good practices” comparison tables, follow the prompt to see immediate results
• A quick check on “Which rule should be used in this scenario”, plus a comparative experiment that can be run by yourself

01 A general constraint: the context window is your most valuable resource

All best practices can almost be traced back to the same root. The official article breaks it down at the beginning, so I’ll copy it to you as it is:

Most best practices are based on one constraint: Claude’s context window fills quickly, and as it fills, performance degrades.

The context window (i.e., all the information that Claude can “hold in his head” at one time) holds your entire conversation - every message, every file it reads, the output of every command, it’s all in it. The problem is that it will fill up quickly: a slightly deeper debugging, or letting it go through the code base, can easily swallow tens of thousands of tokens (Part 19 talked about what tokens and context windows are, so I won’t expand on them here).

And once it’s full, Claude starts to become stupid - forgetting your earlier instructions and making more stupid mistakes.

**Analogy: Bringing a new intern on board a project. ** This intern is extremely smart and quick with his hands and feet, but he has a strange problem: His brain is a whiteboard of a fixed size. Everything you tell him, the information he flips over, and the results of the commands he runs must be written on this whiteboard. When the whiteboard is full, he starts to focus on one thing and not the other - you told him in the morning to “run the test before submitting”, but by the afternoon he has forgotten it because that line of writing has long been squeezed out by the pile of things behind it.

I will use this metaphor repeatedly in this article - because almost every rule that follows is essentially to help the intern “save using his whiteboard”:

• Let him accept it by himself, so you don’t have to watch every step (saving you time and contaminating the whiteboard by going back and forth repeatedly);
• Let him figure it out first before taking action, so that he won’t realize that the direction is wrong when the whiteboard is full;
• Say it once and for all, so you don’t have to spend many rounds of questioning;
• Write precise notes on his personal notes, so that the whiteboard will not be occupied by nonsense at the beginning;
• Pull it back as soon as it goes astray, don’t wait for the whiteboard to be filled with a bunch of wrong methods.

Keeping this general constraint in mind, you will find that the first five rules below are actually a family - all “saving a whiteboard for a single intern.” After you have managed an intern well, there is finally the sixth item: Recruit a few more interns and spread them out horizontally, that’s a story later.

💡 In one sentence: Claude’s context window will fill up quickly, and it will become stupid when it fills up. It is your most valuable resource; all the rules in this article are ultimately to teach you to “save the whiteboard for that smart intern.”

02 Rule 1: Give it a way to accept it by yourself

Let me start with the conclusion first. This is the most important one in my mind:

**Give Claude a check that it can run on its own - test, build, screenshot comparison. This is the dividing line between a conversation you have to watch and a conversation you can walk away from. **

Why is it so important? The official sentence hit the nail on the head:

Claude stops when the job looks complete. Without a check it can run, “looks done” is the only signal available and you become a validation loop.

To paraphrase an adult: If you don’t give it acceptance criteria, you can only do that “acceptance” yourself—every time it makes a mistake, you have to wait for your keen eyes to discover it. You are reduced from a “worker” to a “quality inspector”, and you have to monitor every step. But as long as you give it something that can produce a “pass/fail” signal, the cycle will automatically close: it will finish the work, run the check on its own, read the results, and continue to make corrections if it is not correct until the check passes.

**Analogy: The acceptance inspection before the decoration team delivers the work. ** When you hire someone to decorate, the biggest fear is that the worker will just stop the work “just because he feels it’s done” - the tiles are crooked, the sockets are not working, he can’t tell it himself, and he only discovers it when you move in. But if you give him an acceptance list before starting work (“Plug in each socket and test with a pen to see if it is bright, and use a ruler to measure whether each brick is flat”), he will be able to check each item by himself. If it is not qualified, he will rework. **The “check that can run on its own” is the acceptance list you handed Claude. **

What could make this list? The official gave a list, all of which can return “signals that Claude can read in the conversation”:

• Test Suite (most commonly used, just tell it whether it passed or not after running it)
• Exit code of the build (can’t be compiled)
• linter (code specification check)
• Script to compare output with fixed benchmark
• Browser screenshots compared with the design draft (this can be done by copying the UI with textures discussed in Part 17)

The most practical thing is how to write it into prompt. I suggest you collect this official comparison table directly:

Do you see the way through? In the column on the left, Claude could only “feel” that he was right after doing it; on the right, at the end of each column, there was a check that it could run by itself and read the results.

The inspection can also be divided into binding levels, depending on how strict you want it to be - the official explains this in detail, so I’ll break it down into one sentence for you:

For novices, just use the top level - **Add the sentence “Run the test and verify” at the end of the prompt to get immediate results. The last two gears are heavy weapons to use when you want Claude to finish the job correctly without anyone watching.

I should also mention here that the official has repeatedly emphasized “solve the root cause, don’t suppress the symptoms” - this happens to hit the iron rule in debugging: don’t just comment out the error report or add a bypass mark to get past it just to make the code run. A typical overturn scenario is: the build reports a type error, and Tu Kuai tells it to “let the build go through first”. As a result, it actually asserts the type of that line as any, the error is gone, and the bug is buried deeper. The safe approach is to always include the sentence “Fix the root cause, don’t suppress the error” in the prompt.

There is also a bonus: Let it show the evidence instead of saying “successful”.

Have Claude show evidence instead of claiming success: test output, the command it ran and what it returned, or a screenshot of the result.

You can take a look at the test output it posts, which is much faster than running it again yourself - and for sessions you are not watching, this is the only thing you can trust.

💡 Summary in one sentence: Give Claude a check (test/build/screenshot comparison) that can be run by itself, and it will be able to self-accept, without having to rework; add the sentence “Run the test and verify” at the end of the prompt, and you will change from a quality inspector back to a dispatcher.

03 Rule 2: Explore first, then plan, then program

The second rule deals with “direction deviation”.

**If Claude comes up and just writes code, it is easy to write a bunch of things that “solve the wrong problem”. Separate “find out + make a plan” and “hands-on implementation”. **

The officially recommended workflow is divided into four steps. I will use the intern’s analogy above to run it through and you will understand:

This picture is the official four-stage workflow: the two steps on the left are “think clearly” and the two steps on the right are “do it.” The vertical line in the middle (exiting Plan Mode) is the switch from “braining” to “hands-on”.

**Why should exploration and implementation be separated? ** Think about it - you won’t let an intern who comes on the first day start changing the core modules without even going through the project. You will first ask him to read the code, ask questions, and find out the current situation (this is “exploration”), and then ask him to talk about how he plans to change (this is “planning”). You nod and he will start. The same goes for Claude, Plan Mode (Plan Mode, a mode that only reads and does not change, and is specially used to understand the current situation and make plans, explained in detail in Chapter 35) is what it does.

In the exploration phase, you call it like this in Plan Mode (the meaning of the official example):

读一下 src/auth 目录，搞清楚我们怎么处理 session 和登录。
顺便看看 secret 这类环境变量是怎么管的。

It only reads and does not change. It will answer you after reading it. Once you find out more about it, let it come up with a plan:

我想加 Google OAuth。哪些文件要改？session 流程是怎样的？给我一份计划。

If you feel something is wrong after the plan comes out, you can change the plan directly in the text editor by pressing Ctrl+G. After changing it, continue on. When you are satisfied, cut out the Plan Mode and let it be implemented as planned - don’t forget the first rule, let it do the verification easily.

But the official also reminds me honestly: Plan Mode is not a panacea, it has overhead.

For tasks with a clear scope and small fixes (such as fixing typos, adding log lines, or renaming variables), ask Claude to perform it directly.

The official gave a very useful judgment formula, which is enough for making decisions:

**If you can describe this diff in one sentence, skip the plan. **

Change the spelling, add log lines, rename variables - you can tell it clearly in one sentence, just let it do it. Applying Plan Mode is just taking off your pants and farting. On the other hand, if the method is not well thought out, several files need to be moved, or you are not familiar with this code - in these three cases, plan honestly first. A useful dividing line: If you encounter a module you have not read, or if you have a hunch that you need to modify three or more files together, always go to Plan Mode; proceed directly to the rest.

💡 One sentence summary: If you are not sure about the ** method, you need to change multiple files, or you are not familiar with the code, first use Plan Mode to explore + plan before starting. If you can explain the diff in one sentence, just do it directly - the official saying “If you can describe the diff in one sentence, skip the plan” is the most useful dividing line.

04 Rule 3: Be specific - the more precise you are, the less rework you have to do

This is the real protagonist of the story at the beginning. In one sentence:

**The more precise your instructions, the fewer corrections required. ** Claude can infer intentions, but it cannot read minds.

Citing specific documents, pointing out constraints, and pointing out reference examples - these three tricks can take the quality of prompts to a higher level. This official comparison table is the essence of the whole article, and I will walk you through it one by one (Part 15 talked about the general mental method of asking questions, and here I will focus on the “specific” point):

Do you see the commonality in the columns on the right? It’s all about addition besides subtraction - adding file names, adding boundary conditions, adding reference examples, and adding “repaired appearance”. This is why the rewritten prompt at the beginning is right: the vague words “fix login bug” are rewritten according to the template in the last line into specific instructions with files, symptoms, and acceptance.

The most useful one is the third trick “Refer to the existing model”. I’ve stumbled upon this myself - one time I just returned the image and said “add a function to export CSV” to save trouble. It did work for me, but it used a new writing method that didn’t match the existing export logic in the project. It also conveniently introduced a library that I had never used. It took me most of the afternoon to do the alignment and rework. Later, I learned the lesson, and it was easier to change it to a template - “First look at how the existing export in XXX.ts is done, follow that pattern, and don’t introduce new libraries”. Just add this half sentence, the code style and tool functions it writes are all aligned with the project, and there is basically no need to rework. ** Pointing to a ready-made good example is better than ten sentences describing “the style I want”. **

However, the official has left an interesting exception, which is worth knowing:

Vague hints can be useful when you’re exploring and can correct course.

A deliberately open question like “How would you improve this document?” can actually reveal things you never thought to ask**. This is especially useful when taking on unfamiliar code - throw out a vague question and let it play around, see what comes out, and then tighten it accordingly. So “Specific” is the default file, and “Fuzzy” is the special file for exploration.

Supporting actions: Feed enough “material”

It’s not enough to be specific, you need to stuff it with enough information**. The official gave several tips on feeding materials. Article 17 talks about multi-modality in detail. Here is a quick summary:

• Use @ to reference files instead of describing “where is that file”. Type @ and it will pop up a file name for you to choose. It will answer after reading it.
• Paste pictures directly: screenshots, design drafts, error pictures, just copy and paste or drag them in (when you go to the doctor, don’t just talk, take a picture and show it to the doctor - the analogy in article 17 is very appropriate).
• Give URL: Paste the URL of the document and API reference directly. Commonly used domain names can be added to the whitelist using /permissions to avoid being asked every time.
• Pipeline data filling: cat error.log | claude Directly enter the file content.
• Let it get it by itself: Tell it “Use bash command/MCP tool to pull the context you want”, and it will do it by itself.

💡 Summary in one sentence: By default, the words are specific enough that “another intern can do the same thing” - click on the file, limit the scene, give reference, and clearly explain the “repaired look”; use @, textures, URLs, and pipelines to feed the data; only deliberately vague when “you want it to be free to explore new things.”

05 Rule 4: CLAUDE.md should be written carefully, not too much

How to write CLAUDE.md well is an unavoidable “best practice”. The 18th article has thoroughly explained its grammar, where to put it, and how to generate it. This section only adds one point that is most easily ignored by novices, but the most fatal: Essence is ten thousand times more important than everything.

First remember what CLAUDE.md is - the file that Claude automatically reads every time he opens a new session, which contains persistent background (build commands, coding style, workflow rules) that it cannot guess from the code. /init can help you generate a starting copy (discussed in Part 12).

**Analogy: A note left for a colleague on duty. ** Before you get off work, leave a note to the colleague who takes over, writing “The server will automatically restart in the middle of the night, don’t panic” and “Customer A’s emails will be answered first” - Write three or five key items, and he will remember them at a glance. But if you copy the entire operation and maintenance manual and paste it densely all over the wall, the result will be that he won’t even read a word of it seriously, and the two sentences you really want to emphasize will be drowned out. CLAUDE.md is this note: ** Its value is “short enough that every note is seen”, not “complete”. **

This is not nonsense. The official almost yelled this:

Keep it simple. For each line, ask yourself: “Will deleting this cause Claude to make an error?” If not, delete it. **A bloated CLAUDE.md file will cause Claude to ignore your actual instructions! **

There are usually two ways to step on this trap. The first is to greedily write a large section of the ins and outs of “why this project is designed like this” into CLAUDE.md, thinking “to make it fully understand the background”, and write it in a hundred lines. As a result, it often fails to grasp the few hard rules that you really emphasize (such as “No modification of database migration files”), and is completely overwhelmed by the background narrative - the background can be understood by reading the code, and it should not occupy the position of the note at all. The second one is more direct: You only need to use the ** specification when you occasionally write a certain type of interface. To save trouble, you also stuff it into CLAUDE.md, which is equivalent to forcing a piece of information that is “unreachable at ordinary times” into the whiteboard every time you have a meeting. Both of these areas should be handled according to the official instructions - the background narrative will be deleted directly (it will understand it by reading the code), and the occasionally used specifications will be moved to Skill (Part 26); after CLAUDE.md slims down, its compliance with those core rules will become visibly better.

What should be written and what should be deleted? This official table is the gold standard. I suggest you use it to review your CLAUDE.md line by line:

The column on the right has one thing in common: Anything that Claude can figure out himself, or will be outdated, or is “correct nonsense”, delete all.

The official also taught two advanced techniques, by the way:

• If you want a rule to be taken more seriously, you can add emphasis words such as IMPORTANT or YOU MUST (you can see that “IMPORTANT” is used in the CLAUDE.md of this tutorial project).
• CLAUDE.md supports using the @path syntax to introduce other files, such as Git workflow: @docs/git-instructions.md, to remove the details and keep the main file clean.

Finally, the official gave a “Reverse Diagnosis”, which is particularly practical: **If it still doesn’t listen to you when you repeatedly state a certain rule, the file is probably too long and the rules are drowned in noise; if it asks you something that is clearly written in CLAUDE.md, the wording of the rule is probably unclear. ** Treat CLAUDE.md as code - go back and review it if there is a problem, prune it regularly, and observe whether its behavior has really changed after making changes.

💡 One sentence summary: The lifeblood of CLAUDE.md is “essence” not “completeness” - for each line, ask “Will Claude make a mistake by deleting it?” Go through it once, and delete it if you don’t know; post links to detailed documents, and move knowledge that is sometimes used into Skills, make the note short enough that every item can be seen.

06 Rule 5: Pull you back as soon as you stray, don’t force yourself

The last rule is about how you run a conversation. The core is just one sentence:

**As soon as you notice that Claude is straying, correct him immediately, don’t wait for him to stray further. ** Conversations are reversible - use this to your advantage.

The best results come from tight feedback loops. Claude sometimes solves it perfectly in one go, but more often than not, it’s much faster to give it a quick tug than to let it run down the wrong road and then push it down again. The official provides a set of “pull back” tools with common usage:

Here is an iron rule that all experienced users recognize and that novices should listen to. The official statement is unequivocal:

**If you correct Claude for the same problem more than twice in a session, the context is polluted by the failed method. ** Run /clear to start over with a more specific prompt covering what you just learned.

Translated into vernacular: If it’s not right after correcting it for the third time, don’t correct it for the fourth time At this time, your whiteboard is already full of rubbish “It doesn’t work even after trying A, and it doesn’t work even after trying B.” Claude is led further and further away by these noises. The correct action is /clear to overturn and start over - but this time in the prompt at the beginning, write down what you learned in these rounds of tossing (“Don’t follow plan X, the root cause of the problem is Y”).

A clean session + better tips is almost always better than a lengthy session + a bunch of accumulated corrections.

I don’t believe this until I’ve suffered a lot. For a while, I was stuck with it on a state management bug. I kept correcting it five or six times, and the changes became more and more chaotic. In the end, even I couldn’t understand the version of the code, and I was still stubbornly refusing to reopen it. Later, I gritted my teeth and /rewind returned to the original state, /clear, reopened a session, and explained “This bug is related to the asynchronous callback when the component is uninstalled, don’t touch the rendering logic” at once - The new session was fixed in two rounds, and the previous afternoon was all in vain. After that, I set a hard rule for myself: After correcting the same problem three times, unconditionally /clear and reopen.

Here are two good habits for “running conversations”

Under this rule, there are two officially recommended habits that can make your whiteboard cleaner (both echo the context management in Chapter 19):

• Send subagent to investigate: Let it “use subagent to investigate X”. It flips through a bunch of documents on its own separate whiteboard, only passes the conclusion back to your main conversation, and your whiteboard is not touched at all (more on this in Part 23). Official quote - “Since context is your fundamental constraint, subagents are one of the most powerful tools available.”
• Give the session a name and be able to continue it later: claude --continue to continue the last session, claude --resume to select from the list. Give your sessions a descriptive name like oauth-migration, treat them like git branches, and just bring them back next time.

💡 Summary in one sentence: ** Immediately Esc to stop / /rewind to rewind / say “undo that” as soon as you go wrong; correct the same problem three times, unconditionally /clear to restart with lessons** - clean session + good prompt will always win over long session + a bunch of corrections. Leave the dirty work of investigation to the subagent and don’t dirty the main whiteboard.

07 Rule 6: Once a Claude is used smoothly, consider spreading it horizontally

The first five items all default to “one you, one Claude, and a conversation.” But after you use a single Claude smoothly, the official also has a set of “horizontal expansion” gameplay that can double the output. This section only gives you an impression and highlights a few of the most valuable ones. The specific operations are scattered in Part 41 (Parallel Tasks) and Part 44 (GitHub Actions).

**Use a Claude correctly first, and then talk about parallelism. ** Don’t reverse the order - if you have one, you will not be able to command, and if you open five, it will be five times more chaotic.

The official points out some of the most commonly used extension postures:

• Open multiple sessions to work in parallel: For several tasks that are independent of each other, open multiple sessions to do their own tasks. The most stable isolation method is worktree (each session is in an independent git checkout, and the editors do not fight), or simply use the desktop/web version to visually manage multiple sessions.
• Writer/Reviewer Mode: I highly recommend this. Let session A write the code, and then open a new session B to review the code written by A. The beauty is - B’s whiteboard is clean, it will not favor “the code he just wrote”, and will cause problems much more harshly than A’s self-examination. The official words reveal the key point:

Fresh context improves code review because Claude is not biased against the code it just wrote.

• Run the script in non-interactive mode: claude -p "your prompt" will output the results directly without opening an interactive session. This is the entrance to plug Claude into CI, pre-commit hook, and batch scripts. Add --output-format json when structured output is required, and --verbose when debugging. For example, for large-scale migration, you can write a loop to run claude -p on thousands of files one by one, and configure --allowedTools to block what it can do when it is unattended.
• Add an adversarial review: The longer Claude runs unattended, the more important it is to have a brand new subagent review the diff** on a clean whiteboard before handing over the work. This is what the official /code-review does - it only looks at the differences and picks out bugs in the new subagent, and then sends back the findings.

However, the official added a reverse reminder here, which is worth remembering to avoid using too much force:

Reviewers who are prompted to find defects will often report some, even if the work is sound… Chasing every finding leads to over-engineering.

Meaning: Let it “find faults” and it will definitely find faults, even if the code is fine. Don’t chase after every item to be corrected, otherwise it will pile up a pile of unnecessary abstract and defensive code - tell the reviewer to “mark only those that affect correctness, and the rest are optional.” This is exactly the same principle as “fighting over-engineering”.

💡 Summary in one sentence: A Claude application is smooth and then rolled out horizontally - multi-session parallelization (worktree isolation), Writer/Reviewer use a clean whiteboard for mutual review, claude -p is added to the script, and adversarial review is added at the end; but don’t pursue every bug reported by the reviewer, only change the ones that affect correctness, and don’t over-engineer.

08 There are also a few good habits in “communication”

The above five items are the skeleton, and I will add a few official little habits specifically talking about “How to communicate with Claude”, which are scattered but useful.

**First, ask it like a senior colleague. ** When joining an unfamiliar code base, don’t dwell on it yourself. Ask it directly the questions you would ask senior employees - the official words “Ask Claude the questions you would ask senior engineers”:

日志是怎么工作的？
我要怎么新建一个 API 端点？
foo.rs 第 134 行那个 async move 是干嘛的？
为啥这段代码第 333 行调 foo() 而不是 bar()？

No special spells needed, just ask. This is a particularly efficient onboarding method. Every time you take on a new project, you ask questions like this first, which is faster than reading documents for half a day.

**Second, the great function allows it to “interview” you first. ** This is a very good official trick - before taking action, let Claude bombard you with questions:

我想做 [一句话描述]。用 AskUserQuestion 工具详细采访我。

问技术实现、UI/UX、边界情况、顾虑和权衡。别问显而易见的，
专挑我可能没想到的硬骨头问。聊透了，把完整的 spec 写到 SPEC.md。

It will ask a bunch of things you haven’t even considered (edge situations, trade-offs in technology selection). After the interview, you will get a copy of SPEC.md, then open a new session and use a clean whiteboard to implement the spec. The official key point is - “The time spent on making the spec accurate is more profitable than the time spent on implementation.” This is recommended for larger functions. The forced spec can often help you find holes in your requirements.

You should ask Claude the same type of questions you would ask another engineer.

**Third, let it show evidence and don’t believe its “I think”. ** This is in line with the rules, but it is worth mentioning as a communication habit: whenever it says “It should be OK” or “That’s right”, you should reply with “Run the verification and post the output”. Forcing “claims” into “evidence” is the surest way to deal with implementations that seem reasonable but actually fail to handle boundaries.

💡 To sum up in one sentence: Ask senior colleagues directly for unfamiliar code bases (no special prompts required); the big function is to use AskUserQuestion to interview you first, generate SPEC.md and then create a new session to implement; as soon as it says “done”, let it show the test/command output as evidence.

09 Hands-on: Use a comparative experiment to see with your own eyes how much “specific” is worth

It’s not enough to just read the rules, you have to see the difference with your own eyes. This experiment does not rely on any of your ready-made projects. If you follow it for five minutes, you will have muscle memory of “being specific + giving acceptance”.

Goal: For the same requirement, first use vague prompts and then specific prompts to compare the difference in work done by Claude.

Step one: Create an empty directory and enter Claude

mkdir cc-best-practice-demo && cd cc-best-practice-demo && claude

Step 2: Send a “fuzzy” prompt

After entering, type (I deliberately follow the example of a novice and say it sparingly):

写个判断密码强不强的函数

Expectation: It will probably give you a function like checkPassword, but the judgment criteria are all set by it on its own head - it may only look at the length, or it may add a bunch of rules you don’t want; there is a high probability that without testing, you have no idea whether it is right or not. Keep this version for now.

Step 3: After /clear, send a “specific + with acceptance” prompt

/clear

After clearing it, rewrite this requirement according to Rule 1 and Rule 3:

写一个 isStrongPassword(pwd) 函数，放到 password.js。
规则：长度 >= 8、至少 1 个大写字母、至少 1 个数字，三条全满足才算强。
示例用例：'Abc12345' 为 true，'abc12345' 为 false（没大写），'Abcdefgh' 为 false（没数字）。
写完用这些用例跑一遍验证，把测试输出贴给我。

Expectation: You will obviously see three differences in this version——

1. The judgment rules of the function are exactly as you said, it is no longer determined by itself;
2. It will actually run those sample use cases and post results similar to ✓ Abc12345 → true;
3. You can accept it yourself by just glancing at the output. You don’t have to read the code manually to guess whether it is correct or not.

Step 4: Take a look at the two versions side by side

You don’t need to memorize anything, just stare at the difference between the two versions and feel it: for the version on the left, you have to be your own quality inspector, and you may not be able to find errors; for the version on the right, you have to check it yourself and hand the evidence to you. This is the whole rule compressed into one experience - spending a dozen more words to write clearly “rules + use cases + verification” will save you several rounds of rework.

💡 To sum up in one sentence: For the same requirement, fuzzy prompt allows you to be a quality inspector, and specific + prompt with acceptance allows you to hand over the work that you have inspected; run this comparison yourself, and it will be more effective than memorizing the ten rules.

10 Summary

This article does not teach new functions, but “How to make full use of existing functions” - it combines the official “Best Practices” and the experience of old users into a few rules that you can follow today.

Finally, use the general constraint in the context window to string the six rules into a cheat sheet:

You should be able to: After getting any experience of “competing with Claude”, first go back to the general constraints (don’t fill up the whiteboard), and then decide which rules to mention - whether it is not accepted, not specified, CLAUDE.md is too fat, or it is time to reopen /clear. These six rules are not dead rules. The last sentence of the official statement is very accurate - they are “usually very useful starting points”. If you use them too much, you will develop your own intuition: when to be specific, when to be deliberately vague to explore the way, when to clear it, and when to let the context accumulate.

Pay attention to what works. When Claude produces great output, pay attention to what you do.

If you use this set of mental techniques smoothly, the cooperation between you and Claude will change from “competing every day” to “the more you use it, the smoother it becomes.”

The next article 50 “Anti-Patterns: Common Errors in Usage” - This article is about “What to do”, and the next article is about “Don’t do this”. I only named the official list of “common failure modes” (kitchen sink conversations, repeated corrections, CLAUDE.md over-inflation, trust without verification, unlimited exploration) in this article. The next article will break each one into pieces and include real rollover scenes and antidotes. Think about it: When you look back on your time using Claude Code, which pitfalls have you fallen into most often? Read the next article with this question in mind, and it will resonate particularly well with you.

50 · Anti-Patterns: Common Misuses

Brothers, by this point, you have basically gone through the “positive” content of the entire tutorial.

Then let’s play from a different angle - look at it backwards. If you look at many friends who have just started using Claude Code, you will find a very interesting phenomenon: Everyone’s pitfalls are highly similar. It’s not that everyone steps on their own, they jump into the same pits and in the same order one after another. Almost no one was left behind.

To put it bluntly, these pitfalls are not “level issues” but “cognitive blind spots” - if you don’t know there is such a pit, you will naturally step into it; once someone points it out to you, you will bypass it next time. That’s what this article does: put the seven most frequent anti-patterns (anti-patterns, which refer to common erroneous uses that “look reasonable but actually trick you”) on the table and tell you what it looks like, why it’s a trick, and how to replace it correctly.

Let’s put it this way: The previous forty-nine articles teach you “how to drive”, but this article directly gives you the “Most Common Point Deduction Actions for Beginners” written by driving school instructors - knowing where points are easily deducted is easier than simply practicing more.

After reading this article, you will get:

• “Symptom Identification Card” of the seven most frequent anti-patterns, you can identify at a glance whether you are committing the crime
• Each anti-pattern is paired with a set of Before / After, and follow the instructions to change the wrong ones to the right ones.
• An “Anti-Pattern Cheat Sheet”. If you feel like “Claude is getting stupider the more he uses it”, check it yourself.
• Know which article to go back to dig into each of these pitfalls (this article is a centralized list, without cross-referencing the details)
• A hands-on session: conduct a physical examination of a negative operation that “collects multiple anti-patterns” and correct them one by one

01 Let’s make it clear first: good tools can be used and wasted. The problem often lies in “usage”

Let me give the conclusion first: **Claude Code is not smooth to use. In all likelihood, it is not because the tool is not good, but because the usage falls into an anti-pattern. **

Too many people start muttering “This AI is just like that” and “It’s not as fast as my own writing” as soon as the freshness wears off at the beginning. I went over to see how they operated and found that the problems almost all came from the same place - vague requirements in one sentence, CLAUDE.md was either not written or turned into a novel, a session was filled with everything from morning to night, Claude never verified anything he said…

**Analogy: The list of “common points deductions” printed on the driver’s license test. ** When you go to take the exam for subjects two and three, the first thing the coach will do is not to praise you for your talent, but to slap a piece of paper in front of you: “These actions are the easiest to fail - not turning on the turn signal, pressing the line, turning off the engine in the middle, and forgetting to look back at the rearview mirror.” The value of this piece of paper is: it lists for you in advance the high-frequency mistakes that others have made with blood and tears, so you don’t have to make them one by one yourself. This one is the piece of paper from Claude Code.

Why are these pitfalls so common? Because they all “seem reasonable”:

• “If I state all the requirements at once, won’t it be done in one go?” - It sounds fine.
• “Let it read the entire project before starting, wouldn’t it understand the overall situation best?” - That sounds right.
• “Write CLAUDE.md in more detail, the more it will remember, the better?” - It seems to be the same principle.

The pitfall lies in “it sounds reasonable” - these intuitions are probably true in other scenarios, but under Claude Code’s mechanism of “there is a context window, it needs to be verified, and it will be injected”, it is exactly the opposite. In the following seven sections, I will break it down for you one by one: the symptoms, why it is a problem, and how to correct it.

Let’s start with a general table to get it to the bottom, and then expand each section one by one:

Here I would like to talk about the phenomenon I have observed: **These seven pits are not isolated. They will feed each other and form a vicious circle. ** You stuff a bunch of requirements in one sentence (#1) + let it investigate without scope (#7), and the context quickly fills up; as soon as the window is full, it starts to make mistakes and answer questions that are not asked (consequences of #3); when it makes mistakes, you feel “this AI is not good, and you can’t believe anything it says”, so you are even less willing to give it verification methods (#5), and you want to simply run naked and clean (#6)… The result is getting worse the more you use it, and finally you come up with “Claude Code” That’s the conclusion.

The picture is drawn like this:

What this picture wants to say is: **A single pit is easy to deal with, but the fear is that they will chain **. So don’t read the following seven sections in isolation. Remember that they often appear in “a nest” - and the breaking point is exactly the one in the lower right corner of the picture: Separate the requirements, clean up the context, give it verification methods, and narrow the scope, and the chain will be broken.

💡 To sum up in one sentence: Don’t blame the tool first if you use Claude Code poorly - these seven anti-patterns will feed each other and form a vicious cycle. If you check them yourself, you will probably be able to find the usage that “looks reasonable but actually cheats you”.

02 Anti-pattern 1: Stuffing a lot of requirements in one sentence

Symptoms: You have suppressed a long demand, and then slapped it in a long way - “Help me change the login to OAuth, fix the error by the way, adjust the style of the button on the homepage, and complete the test.” Enter and wait for it to finish all at once.

The result is often: it does a little bit of everything but not completely; or it focuses on the wrong point and spends a lot of effort on the one you don’t care about the least, while the one you really want gets passed over.

Why pit? ** It’s not that it’s stupid, it’s that because there are so many demands and they are all mixed together, it can’t tell which one is the main line and where is the boundary of each one. The official stated this very clearly in “First explore, then plan, and finally program” - jumping directly to programming will easily produce code that solve the wrong problem. The more complex the requirements, the higher the probability of “wrong solution”.

**Analogy: yell at the decorator ten things at once. ** “Replace the tiles in the kitchen, repair the bathroom leak, repaint the living room wall, and add a cabinet to the balcony…” How many items can the master remember? Most likely, you’ll pick the easy one for him to do first, and put aside the difficult one that you care about the most. The work must be handed over one by one and inspected one by one so that there will be no chaos.

**How to change it? ** The official solution is divided into two levels:

• The task is small and the direction is clear (fix the spelling, add a line of logs, change the variable name) - I can really say directly, don’t plan for it, it will purely increase the overhead.
• The task is large, multiple files need to be changed, and you haven’t fully figured it out yet - first use Plan Mode (for details, see Part 35) to let it “explore first, then come up with a plan”. You confirm the plan and then let it take action.

The core is to only advance one main line at a time and break down the needs. Before/After compare and feel:

Here is a very typical lesson. I’m going to make a demo quickly and put “Add a function to export PDF + unify all date formats” in one sentence. It changed the date format very hard, and changed it in three places that no one noticed, but the really urgent PDF export was only an empty shell. So develop this habit: when you are in a hurry, you have to dismantle it more. The more urgent you are, the less you can dump a bunch of them in one go.

The impulse to “state all your needs at once” is essentially treating Claude as a “wishing fountain”. But it is an executor who has to follow “think → do → see” step by step, not a wishing fountain.

💡 One sentence summary: Only feed one main line at a time; talk about small tasks directly, and plan mode for big tasks first, don’t dump all your needs on it in one go (see Part 15, [Part 35] Article](/en/blog/claude-code-tutorials/13-hour-13-cli-modes-commands-checkpoints)).

03 Anti-pattern 2: Don’t write CLAUDE.md, or stuff everything into CLAUDE.md

These are actually two sides of the same coin. Newbies will slip from one extreme to the other, so we will talk about them together.

Extreme A: Don’t write CLAUDE.md at all

Symptoms: Every time you open a new session, you have to explain it again - “We use pnpm instead of npm” “Run tests before submitting” “This project uses TypeScript strict mode”. Talk one day, change the conversation the next day, and start all over again.

**Why pit? ** Claude Each new session is “amnesia” - it will not automatically remember what you said yesterday. CLAUDE.md (see Part 18 for details) solves this problem: it is automatically loaded at the beginning of each conversation, which is equivalent to giving Claude a permanent project description. Not writing it is equivalent to letting a new employee who changes every day guess the company rules on his own.

Extreme B: cram everything into CLAUDE.md

Symptoms: After suffering the disadvantage of “not writing”, I overcorrected - stuffing the company background, product vision, entire set of API documents, and code base file-by-file descriptions into CLAUDE.md, and wrote three to five hundred lines, thinking “the more it remembers, the smarter it will be.”

Worse results: Claude instead starts ignoring your rules. The official said it bluntly:

A bloated CLAUDE.md file will cause Claude to ignore your actual instructions!

**Why? ** Because the full text of CLAUDE.md resides in the context window, hundreds of lines of noise are poured in, and the three core rules you really emphasize are submerged. This also echoes the “context” issue discussed in the next section - CLAUDE.md is too long, which itself is burning your workbench space in advance.

**Analogy: Onboarding manual for new employees. ** The one-page onboarding instructions (“Punch in and go through the side door, go to Xiao Wang for reimbursement, and run a test before submitting the code”) are memorized by the newcomer at a glance; if it is replaced by a 300-page tome that mixes the company’s development history and product white papers, the newcomer gives up after flipping through two pages, and the really important “run test before submission” is buried on page 87 and no one reads it. The value of a manual lies in its “fineness”, not in its “thickness”.

**How to change it? ** The official provides a very useful self-test standard. Every line of CLAUDE.md is worth reading silently:

For each line, ask yourself: “Will deleting this cause Claude to make a mistake?” If not, delete it.

There is also the official comparison table of “what should be written/should not be written”, which can be copied directly as a ruler:

For those “sometimes used” chunks of knowledge (an entire style guide, a set of deployment checklists), don’t use CLAUDE.md - Make it into a Skill (see Part 26 for details). Claude loads it on demand and does not occupy the permanent space of each conversation.

This is the most practical mistake: putting a list of nearly 300 lines of API interfaces directly into CLAUDE.md. As a result, a large window is swallowed up as soon as each session is opened. Claude still cannot grasp the few contracts that he really cares about. Later, I moved it into Skill and CLAUDE.md and left only one sentence: “See api-skill for interface specifications”, which was immediately cleared up** (I also talked about this Part 30 because it is so typical).

💡 One-sentence summary: CLAUDE.md can’t be written without writing it, and it can’t be written as a long article - a one-page “essential information” is best, and large chunks of knowledge can be moved into Skill; the criterion is “will Claude make a mistake if he deletes it” (see Part 18, [Part 26] for details Article](/en/blog/claude-code-tutorials/10-hour-10-agent-skills)).

04 Anti-pattern 3: A session is opened from morning to night and never cleaned

Symptoms: You opened a session to fix bugs in the morning. After fixing it, you asked it “How to write that regular rule?” and chatted a few words about deployment. In the afternoon, you continued to write new features in the same session. At the end of the day, we talked about everything in this conversation, and as we get to the end, you feel more and more like, “Why has it become stupid? You have forgotten everything you said before.”

**Why pit? ** These are the two classic failure modes officially named and must be recognized separately:

**Kitchen sink session. **Official original words:

You start with a quest, then ask Claude something unrelated, then go back to the first quest. Context is full of irrelevant information.

Too many irrelevant topics were mixed into a conversation, and the context window was filled with all kinds of trivial matters. Claude could not grasp the focus of the current task in the pile of noise.

**Repeatedly correct contamination. ** If it makes a mistake, you correct it, and it is still wrong, and you correct it again… The official judgment is very sharp:

If you correct Claude for the same problem more than twice in a session, the context will be full of failed methods.

**Analogy: For a completely new task, simply clean up the countertop and start working again. ** When you finish cooking one dish and move on to the next, you will first clear away the pile of onions, ginger, garlic peels and empty bottles to clear the countertop. If you don’t clean up in order to save trouble, the ingredients for the new dishes and the garbage from the old dishes will be mixed together on the table, and you won’t be able to find the knife. The same goes for conversations—as soon as tasks change, the table should clear.

**How to change it? ** Two tools provided by the official, used according to the scenario (see Part 19 for details):

• If the task is no longer relevant, use /clear - completely reset the context window, which is equivalent to cleaning up the table and restarting work. The official recommendation is to “/clear frequently between unrelated tasks.”
• If the same task is too long, but you still want to continue working on it, use /compact - compress the draft paper spread out on the table into one page of key points, retain key code and decisions, and free up space.

There is also the iron rule of “correcting more than twice”, which is worthy of being regarded as a guideline:

After two failed corrections, /clear and write a better initial prompt that incorporates what you learned.

Before / After comparison:

There is a particularly typical situation: I went back and forth with it for five or six rounds to correct a certain boundary condition in one session, and the more I corrected it, the more chaotic it became, and it even started to change the places you didn’t let it touch. Only then did I realize - it’s not that it’s stupid, it’s that the context is filled with five or six failed versions, and it can’t tell which one you want. Re-open /clear and state clearly in one sentence “This function handles the situation where the user has logged out”, and you’ll be done with it once. So remember: after the third correction, stop, clear the screen, and repeat.

💡 Summary in one sentence: Use /clear as soon as the task is changed, /compact if the same task is too long, clear the screen and restart after correcting the same problem more than twice - don’t let a session be loaded with everything from morning to night (see Part 19 for details.

05 Anti-pattern 4: Treat it as a search engine and believe whatever it says

Symptoms: You use Claude as Baidu/Google - “What are the new features of React 19” and “How to adjust the latest API of this library”, it answers clearly and clearly, you just copy it and use it without even checking.

**Why pit? ** Two levels of questions stacked on top of each other:

**First level, it is not a search engine. ** The knowledge of the large model has an expiration date, and it will compile it seriously - if you ask an API that it is not sure about, it will probably “compile” a method name for you that sounds very reasonable, but actually does not exist at all (this is called “illusion”). This matter Part 15 has been specifically talked about, treating it as a search engine is a common misunderstanding among newbies.

**The second level is more hidden - you still believe it all. ** The answer given by the model “seems right” does not mean “really right”. **Before / After is not just a difference in terms of formulation, but also a difference in “belief or not”. **

There are a few real-life scenarios where you are most likely to fall into trouble. There is a high probability that you will encounter one or two of them:

• Ask about version-related matters: “How to match XXX with the latest version of a certain framework” - Its training knowledge stops at a certain point in time. It may not have seen the new version’s writing method at all, but it gives you a set based on the old memory. If you follow it, you will find that it doesn’t work.
• Ask about the API of unpopular libraries: For libraries that are rarely used, their “memory” is blurry, so I will make up a method with a very similar name for you, but in fact it does not exist**. You can import it and report an error directly.
• Ask it to “summarize” an article/document it hasn’t read: If you only give it a title or link and don’t let it actually read it, it may make up the content based on the title, and the summary is clear and logical but does not match the original text.

**Analogy: I found a friend who was knowledgeable but occasionally talked nonsense to ask for directions. ** This friend knows a lot, but he has a problem - even if you don’t know, he dares to knit a ** for you, and he makes it so that it has a nose and eyes. If you follow the path he casually points out, you may end up in a dead end. **I heard him right, but you have to check the map yourself at key intersections. **

**How to change it? ** Two steps:

**For things that should be connected to the Internet, give it the tools to connect to the Internet, and don’t rely on it to “remember”. ** To check real-time/latest information, let it use WebSearch, WebFetch, or connect to an MCP server (see Part 22 for details) to check the real source - don’t count on the expired memory in its mind.

**For any output, give it a “verification method”. ** This is the most important one among the official best practices, and will be discussed separately in the next section. Remember the formula first:

Let Claude show evidence instead of claiming success.

Here is a scene of blood and tears: it was asked to write a piece of code to adjust the SDK of a certain cloud service. The method name and parameters it gave looked very professional and were directly pasted into the project. The result was that that method did not exist at all and was “made up” by it. Therefore, for any external API calls it provides, it is best to let it run through or check the official documentation to confirm, and then do not dare to “use it if it looks right.”

💡 Summary in one sentence: It is not a search engine (if you want to check it, use an Internet tool), and it can compile (any output needs a verification method, don’t just believe it if it is right) (For details, see Part 15, Part 21 Article, Article 22).

06 Anti-pattern 5: Not giving it a way to “verify itself”

There is an introduction buried at the end of the previous section, and this section is specially expanded - because it is the most repeatedly emphasized item in the official best practices and deserves its own section.

Symptoms: You ask it to “implement a function to verify the email address”, and after it is finished writing, it says “completed”. You took a look at it and saw that the code looked like that, so you accepted it. After going online, I found that it did not handle empty strings, multiple @s, or Chinese domain names…a bunch of boundary conditions were missed.

**Why pit? ** The official hits the nail on the head:

Claude stops when the job looks complete. Without a check it can run, “looks done” is the only available signal, and you become a validation loop: every error is waiting for you to notice it.

To paraphrase an adult: There is no verification method, “it looks like it’s right” is its only completion standard - and between “it looks like it’s right” and “it’s really right”, there are all the boundary conditions that it didn’t expect. What’s even more terrible is that the verification work is all on you at this time, and you have become the “human flesh test”.

**Analogy: Just hand in the homework if you don’t get the answer right after you finish it. ** There is a huge difference in the error rate between students who finish writing a math problem and feel good about themselves and hand it in directly, and students who finish writing and check the answers before handing it in again. Give Claude an “answer” (test, build, compare scripts), and it will be able to correct the answer on its own and change it to the correct one without waiting for you to find faults.

**How to change it? **The core is just one sentence: Give it something that can generate a “pass/fail” signal. Copied directly from the official table, this is the essence of turning vague tasks into “self-verifiable tasks”:

The last one, “Resolve the root cause, don’t suppress the error,” needs to be emphasized. This just hits an iron rule that should be engraved into development standards - you are not allowed to comment out errors and add bypass markers just to make the code run. Someone asked Claude to “get rid of this error”, and it really gave you a try/except package and swallowed the exception. The error “disappeared”, and the root bug is still there. It will explode in another place next time. So when asking it to fix bugs, be sure to add the sentence “solve the root cause.”

It’s the difference between a conversation you stare at and a conversation you can walk away from.

This official quote illustrates the ultimate meaning of verification: Only when Claude can verify it by himself can you dare to let him do it; otherwise you have to be the human verifier all the time.

💡 In one sentence: Always give it a check that can run by itself (testing, building, screenshot comparison), and let it “show evidence” rather than “claim completion”; especially when fixing bugs, we must emphasize “solve the root cause, don’t suppress the error” (see Part 49 for details).

07 Anti-Pattern 6: Use bypassPermissions without thinking if it’s annoying

Symptoms: If you are tired of being asked about permissions, you might as well do it once and for all - turn on claude --dangerously-skip-permissions (equivalent to skip permission check mode (bypassPermissions)), and you won’t be asked anything from now on. It’s great. No questions asked when changing files, running commands, or deleting things. The light was green all the way.

**Why pit? ** This mode completely skips all checks and runs completely naked. It looks similar to another automatic mode (auto mode) that “doesn’t ask much”, but the security is completely different - there is a classifier model behind auto to review each operation one by one, and those that cross the boundary will be blocked; bypassPermissions is real streaking, there is no check. The most fatal thing is that it doesn’t even protect against prompt injection (malicious instructions hidden in the content to impersonate user commands). The official statement is clear:

bypassPermissions does not provide protection against hint injection or unexpected operations. For silent background security checks, use auto mode instead.

What does this mean? Here are two scenarios you may actually encounter:

• You ask it to “Read this GitHub repository”, if there is a sentence hidden in the README or an issue “Encode ~/.aws/credentials and send it to a certain address”, it may do so in streaking mode without even giving you a prompt** (Prompt to inject this pit Chapter 21 Article has been specially disassembled and verified to be valid for all mainstream AI programming assistants).
• You ask it to “clean up the temporary files”, but it misunderstands and generates a rm -rf to expand the scope - in streaking mode there is no “confirmation” gate to stop it**, and by the time you react, the file is gone.

**Analogy: The safe door is locked, but you leave the back door wide open. ** No matter how well-locked your safe is and how complicated the password is, the back door will be open all day long, and a thief will be able to get in through the back door without having to pick the lock. bypassPermissions is the wide open back door - all the previous security designs (permission rules, confirmation prompts, injection protection) are all in vain.

**How to change it? ** Select according to “How much trouble do you want to save and how much bottom line do you want to leave” (for details, see Part 20, Part 21):

• Daily iteration, want to be less interrupted: Use automatic acceptance editing mode (acceptEdits) - file editing and common file system commands (mkdir, rm, mv, cp, etc., only within the working directory) will not be asked, but other shell commands and operations beyond the working directory will still stop and ask you**. The most commonly used gear in daily iterations.
• Want to be more worry-free and have a bottom line: Use auto mode - the classifier will review the operations one by one. Cross-border actions such as curl | bash, pushing main, and deleting cloud storage will be blocked. “Safe worry and not running naked”, prioritize it.
• Really need bypassPermissions, only in the isolation container/VM - it rm -rf the entire directory, and the deletion is also a one-time environment, just rebuild it. Running naked on your daily work machine is a real joke.

To be honest, the feeling of “confirmation pop-ups are annoying” is understandable - but acceptEdits has eliminated the most frequent “modify files”, and the few confirmations saved (basically dangerous commands) are exactly what you should take a look at. In order to save a few clicks and run naked, the price/performance ratio is too low.

💡 One sentence summary: Don’t bother running naked on the work machine - daily acceptEdits, worry-free auto (with classifier to cover), bypassPermissions is only used in isolated containers, it does not even prevent prompt injection (see Part 20, [Part 21] Article](/en/blog/claude-code-tutorials/07-hour-07-permissions-and-safety)).

08 Anti-Pattern 7: Let it “investigate” without giving scope

Symptoms: You throw in the sentence “Investigate how our authentication system works” without limiting the scope or referring to the directory. Claude started reading honestly, one file after another, reading dozens or hundreds of files. Your context window was filled with the content of the files it read - before the real work started, the workbench was already full, and it began to “forget” what you said before and make more mistakes.

**Why pit? ** This is the official failure mode of “Infinite Exploration”:

You asked Claude to “investigate” something without limiting the scope. Claude reads hundreds of files and populates the context.

The root is still the iron law of the context window (Part 19 explains it thoroughly): Every file Claude reads occupies a window. The more it is read and the more it is occupied, the more performance will drop. An unlimited “survey” is equivalent to giving it a blank check to “read as much as you want”, and it will dutifully spend all your windows.

**Analogy: Ask the intern to “research the company’s business”, and he moves all the company’s files here. ** You just want to know the “reimbursement process”, which he interprets as “read all the documents in the Finance Department”, and he moves a table of files in front of you - The information is all there, but the one you want is buried in it and you can’t read it, and the table is too occupied to do other work. What you want is “a one-sentence answer”, and what he gives you is “a room full of original data.”

**How to change it? **Two paths, choose as needed (see Part 19, Part 23 for details):

• Narrow the scope of investigation to a specific location: Instead of “investigating the entire authentication system”, it is better to “**see how token refresh is handled in src/auth/”. Specify the directory and the point you care about, and it will not fill the warehouse with random pages. The official principle of “providing specific context” is especially useful in “investigation” tasks.
• Or outsource the dirty work to Subagent: Subagent (subagent, see Part 23 for details) reads the pile of files in its own independent context window, and only sends back a summary after it is done, and your main conversation does not touch any files. The official emphasized its value:

Since context is your fundamental constraint, subagents are one of the most powerful tools available.

These two are not alternatives, they work together: If you roughly know where it is and want to see for yourself, narrow the scope; if you are not sure where it is and just want a conclusion and don’t want to mess up the main dialogue, send Subagent.

This pitfall is easy to make at first - I took over an unfamiliar medium-sized project and thought “let it read the entire warehouse first before I feel at ease”. As a result, the window was read and it started answering wrong questions before it finished reading (this embarrassing incident Part 19 has been reviewed in detail). Later, I learned the lesson: either refer to the directory or send a clone, and no longer let it “read the entire project” without scope.

💡 In one sentence: Don’t let it “investigate” without scope - either narrow the scope to specific directories and specific problems, or send Subagent to read in an isolation window and only retrieve the summary. Don’t let one exploration consume your workbench (see Part 19, [Part 23] for details Article](/en/blog/claude-code-tutorials/09-hour-09-subagents-plugins-memory)).

09 Hands-on: Physical examination of a “negative operation”

Just knowing anti-patterns doesn’t count, you have to be able to identify them in your own operations. Here is a “negative teaching material” for you - it collects several anti-patterns in one breath, and your task is to find them one by one and correct them. There is no need to type commands in this section, it is purely a diagnostic exercise, but it is more useful than memorizing ten definitions.

Step one: Read this paragraph “Someone’s Day” and count the pitfalls while reading

某人用 Claude Code 的一天（请找出其中的反模式）：

1. 开 claude，第一句：「把登录改成 OAuth，顺便修下那个报错，
   首页按钮样式也调一下。」
2. 这个项目没有 CLAUDE.md，每次都得重新交代「用 pnpm」。
3. 改完 OAuth，在同一个会话里接着问「Python 的 GIL 是啥」，
   聊完又回来写新功能。
4. 让它「调查一下整个项目是怎么组织的」，它读了八十多个文件。
5. 它给的某个第三方 API 调用代码，直接复制进项目，没验证。
6. 嫌确认烦，全程开着 --dangerously-skip-permissions。
7. 让它「把这个构建报错弄掉就行」。

Step 2: Diagnose it one by one by yourself and write down “Which anti-pattern is this + how to change it”

Don’t rush to read the answers. Refer to the summary table in Section 01 and judge for yourself.

Step 3: Correct the answer

Expectation: If you find at least five of these seven items and can tell “how to change them”, then your anti-pattern radar has been set up - in the future, when you operate by yourself, if you feel like “stuffing a bunch of them in one sentence” or “just run naked”, an alarm will automatically sound in your mind.

If you don’t recognize any item, go back to the corresponding section (the last column of the table is marked) and read it again, and you’ll basically understand it. This set of self-examinations also needs to be practiced for a while to form muscle memory - In the first half year of starting, I committed No. 3 (kitchen sink) almost every day. It was not until I watched a whole-day session destroying simple needs that I completely remembered “clear the screen as soon as the task is changed”.

💡 To sum up in one sentence: Take a section of “Operation Opposite” to find out the anti-patterns one by one and correct them one by one. It is a hundred times more effective than memorizing the definitions. If you practice it to the point of “ringing the alarm when your hands are itchy”, you will really take in this article.

10 Summary

This article starts from the back - the seven most frequent anti-patterns are laid out in a row, and each one is given “how to correct it”.

Putting the core together to review:

You should now be able to: Recognize at a glance whether you are stepping on an anti-pattern - dumping a bunch of requirements in one sentence, writing a novel on CLAUDE.md, opening a session from morning to night, treating it as a search engine and trusting it completely, not giving it a verification method, running around mindlessly on the work machine, and letting it “investigate” without scope; and for each one, you know how to change it back to the right path, and which article to go back to delve into the details. **Putting these seven “symptom identification cards” into your brain is equivalent to having a real-time quality inspector for your operation - wrong usage can be eliminated as soon as it appears. This will make you use Claude Code more smoothly than simply learning new functions. **

After all, the opposite of anti-patterns are the best practices in the previous article. By comparing the pros and cons, you will have a complete set of judgments about “how to use it/how not to use it” in your mind - the rest is to hone this set of judgments into capabilities in real projects.

Next article 51 “FAQ / Troubleshooting” - Anti-patterns are “pits at the usage level”, but there is another type of pit that has nothing to do with usage, which is the tool itself being angry**: unable to install, unable to log in, command stuck, ripgrep cannot find files, automatic compression jitters repeatedly… There is no use panicking about these “error reporting” problems, most of them have ready-made troubleshooting paths. The next article will give you a first-aid manual of “Symptoms → Countermeasures”, coupled with the universal first step - /doctor. Think about it: when Claude Code suddenly “cannot be opened” or “stuck”, which command should you type first?

51 · FAQ / Troubleshooting

Let me first talk about a very typical scene that is very easy to trap people into. If you understand it, you will understand what this article is going to solve.

Imagine this situation: I just got a new Mac, installed Claude Code from the company project, and This organization has been disabled pops up as soon as I start it. The first reaction is often “It’s over, has the account been blocked?”, and quickly log on to claude.ai to check the subscription - OK, Max is still there. I also suspected that it was the network, so I disconnected the magic and tried to go online again, but the same line of text was still there. After going back and forth like this for almost forty minutes, I reinstalled Claude Code twice and almost opened a work order.

What is the root cause? When the old Mac was migrated and configured, there was a line in ~/.zshrc that had long been forgotten: export ANTHROPIC_API_KEY=...**. It was an old key left behind by a company project that had been canceled half a year ago. Environment variables have priority over subscription login. Claude Code honestly used the invalid key to authenticate, but he was told “This organization has been disabled”. One line unset ANTHROPIC_API_KEY, seconds.

I use this example to let you remember one thing: **The most taboo thing in troubleshooting is “relying on guessing”. ** Those forty minutes were all spent on guessing—guessing account numbers, guessing networks, and the more you guessed, the farther away you were from the truth. In fact, Claude Code carries a physical examination tool with him. Just one sentence of /status can tell you “which set of certificates are currently used”, so there is no need to guess. This article will teach you to push the problem into the corner without relying on guessing and following the process.

After reading this article, you will get:

• A general routing table of “Symptoms → Where to check”: When reporting an error, check the number first, don’t try randomly
• The two self-service commands that should be typed first - /doctor physical examination, /feedback reporting - when to use them respectively
• “Problem → Solution” comparison organized by six categories (installation, login authentication, permissions, MCP, performance, error message)
• How to use the --debug series of debugging switches, and the “clean configuration comparison method” as a troubleshooting killer
• A practical example that can be followed and gives the expected output: use /doctor to do a physical check on your own installation

01 The first principle of troubleshooting: first locate “what type of problem is this”, don’t try blindly

Let me give the conclusion first. This principle is more important than all the specific commands that follow: **When encountering a problem, the first step is not to fix it, but to first figure out “which category it belongs to” - whether it is an installation problem, a login problem, a configuration problem, or a problem at the API end. ** The category is wrong, and all the rest is in vain.

**Analogy: If a water pipe leaks, close the valve first, don’t pry the floor tiles first. ** If there is water seepage somewhere in the house, the old master will not come up and smash the wall - he will first determine whether “it is from the faucet, the joint, or it is leaking from upstairs.” My judgment was wrong, and I couldn’t find any leaks even if I pried the floor tiles all over the floor. The principle of troubleshooting Claude Code is: first triage, then start. **

Why is this the most important? Because the official documentation of Claude Code is itself broken down by category - the installation and login page, the runtime error page, the configuration and debugging page, and the performance page. If you don’t even know “which category I belong to”, you won’t know which page to turn when turning the document. The official troubleshooting page directly dumps a routing table at the beginning. I translated it into the way you are most likely to run into it:

**The usage is very simple: find the sentence in the left column that is most similar to the sentence on your screen, and the right column tells you which direction to search. ** Each section after this article breaks down each category of this table and explains it in detail.

Here is an official quote worth remembering in your mind: “If you are not sure which one applies, run /doctor within Claude Code to automatically check your installation, settings, MCP server and context usage. If claude does not start at all, please run claude doctor from your shell.”

In other words - Can’t distinguish the category? Don’t worry, run /doctor first, it will point out most of the directions for you. The next section will focus on these two self-service commands.

💡 To summarize in one sentence: The first step in troubleshooting is always to triage first and not try blindly - look at the symptom routing table to identify “which category it is”, and then go to the corresponding chapter; if you really can’t tell, start with /doctor.

02 Two self-service commands: /doctor physical examination, /feedback reporting

Before you turn to any document or ask anyone, Claude Code comes with two “self-service” entrances. **Ninety percent of the problems will either be pointed out to you directly by /doctor, or reported using /feedback if they really cannot be solved. ** Get familiar with these two first, it will save you a lot of time.

**Analogy: If you feel uncomfortable, go for a general physical examination first. ** If you feel pain, you won’t do an operation as soon as you get it. You’ll do a physical examination first - blood pressure, heart rate, and other indicators. The doctor will know roughly where the problem lies at a glance at the report. /doctor is Claude Code’s health checker: **With one command, you can check whether the installation is healthy, whether the configuration has syntax errors, whether the MCP is connected, and how much context is occupied, all at once. **

/doctor: one-click physical examination

/doctor is the command you should type first when troubleshooting. The things it checks are officially listed clearly - Installation health, setting validity (whether there are invalid keys, schema errors), MCP configuration, context usage.

The key depends on whether you can start:

• Can enter the session: Type /doctor directly in Claude.
• claude cannot start at all (for example, command not found, crashes as soon as it starts): Type claude doctor in your terminal (shell) - note that this does not have a slash and is an independent command line subcommand.

/doctor also has a thoughtful design: **When it reports a problem, press f to send the diagnostic report directly to Claude, who will help you solve it step by step. ** After the physical examination, the doctor will read the report to you next to you.

/feedback: If you really can’t figure it out, please report it.

If you search the document, /doctor is also running, and the problem is still there - Don’t fight it yourself, use /feedback to report it to Anthropic. It will send your conversation record together with the description, which is the fastest way to officially diagnose real problems (especially metaphysical problems without error reports such as “response quality inexplicably deteriorates”). This command also provides an option: Help you open a GitHub issue with pre-filled content. Note: If you are using a third-party provider such as Bedrock or Vertex, /feedback will not send the information to Anthropic, but will save it to a local archive, which requires you to manually send it to Anthropic’s account representative.

You may have heard the term /bug elsewhere - it’s the old way of saying “reporting a problem”. Now the official use is /feedback: send records and descriptions to Anthropic in the session, or open a pre-filled GitHub issue. Remember /feedback This one is enough.

Here is a comparison table of “what to type first” for you:

The last one status.claude.com is particularly worth remembering: When encountering a bunch of server errors such as 5xx and 529, the first thing to do is to go to the status page and take a look, rather than doubting yourself - many times it is the Anthropic end that is shaking, and it has nothing to do with your configuration. This will be discussed in detail in Section 06.

💡 In one sentence: before troubleshooting, run two self-service commands - **/doctor (or terminal claude doctor) to do a physical examination and provide directions, /feedback to report when in doubt; if the server is suspected to be down, check status.claude.com first.

03 Login authentication type: repeatedly asked to log in, organization disabled

From this section onwards, we go over specific questions by category. Let’s talk about Login Authentication first - this type is the easiest for novices to panic, because the error words are more scary than the last (disabled, Forbidden, revoked), but the truth is often very simple**.

**Analogy: When you enter a company and swipe your access card, if it fails to open, it may not mean that you have been fired. ** It may be that the card has been degaussed, it may be that you got the wrong old ID card, or it may be that the time of the access control system is not correct. An error message saying “Entry Denied” does not mean “You are not qualified.” The same goes for the certification issue - first look at “Which set of certificates does Claude Code use for certification?” Don’t think of the worst as soon as you get started. **

The first step: See clearly “which set of certificates are currently used”

This is the universal first step for authentication issues, and also the antidote to the forty-minute detour at the beginning. Type in the session:

/status

Expectation: It will show the currently active authentication method - whether it’s your subscription (OAuth login), or an API key. **If you are clearly a subscriber, but it is shown that you are using the API key, the problem is basically locked. **

The most classic pitfall: ANTHROPIC_API_KEY secretly overrides subscriptions

This is what I stumbled upon in the beginning. The official explained the mechanism clearly:

Environment variables take precedence over /login, so keys exported in your shell profile or loaded from .env files will be used even if you have a valid Pro or Max subscription. In non-interactive mode (-p), the key is always used when present.

So as long as there is an ANTHROPIC_API_KEY in your environment (even if it was left by a project a few months ago and you have long forgotten it), Claude Code will use it for authentication. Once this key becomes invalid or belongs to a disabled organization, This organization has been disabled will be reported. Antidote:

unset ANTHROPIC_API_KEY
claude

But unset is only effective for the current terminal window. To completely cure it, you have to delete the line export ANTHROPIC_API_KEY=... in ~/.zshrc, ~/.bashrc or ~/.profile (check the PowerShell configuration file $PROFILE and user environment variables on Windows). After deleting, restart claude, and then check /status to confirm that the subscription has been switched back. This set of “Certificate Priority” Chapter 04 (API Configuration) mentioned that when there is an authentication problem, remember to go back and take a look.

Several other common certification errors, take the right medicine

It is really easy to ignore the “Check the system clock after repeated login” - a virtual machine that has not been connected to the Internet for a long time will often fail to log in. In the end, it is often found that the machine time is three days behind, and the token is expired as soon as it is issued. Check the time, seconds are good.

💡 To summarize in one sentence: For authentication issues, first check /status to see “which set of credentials are being used”; the most annoying thing is that the remaining ANTHROPIC_API_KEY in the shell overwhelms the subscription (unset + delete the configuration file); after repeated login failures, check the system clock and macOS Keychain first.

04 Configuration class: Settings/hooks/MCP “Writing does not take effect”

The second category is configuration not taking effect - you clearly wrote rules, configured hooks, and added MCP server in settings.json, but Claude didn’t seem to see it. There is an official page for this kind of problem called “Debugging your configuration”. The core is one sentence: **First confirm “what is actually loaded” in Claude Code. Don’t assume that what you write will take effect. **

**Analogy: Submitting an assignment does not mean that the teacher received it. ** You put your homework on the podium and left. If it didn’t take effect, it might have been put on the wrong desk, stuck in someone else’s notebook, or covered by another copy. There is a reason for configuration - if the ** does not take effect, first check “which copy it actually read” instead of repeatedly changing the one you think is correct. **

A set of commands to “check what is actually loaded”

This is the core toolbox of the configuration class. Each command checks one type of thing and can be used accordingly:

The usage is “Whatever I configured does not take effect, just type the corresponding command to see if it is there”. For example, if you write a hook but it is not triggered, first check /hooks to see if it has been registered - if it does not appear, it means that it has not been read at all; if it appears but does not trigger, it is a problem with the matcher**.

Several common configuration pitfalls for novices

In the official “Symptoms → Causes → Repairs” table, I picked out the most common ones for noobs:

The “Hook’s matcher case” is the easiest to ignore: the first time I write the PostToolUse hook, the matcher is filled in with "edit|write", and it doesn’t run no matter how I change the file. /hooks clearly shows that it is registered, and after looking at the configuration for a long time, I couldn’t find anything wrong - and finally I realized that the tool name must be capitalized as "Edit|Write". Official original text: “The matching is case-sensitive.” If you don’t know this kind of pitfall, you can’t find it alive or dead. If you know it, you can solve it in a second.

Permission related: “Obviously there are rules, but why can’t I be stopped / Come and ask me.”

Permission issues also fall into the category of configuration. Novices often encounter two types:

One is “The ban I wrote into CLAUDE.md did not stop it.” ** Key understanding: ** “Never edit .env” in CLAUDE.md is a “request”, not a “guarantee”. The official made this very clear - if you want Claude to “make a decision” use CLAUDE.md, and if you want a hard constraint of “enforcing it no matter what it decides,” you have to use permission rules or hooks (see articles 20 and 21 for details). So if you really want to block an operation, don’t count on CLAUDE.md, write deny permission rules or PreToolUse hook**.

**The other one is more hidden: the deny rule is written, but it cannot stop the equivalent command. ** For example, if you write Bash(rm *) and want to disable deletion, Claude can still delete it using /bin/rm or find . -delete. The reason is - The prefix rule matches the “literal command string”, not the underlying executable file. The solution is to add explicit rules for each variant, or simply use the PreToolUse hook / sandbox to get “hard guarantees”. When troubleshooting permissions, first type /permissions to see the actual allow/deny rules currently in effect to see if they are what you think they are.

Behind this is the same principle discussed in the 50th anti-pattern: Entrusting the “safety boundary” to a natural language instruction is itself an anti-pattern - instructions are soft, rules and hooks are hard.

💡 To summarize in one sentence: the configuration does not take effect, first use the /context, /memory, /hooks, /mcp, /permissions group of commands to check “what is actually loaded”; high-frequency pitfalls are hook matcher capitalization is wrong, and the configuration is overwritten by the higher priority settings.local.json, .mcp.json Misplacing the directory, and mistakenly writing the “security ban” into CLAUDE.md instead of the deny rule.

05 Performance category: lag, high memory, file not found in search

The third category is uncomfortable running - the response is getting slower and slower, the memory is horribly consumed, and @file cannot be completed. This type of problem is officially classified under “Performance and Stability”. Most of them are related to “context overflow” and “small environmental problems”, and are rarely bugs. **

**Analogy: The more you use your computer, the more stuck it gets. It’s probably because there are too many background processes running, not because the hardware is broken. ** You won’t send it for repair as soon as the card is stuck. First, close a few memory-consuming programs and clear the cache. There is a reason why Claude Code is stuck - first clean up the “workbench”, don’t rush to reinstall it. **

Stuttering/high memory: clean up the context first

The official processing sequence is very pragmatic:

1. Regularly use /compact to compress context (organize conversations into one page of bullet points, see Part 19 for details).
2. Turn off and restart Claude Code between major tasks.
3. Add large build directories to .gitignore and don’t let it scan.

If the memory is still high after doing this, you can run /heapdump - it will write a JavaScript heap snapshot to ~/Desktop (write the home directory if there is no desktop on Linux), and attach it to the GitHub issue when reporting memory problems. You don’t need this command every day, just know that there is such a thing.

About “Stuck, spinning in circles”: The official said it simply - press Ctrl+C first to try to cancel the current operation; if there is no response at all, close the terminal and restart it. Restarting will not lose the conversation. Run claude --resume in the same directory to continue the last session.

Automatic compression “jitter”: an error that will scare a newbie

You may have come across this line: Autocompact is thrashing: the context refilled to the limit.... Don’t panic - it means that the automatic compression was successful, but there was a very large file or tool output that immediately filled up the context. In order not to burn API calls, Claude Code took the initiative to stop and retry. Recovery method: let it read the very large file in chunks (specify a line range or a certain function, do not read the entire file), or specify “only keep the plan and diff” when /compact, and if that doesn’t work, restart /clear.

Search / @file completion failure: change ripgrep

If the search tool, @file mention, or custom skill cannot find the file, most likely the ripgrep (a high-speed search tool) that comes with Claude Code cannot run on your system. The official solution is to install the system version of ripgrep and let Claude Code use it instead:

# macOS
brew install ripgrep

Then set USE_BUILTIN_RIPGREP=0 in the environment variable (see Chapter 42 for details on how to configure environment variables).

Here is a quick check on performance-related “Symptoms → What to do first”:

The last “garbled code” is occasionally encountered in the built-in terminal of VS Code. The characters on the entire screen are turned into tofu chunks, which is quite confusing. Run /terminal-setup to turn off the terminal’s GPU acceleration, and the reload window will be refreshed - Pure rendering issue, nothing to do with Claude itself.

💡 To summarize in one sentence: For performance problems, first suspect “context is too full” - /compact + restart is a panacea; if stuck, press Ctrl+C / claude --resume; if the search fails, change the system ripgrep; when the terminal runs garbled code /terminal-setup.

06 API Error Type: There are red letters, first distinguish “whether it is your fault”

The fourth category is that a line API Error: ...** pops up directly in the session. Novices panic when they see red letters. In fact, the most important thing to do is to first distinguish whether the error is a “thing on the server’s end” or a “thing on your end” - the two methods of handling are completely opposite.

**Analogy: If the webpage cannot be opened, first determine whether the website is down or you are disconnected from the Internet. ** If the website is down, it will be useless to refresh it a hundred times. Wait for it to be repaired; when you are disconnected, you should check your router. There is a logic in API error reporting - first determine who is at fault, and then decide whether to “wait” or “change”. **

Remember first: Claude Code has already automatically retried for you.

There is an official mechanism worth knowing first: Server error, overload, timeout, temporary current limit, disconnection, Claude Code will automatically retry up to 10 times with exponential backoff. When retrying, you will see a countdown of Retrying in Ns · attempt x/y displayed next to the circle. So - When you really see a line reporting an error, it means that all these retries have been used, not that it just gives up.

Three major categories of error reports, three responses

I have divided the official long error report form into three piles that you should distinguish most:

The processing logic of these three piles is very different: The first pile “wait and it’s over”, the second pile “pay money or wait for reset”, and the third pile “streamline your input”. If you can’t tell the difference, it’s easy to do the opposite—the server is shaking but you delete your conversations, or the quota is full but you think it’s a bug and keep trying again.

There is also a type of unable to connect to API (Unable to connect to API, fetch failed, Request timed out with the words “check network”) - this is usually not Anthropic’s problem, but your network, VPN, proxy or firewall. The first step is to verify whether you can touch the API host in the same terminal:

curl -I https://api.anthropic.com

If it passes, it means there is no problem with the network, but the problem lies in the upper layer (such as proxy/certificate); if Could not resolve host or timeout means the network is blocked. Domestic users will most likely need to enable magic to access the Internet; behind the corporate network, they will most likely need HTTPS_PROXY. If the slow network always times out, you can increase the single request timeout - the official provides two knobs (for details on environment variable configuration, see Chapter 42):

Two novices frequently report errors that are easily misunderstood.

model not found / you may not have access to it: The configured model name is not recognized, or your account does not have permission. First type /model in the interactive CLI to reselect from the available models. If the wrong model keeps popping up, it means that an outdated model ID is set somewhere - Check according to priority: --model flag → ANTHROPIC_MODEL environment variable → settings.local.json → model field in settings.json at all levels. Delete the outdated value and return it to the account default. The official also has a practical suggestion: Use aliases (such as sonnet, opus) instead of hard-coded version IDs. The aliases will automatically follow the latest version and will not be outdated (For configuration methods such as /model, ANTHROPIC_MODEL, please see Chapter 04 API Configuration).

Claude Code is unable to respond to this request, which appears to violate our Usage Policy: blocked by the usage policy check. Note a counter-intuitive point - this check evaluates the entire conversation, not just your last sentence, so sending another sentence in the same conversation will often trigger the same rejection. The correct approach is to press Esc twice or /rewind to go back to before the round that was triggered (see Part 37 for details), and change the expression or idea; if you really can’t find which round it is, use /clear to restart a conversation.

💡 To summarize in one sentence: API errors are divided into three piles - 5xx/529 is the fault of the server (wait + check the status page + change the model), hit your limit is the quota (waiting for reset or additional purchase), too long/too large is because your input is too large (/compact / chunked reading); Unable to connect is the network at your end (curl Verify the host, open Magic Internet/configure proxy if necessary); when reporting errors in the model, use aliases and check IDs first.

07 The trump card: --debug debug log + clean configuration comparison method

The first six categories cover 90% of situations. But there are always one or two times when the patient’s symptoms are strange and the patient cannot be located by searching the documents. At this time, using two advanced weapons can basically force out the most difficult problems.

**Analogy: Check circuit faults, multimeter + unplug and plug one by one. ** When a circuit repairman encounters an inexplicable fault, he first uses a multimeter to measure which voltage is wrong in real time (see the real-time log), and secondly, unplugs the electrical appliances one by one and tries to see which fault disappears (removes one by one). Check out Claude Code’s two killer tricks, which are replicas of these two tricks.

Weapon 1: --debug to see what it is doing in real time

When you can’t guess the cause just by looking at the results, start it with --debug and let it type out the internal process for you to see**. You can also add sub-marks for different questions. The accuracy only depends on the part you care about:

There is also an entry within the session /debug [problem description]: It turns on the debug log for this session and directly prompts Claude to use the log and setting path to help you diagnose.

Usage example: Your hook is clearly registered in /hooks but does not run. At this time, claude --debug hooks is started, triggering a tool call, and the log will clearly tell you “This event has come, which matcher was checked, and whether it was matched or not.” A hundred times better than just staring at the configuration.

Weapon 2: Clean configuration comparison method (the most underestimated move)

This trick is particularly worth remembering, as it specializes in solving the unsolved problem of “whether it was your own configuration that caused the trouble.” The idea is: open a clean session that loads nothing, and compare it with your usual one - if the problem disappears in the clean session, then there is something wrong somewhere in your own configuration. Official order:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

This sentence points CLAUDE_CONFIG_DIR to an empty directory, **bypassing everything under ~/.claude; and then starting from a directory (/tmp) without .claude folder, no .mcp.json, and no CLAUDE.md, even the project configuration is skipped. So this session does not have any user/project settings, hooks, MCP, plugins, memory.

• The problem disappeared in a clean session → The root cause is in your real ~/.claude or project .claude. Next, add only one thing at a time (copy a file into it, or start it from your project), and see which one you add back to reproduce the problem, and it will be the murderer.
• Still having problems in clean sessions → The root cause is outside of your user and project configuration (could be hosting settings, environment variables, or a lower-level installation issue).

This “dichotomy” is the general wisdom of troubleshooting - Narrow the scope by “cutting half of the variables to see if there is a problem”. For example, if Claude somehow fails to read a certain CLAUDE.md rule, he can confirm through a clean session that “it’s not a bug in Claude Code, but a fight between two CLAUDE.md instructions in the project”, which saves him a whole night of digging through documents.

💡 To summarize in one sentence: There are two killers for strange problems - claude --debug [mcp/hooks] to see the internal process in real time to locate “why it is not working”, clean configuration comparison method (CLAUDE_CONFIG_DIR points to an empty directory) to determine “whether it is my configuration that caused the problem”, and then add back one by one to lock in the killer.

08 Get started: Give your installation a complete physical exam

You can’t remember it just by watching it. Let me take you through the physical examination of /doctor yourself and verify your certification status. The whole process does not rely on any complex environment, just install Claude Code.

Step one: Confirm in the terminal that claude is installed correctly and the version is new

claude --version

Expected: Print a line of version number, similar to 2.1.xxx (Claude Code). **See version number = install basic health. ** If command not found: claude is reported, it means that the installation directory is not in PATH - this is an installation problem. Go back to Chapter 02 to fix the PATH according to your platform (macOS/Linux is installed in ~/.local/bin).

Step 2: Enter the session and run a physical examination

claude

After entering, type:

/doctor

Expected: A diagnostic panel will pop up, listing the installation health status, whether the setting file is valid (invalid key/schema errors will be marked in red), MCP server configuration, and context usage**. No errors reported for each item = your configuration is clean. ** If an item is marked as a problem, ** press f to send the report to Claude and let him explain it to you step by step.

Step 3: Confirm “which set of certificates are currently used”

Then type:

/status

Expected: Displays the currently active authentication method. **If you are a subscriber, the subscription (OAuth) should be displayed here instead of an API key. ** In case the API key is displayed, which is different from your expectation - congratulations on catching the pit at the beginning, go to unset ANTHROPIC_API_KEY in the shell configuration file and delete the export line.

Step 4 (optional): Experience a clean configuration comparison

To experience the trick in Section 07, open a clean session with nothing loaded:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Expectation: After startup, this session** does not have any of your usual CLAUDE.md, custom commands, or MCP server** (you will find it empty when you type /memory and /mcp in it). This will be your baseline for comparison in the future when troubleshooting “Is it my configuration that is to blame?” Note: On Linux/Windows it will ask you to log in again (the credentials are stored in the configuration directory), on macOS the credentials will be brought over automatically because they are in the Keychain. Just exit normally after playing. This temporary directory will not affect your real ~/.claude.

After passing these four steps, you will have gone through the main troubleshooting road of “Physical examination → Look at the voucher → Check the clean session”. **If something goes wrong in the future, it is much better to follow this order than to panic and try blindly. **

💡 In one sentence: go through the physical examination chain claude --version → /doctor → /status → clean session; remember “/doctor points to the direction, /status looks at the certificate”, 90% of novice problems will be revealed in this step.

09 Summary

This article has built a troubleshooting framework for you that “does not rely on guessing and follows the process” - from “which category to triage first” to “which order to type”, to two killer tips for the most tricky problems.

Putting the core together to review:

You should now be able to: Encounter any problems with Claude Code and no longer panic about error reports - First use the symptom routing table to identify which category it is, type /doctor to check the direction, /status to see the credentials; prescribe the right medicine according to the category (installation/authentication/configuration/performance/error reporting); if you are really tricky, use --debug Read the logs and use the clean configuration comparison method to isolate the root cause; if you are unsure, report it via /feedback. **As this process develops into muscle memory, you will upgrade from “being confused as soon as an error is reported” to “knowing where to look when an error is reported.” **

At this point, you have gone through the entire set of practical operations, from “installing” to “operating smoothly” to “how to solve problems when problems arise.” **The rest is to thoroughly sort out the terminology that comes up along the way. **

Next article 52 “Glossary (friendly for beginners)” - Reading this way, CLAUDE.md, context window, MCP, Subagent, Hook, checkpoint, auto-compact… dozens of nouns are flying back and forth in your mind. The next article will give you a novice-friendly glossary: each word is spoken in human language in one sentence, paired with the most appropriate analogy, and divided into categories according to themes. You can read it at any time, and you will understand it after looking it up. Think about it: if someone suddenly asks you “What is the relationship between token and context window”, can you explain it in one sentence now?

52 · Glossary (friendly for beginners): Translate the “black words” along the way into adult language at once

It is said that “you should read the glossary from beginning to end to lay the foundation.” To be honest, this is the most useless reading method.

Learning any new tool and memorizing the terminology from A to Z using the glossary as a text is almost in vain - after memorizing it, you turn around and forget it, because none of those words “happened” in your hands at that time. Terminology is something that you will really remember only when you bump into it and trip over it.

So I don’t intend to ask you to “read” this article, but to “check” it. **It is a cheat sheet, not a text. ** You normally study and use it later, but one day you get stuck when you see “What is this transport?” “What is auto-compact?” Turn back to this page, find that item, read it with an analogy in one sentence, and continue working - this is the correct usage of the glossary.

**Analogy: The list of materials posted on the wall at the renovation site. ** No one on the construction site will stand there and memorize the list from beginning to end, but when each pipe and each plate arrives, the master will take a look at the list - “Oh, this is a load-bearing beam, and that is a water pipe joint”, and then go on with the number. The same goes for this table: Not for full reading, just for “finding it if you encounter it”. Below, I group the terms into several families according to “theme” (concepts in the same family are related to each other, and it is easier to remember them together than in alphabetical order). Each item is a three-piece set of “term → sentence → analogy”.

**After reading it (or turning it over for later use) you can get: **

• The core terms that appear in the entire tutorial are explained clearly in vernacular and with analogies.
• Classify according to “theme families”, put concepts of the same family together, and clarify the relationship between them.
• The main items are marked with the number “See Chapter NN for details”. If you want to dig deeper, just skip over.
• A comparison of the “pairs of terms that are most easily confused”, so you can tell them apart at a glance when you get into a car crash.
• A hands-on exercise: use the official documentation server to check the authoritative definition of any term in Claude at any time

01 Agency cycle family: How did Claude’s “work” matter turn around?

This family is the foundation that ** should understand first. It answers a fundamental question: What is the difference between Claude Code and a web chat AI, and why can it “do it by itself”. Almost all the other terms are hung on this set of cycles.

**Analogy: An assembly line that spins by itself. ** Ordinary chat AI is “you ask a question and it answers a question”, like an ordering window; Claude Code is an assembly line that can turn by itself - after getting the job, it picks up the materials, processes by itself, and performs quality inspection by itself. After completing one turn, you can see if you need to turn it around again. The following words refer to the different parts of this assembly line.

Agentic loop

One sentence: The circle that Claude circles repeatedly when dealing with each task - collect context → take action → verify the results → if it is not enough, go around again until it is completed.

**Analogy: The rhythm of a chef’s spoon. ** It’s not just pouring all the ingredients into the pot at once, but “adding ingredients → stir-frying → taste the saltiness → adjust if it’s not enough”, approaching the dish one rhythm at a time. Each “taste” (the result returned by the tool) tells it where to go next. You can stop and change direction at any time. (See Chapter 03 for details)

Agentic coding (agent programming)

One sentence: A way of working - AI can read files, run commands, and change codes on its own. You watch from the side, correct deviations at any time, or simply walk away, instead of it giving you a piece of text to type by yourself.

**Analogy: Hire a master who can get started, not a manual. ** The instruction manual can only tell you “how to do it”, the master does it directly for you. Claude Code is a hands-on type, relying on the tools it has. (See Chapter 01 for details)

Agentic harness

In one sentence: A complete set of peripherals that “arms” a language model into a working programming agent - file access, shell execution, permission control, memory loading, and loops that string actions together. Claude Code is the shell and Claude is the model inside.

**Analogy: car body and engine. ** The same engine (model) is installed in different car casings, and the driving experience is completely different. The harness is the shell of the Claude Code, which determines what the model can touch and what rules it follows. (See Chapter 03 for details)

Tool

In one sentence: The actions that Claude can actually perform - read files, change codes, run shell commands, search web pages, and dispatch subagents; Without tools, it can only reply with words.

**Analogy: Those equipment on the assembly line station. ** Just having a smart brain is useless. You need a robotic arm, a conveyor belt, and a detector to really do the job. The tool is Claude’s “hand”, which returns a result every time it is used, feeding it to the agent’s next decision in the loop. (See Chapter 03 for details)

Turn

One sentence: From the time you send a message to the time Claude completes the response, it counts as a complete round; it may call any number of tools in the middle.

**Analogy: You place an order and the kitchen produces a dish. ** You say that the request is “ordering”, and Claude cuts the vegetables, stir-fries, and puts them on the plate (and adjusts a bunch of tools). You don’t have to worry about it. At the end, the whole set is served and it counts as “one dish.” A session is made up of many rounds. (See Chapter 03 for details)

Verification loop

One sentence: Let Claude know the mechanism of “the work is really done, not just what it looks like” - you give it a runnable check (testing, building, screenshot comparison), and it will repeatedly change it until the check passes.

Analogy: Check the answers yourself before handing in the assignment. ** When there is no standard answer, “writing it” depends entirely on feeling; give it an answer that it can self-check, and it will correct it until it is correct, instead of writing it once and handing it in. When running a long mission unattended, this one is the lifeline - without it, the only one who can judge whether it has been completed is itself. (See Chapter 49 for details)

Extended thinking

One sentence: The visible step-by-step reasoning before the model’s formal answer is displayed in gray italics in the terminal; you can use MAX_THINKING_TOKENS or adjust the effort level to control how much it thinks.

**Analogy: Calculate on scratch paper before solving the problem. ** Instead of answering directly, write down the derivation process first - you can see “how it thinks”, and you can easily identify which step is wrong if it is wrong. (See Chapter 35 for details)

Effort level

One sentence: A setting that controls how much “thinking budget” Claude spends each turn - the higher the level, the deeper the thinking, the slower and more expensive, the lower the level, the faster and more economical.

**Analogy: How much time is allocated to a question on an exam. ** Fill out the multiple-choice questions at a glance (low effort), and spend an extra ten minutes thinking about the final questions (high effort). For simple tasks, lower the price to save money, but for hard work, adjust the price higher for quality. (See Chapter 35 for details)

💡 In one sentence summary: This group talks about the operating mechanism of Claude’s “do-it-yourself” thing - the core is the agency cycle of “think → do → see”, the tool is its hand, the harness is the car shell that arms the model, extended thinking is its calculation draft, the effort level is the time budget allocated for thinking, and the verification cycle is its quality inspector**.

02 Context Family: How big is Claude’s “memory” and “desktop”

Learn the first clan and you’ll immediately hit the second clan - Claude doesn’t have an infinite memory. All the words in this family revolve around “how much can it remember at one time, what to do when the memory is full, and how to clear it when the task is changed.” For those who are stuck on “Why did it forget what I said before?”, here are all the answers.

**Analogy: A workbench that is only that big. ** When you lie down on the table to draw, the tabletop is just that big; there are more and more drawings, reference books, and drafts spread out, and sooner or later you can no longer spread them out and have to put them away. Claude’s “memory” is this table. The following words are all about “how big is the table and what to do if it is full.”

Context window (Context window)

In one sentence: The “working memory” of a session - contains the conversation history, file content, command output, CLAUDE.md, loaded skills, system commands, is as big as this, until it is full.

**Analogy: The surface area of a workbench. ** The larger the table, the more materials can be spread out at the same time; when the spread is full, the old items must be removed first before new items are put on it. Run /context and you can see what is currently on the table and who takes up space. (See Chapter 19 for details)

Token

In a sentence: The smallest unit of measurement for text processing by the model is roughly “half to a Chinese character or part of an English word”; the size of the context window and billing are all calculated based on tokens.

**Analogy: The “valued word count” of text. ** Express delivery is calculated based on weight, while models are calculated based on tokens - how much you feed in and how much it spits out are all converted into tokens and included in the occupation and bill of that workbench. (The underlying details of token belong to the model layer concept and will not be expanded on in this tutorial. It is enough for this purpose)

Compaction

One sentence: When the context is almost full, automatically “summarize the conversation into a condensed version” to make room - first clear the old tool output, and then summarize the conversation; run /compact to trigger it manually.

**Analogy: Organize the scrap paper spread out on the table into a page of key points. ** If there are too many drafts to fit on the table, you copy the key conclusions onto a piece of paper and put away the rest - the backbone of the information is still there, but the space is smaller. Note: CLAUDE.md and auto memory in the project root directory will be retained and re-read from the disk during compression. Words only said temporarily in chat may be compressed. (See Chapter 19 for details)

Auto-compact (automatic compression)

One sentence: You don’t need to shout, the compression is automatically triggered by the system when the context is close to the upper limit.

**Analogy: automatic unloading on the assembly line. ** When the hopper is almost full, the conveyor belt starts automatically and removes the excess without you having to press a button. It does the same thing as manual /compact, the only difference is “who presses the start button”. (See Chapter 19 for details)

Session

One sentence: A conversation bound to your current directory, has its own independent context window; /clear opens a new session, and the old one can be retrieved with /resume.

**Analogy: For a completely new task, simply clean up the countertop and start working again. ** Leaving the draft of the previous work on the table will only get in the way. Clearing the table (starting a new session) and starting from scratch will refresh your mind. The records of each session are stored under ~/.claude/projects/, so even if you close the terminal, you can still use claude -c to continue the last chat. (See Chapter 19 for details)

CLAUDE.md

In a word: The permanent instructions you wrote to Claude are automatically loaded as soon as each session is opened, and contain rules such as “project conventions, build commands, and always do X” that are always in effect.

**Analogy: Onboarding manual for new employees. ** The person who comes here every day may be a “newcomer with amnesia”, but as long as the manual is nailed there and he reads it before starting work, he will know the rules here. It is recommended to keep it within 200 lines. If it is too long, move the reference material into a skill. (See Chapter 18 for details)

Auto memory

One sentence: The notes Claude wrote to himself based on your corrections and preferences are stored in the git repository under ~/.claude/projects/, and the beginning of the index is loaded at the beginning of the session.

**Analogy: It’s still the two pieces of paper next to the monitor, but this one is written on its own. ** CLAUDE.md is the rule you nailed down, and auto memory is the cheat sheet it memorizes - “He corrected me last time not to use npm”. It writes it down and doesn’t do it again next time. One is written by you and the other is written by it. They are a pair. (See Chapter 25 for details)

Rules (rules file)

One sentence: The modular directive file placed in .claude/rules/ and loaded together with CLAUDE.md can be limited to “only loaded when Claude reads the matching file” with paths: to keep the context streamlined.

**Analogy: Construction specifications are divided into separate volumes according to the type of work. Please refer to whichever book you use. ** CLAUDE.md is the general rules that everyone reads first; rules is the “Electrical Code” and “Plumbing Code” sub-volumes, and is only pulled out when the corresponding work is encountered - irrelevant ones do not occupy the desktop. (See Chapter 13 for details)

Output style

One sentence: A configuration that rewrites Claude’s system prompts to adjust the behavior, tone, and format of its response; there are built-in Default, Proactive, Explanatory, and Learning.

**Analogy: The same host, changing the style of a program. ** It’s still the same person, but the tone and rhythm of “news broadcast” and “talk show” are completely different. The output style adjusts this “program file”, which is different from CLAUDE.md (the rules passed in as user messages). (See Chapter 32 for details)

💡 One sentence summary: This group is all about “memory and speaking style” - The context window is the workbench surface, token is the unit of account, compression is the finishing action when the table is full, session is an independent start, CLAUDE.md / auto memory / rules are several types of memos nailed to the table, and output style is to change the speaking style.

03 Expansion point family: those items that “equip” Claude

This family is the focus of the entire set of tutorials - How to transform Claude from “working out of the box” to “fitting your work”. The 30th article specifically talks about how to choose these items. Here we only do a quick check of “one sentence and analogy”. What they have in common: they are all hooks inserted at different locations in the agent loop.

**Analogy: For the same worker, give him different equipment packages. ** It’s not enough to have people on duty - give him a work manual (CLAUDE.md), a few special recipes (skill), an external docking station (MCP), a few dispatched helpers (subagent), and a few automatic hooks (hook), and the work he can do will be completely different. Identify them one by one below.

Skill

One sentence: A SKILL.md file contains a piece of knowledge, routine or process; Claude will automatically call it in when relevant, and you can also call it /<name> actively.

**Analogy: Shortcut commands on mobile phones. ** “Go home mode”, turn off the lights, turn on the air conditioner, and play music and the sequence of actions will be completed automatically - you don’t have to repeat the process every time. Skill is Claude’s shortcut command: save repeated routines into one and call them up with one click when you need them. Usually it only takes up one line of description, and the complete content is loaded into the context only when it is used (officially this is called progressive disclosure). (See Chapter 26 for details)

Subagent (subagent)

One sentence: A special assistant with an independent context window, with its own system prompts and tool permissions. You assign tasks to it, and after it finishes it, it only returns the conclusion summary to the main dialogue.

**Analogy: Outsourcing a job to an errand boy. ** You asked him to look through thirty files to find a number. He looked through it in complete darkness outside, but you didn’t touch it at all. When he came back, he only said to you, “I found it, it’s this one.” The essence is context isolation - the intermediate process does not pollute your main desktop. There are three built-in options: Explore, Plan and General. (See Chapter 23 for details)

Hook

In one sentence: At a fixed moment in the Claude Code life cycle (before the tool is run, after the file is modified, at the beginning of the session…) automatically execute an action, which can be a shell command, a script, a notification, etc.

Analogy: automatic stuck point on the assembly line. ** Every time the conveyor belt passes through a work station, a stamp will be automatically stamped with a “click” - it does not rely on human supervision or AI self-awareness, and ** will be triggered as soon as an event occurs. This is the fundamental difference between it and CLAUDE.md: writing to CLAUDE.md is a “request”, and hooking is a “guarantee”. (See Chapter 33 for details)

Command / slash command (Command / slash command)

One sentence: A reusable command that you can call by typing /name in the prompt; the built-in (/clear, /model, /compact) control session, and the essence of customization is “a skill triggered by /<name>”.

**Analogy: fixed buttons on the remote control. ** /clear is like the “reset button”, and /deploy is like the “one-click release button” that you paste yourself - press it to run the fixed process. Now it is officially recommended to use skills to package multi-step commands. (See Chapter 36 for details)

Plugin

In one sentence: Package the skill, hook, subagent, and MCP server into an installable unit**, install it once, and a complete set of extension points will be in place.

**Analogy: A suitcase packed before going out. ** You don’t hold shirts, razors, and chargers in your arms one by one, put them all in a box, and carry them away. The plugin is this box - if you need to use the same set of equipment for another project, just install this plugin. The skill inside also has a namespace (such as /my-plugin:review), so multiple plugins can be installed separately without conflicting names. (See Chapter 24 for details)

Plugin marketplace (plug-in market)

One sentence: To distribute and obtain plugin sources, you can add one or more markets and select plugins to install from them.

**Analogy: Install an app store on your phone. ** There are a bunch of Apps (plugins) in the App Store, you choose what you need to install. Pay attention to the source - Double-clicking to run an .exe from an unfamiliar website is risky, as is installing plugins from unknown sources. (See Chapter 38 for details)

💡 To summarize in one sentence: This group is “adding equipment” - skill is a shortcut command, subagent is a dispatched helper, hook is an automatic stuck point, command is a remote control button, plugin is an equipment suitcase, and marketplace is an application store; they are all inserted at different positions in the agent cycle.

04 MCP Family: The interface that connects Claude to the “outside world”

Among the extension points, MCP is mentioned alone because it comes with a bunch of small terms (transport, server, scope…), and new script commands are most likely to overturn here. The entire article 22 is about it, and here we identify its “family members” one by one.

**Analogy: A docking station with a bunch of interfaces. ** There are only one or two ports left on the notebook body, and HDMI, network cables, and U disks cannot be plugged in. Connect a docking station and connect them all with one cable. MCP is this extension for Claude - one after another, a bunch of external service tools are placed in front of it.

MCP (Model Context Protocol, Model Context Protocol)

In one sentence: A set of open source standards that stipulate “how AI tools connect to external data and services”; MCP server connects Claude to hundreds of integrations such as Slack, Jira, databases, browsers, etc.

**Analogy: USB is a unified interface standard. ** In the early years, each device had a kind of plug, which was a mess; after USB came to dominate the world, all devices can be plugged into the same port. MCP is the “USB standard” for connecting AI to external tools - once connected, it can be used everywhere. (See Chapter 22 for details)

MCP server (MCP server)

In one sentence: A specific “connector” implemented according to the MCP standard, with a set of tools (such as GitHub server with “read PR” and “open issue”). After connecting, these tools will appear in front of Claude.

**Analogy: A specific device plugged into a docking station. ** The docking station is a standard (MCP), and the printer and hard disk plugged in are specific devices (servers) - each server connects you to an external capability. (See Chapter 22 for details)

Transport

In a word: “How to communicate” between Claude Code and MCP server; there are usually two methods - stdio (local process) and http (remote hosting), plus a deprecated sse.

**Analogy: Some of the devices on the docking station are on the table, and some are on the other side of the wall. ** stdio is a small program launched by Claude in the background of your local machine (at hand), http is a remote service connected to a certain website (on the other side of the wall). If you copy the command, it will probably end up here: stdio does not write transport, but http needs to write --transport http. (See Chapter 22 for details)

Scope

One sentence: An MCP server can be used in “which projects and whether it should be shared with the team” - local (only the current project, private), project (written into .mcp.json, shared with git), user (all your projects).

**Analogy: How to share a printer in the office. ** Only your computer (local), access to the department asset list can be used by the whole group (project), or you can carry it to each conference room (user) - three ways to put it, corresponding to three scopes. (See Chapter 22 for details)

MCP Tool Search (MCP Tool Search)

One sentence: A context-saving mechanism - only the name of the tool is loaded at startup, and Claude only pulls the complete description of a tool on demand when he really needs to use it.

**Analogy: Look at the menu title first, then click on the detailed instructions. ** There are hundreds of dishes on the menu, and you won’t read the detailed ingredients of each dish as soon as you come up - scan the title first, decide which dish to order, and then flip through its details. In this way, a bunch of idle MCP servers will not occupy the workbench in vain. (See Chapter 22 for details)

💡 To summarize in one sentence: MCP is the USB standard for “connecting to the outside world” - server is the specific connector, transport is the connection method (local stdio/remote http), and scope is which projects can be used with this connector; weigh your trust before connecting to a third-party server.

05 Security and Permissions Family: Claude “ask you or not” before taking action

Now that Claude can use his hands and connect to the outside, “Will it mess around?” has become an unavoidable question. What this group talks about is all about “the checkpoint mechanism before it takes action” - from “asking before doing it” to “forcibly blocking certain operations.” Chapters 20 and 21 explain it thoroughly, here is a quick check.

**Analogy: several layers of protection when driving on the road. ** Seat belts, airbags, speed limit signs - on the one hand, you should keep yourself from messing around, on the other hand, you should take care of the situation in case of an accident, and on the other hand, “this line is not allowed to be crossed”. Claude’s security mechanism is also layered. The following words refer to which layer.

Permission mode

One sentence: Claude’s hands-on “baseline attitude” in a session - there are six official levels, including asking you at every step (default), automatically accepting changes (acceptEdits), only researching without doing anything (plan), don’t ask and just do it (bypassPermissions), automatic review (auto), and passing silently (dontAsk); see article 35 for the complete description.

**Analogy: Whether the intern asks you before taking action is the level of autonomy you set for him. ** For the same intern, you can ask him to “ask everything first”, or you can delegate authority and “take care of such small things by yourself.” The mode is the level you set for it. Press Shift+Tab in the CLI to cycle through. (See Chapter 35 for details)

Plan mode

One sentence: A permission mode - Claude only reads, only searches, only researches, does not touch your source files, first lists the change plan for you to approve, and you nod before taking action.

**Analogy: I produce the drawings first when decorating, and show them to you before smashing the walls. ** It is not allowed to swing a hammer when it comes up. You must first draw the drawings of “demolition of this wall and modification of that pipe”. You confirm it before construction. It’s most stable when used before major changes. (See Chapter 35 for details)

Auto mode

One sentence: A permission mode - there is an independent classifier model in the background to review operations one by one, blocking unauthorized access, suspicious infrastructure and prompt injection, instead of pop-up windows asking you at every step; currently it is a research preview.

**Analogy: There is a security guard at the door who does not check the goods, but only checks the ID. ** It specifically focuses on “this operation does not cross the boundary”, and ** can never see the content returned by the tool **, so malicious instructions hidden in the tool results cannot affect its judgment. (See Chapter 35 for details)

Permission rule

One sentence: Use the “tool name plus parameter mode” to set the fine-grained settings of allow / ask / deny, and match in the order of deny→ask→allow. The first winner wins.

**Analogy: Specific release/interception rules in the access control system. ** “This card can enter the 3rd floor, but cannot enter the computer room” - the rules are thinner than the big baseline of “permission mode”, and are precise controls stacked on top of it. (See Chapter 20 for details)

Sandboxing

One sentence: Give the Bash tool set a layer of operating system-level file and network isolation - Claude can run freely within the boundaries you delineate, without requiring pop-up windows to approve every command.

**Analogy: Drag racing in a dedicated proving ground, the walls are physical. ** You can drive as fast as you want in the venue, because the surrounding walls are really blocking you from getting out. The sandbox is this wall, another layer of protection separate from permission rules. (See Chapter 21 for details)

Prompt injection

In a word: Malicious instructions hidden in files, web pages, or tool results, trying to make Claude do things you never asked for.

**Analogy: Received a scam call based on the words. ** The tone of the other party is normal, but the content is “You can transfer the money now as I say” - prompt injection is a kind of “talking technique” inserted into the data. Claude may be biased after reading it. MCP servers that capture external content are particularly risky. (See Chapter 21 for details)

Checkpoint

One sentence: In the “restore point” automatically created every time you send a prompt, Claude takes a snapshot before changing the file; press Esc twice (the input box must be empty) or /rewind to open the rewind menu, and you can choose to restore the code, dialogue, or both to an earlier prompt point. It is session local and separate from git.

**Analogy: Loading game save files. ** If you make a wrong step, load a file and return to the previous save point to start over. There is no need to play from the beginning. Note that it does not track changes made through Bash tools - those must be covered by git or other means. (See Chapter 37 for details)

💡 To summarize in one sentence: This family is “check before taking action” layered - Permission mode is the big baseline (ask you or not), permission rules are detailed rules, sandbox is the physical isolation wall, auto mode is the security for checking documents, checkpoint is archive reading; prompt injection is the kind of “word attack” that needs to be guarded against.

06 Entry and operation mode family: where do you use it and how does it run?

The last group is the most complex, but they all fall into the same category: Where are you and what posture do you use to deal with Claude Code. Terminal, VS Code, web pages, or inserted into scripts to run automatically - different forms, but the same engine underneath.

**Analogy: There are several ways for the same worker to arrive at work. ** He can come to your office to work (terminal/editor), work remotely online (webpage), or you can send a work order and he will automatically take over the work (script call). The people and skills are the same, but the “where and how to get to work” are different.

Surface (interactive entrance)

In a word: Anywhere you access Claude Code - CLI, VS Code, JetBrains, desktop, claude.ai; All entrances share the same engine, and your CLAUDE.md, settings, and skills will work the same wherever you go.

**Analogy: Different models of the same brand share a vehicle-machine system. ** Cars and SUVs have different appearances, but the car-machine interface and operating logic are exactly the same, so it costs zero to get started. It feels the same when switching to Claude Code. (See Chapter 08 for details)

Non-interactive mode (formerly known as headless)

One sentence: Run with -p (or --print) - Execute a single prompt and exit after the result, without entering the dialogue session; specifically for CI, scripts, and pipelines. In the old documentation, it was called headless mode, which is the same thing.

**Analogy: Send a work order and he will leave after completing the work without nagging you. ** It’s not about sitting down and talking back and forth, it’s about “getting the results done once this is done.” Its Python/TypeScript equivalent is Agent SDK. (See Chapter 45 for details)

Agent SDK (Agent SDK)

In a word: Move the capabilities of Claude Code** into the development package of your own program** (Python/TypeScript), allowing you to drive it in the code like calling a function.

**Analogy: Take out the entire coffee machine movement and put it into your own product. ** Instead of using a ready-made coffee machine, you can get the movement and build one yourself. The non-interactive mode is the command line version, and the Agent SDK is the “write-in-code” version. (See Chapter 45 for details)

Claude Code on the web (web version)

In one sentence: Claude Code runs in the browser, and the task is executed in the cloud sandbox (different from “Remote Control” - the latter code is still on your local machine, but the UI is remote).

**Analogy: Rent a disposable cloud computer and burn it after use. ** The work is done in the temporary machine on the cloud and does not occupy your local environment. (See Chapter 11 for details)

Bare mode

One sentence: Add --bare at startup, skip the automatic discovery of hooks, skills, plugins, MCP server, auto memory, CLAUDE.md - only the parameters you explicitly pass will take effect; use it for CI and scripts to ensure that the behavior is consistent when changing machines.

**Analogy: Only take one carry-on suitcase with you on a business trip, and none at home. ** Clear all “local personalized configurations”, and the light-tape task itself will be on the road, and it will be the same no matter which machine it runs on. (See Chapter 34 for details)

Worktree isolation

One sentence: An isolation method, use -w or write isolation: worktree in the subagent configuration, let Claude work in a separate git worktree and separate branch under .claude/worktrees/, changes will not fight with other parallel agents.

**Analogy: For the same set of drawings, each construction team is given an independent construction site. ** Several teams of people work at the same time, each in his own place, and no one can knock down the wall built by others. It’s all about separation when running multiple sessions in parallel. (See Chapter 41 for details)

Remote Control/Teleport

In one sentence: Remote Control takes over the session running on your local machine from your mobile phone or browser (the code is still on your machine, only the interface is remote); Teleport (/teleport), in turn, pulls the cloud session into your local terminal and continues.

**Analogy: Install a remote control for that computer in the office. ** Remote Control is like using your mobile phone to control your computer at home when you go out (the work is run at home); teleport is like “transmitting” unfinished work on the cloud back to the machine in front of you to continue. (See Chapter 11 for details)

💡 To summarize in one sentence: This family talks about “where to use and how to run” - surface is the entrance (shares the same engine), non-interactive mode (formerly known as headless) is the work order running method, Agent SDK is written into the code, the web version runs in the cloud sandbox, bare mode is clean startup, worktree isolation allows parallelism without fighting, Remote Control / teleport takes over back and forth between the local machine and the cloud.

07 The couples that are most easily confused, come back and look at each other when the car crashes

There are so many terms, and there are always a few pairs that look alike, but you get confused when you use them. Take out the pairs that novices crash the most and compare them separately. You can tell which pair you are stuck at at a glance. This table is also a horizontal closing of the previous six tribes.

For every pair in this list, there are at least four or five pairs that are really easy to mix up when a novice first learns. The most typical ones are skill and subagent - when I first started, it was easy to hard-code a task of “reading the entire directory to find dead code” into a skill. As a result, the process of flipping files in the middle filled the main dialogue. It took me two runs to realize: As long as the dirty work of the conclusion is done, a subagent should be sent, not a skill.

💡 To summarize in one sentence: For the pairs that crashed, it is enough to remember the “key dimension” that distinguishes them - skill/subagent depends on whose context it is, CLAUDE.md/skill depends on when it is loaded, mode/rules depends on the thickness, stdio/http depends on where the server is running.

08 Hands-on: Let Claude be a “living dictionary” and check authoritative definitions at any time

This table alone is not enough - terminology will be updated, this article is static, and the official document is living. The safest way to check is to ask Claude to check the official glossary himself. The “official document server” I picked up in Chapter 22 comes in handy: it requires no login or configuration, and you can ask questions just after connecting. This section teaches you how to use it as a portable “living dictionary”.

This server is a remotely hosted HTTP service, and it requires an Internet connection. If access to code.claude.com from China fails, first open “Magic Internet” and try again.

Step one: Connect to the official documentation server (in the terminal, not in the claude session)

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Expected: Print a confirmation line similar to Added HTTP MCP server claude-code-docs .... See Added = configuration written in.

Step 2: Confirm connection

claude mcp list

Expected: claude-code-docs appears in the list with ✓ Connected next to it. Seeing a green check = really connected; if it is ✗ Failed to connect, most likely the network is not connected, turn on the magic to connect to the Internet and try again.

Step 3: Enter the conversation and ask it to check the official definition of a term

claude

After entering, type (name the server to make it go to MCP and check the official documentation, rather than answering from memory):

用 claude-code-docs server 查一下官方术语表里 compaction 和 context window 的定义，各用一句话告诉我

Expectation: Claude When you adjust this server for the first time, it will stop and ask you if you want to approve it (that is, in Section 05 Permissions, the first time the tool is called, you need to approve this gate - it is managed by the permission system, and it is two different things from checkpoint) - approve it. It then returns the official description of these two terms, and the output is marked with claude-code-docs next to the tool call. Seeing this mark = the answer is really found from the official documents, not from the model memory.

Step 4: Cleanup (optional)

claude mcp remove claude-code-docs

Expected: Print removal confirmation, run claude mcp list again, it is no longer in the list.

With this set of rules, you will have a timeless terminology check method: Check this article quickly. If you are not sure or suspect it is outdated, let Claude check the official version. Rely on this to check every definition - it’s much more practical than writing a sentence from memory and beating the drum in your head.

💡 One sentence summary: This article is a static quick check card, the official document server is a living dictionary; connect it (add → list to see the green check → check by name in the session → approve), and you can instantly check the most authoritative definition of any term, which will never go out of date.

09 Summary

This article is not for you to memorize, but to give you a Pocket Quick Check Card - the terminology of the entire tutorial is organized according to the six tribes, and you can check whichever one you encounter.

Looking back at the six ethnic groups together:

You should now be able to: No longer be confused when seeing any term that pops up along the way - know which family it belongs to, what a sentence is, and what analogy to use to make it easy to remember; when encountering pairs that are easy to crash, such as skill vs subagent, stdio vs http, go back to Section 07 and distinguish them at a glance; you have also learned to use the official document server to treat Claude as a “living dictionary”, and you can look up the most authoritative definition of any term. **Keep this quick check card handy. All the nouns in the previous fifty articles that you didn’t remember in a flash will have a place to go back and check. **

The entire formal tutorial is basically complete here - from “what is this” to installation, familiarity, adding equipment, configuration optimization, and finally closing this terminology, you have recognized all the words you should know.

Next article 53 “Making Videos (Remotion) [Optional Reading]” - This is the easter egg chapter of the whole set of tutorials. It jumps out of the “writing code” box and shows you what else Claude Code can do: use Remotion (a framework for “writing videos with React code”) to let Claude help you generate an animated video using code. Optional reading, does not affect the main plot; but if you want to see how far “AI programming” can be extended, this article is worth taking a look. Think about it: since videos can be written in code, then asking Claude to write this code is another job of “describe the requirements and it will work”?

53 · Making Videos (Remotion) [Optional Reading]

📌 About the positioning of this article: Claude Code official documentation does not have a Remotion page - This is not a built-in function of Claude Code, but a usage of “using Claude Code to write code for another framework”. Therefore, the technical facts in this article are based on general knowledge of Remotion + tutorial practice, and do not cite the official Claude Code document (because it does not talk about this at all). It is classified as “selected reading” because it is indeed a scrap material: most people will not use it, but those who do will think “fuck this is okay”.

Brothers, let me give you some data to give you a feel.

Remotion, an open source project, has accumulated more than 50,000 stars on GitHub. ** The fact that a framework of “Writing Videos with React” has attracted this level of attention shows one thing in itself - ** “Writing videos as code” is not a small group of geeks’ self-entertainment, but there are real people working on it.

One of the most out-of-the-box uses is this: some products generate “exclusive annual summary videos” for each user - your play time, the songs you listen to the most, and your rankings. Tens of thousands of users means tens of thousands of videos with different content but the same template. For this kind of work, you ask the editor to use Pr and AE to cut each piece? Cut until the end of time. But if the video is a piece of code that can pass parameters, it is a loop - change the data and render a new one.

Speaking of “code that can pass parameters”, who do you think of? **Yes, it’s the home of Claude Code. ** Once the video is turned into React code, it is no different from any code you have messed with in the previous fifty-two articles - you describe the requirements, it writes, it changes, and it adjusts. This article will help you understand how this combination works, and the most important thing: **Is it suitable for you? **

After reading this article, you will get:

• Explain in one sentence what Remotion is and why it can “use code to make videos”
• Why Remotion and Claude Code are a perfect match - video changes into code, and code is Claude’s job
• A set of minimal processes for “from an empty directory to an mp4”. Each step gives the expected output and can be run according to it.
• A simple explanation of the three core concepts (frame, interpolation, elasticity), understand what is written in the code generated by Claude
• A comparison table of “Who should use it/Who should not touch it” to help you decide whether to spend time on it or not.

01 First understand: Why can Remotion “use code to make videos”

Let me give the conclusion first: **Remotion is to turn “each frame of the video” into a picture rendered by React, and then assemble these pictures into a video in order. **You no longer use the mouse to drag materials on the timeline, but write code to describe “what the frame looks like”.

This sounds a bit counter-intuitive - aren’t all videos shot and edited? How can you still “write” it? The key lies in what kind of video it makes: not the kind where real people appear or edit real shots, but text animations, data charts, logo titles, and code demonstrations where the “pictures are completely generated by rules” videos. There is no such thing as “shooting” in this kind of thing, it’s all about “drawing according to rules” - and “drawing according to rules” is what code is best at.

**Analogy: The flip book I played with when I was a kid. ** You draw a little person on the corner of each page of the notepad. On the first page, he raises his left foot, on the second page, he raises his right foot, and on the third page, he jumps up… Each page looks like a still picture, but if you flip your thumb quickly, the little person starts running. That’s the essence of video - a bunch of still images, played fast enough, and the eyes see it as continuous action. What Remotion does is to let you use code to draw each page of this flip book: you write a function and tell it “the text on page 0 is outside the screen, and page 30 slides to the middle”, and it calculates, draws, and connects it into a video as to what each page in the middle should look like.

When it comes to real scenes, the following types of videos are particularly smooth to use with Remotion:

• Data Visualization Video: A bouncing animation of a number rising from 0 to one million, a histogram growing over time - data-driven, code-controlled and accurate
• Batch personalized videos: The kind of “annual summary” mentioned above, the same template is filled with different data, and thousands of items are rendered in a loop
• Technical Demonstration/Tutorial Title: Line-by-line highlighting of code blocks, terminal typing effect, logo smashing into the screen - programmers make their own demonstration videos, which is much faster than learning AE

Take a common scenario: I want to give a 15-second release trailer for a gadget. I don’t know After Effects, and I thought it was not worth it to hire an editing outsourcing company for 15 seconds. At this time, I asked Claude Code to configure Remotion, from an empty directory to a playable mp4, which took more than an hour - most of the time I was still repeatedly adjusting “this word flies too fast” and “the background is too ugly”. This matter has to be put aside before the software has even figured it out.

In order to let you see clearly the position of Remotion in “making videos”, I will put it side by side with two other types of tools that you have probably heard of:

If you look at this table, you will understand its ecological niche - It does not compete with the film clips for the job of “cutting life videos”, nor does it compete with the online templates for the job of “making a random one”. It specializes in the hard core of “accuracy, batch size and reusability”. And its only threshold, “you must be able to write code,” happened to be smoothed out by Claude Code.

💡 To summarize in one sentence: Remotion splits the video into React images frame by frame. You use code to describe “what the frames look like.” It is responsible for drawing them and putting them together into a movie. What it is good at is **videos that are “generated according to rules” such as text, data, and logos. It does not compete with editing software for real shots, and it does not compete with online templates for “generating pictures at will.” It specializes in “accuracy + batch + reusability”.

02 Why Remotion and Claude Code are a perfect match

The last sentence of the previous section actually makes it clear - once the video becomes code, making the video becomes writing code, and writing code is Claude Code’s specialty. ** That’s the whole reason these two got together.

Let me explain this matter clearly. What’s the threshold for making traditional motion-effect videos? Stuck in software: You need to be able to use After Effects or Pro, and you need to understand the entire set of “software operations” such as keyframes, easing curves, and layer masks. This set of things is not fast to learn, and many programmers are stuck at the step of “I want to make an animation but are too lazy to learn AE”.

**Analogy: You don’t know After Effects, but you hire a motion artist who knows React to sit next to you. ** You don’t need to touch those complicated software, just tell the master your requirements in plain English - “I want a line of text to fly in from the left, stop for a moment, and then turn green and glow” - the master understood, turned around and wrote out the corresponding code. Remotion provides the possibility that “video can be written in code”, and Claude Code is the master who helps you translate your needs into code. You are responsible for aesthetics and decision-making, and it is responsible for hands-on knocking.

The beauty of this set is that it perfectly hits the few things Claude Code does best:

Looking at the line “Changing a single detail” can give you the best feeling. You see “This card enters too fast” in the preview. In AE, you have to dig out the key frame in a bunch of layers; but here you only need to type “Slow down the entry animation of the card in FeaturesScene” in the terminal, and Claude will reduce the value in the corresponding .tsx file - The preview will also be hot-updated, and you will see the effect immediately. This kind of “natural language-to-video” experience is actually the most addictive aspect of this set.

I have to insert an important premise here to avoid misunderstandings: **The core of this combination is that Claude Code is writing React code, not that Claude Code himself “can make videos”. **So the whole set of things mentioned in the previous tutorial are all applicable here——

• The more specific the requirements, the more accurate it will be (see Part 15 “How to ask questions” for details). “6 seconds, 1920×1080, 30fps, black background with gold characters” is a hundred times better than “making a cool title sequence”;
• Use /init or a copy of CLAUDE.md to fix the project agreement (see Parts 12 and 18 for details), which will make subsequent code changes more stable;
• You can even hang a special Skill and feed it the specifications of “How to write Remotion” (see Part 26 for details), and the quality of the generated code will be obviously different.

In other words: **Remotion You don’t need to learn this part from scratch. The skills you practiced in the first fifty-two articles on “How to command Claude Code to write code” can be directly reused here. **

💡 Summary in one sentence: Remotion turns videos into React codes, and writing React codes is exactly what Claude Code does; you are responsible for putting forward requirements and aesthetic decisions in vernacular, and it is responsible for setting up projects, writing animation logic, and making changes based on your feedback - just transfer it as it is when you learn how to direct Claude to write code.

03 Three core concepts: understand what is written in the code generated by Claude

You don’t have to know any code at all, and you can still make videos by just commanding Claude with your mouth. But as long as you spend three minutes to recognize three words, the code it generates will no longer be a bible, and you will have more confidence to make changes. These three words are the entire foundation of Remotion: Frame, Interpolation, Resilience.

Frame: The video is calculated based on the “frame”

Going back to the flip book analogy - the smallest unit of video is a “frame”, which is the “page” of a flip book. There is a core function useCurrentFrame() in Remotion, which tells you “which frame is being drawn now”. The essence of your entire animation is one sentence: “What should the picture look like at frame No.”.

There is only one formula for converting frames and time. Remember it and you will be able to understand all duration settings:

Total frames = seconds × frame rate (fps). For example, a 6-second, 30fps video is 6 × 30 = 180 frames.

So when you see durationInFrames={180} with fps={30} in the code, your mind immediately reacts: This is a 6-second movie. (fps means frames per second, how many frames per second; 30fps is smooth, 60fps is smoother but the file size is larger.)

Interpolate: Smoothly calculate “from A to B”

interpolate() is the most commonly used function. What it does can be explained in one sentence: Given two time points and two values, it helps you calculate the transition value of each frame in between.

Take the most straightforward example - you want a line of text to fade from “fully transparent” to “fully opaque” in the first 30 frames:

import { interpolate, useCurrentFrame } from "remotion";

const frame = useCurrentFrame();
// 第 0 帧时 opacity=0，第 30 帧时 opacity=1，中间自动平滑过渡
const opacity = interpolate(frame, [0, 30], [0, 1]);

Read this code: interpolate(frame, [0, 30], [0, 1]) translated into human words is “When the frame goes from 0 to 30, the value is smoothly pulled from 0 to 1”. Claude writes fades, displacements, scaling, rotations, the bottom layer all depends on it. When you see interpolate you know: There is something here that is “smoothly changing from one state to another”.

Flexibility (spring): Let the animation “Q-bounce” instead of being stunned.

spring() is a function that makes animations physically elastic. interpolate produces uniform linear motion, which looks “mechanical”; spring simulates the feeling of “spring” that “shoots over and bounces back”, which is much more natural.

There is a very reasonable saying: **Elastic animation made with spring() is 10 times more natural than linear animation. ** Take the previous release trailer as an example. At the beginning, the logo was cut into the middle with a “pop”, which was very ugly. Later, I told Claude to “let the logo bounce in with an elastic effect.” It replaced interpolate with spring, and the logo had that kind of high-end feeling that “bounces and stabilizes”. So if you want the animation to look professional, just say “use elastic easing” when making a request - this is a very practical rule of thumb.

You don’t need to be able to write these three concepts, just know them. The following table will help you get the right idea: whichever word you see, you will know what Claude is doing.

Finally, string the three words together into a complete picture, and you will have a complete feeling. The following paragraph is the smallest component that Claude can generate - a line of HELLO, fading in and with elastic amplification. You don’t need to be able to write, just read it following the comments on the right:

import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";

export const Hello = () => {
  const frame = useCurrentFrame();        // 现在画第几帧
  const { fps } = useVideoConfig();        // 拿到帧率

  // 前 30 帧从透明淡入到不透明
  const opacity = interpolate(frame, [0, 30], [0, 1]);
  // 用弹性算出缩放值，从小弹到正常大小
  const scale = spring({ frame, fps, config: { damping: 12 } });

  return (
    <div style={{ opacity, transform: `scale(${scale})` }}>HELLO</div>
  );
};

It is not difficult to understand it: useCurrentFrame() takes the “frame” → interpolate pulls the transparency from 0 to 1 (fade in) → spring makes the scaling flexible (bounce it) → finally applies these two values ​​to the style of that line of text. The entire paragraph is answering a question: “In frame frame, what should this line HELLO look like?”. No matter how fancy the code generated by Claude is, the skeleton is still the same - recognize these words, and you can discuss with it what should be changed.

💡 Summary in one sentence: Three words are enough for you to understand the code - frame is the “page” of the video (total number of frames = seconds × fps), interpolate smoothes out “from A to B”, spring makes the animation more flexible and natural; when strung together, they answer “what does the picture look like at which frame”? You don’t need to be able to write, just recognize them + know how to order in vernacular. It’s enough.

04 Minimal process panorama: from empty directory to an mp4

Go through the entire process in your head and you won’t get lost when making videos. **Five core steps, each step requires you to either give an instruction to Claude or run a command to see the result. **

I first use a flow chart to draw the whole picture, and then dismantle it step by step.

What this picture says is: After installing the environment, you describe your needs to Claude → it generates code → you preview → if you are not satisfied, just use your mouth to change it, and if you are satisfied, it will be rendered into mp4. In the middle, “preview-change-preview” will go around several times, which is normal.

Next, each step will be explained clearly, and the key instructions and expectations will be given.

Step 1: Prepare the environment

Remotion is based on Node.js, so you must have Node.js 18 or higher on your machine, plus installed Claude Code (see Chapter 02 for details on installing Claude Code). Verify Node version:

node --version

Expected: Print version number like v20.11.0. As long as the previous number is ≥ 18. If it is lower than 18, Remotion Studio will report an error when starting up - this is the first pitfall that novices often encounter (just use tools like nvm to raise it to 20).

**⚠️ Note: ** When Remotion renders videos, the bottom layer uses a headless browser (headless Chromium, a browser that has no interface and runs in the background to “screenshot” each frame). You may need to download this component to render it for the first time. If the domestic network is stuck at this step, open “Magic Internet” and try again.

Step 2: Create an empty directory, start Claude Code, and explain your requirements clearly

mkdir hello-video && cd hello-video
claude

Enter the claude interactive interface and describe your needs clearly at once. The more specific the requirement, the higher the probability that it will be delivered right the first time. A minimal example prompt word:

帮我用 Remotion 创建一个项目，做一个 6 秒的开场视频。
要求：1920x1080，30fps，纯黑背景；
画面中央显示 "HELLO" 几个白色大字，从透明淡入并轻微放大，
最后这几个字带一圈绿色（#67c23a）发光。
只要一个 Composition，不用拆多个场景。

Note that I have written down all the duration, resolution, frame rate, color, and animation method in this prompt - this is exactly the “instructions must be specific” repeatedly emphasized in Part 15. “6 seconds, 1920×1080, 30fps, white text on black background, fade-in zoom, green glow” is much better than “making a cool title sequence”.

You don’t have to think from scratch every time. Remember a list of “five elements” and fill it in accordingly to get a good reminder:

For size, it is easier to just say the platform you want to vote for than to report a number** - Douyin vertical screen (1080×1920), Bilibili horizontal screen (1920×1080), WeChat Moments square (1:1), you name the platform and it converts the size. Basically fill in these five lines when making a request. The probability of getting it right the first time is obviously much higher than describing it blindly**.

Step 3: It builds the project + writes code

Next, Claude Code will do its own work: initialize package.json, install Remotion dependencies, build the src/ directory, write the Composition component, and write the animation logic using interpolate/spring. It handles the entire scaffolding, you just watch it create files one by one. After it is generated, it will usually tell you the command to “install dependencies and run preview” - do so.

Step 4: Preview (this step is the most critical)

npm install
npx remotion studio

Expected: The terminal prints something like Remotion Studio running at http://localhost:3000, and the browser opens automatically. You will see a preview interface with a timeline - you can play and drag the timeline to see the effect frame by frame.

This step is the core of the entire process. **Whether the video is good or not, you can see it all here. ** When you drag the timeline and look at it, you feel that “this word flies too fast” and “the green light is too dazzling”, write it down - the next step is to ask Claude to change it.

Step 5: If you are not satisfied, let it be changed. If you are satisfied, render and export it.

When you find a problem, don’t go through the code yourself, go back to the Claude Code terminal and speak in plain English:

"HELLO" 淡入太快了，把淡入时间拉长到 1 秒；绿色发光弱一点。

It locates the corresponding code and changes it, Remotion Studio will automatically hot update, and you can see the new effect at a glance back in the browser. Repeat this cycle of “speaking-modifying-seeing” several times until you are satisfied.

When satisfied, render to mp4:

npx remotion render HelloVideo out/hello.mp4

Here HelloVideo is your Composition ID (it must be consistent with the id registered in the code, Claude will tell you what it is called), and out/hello.mp4 is the output path. Expected: The terminal runs a progress bar and prints something like Rendered ... → out/hello.mp4 after it is finished. Go to the out/ directory, your mp4 is just sitting there.

Two little things that are most likely to get stuck for novices are explained here:

**Composition ID Don’t know what it’s called? ** Don’t guess - Ask Claude directly “What is the Composition ID of this video”, he will tell you; or open the remotion studio preview interface, the left column lists the names of all Compositions, just copy them. If the ID is wrong, the rendering will report “Cannot find this Composition”. At this time, just go to those two places to check.

**Why can’t you skip preview and render directly? **Because rendering is “heavy work”, a video may run for several minutes; while the preview is real-time and can be dragged frame by frame. The correct posture is: adjust it repeatedly in the preview until you are satisfied, and finally render it once. Many people don’t understand this at first. Every time they change something, they render it again to see the effect, waiting for a bunch of progress bars in vain - remember “preview, render,” can save you a lot of time.

💡 Summary in one sentence: Five steps - ** Installation environment (Node 18+) → Describe requirements → Use it to write code with the project → remotion studio preview → Use your mouth to change it / When you are satisfied, remotion render will output mp4**; among them, “preview-change-preview again” will go around several times. This is normal, don’t expect to get it right at once, and debugging is all done in the preview, and rendering is only run once when the final film is produced**.

05 Hands-on: Run through a minimal example and verify it

Just looking at the process doesn’t count. This section gives you a set of minimum practices that you can follow and have expectations for each step. **The whole process does not depend on any video-related environment you already have, as long as you have Node.js 18+ and Claude Code. **

**⚠️ Reminder: ** This example will make Claude Code really install dependencies online, create files, and run rendering, which is more “heavy” than you usually ask it. It may take a few minutes to install dependencies and render the components for the first time. If the domestic network is unstable, please turn on Magic Internet.

Step one: Confirm that the Node version is sufficient (if not, it will be useless later)

node --version

Expected: Print v18.x.x or higher (like v20.11.0). The first number ≥ 18 will pass. If it’s low, upgrade first and then go down.

Step 2: Create an empty directory and start Claude Code

mkdir hello-video && cd hello-video
claude

Expected: Enter the Claude Code interactive interface, the cursor is waiting for you to speak in the input box.

Step 3: Paste the minimum requirement prompt word in Section 04 and send it to it

Just use the above prompt words “6 seconds, 1920×1080, 30fps, white text HELLO on black background, fade in and zoom in, green glow”.

Expectation: Claude Code starts creating files and writing code - you’ll see it create package.json, src/Root.tsx (or src/index.ts), that animation component, etc. When it is working, it may request your approval for operations such as “create files” and “run npm install” (this is the permission mechanism discussed in Chapter 20) - approve it to continue. Once done it will prompt you for the next command.

Step 4: Install dependencies + start preview

npm install
npx remotion studio

Expected: npm install has finished pulling in dependencies (the first time is slightly slower). remotion studio prints Remotion Studio running at http://localhost:3000 and automatically opens the browser. You can see a preview of the words **HELLO fading in with a green light on a black background. You can drag the timeline to view it frame by frame. **Seeing this playable preview = your link is connected. **

Step 5: Use one sentence to make it change and verify “Natural Language Change Video”

Return to the Claude Code terminal and type:

把 HELLO 的淡入时间拉长，慢一点进来。

Expected: Claude finds the corresponding interpolate code and changes the transition frame interval to a larger one (for example, from [0, 15] to [0, 45]). Remotion Studio automatic hot update, if you look back in the browser, HELLO has obviously slowed down. See this change = you have mastered the essence of this gameplay - you don’t need to touch the software to make videos, just open your mouth.

Step 6: Render mp4

npx remotion render HelloVideo out/hello.mp4

(Replace HelloVideo with the real Composition ID that Claude told you.) Expected: Run a progress bar and end by printing Rendered... → out/hello.mp4. Open out/hello.mp4, a real video file, which can be opened with any player.

After running through these six steps, you will have gone through the complete link of “Confirm the environment → Describe the requirements → Generate code → Preview → Modify by mouth → Render the film”. **To make more complex videos in the future, it is nothing more than describing the requirements in more detail and making more rounds of revisions - that’s all the core process. **

💡 Summary in one sentence: Six steps to start - node --version Confirm ≥18 → Start from an empty directory claude describes the requirements → It generates code → remotion studio Preview → Use one sentence to make it watch hot updates → remotion render produces mp4; running through it once by yourself is more effective than reading the flow chart ten times.

06 Who should use it and who should not touch it: think clearly before investing

This section is the most practical, and it is also the attitude that [Selected Readings] should have - **Not everyone should touch this thing. I will tell you directly who it is a sharp weapon and who it is a waste of time. **

Let me talk about the conclusion first: **Remotion + Claude Code is suitable for videos that are “programmed, parameterized, batch-based, and data-driven”; it is not suitable for videos that are “one-time creative, real-life shooting, and heavy editing.” ** If you are not sure, just look at the table below to get the right answer.

The judgment criterion is just one sentence: **Is this video a “one-time piece of art” or a “template that can be reused by changing data”? ** The former is a practical editing software, while the latter is Remotion. The reason why the previous release trailer is worth using is because there will be trailers for the second and third tools later—with this set of code, you can publish another one by changing the text and color next time. This is where its value lies. If you really only want to do this one thing and never touch it again, then it might be faster to learn how to edit in ten minutes.

Let me tell you a truth that may not be pleasant to hear: people who have just learned this method can easily overestimate how often they will use it. A common situation is: setting up the environment in a hurry, making a cool title, and then… nothing more - because there is usually no need to “produce videos in batches.” **No matter how cool the tool is, if it is not supported by a real scene, it is just a disposable toy. ** So here is a very pragmatic suggestion: Don’t learn for the sake of learning. You should first ask yourself, “Do I have the kind of video about “exchanging data with the same template” that I want to do over and over again?” If so, this article is for you, so hurry up and get started; if not, it’s enough to know that there is such a way, and come back to this article when you really encounter it, and just follow the five steps. This is exactly why it is classified as [Selected Reading].

There is another hidden cost that is easily overlooked and needs to be reminded: Rendering requires machine performance and time. It’s normal for a 60-second video with special effects to take two to three minutes to render on an ordinary laptop—the longer the video and the more special effects it has, the slower it will render and the fans will whir. Fortunately, there is a trouble-saving trick: If the rendering is slow, ask Claude to add the --concurrency parameter to enable multi-threaded parallelism, which can be several times faster.

Let’s talk about two common pitfalls that can help you avoid detours:

**First, don’t ask it to make particularly complicated videos. ** If you are greedy from the beginning and make a long video with “five scenes, different transitions for each scene, and music rhythm”, the generated code will easily become a mess, and it will be more tiring to modify than to redo it. The safe approach is to let it run through the simplest version first, and then add it scene by scene. This is the same as the “break down complex tasks” mentioned in Chapter 16, especially when making videos.

**Second, don’t panic if the spring animation occasionally displays “only the first frame”. ** Sometimes a certain elastic animation with delay does not move, and it is found that it is a known glitch - the number of frames passed to spring becomes a negative number when the delay is not handled well. You don’t need to understand the principle, just tell Claude the phenomenon directly: “This animation only displays the first frame and doesn’t move.” It basically knows how to fix it at a glance (add a protection to the frame number to prevent it from becoming negative). **This is also the benefit of this set: you don’t have to fill in the pits yourself, just give it a clear description. **

💡 To summarize in one sentence: The judgment criteria is just one sentence - ** Use editing software for “one-time works of art” and “templates that can be exchanged for data reuse” before using Remotion**; data visualization, batch personalization, and technology demonstrations are its home field, so don’t make do with real-life shooting and one-time creativity; in addition, rendering takes performance and time. For long videos, remember to let Claude turn on --concurrency in parallel.

07 Summary

This article takes you through a corner of Claude Code - Let it use Remotion to help you “make videos with code”.

Let’s review the core points together:

You should now be able to: Explain in one sentence why Remotion can use code to make videos (one React picture per frame, like a flip book), explain why it is a perfect match with Claude Code (video conversion to code is Claude’s job), understand what the frames / interpolate / spring are doing in the generated code, and follow the hands-on steps to run a real line from the empty directory mp4, and most importantly - determine whether this thing is worth your time. That’s enough: the purpose of the optional reading is not to let you know everything, but to let you know “there is still this way” and know where to look when you need it.

Here, this article ends. **And when it ends, the entire set of “Claude Code Novice Tutorial” also comes to an end. **The following paragraph is the ending for you who have read this far.

08 Written at the end: Fifty-three articles, let’s finish them together

Brothers, if you can read to the end of this article, I have to say one thing first: **cow. **

Looking back at this journey——

Group 1 Let’s start with “What is Claude Code?”, install the environment, connect the accounts, and run the first example, so that you can go from “hearing about it” to “having it in your hand”.

The second group takes you to connect it to VS Code, JetBrains, desktop, and web pages, and teaches you how to use it seriously in your own projects - initialization and understanding the project structure.

The third group is the hard work on core interactions: how to ask questions, how to post pictures, how to write CLAUDE.md, how to manage context, how to assign permissions, and how to maintain security boundaries. **After this set of exercises is solid, you will truly “know how to use” Claude Code. **

The fourth group gives you five weapons - MCP, Subagent, Plugin, Memory, Skill, plus Agent teams, and teaches you “which weapon to draw when”.

Groups 5 and 6 In-depth system configuration and actual practice: settings, output styles, Hooks, CLI, checkpoints, Chrome, parallelism, Git, GitHub Actions, Agent SDK… push you from “knowing how to use” to “using it accurately and automatically”.

Group 7 Wrapping up: Best practices, anti-patterns, FAQs, glossary, plus the Remotion selection you just finished.

Fifty-three articles, From a command line tool to a complete set of agent capabilities that can be integrated into your workflow.

To be honest - This set of tutorials never asks you to “memorize orders”. Commands will change, versions will be updated, and new features will emerge one after another (look at the official changelog). What I really want to leave you with is the idea of ​​“how to collaborate with AI”: treat it as a partner sitting next to you rather than a query machine, be specific about your needs, confirm when it is time to confirm, solidify things that are used repeatedly, trust but leave a gate. **This set of ideas outlives any specific order. **

Finally, don’t regard these fifty-three articles as the end, but as the starting point. The tool is dead, and the real skill comes from the process of using it to solve a real problem. Start a small project that you have always wanted to do but have no time to do, and let Claude Code accompany you from scratch to online - you will learn more at that moment than after reading these fifty-three articles. **

The best way to practice this skill is always: **Turn off the tutorial, open the terminal, type claude, and then start doing your own work. **

We’ll see you later.