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.
Top comments (0)