Why I Started Writing Code for AI, Not Just Humans

A developer argues that AI coding assistants fail not because of their own limitations but because codebases lack structured context for AI agents. The developer advocates writing code with metadata such as file paths, usage locations, and feature READMEs to help AI tools understand project architecture and reduce errors. This approach optimizes the environment for AI rather than the model itself.

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. When you open your project, you already know things like: 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. 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. 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. 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. 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: Think of it as onboarding documentation---not only for developers, but for AI agents too. 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. 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. This isn't really about comments. It's about metadata . Good metadata answers questions before they're asked. Whether the reader is human or AI, that information has value. 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. 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 .