CODE IN TOKYO

Repository Design That Keeps Claude Code from Becoming Stupid

AI Is Smart, But Surprisingly Easy to Mislead

Recently, while using Claude Code, I have been thinking about something again.

AI is smart.

Really smart.

But at the same time, it is surprisingly easy to mislead.

And it often does not notice that it has been misled.

A human might look at something and think:

“This code looks old.”

“This documentation has not been updated.”

But AI often believes it honestly.

As a result, it starts writing code that makes you wonder:

“Why did you implement it like that?”

At first, I suspected the model’s ability.

Did Opus get worse?

Was my prompt bad?

Those can be factors, but in many cases the real cause was on the project side.

AI Lives on Context

After using Claude Code for a long time, one thing becomes clear.

AI performance is not determined only by model performance.

It depends heavily on the quality of the context it receives.

In a clean project, AI can be surprisingly smart.

In a messy project, AI can become surprisingly stupid.

That is why I now think the important question is not only:

“How do I make AI write code?”

It is also:

“How do I create an environment where AI does not get lost?”

Make ADRs the Source of Truth

In the past, I often designed things through conversation alone.

If I discussed the design with Claude and implemented it together, things usually worked out.

And in fact, they did.

The problem came one month later.

Why did we design it that way?

Why did we choose this library?

Why did we reject the other option?

Nobody remembered.

Of course, the AI did not remember either.

So I started keeping ADRs, or Architecture Decision Records.

The important part is not just creating them.

The important part is updating them.

The moment ADRs and implementation drift apart, AI starts learning from old lies.

Then it runs in the wrong direction with full confidence.

AI Needs a Map Too

Many people create a lot of documentation.

I do too.

But when documentation increases, it becomes harder to find things.

Even humans get lost.

There is no reason AI would not get lost too.

So recently, I have been placing an index file at the root of the repository.

It can be README.

It can be INDEX.md.

The point is to explain first:

“What exists where?”

I make Claude Code read that file first.

Then the amount of unnecessary exploration drops sharply.

It seems AI, like humans, gets lost when dropped into a huge unfamiliar project with no map.

Old Code Becomes Poison

This is where I learned the lesson most painfully.

I once left some mock code for a local environment in a repository.

It was no longer used.

I had simply not deleted it because it was a hassle.

Then Claude found it.

And it confidently said:

“The current system works this way.”

It did not.

That mechanism had been abandoned more than six months earlier.

But from the AI’s point of view, if code exists in the repository, it looks like an active player.

That taught me something.

AI overvalues code that exists.

So unnecessary code should not be left behind.

This is not only about readability for humans.

It is also repository hygiene for AI.

Huge Files Are Bad for Humans and AI

Recently, even when I do not go as far as microservices, I pay a lot of attention to responsibility boundaries.

If you make AI read a ten-thousand-line file, its accuracy drops.

Humans hate that too.

So I try to make boundaries clear.

This part is authentication.

This part is payment.

This part is notification.

When the boundaries are clear, AI has less to read.

When it has less to read, its accuracy improves.

In the end, a design that is easy for humans to understand is also easy for AI to understand.

Slack and Email Also Become Knowledge

Specification changes happen in Slack.

Important decisions arrive by email.

Meeting conclusions get buried in minutes.

But AI does not know any of that.

So I have AI collect that information automatically and turn it into documentation.

It gathers only the important decisions.

Then it registers them in the index.

That allows AI to follow the history of the project too.

What I Am Doing Recently

That said, it is annoying to give all of these instructions every time I log in.

So I use Claude Code’s Skill feature to automate it.

When Claude enters the project, I make it run an onboarding flow automatically:

In short, it is onboarding for AI.

When a new member joins a project, they first read design documents and operating rules.

I am making AI do the same thing.

What is interesting is that after introducing this system, the quality of AI’s answers became much more stable.

Many cases where AI suddenly starts implementing something strange are not caused by a lack of ability.

They are caused by a lack of context.

Recently, I have even created a Skill that says:

“Suggest improvements that will keep yourself smart.”

Then the AI itself finds problems such as:

It feels like I am using AI, but at the same time, half of the project is being managed by AI.

In the End, the Work Changed

The important thing is not becoming a prompt craftsman.

The important thing is creating an environment where AI does not get lost.

Maintain ADRs.

Delete unnecessary code.

Create an index.

Collect knowledge.

Then use Skills to make AI reach that knowledge automatically.

When you think about it, this is not very different from what you do when a capable new hire joins the company.

The only difference is that the new hire is AI, not human.

The essence of AI-driven development is not making AI write code.

It is preparing an environment where AI can make correct decisions.

And the better that environment becomes, the more AI turns into a surprisingly capable colleague.

Conversely, in a messy repository, even a high-performance model will get lost.

Recently, I feel like I spend more time improving Claude Code’s working environment than reviewing code.

Unexpectedly, that may be the most cost-effective kind of development.