[AI Design] When Claude Code Doesn't Follow Rules, I Split Instead of Adding—What I Learned from 12 Skills Exceeding 500 Lines: Instructions Get Read Less as They Grow

Every time Claude Code failed to follow a rule, I would add one line to the instructions. Before I knew it, I had 12 skills that exceeded 500 lines. Instead of adding more, I split them, reducing a total of 9,770 lines down to 3,369 lines. However, when I recounted them a little over a month later, they had grown again by about 600 lines.

• Claude Code is a tool that allows AI to perform file operations and execute commands on your local PC. Skills are instruction files passed to Claude Code that say, "Follow this procedure for this task," and they are read when called. CLAUDE.md is an instruction file that is always read at the beginning of every conversation. In this article, I refer to both collectively as "instructions." You can think of them as relatives of ChatGPT's custom instructions.

This article is written for people who use Claude Code or ChatGPT for work and have been adding lines to their instructions one by one as they repeat the same rules over and over.

1. I was adding one line at a time whenever a rule wasn't followed

Claude would skip rules I thought I had written. Every time that happened, I would add a line to the skill, using stronger wording than before and adding a 🚨 to the beginning.

As of August, the longest one was the skill for the procedure to publish a note article. It had 1,225 lines. Of those, 74 lines had 🚨 attached. In an instruction file where 74 out of 1,225 lines say "this is absolute," even the person who wrote it couldn't tell what was truly absolute anymore.

What hit me the hardest was the morning summary skill in May. Every morning, I had it list the day's news and potential candidates for articles. One morning, an article I had placed in the news section appeared again in the candidates section. A similar mistake had happened two days prior, and I had just added a note of caution.

When I listed the causes later, there were four: trying to get by with local search results; creating 11 sections at the same time and being pressed for time; only reading the one line of the caution note in the list; and not re-reading the prohibitions written in the middle of the procedure at startup. That skill had 1,445 lines in the version saved two days later.

The rule was written down. It just wasn't read. I can't say that length was the only cause. Even so, one of the four was clearly related to length.

The official documentation from Anthropic, the company that makes Claude, titled "How Claude remembers your project," says the same thing about CLAUDE.md.

"Longer files consume more context and reduce adherence."

The guideline is to keep each CLAUDE.md file under 200 lines.

The morning summary skill continued to grow after that, reaching 2,240 lines. I split it once in June down to 542 lines. Even so, it was back to 656 lines by August, becoming one of the 12 counted in the next chapter.

2. 12 skills exceeding 500 lines—the longest was 1,225 lines

On August 11, I counted the lines of my skills. I counted the lines of the files as they were, including blank lines as one line.

There were 12 that exceeded 500 lines. The longest was 1,225 lines for the article publishing procedure, followed by 1,201 lines for the Indian news distribution procedure, and third was 975 lines for the meeting minutes creation procedure. Adding the 12 together results in 9,770 lines. On average, each one exceeds 800 lines.

Regarding how to write skills, Anthropic has published best practices titled "Skill authoring best practices."

"Keep SKILL.md body under 500 lines for optimal performance."

It continues, "Split content into separate files when approaching this limit." My 12 were not just approaching it; the longest was two and a half times the limit.

None of them were long from the start. One line every time an accident happened, one line every time it was pointed out. One line at a time, adding them seemed like the right thing to do. When I added them, I wasn't thinking that those lines would be read along with the other 1,000 lines.

3. I split them—The "map" you read every time, and the "content" you open only when needed

Before I decided to split them, I remembered something. This is a story from a different context. Regarding the problem of a to-do list that kept expanding, I implemented four measures of the "add a warning" type, and all four were ignored. The mechanism to push out old items failed, the procedure for judgment showed no signs of being executed, moving the history to a separate file only reduced it by 0.4KB, and when I decided to review it once a week, that weekly task itself hadn't been done for 84 days.

I realized that adding 🚨 to the instruction manual is the same type of approach. An added warning only works if it is read. Adding anything to a place that isn't read will have no effect.

What I did was simple. In the main body of the skill, I left the order of operations and "when, why, and which file to open", and moved the detailed procedures and the history of how those rules came to be to a file one level down. The main body is the map, and the file below is the content.

The same best practice, "Skill authoring best practices", describes the role of the main body like this.

“SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide.”

If it's a skill for the procedure of publishing an article, what remained in the main body was the order of operations and a table of guidance such as "use this file when starting to write" and "use this file after receiving approval for publication." 1,225 lines became 361 lines.

I wrote about what to write in the map side, that is, the CLAUDE.md that is read every time, in How to write CLAUDE.md before. This story is about how to place the content beyond that map.

On the same day, I also added a mechanism that issues a warning when a skill exceeds 500 lines. This would later take on a different meaning.

4. I tried counting—9,770 lines became 3,369 lines. And in one month, about 600 more lines

Immediately after splitting, the total for the 12 items became 3,369 lines. That is a 65% reduction from 9,770 lines.

On September 14, 34 days after splitting, I recounted the same 12 items using the same counting method. It was 3,988 lines. In just over a month, it had increased by 619 lines, which is 18%.

11 out of the 12 items had increased again after being split. The only one that didn't increase was the one for creating a family travel itinerary. The one that increased the most was the weekly review skill, which went from 238 lines to 375 lines, an increase of 137 lines.

I tracked what increased through the change history. The weekly review included a procedure to review accumulated pending items every week. The skill to leave a record when closing a task had increased from 366 lines immediately after splitting to 529 lines in three weeks. The content consisted of procedures adjusted to the recreation of the to-do list and three rules added every time an accident occurred. A rule for after part of the record disappeared, a rule for after the file became empty, and a rule for after the writing collided with another task.

