How to Write CLAUDE.md When Claude Code Breaks Working Code

Asking Claude Code to build a program is not difficult. But checking whether it built the program as requested, and managing changes so existing features do not break, are separate tasks.

CLAUDE.md is a file for writing project rules that AI can refer to. Let’s look at where to put this file and how to use it, with rules from actual files as examples.

Why AI can break code that was working

When Claude Code edits existing code, the code already in the project becomes a reference. But if that code is poor quality, AI may carry its problems forward or cover up only the issues that are visible.

It may also misunderstand a request and change code that was working well. In particular, it is important to structure a program so that changing one feature does not affect another. This is called modularization. If the design is not well planned, changing one feature can also change other features or code.

The impact of a problem also differs between a program someone uses alone and a service that handles money. Even when AI writes the code, people are responsible for checking the result.

What is CLAUDE.md, and where should it go?

CLAUDE.md is a project rules file that Claude Code refers to when working in that folder. The video explains that you can think of it as a prompt or set of instructions. The project rules in this file remain in place even when you start a new conversation.

You can put rules in different folders, separating rules for the whole project from rules for specific tasks. For example, you can put shared rules in the top-level folder, and put server and client rules in their respective folders. Depending on where you work, Claude Code refers to both the top-level rules and the rules in that folder.

The actual Union project has this folder structure. Union consists of a Node server, a React web client, and an Android app.

CLAUDE.md                  ← Shared coding rules
server/CLAUDE.md           ← Server rules
client/web/CLAUDE.md       ← Web rules
client/android/CLAUDE.md   ← Android rules

• CLAUDE.md contains shared coding rules that apply to the whole project.
• server/CLAUDE.md contains rules for the server.
• client/web/CLAUDE.md contains rules for the web client.
• client/android/CLAUDE.md contains rules for the Android app.

Include the reason for each rule

It is better to explain why a rule is needed, rather than listing the rule alone. In the video, the reason for adding commas and the won symbol to prices is to make them appear in the same format as on the menu. Knowing the reason gives you a basis for applying the rule in new situations.

The top-level CLAUDE.md has a rule to keep the direction of comparison operators consistent when comparing numbers.

Number comparisons: Use only < and <= for comparison operators (> and >= are not allowed). Always put the smaller number on the left and the larger number on the right (min < max). For a range, use min <= x && x <= max.

The file also explains why. If the comparison operators point in different directions, you have to check the direction each time you read the code, which can lead to mistakes. Using one direction consistently can reduce the chance of errors.

You still need to check the rules yourself

Writing a rule in CLAUDE.md does not mean AI will always follow it. You should allow for the possibility that it may ignore the rule. For areas where bugs must not occur, you can ask another AI to check the work or use a verification program.

The fact that Claude Code created a file does not mean the result is what you wanted. Check the screen and behavior yourself, and ask for changes where needed. The process requires making a request, checking the result, fixing it, reverting changes, and recording rules.

When you write rules in CLAUDE.md, do you also document why each rule is needed?

This article is a summary of my Korean YouTube video below, translated into English with AI and reviewed by me. #ABotWroteThis

Previous video: Why the Same Claude Code Can Produce Different Results