Mastering Claude Code

Introduction

A newly hired employee shows up for their first day. You open the office door, let them in, and say nothing but "get to work." What happens? They don't know where the bathroom is. They don't know where the contacts for major clients are kept. They don't know what the company's tone and manner are. They start writing emails knowing none of this. The result cannot help but be wrong. Using Claude Code on a new project for the first time is exactly this.

The agent opens a folder and looks for one file first: claude.md. Without this file, the agent is no different from a new employee who showed up with no guidance.

The Role of System Prompts

If you have built an AI agent in n8n, you have probably seen the field in the node settings window where you enter a system prompt. If you have created a custom GPT in ChatGPT, you have experienced adding your role and rules to the Instructions tab. claude.md serves the same purpose.

The name is different, but the essence is the same. It is the document the agent always reads before reading the user's message.

Let me trace the sequence. The user sends a message to Claude Code. Before processing that message, the agent reads the entire claude.md file from the project root. Only then does it check the user's message and generate a response. This order is always the same. Every time you start a new conversation, every time you run /clear, the agent reads claude.md first.

What this means is clear. Content written in claude.md becomes the baseline that runs through all of the agent's behavior. If you write "all responses should be in Korean," the agent answers in Korean. If you write "always include error handling when creating Python scripts," the agent won't skip try-except blocks.

[Figure 8-1] Flowchart showing the order in which the agent processes a message. Read claude.md → Check user message → Explore files as needed → Generate response.

What to Include

The information that should go in claude.md divides into three main layers.

What: the project's identity. Specify what this project is, what its tech stack is, and what core packages or skills it needs. A real example looks like this.

One paragraph. It contains the agent's role and the user's top priority goal.

Why: the purpose of each component. If you write only "the tools folder contains Python scripts," the agent knows the folder exists but does not understand why to check it first. If you write "when you get a new task, check the tools folder first,there might already be a tool built for it," the agent's behavior changes.

How: the working method expected of the agent. Action rules like "if an error occurs, fix the script and then add that error handling method to the workflow document" belong here.

What Not to Include

Do not include the resumes of all team members. Do not copy and paste the entire project meeting log. Do not include detailed documentation of every API endpoint.

The reason is the token count discussed in the previous chapter. claude.md is read in its entirety at the start of every conversation. If the file is 500 lines, each time those 500 lines' worth of tokens eat into what the model can read in one session. To answer a single question, a large chunk of context is already consumed by the system prompt before the conversation even starts.

The rule is straightforward. Put only what the agent needs to know every single time in claude.md. Information needed only occasionally goes in a separate file, with claude.md pointing to that file's location.

The 150-to-200-Line Principle

So what is the right length for claude.md?

The validated standard in practice is between 150 and 200 lines. Within that range, you can fit project identity, core rules, and file location guidance. There is a real example: the claude.md file right after setting up an agent secretary project was about 87 lines. As the project grows,skills and tools added, reference files multiplying,it naturally expands toward 150 lines.

Once you start crossing 200 lines, you should be alert. At that point, items in claude.md definitely exist for which the answer to "do I really need to read this every time?" is no. Those items should be moved to a separate file.

As time passes, new skills are added to the project, reference documents accumulate, and rules become more detailed. claude.md naturally expands. You now need a routing strategy.

Routing Strategy: Pointing from claude.md to Other Files

Open the agent secretary project's claude.md and you will see a passage like this in the middle section.

This is routing. claude.md itself contains no detailed information about "who the user is." Instead, it just points to "read this file if you want to know about the user." The agent reads context/me.md only when the user's question involves the user's personal information. If it does not, it skips it.

This way, the only tokens consumed each time are the brief guidance lines in claude.md.

Let me show routing's impact with numbers. If you cram user profile, work details, team information, priorities, and project description all into claude.md, you will easily exceed 500 lines. With routing, claude.md stays at 100 to 150 lines while the agent pulls in those files only when needed. That frees up proportionally more breathing room in what it can read at once.

Here are examples of files that can be routing targets.

[Figure 8-2] Hub-and-spoke diagram with claude.md as the hub and me.md, work.md, team.md, and others as spokes.

The Habit of Updating claude.md as Your Project Grows

claude.md is not something you write once and shelve. It lives and breathes with your project.

Initial Generation: The /init Command

If your existing project lacks claude.md, run the /init command. The agent scans the project's folder structure and code, then automatically generates a claude.md draft. It will not be perfect, but it beats starting from a blank page. Review the draft, add any missing rules, and delete anything unnecessary.

Daily Updates

When you add a new skill or workflow, just tell the agent directly: "I just added a folder called brand-assets. Update claude.md so it tells me to check that folder whenever I need a logo or brand guidelines." The agent opens claude.md and adds the entry. This habit, built over time, turns claude.md into a precise map of your project's current state.

Periodic Compression

After a project runs for weeks or months, accumulated entries in claude.md start to exceed 200 lines. At this point, ask the agent like this: "claude.md has gotten long. Clean it up to reflect where we are now. Remove tools and project references we do not use anymore, and consolidate similar rules." The agent analyzes and reorganizes the file. You review the result and sign off.

The Relationship Between claude.md and the .claude/ Directory

Alongside claude.md in the project root, a hidden directory called .claude sometimes appears. Inside sit detailed rule files like communication style guides. If claude.md is the broad-brush guidance, the files inside .claude are supplementary rules.

[Figure 8-3] Tree structure visualization showing the relationship between claude.md and the .claude/ directory, as well as the context folder in the project folder structure

In summary, claude.md is the agent's job description. It defines the role, specifies core rules, and points to where files with detailed information are located. Keep it to between 150 and 200 lines. Update it whenever the project changes.

You have organized who the agent is, what it remembers, and what rules it follows. But however intelligent the agent may be, its ability to act is limited without a means to interact with the outside world. To send emails, collect information from websites, or add events to a calendar, the agent needs 'hands.'

Gyeong-jin Kim, AI Policy Expert and Attorney

AI legal policy specialist, former member of parliament, author of multiple works

If this book has spent even a moment with you, please help the next story reach the world.

(Voluntary support requested - Account: Nonghyup 302-1096-0948-81, Account holder: Gyeong-jin Kim)