{"slug": "why-i-started-writing-code-for-ai-not-just-humans", "title": "Why I Started Writing Code for AI, Not Just Humans", "summary": "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.", "body_md": "What if the biggest problem with AI coding assistants isn't the\n\nAI... but the way we write our code?\n\nIf you've ever asked Claude Code, Codex, Cursor, or ChatGPT to modify a\n\nfeature, you've probably seen this happen.\n\nThe AI confidently changes a component.\n\nEverything looks perfect.\n\nThen another page breaks because the component was used somewhere the AI\n\nnever checked.\n\nYou blame the AI.\n\nI used to do the same.\n\nThen I realized something.\n\n**The AI wasn't missing programming knowledge. It was missing context.**\n\nThat changed how I write code.\n\nToday, I don't just write code for the next developer.\n\n**I write code for the next AI agent that opens my repository.**\n\nWhen you open your project, you already know things like:\n\nAn AI doesn't.\n\nEvery task starts with exploration.\n\nIt searches.\n\nIt opens files.\n\nIt follows imports.\n\nIt tries to reconstruct your architecture from scratch.\n\nBecause every model has a limited context window and reasoning budget,\n\nevery unnecessary search increases the chance that something important\n\ngets missed.\n\nThe goal isn't to make AI smarter.\n\nThe goal is to make your project easier to understand.\n\nStart every important file with its project path.\n\n```\n// File: /src/components/common/Button.tsx\n```\n\nInside VS Code, this isn't always necessary because agents already know\n\nyour workspace.\n\nBut when you paste a file into ChatGPT or Claude on the web, this tiny\n\ncomment immediately tells the model where the file belongs, what\n\nconventions you're following, and how imports are likely organized.\n\nOne line.\n\nA surprising amount of context.\n\nOne thing AI agents regularly miss is downstream impact.\n\nThe parent imports the child.\n\nThe child doesn't know who imports it.\n\nSo add that information.\n\n```\n// Used in:\n// - /src/pages/Login.tsx\n// - /src/pages/Register.tsx\n// - /src/pages/Profile.tsx\n```\n\nNow the AI knows exactly where changes should be verified before\n\ndeclaring the task complete.\n\nThat isn't just useful for AI.\n\nFuture-you will thank you too.\n\nDon't make an AI read 500 lines just to answer:\n\n*\"What does this file do?\"*\n\nInstead:\n\n```\n/**\n * Handles login, registration,\n * validation and API submission.\n */\n```\n\nNow the model can quickly decide whether this file matters before\n\nspending valuable context reading the implementation.\n\nThis has become one of my favorite habits.\n\nInstead of making an AI inspect twenty files just to understand\n\nAuthentication, give it an entry point.\n\n```\n/features/auth/README.md\n/features/dashboard/README.md\n/features/payroll/README.md\n```\n\nA good feature README should answer:\n\nThink of it as onboarding documentation---not only for developers, but\n\nfor AI agents too.\n\nTell the AI what **not** to do.\n\n```\n/**\n * Never call authentication APIs directly.\n * Always use authService.\n */\n```\n\nThe fewer assumptions an AI has to make, the fewer mistakes it will\n\nmake.\n\nIf changing one hook affects five screens, don't hide that knowledge.\n\nWrite it down.\n\n```\n/**\n * Affects:\n * - Dashboard\n * - Notifications\n * - Analytics\n */\n```\n\nNow impact analysis becomes dramatically easier.\n\nThis isn't really about comments.\n\nIt's about **metadata**.\n\nGood metadata answers questions before they're asked.\n\nWhether the reader is human or AI, that information has value.\n\nIn my experience, yes.\n\nNot because the AI suddenly becomes more intelligent.\n\nBecause it spends less time guessing.\n\nModern AI coding assistants already know how to write code.\n\nWhat they often lack is project-specific knowledge.\n\nThe more structured context you provide, the better their decisions\n\nbecome.\n\nYou're not optimizing the model.\n\nYou're optimizing the environment the model works in.\n\nFor years we've optimized code for humans.\n\nReadable names.\n\nClean architecture.\n\nGood documentation.\n\nNow there's another reader sitting beside us.\n\nIt writes code.\n\nReviews pull requests.\n\nRefactors components.\n\nFinds bugs.\n\nThat reader is AI.\n\nMaybe it's time we started designing our codebases with both audiences\n\nin mind.\n\nThe future isn't just clean code.\n\nIt's **AI-readable code**.", "url": "https://wpnews.pro/news/why-i-started-writing-code-for-ai-not-just-humans", "canonical_source": "https://dev.to/ganesh_sharmaz/ai-first-codebases-why-every-developer-should-start-writing-comments-for-ai-agents-3a2j", "published_at": "2026-07-13 12:18:41+00:00", "updated_at": "2026-07-13 12:46:27.074988+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "ai-agents", "large-language-models", "ai-products"], "entities": ["Claude Code", "Codex", "Cursor", "ChatGPT", "VS Code"], "alternates": {"html": "https://wpnews.pro/news/why-i-started-writing-code-for-ai-not-just-humans", "markdown": "https://wpnews.pro/news/why-i-started-writing-code-for-ai-not-just-humans.md", "text": "https://wpnews.pro/news/why-i-started-writing-code-for-ai-not-just-humans.txt", "jsonld": "https://wpnews.pro/news/why-i-started-writing-code-for-ai-not-just-humans.jsonld"}}