In every case, the reason for adding them was correct. And it was the exact same pattern as before splitting. Every time something happens, add it to the main body.

After this skill exceeded 500 lines, the warning had appeared 4 times just in the records. However, the warning is designed not to stop the work. The skill continued to run as is, and I split it again on September 5, returning it to 390 lines. By September 14, it was back to 418 lines.

I also counted the number of 🚨. For the 12 items, it was 351 lines before splitting, 158 lines immediately after splitting, and 353 lines on September 14. Even though the line count is about 40% of what it was before splitting, there were 2 more 🚨 than before splitting.

I will write one more thing honestly. Did splitting make Claude follow the rules? The truth is, I haven't been able to measure that yet. This is because I didn't keep records comparing how the same tasks were followed before and after splitting. All I know is the line count and the number of 🚨.

Right now, there are 0 skills out of 88 total that exceed 500 lines. However, there are 8 that exceed 450 lines. One of the 12 items I split this time, and 7 that were not included in the 12. Whether to split them or change the way of adding them entirely, I haven't decided on the next move yet.

5. 5 minutes with your instruction manual—"Lines needed every time" and "Lines needed only at that time"

From here on, this is about your instruction manual.

Whether it's CLAUDE.md, ChatGPT's custom instructions, or project instructions, it doesn't matter. Open it up and, line by line, put each one into one of two boxes.

The first is Map lines. These are lines you need every single time, regardless of the task. For example, "Answer in Japanese" or "Include sources for numbers."

The second is Content lines. These are lines you only need for specific tasks. For example, "When drafting a blog post, limit it to three headings" or "When writing a weekly report, start by describing the changes from last week."

When you find a content line, add "Only when [task]" to the beginning of the line. "Only when drafting a blog post: limit to three headings." That's it. You don't need any tools, and it takes five minutes.

Anthropic's official documentation, "How Claude remembers your project," also separates what you keep in CLAUDE.md along the same lines.

"Keep it to facts Claude should hold in every session."

Furthermore, it suggests moving procedures with multiple steps or those relevant only to parts of a project to other places, such as skills.

For content lines, if you're using Claude Code, you can move them to skills or separate files. For ChatGPT, moving them to project-specific instructions is a similar approach. Even if you don't move them, adding "Only when [task]" to the start of the line makes it visible to the reader which line is for which task.

In my 12 skills, what I kept in the main file was only about a third of the original. The number of lines needed every time was far fewer than I, the author, had thought.

6. What I dare not do—deleting rules

If your instruction manual is long, you could just delete parts of it. If you search, articles explaining criteria for deleting rules appear at the top. I didn't delete them.

Somewhere in those 1,225 lines, there is a line I added after an accident that was actually effective. Since I can't measure which lines are effective, if I delete them, the effective lines will be deleted along with them. You can't undo a deleted line. If you push a line down one level, it will still be read when that specific task occurs.

Another approach is to stop relying on text and instead use machine constraints. The same official documentation, "How Claude remembers your project," says this:

"If the instruction is something that must run at a specific point, such as before every commit or after each file edit, write it as a hook instead."

A hook is a small program that runs at a fixed timing, regardless of what Claude is thinking. The last thing I added regarding the morning summary in Chapter 1 was a hook that stops the response if the same article is listed in two columns. The record of inserting 49 hooks and stopping 1,761 times is written in "49 Recommended Claude Code Hooks."

However, where to draw the line between asking via text and constraining via machine is still something I'm wavering on. Machines can only stop things that can be judged by form. Rules that require judgment ultimately have to be written somewhere.

7. A word from me

When rules aren't followed, I think it's natural to want to add a line. I kept adding lines until my skills exceeded 500 lines and grew into 12 separate ones.

However, the line I added wasn't read with the same level of attention as the other lines. Even after splitting them, they grew by about 600 lines in just over a month. The urge to add more probably won't stop. If it won't stop, I think the turning point is whether you can pause to ask a question before adding.

As someone who was just an ordinary ChatGPT user six months ago, I've learned from growing 12 skills to over 500 lines each—totaling 9,770 lines—that the issue of length isn't about how much you've written, but about how much you are forcing it to read every single time.

Out of your instructions, how many lines actually need to be read every time?

8. For those who want to know more

For those who want to know what to write in the CLAUDE.md that gets read every time

• [How to Write CLAUDE.md] Embedding a Personal AI Secretary Persona and Role into Claude Code—Non-Engineer AI Agent Building Course Part 5 — This is the episode where I wrote the 'map' side of Chapter 3

For those who want to stop relying on text and start using mechanical constraints

• [49 Recommended Claude Code Hooks] A True Record of Pushing Back Against AI Agent 'I Can'ts' for 4 Months—Design That Stopped 1,761 Times After Running 390,876 Times — A record of 49 hooks from Chapter 6 lined up

For those who want to know where to split skills and how to draw the line

• [True Record] Skills Don't Break Even When They Increase to 80—It's Not About Quantity, It's About Granularity. 3 Criteria for 'One Skill, One Responsibility' — These are the criteria for what to include in a single skill

The next day, Saturday, 9/19 at 10:00 AM, I will release a true record of running the automation I built with Claude Code on Windows for 5 months.

Until a little while ago, I was just an ordinary user who used ChatGPT to summarize meeting minutes.

Since then, in between my main work, I have been growing my own personal AI agent, 'NiKo.' My Claude usage is now in the top 8% worldwide.

At NiKoKobo, I write about that trial and error at a resolution that 'the me from 6 months ago could understand.' Living in India, managing a local subsidiary of a Japanese manufacturer.

#ClaudeCode #AIAgent #ChatGPT #NonEngineer #GenerativeAI #Claude #AIImplementation #AIUsage #AIEfficiency #Prompt