What if the biggest problem with AI coding assistants isn't the

AI... but the way we write our code?

If you've ever asked Claude Code, Codex, Cursor, or ChatGPT to modify a

feature, you've probably seen this happen.

The AI confidently changes a component.

Everything looks perfect.

Then another page breaks because the component was used somewhere the AI

never checked.

You blame the AI.

I used to do the same.

Then I realized something.

The AI wasn't missing programming knowledge. It was missing context.

That changed how I write code.

Today, I don't just write code for the next developer.

I write code for the next AI agent that opens my repository.

AI Doesn't Read Your Project the Way You Do

When you open your project, you already know things like:

• where files belong


• which components are shared


• what architectural rules exist


• which hooks have side effects


• why a strange workaround exists

An AI doesn't.

Every task starts with exploration.

It searches.

It opens files.

It follows imports.

It tries to reconstruct your architecture from scratch.

Because every model has a limited context window and reasoning budget,

every unnecessary search increases the chance that something important

gets missed.

The goal isn't to make AI smarter.

The goal is to make your project easier to understand.

1. Tell the AI Where It Is

Start every important file with its project path.

// File: /src/components/common/Button.tsx

Inside VS Code, this isn't always necessary because agents already know

your workspace.

But when you paste a file into ChatGPT or Claude on the web, this tiny

comment immediately tells the model where the file belongs, what

conventions you're following, and how imports are likely organized.

One line.

A surprising amount of context.

2. Tell the AI Who Depends on This File

One thing AI agents regularly miss is downstream impact.

The parent imports the child.

The child doesn't know who imports it.

So add that information.

// Used in:

// - /src/pages/Login.tsx

// - /src/pages/Register.tsx

// - /src/pages/Profile.tsx

Now the AI knows exactly where changes should be verified before

declaring the task complete.

That isn't just useful for AI.

Future-you will thank you too.

3. Explain the Purpose Before the Implementation

Don't make an AI read 500 lines just to answer:

"What does this file do?"

Instead:

/**

 * Handles login, registration,

 * validation and API submission.

 */

Now the model can quickly decide whether this file matters before

spending valuable context reading the implementation.

4. Give Every Major Feature Its Own README

This has become one of my favorite habits.

Instead of making an AI inspect twenty files just to understand

Authentication, give it an entry point.

/features/auth/README.md

/features/dashboard/README.md

/features/payroll/README.md

A good feature README should answer:

• What is this module responsible for?


• Which files are the entry points?


• Which services does it use?


• What architectural rules should never be broken?


• Which modules depend on it?

Think of it as onboarding documentation---not only for developers, but

for AI agents too.

5. Document Constraints

Tell the AI what not to do.

/**

 * Never call authentication APIs directly.

 * Always use authService.

 */

The fewer assumptions an AI has to make, the fewer mistakes it will

make.

6. Document Side Effects

If changing one hook affects five screens, don't hide that knowledge.

Write it down.

/**

 * Affects:

 * - Dashboard

 * - Notifications

 * - Analytics

 */

Now impact analysis becomes dramatically easier.

Comments Aren't the Point

This isn't really about comments.

It's about metadata.

Good metadata answers questions before they're asked.

• What is this?


• Why does it exist?


• Who uses it?


• What should never change?


• Where should related changes happen?

Whether the reader is human or AI, that information has value.

Will This Actually Improve AI Output?

In my experience, yes.

Not because the AI suddenly becomes more intelligent.

Because it spends less time guessing.

Modern AI coding assistants already know how to write code.

What they often lack is project-specific knowledge.

The more structured context you provide, the better their decisions

become.

You're not optimizing the model.

You're optimizing the environment the model works in.

A Small Shift With Big Consequences

For years we've optimized code for humans.

Readable names.

Clean architecture.

Good documentation.

Now there's another reader sitting beside us.

It writes code.

Reviews pull requests.

Refactors components.

Finds bugs.

That reader is AI.

Maybe it's time we started designing our codebases with both audiences

in mind.

The future isn't just clean code.

It's AI-readable code.