{"slug": "ai-coding-changed-the-bottleneck-it-isn-t-writing-code-anymore", "title": "AI Coding Changed the Bottleneck. It Isn't Writing Code Anymore.", "summary": "A developer argues that AI coding agents have shifted the bottleneck from code generation to context engineering, proposing that repositories expose project-level instruction files such as AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md so agents inherit the same engineering context a human would need. The approach emphasizes documenting decisions an agent cannot infer from the code alone, while warning that overloading a single instruction file becomes counterproductive.", "body_md": "A few years ago, when we talked about AI-assisted programming, the workflow was fairly simple.\n\nOpen your editor.\n\nWrite some code.\n\nAsk the AI to complete it.\n\nAccept the suggestion.\n\nMaybe ask it to write a test.\n\nThat model is changing.\n\nToday's coding agents can inspect a repository, understand relationships between files, run commands, modify multiple files, execute tests, investigate failures, and continue working based on the results.\n\nThe interesting problem is no longer:\n\n**\"Can AI write this code?\"**\n\nIncreasingly, the problem is:\n\n**\"Does the AI have enough context to write the *right* code?\"**\n\nThat distinction matters.\n\nAnd it has led us to think about AI-assisted development less as a prompting problem and more as a **harness engineering problem**.\n\nConsider a fairly ordinary backend task.\n\nYou receive a Jira ticket:\n\nAdd support for a new API parameter.\n\nA human engineer doesn't immediately start typing.\n\nThey usually do something like:\n\nA capable coding agent can perform many of these steps.\n\nBut there is a catch.\n\nThe agent doesn't automatically know all the things that an experienced engineer has accumulated through months of working on the project.\n\nIt may not know that:\n\nThis is where **context engineering** becomes important.\n\nInstead of giving an AI agent a giant prompt every time we start a task, we can make the repository itself provide much of the context.\n\nThink of the repository as having a layer specifically designed for AI-assisted development.\n\nFor example:\n\n```\nrepository/\n│\n├── AGENTS.md\n├── CLAUDE.md\n├── .github/\n│   └── copilot-instructions.md\n│\n├── specs/\n│   ├── JIRA-1234.md\n│   ├── JIRA-1278.md\n│   └── JIRA-1302.md\n│\n├── src/\n├── tests/\n├── scripts/\n└── README.md\n```\n\nThe exact filenames aren't important.\n\nThe important idea is that **the agent has access to the same engineering context that a human engineer would need.**\n\nModern coding tools increasingly support this pattern. GitHub's current documentation supports repository-wide instructions through `.github/copilot-instructions.md`, path-specific instructions, and agent instructions such as `AGENTS.md` and `CLAUDE.md`.\n\nClaude Code similarly uses `CLAUDE.md` as project-level context that is automatically read when working in the repository.\n\nSo these files aren't just documentation.\n\nThey can become part of the **development interface between the codebase and the coding agent.**\n\nThe first layer is project-level instructions.\n\n```\n# Project Instructions\n\n## Architecture\n\nThis repository contains:\n- API service\n- Business logic layer\n- Data access layer\n- Background workers\n\nDo not put business logic inside API handlers.\n\n## Python\n\n- Python 3.12\n- Use async APIs where the surrounding code is async\n- Use existing project dependencies before introducing new ones\n\n## Testing\n\n- Every new behaviour requires tests\n- Run pytest before considering a task complete\n- Do not modify existing tests simply to make a new implementation pass\n\n## API changes\n\n- Maintain backwards compatibility\n- Follow existing response and error formats\n\n## Before finishing\n\n- Run relevant tests\n- Review the git diff\n- Do not modify unrelated files\n```\n\nNotice what isn't particularly useful:\n\n```\nWrite clean code.\nFollow best practices.\nUse good naming.\nWrite maintainable software.\n```\n\nAn AI agent already knows these phrases.\n\nThe useful information is the stuff it **cannot reliably infer from the code alone**.\n\n\"This service uses X for authentication because Y depends on it. Do not replace it with Z.\"\n\nThat's valuable.\n\nVS Code's current guidance makes essentially the same point: project instructions are most useful when they document decisions an agent cannot reliably infer from the codebase.\n\nThere's a temptation to keep adding everything to `CLAUDE.md`.\n\nThat can become counterproductive.\n\nA good instruction file should answer:\n\n**\"What does an engineer need to know before touching this repository?\"**\n\nNot:\n\n**\"Can we document the entire repository in one Markdown file?\"**\n\nKeep stable, high-value information there:\n\nPut task-specific information somewhere else.\n\nThat's where `specs/` becomes useful.\n\nOne of the biggest problems with AI coding is that the prompt often contains too little information.\n\nA Jira ticket might contain the actual requirement, but the agent doesn't necessarily have convenient access to the entire ticket conversation, linked issues, acceptance criteria, or decisions made during refinement.\n\nOne approach is to maintain a Markdown representation of the relevant specification.\n\n```\nspecs/\n├── JIRA-1234.md\n├── JIRA-1235.md\n└── JIRA-1236.md\n```\n\nA specification might look like:\n\n```\n# JIRA-1234\n\n## Summary\n\nAdd support for X to the Voice Gateway.\n\n## Requirements\n\n- Accept X through the websocket API\n- Preserve existing clients\n- X must be optional\n- Default behaviour must remain unchanged\n\n## Acceptance Criteria\n\n- Existing requests continue to work\n- New requests support X\n- Invalid X values return the existing validation error\n- Unit tests cover both paths\n\n## Technical Notes\n\nThe downstream NLU service already supports X.\n\nDo not modify the NLU integration.\n\n## References\n\n- JIRA: JIRA-1234\n- Related: JIRA-1189\n```\n\nNow the agent isn't starting with:\n\n\"Implement JIRA-1234.\"\n\nIt starts with an actual specification.\n\nThat's a huge difference.\n\nOne of the mistakes I see with AI-assisted development is treating context as one enormous prompt.\n\nI'd rather think of it as layers.\n\n```\n                 ┌──────────────────────┐\n                 │       Task Spec      │\n                 │       specs/*.md     │\n                 └──────────┬───────────┘\n                            │\n                 ┌──────────▼───────────┐\n                 │   Project Context    │\n                 │ AGENTS.md / CLAUDE.md│\n                 └──────────┬───────────┘\n                            │\n                 ┌──────────▼───────────┐\n                 │     Codebase         │\n                 │ source + tests       │\n                 └──────────┬───────────┘\n                            │\n                 ┌──────────▼───────────┐\n                 │   Agent + Tools      │\n                 │ shell / git / tests  │\n                 └──────────────────────┘\n```\n\nEach layer answers a different question.\n\n**How should I work?**\n\n**What am I supposed to build?**\n\n**How does the existing system work?**\n\n**How can I verify that my changes work?**\n\nThis is much closer to how a human engineer actually works.\n\nThe next step is important.\n\nAn AI coding agent becomes significantly more useful when it can interact with the development environment.\n\n```\nRead files\n   ↓\nUnderstand architecture\n   ↓\nModify code\n   ↓\nRun tests\n   ↓\nRead failures\n   ↓\nModify code\n   ↓\nRun tests again\n   ↓\nReview diff\n```\n\nThe agent isn't simply generating text anymore.\n\nIt's participating in a feedback loop.\n\nThat's why modern coding agents are fundamentally different from autocomplete.\n\nThe agent can execute commands, inspect their output and use that output to determine the next action.\n\nThis also changes how we should evaluate AI-generated code.\n\nThe question shouldn't simply be:\n\n\"Did the model generate good code?\"\n\nIt should be:\n\n\"Can the system reliably detect when the generated code is wrong?\"\n\nThis is probably the most important change in my own thinking about AI-assisted development.\n\nIf generating code becomes cheap, **verification becomes expensive**.\n\nSuppose an agent writes 300 lines of code in a few minutes.\n\nThat's great.\n\nBut if reviewing those 300 lines takes an engineer 45 minutes, the bottleneck has moved.\n\nAnd if the engineer doesn't have good tests, the problem becomes even worse.\n\nSo the coding harness should provide strong feedback loops.\n\nAt minimum:\n\n```\nImplementation\n     ↓\nLint\n     ↓\nUnit tests\n     ↓\nIntegration tests\n     ↓\nType checks\n     ↓\nBuild\n     ↓\nDiff review\n```\n\nThe agent should be able to run these checks itself.\n\nMore importantly, failures should be useful.\n\nCompare:\n\n```\nTests failed.\n```\n\nwith:\n\n```\ntest_api_returns_existing_error_format\nAssertionError:\nExpected HTTP 400\nReceived HTTP 500\n\nResponse:\n{\"error\": \"...\"}\n\nExpected:\n{\"code\": \"INVALID_PARAMETER\", ...}\n```\n\nThe second output gives the agent something it can reason about.\n\nGood engineering infrastructure becomes **feedback infrastructure for the AI agent**.\n\nThere's another important idea here.\n\nWe don't actually want an autonomous agent with unlimited freedom.\n\nWe want an agent operating inside a set of boundaries.\n\n```\n                    ┌───────────────┐\n                    │     Agent     │\n                    └───────┬───────┘\n                            │\n             ┌──────────────┼──────────────┐\n             │              │              │\n             ▼              ▼              ▼\n        Instructions     Tools          Tests\n             │              │              │\n             └──────────────┼──────────────┘\n                            ▼\n                       Constraints\n                            │\n                            ▼\n                         Codebase\n```\n\nThe harness defines things like:\n\nThis is why I like the term **coding harness**.\n\nWe're not simply asking an LLM to write software.\n\nWe're designing an environment in which an AI agent can safely perform software engineering work.\n\nThis idea is increasingly being discussed as \"harness engineering\": designing constraints, feedback loops and quality gates around coding agents rather than focusing solely on the model itself.\n\nHere's another useful pattern.\n\nSuppose the agent makes a mistake.\n\nDon't use library X here. This project uses library Y because X doesn't support our async execution model.\n\nYou could simply correct the agent and continue.\n\nBut that means you'll probably have to make the same correction again.\n\nInstead, turn the correction into durable project knowledge.\n\n```\n## Important\n\nDo not use library X for HTTP requests.\n\nThe service uses library Y because the request path is asynchronous.\n```\n\nNow the next agent session starts with that knowledge.\n\nAnthropic itself recommends treating `CLAUDE.md` as shared project memory and updating it when the agent repeatedly makes a mistake.\n\nThis creates an interesting feedback loop:\n\n```\nAgent makes mistake\n       ↓\nEngineer corrects it\n       ↓\nCorrection becomes project guidance\n       ↓\nFuture agent sessions see it\n       ↓\nSame mistake becomes less likely\n```\n\nThe repository gradually becomes better at working with AI.\n\nThis doesn't mean developers disappear.\n\nIt changes where their time goes.\n\nInstead of spending most of the time on:\n\n```\nTyping → debugging → typing → debugging\n```\n\nthe workflow starts looking more like:\n\n```\nUnderstand requirement\n        ↓\nDefine constraints\n        ↓\nProvide context\n        ↓\nDelegate implementation\n        ↓\nReview\n        ↓\nRun verification\n        ↓\nCorrect\n        ↓\nCapture important learning\n```\n\nThe developer increasingly becomes the person designing and supervising the system.\n\nThat requires stronger engineering fundamentals, not weaker ones.\n\nYou still need to understand:\n\nIn fact, when an AI can produce code very quickly, understanding whether that code belongs in the system becomes more important.\n\nHere's a workflow that I think works well for an existing engineering team.\n\n```\nCLAUDE.md\nAGENTS.md\n.github/copilot-instructions.md\n```\n\nDon't duplicate everything blindly across them. Keep the instructions relevant to the tools your team actually uses.\n\n```\nspecs/\n    JIRA-1234.md\n    JIRA-1235.md\n```\n\nConvert important requirements into Markdown that an agent can consume.\n\nInstead of:\n\nImplement JIRA-1234.\n\nTry:\n\nRead `specs/JIRA-1234.md`.\n\nInspect the relevant parts of the codebase.\n\nIdentify the files that would need to change and explain your proposed implementation.\n\nDon't modify anything yet.\n\nThis gives you a chance to catch a misunderstanding **before code is generated**.\n\nOnce the approach looks right:\n\nImplement the proposed change. Follow the repository instructions and the specification. Add or update tests.\n\n```\nRun tests.\nRun linting.\nRun type checks.\nReview the diff.\n```\n\nThe human still owns the final decision.\n\nThe agent can propose.\n\nThe agent can implement.\n\nThe agent can test.\n\nBut the engineer decides whether the change belongs in the system.\n\nI don't think the biggest productivity improvement comes from having a better prompt.\n\nIt comes from reducing the amount of information that has to be supplied manually every time.\n\nImagine two developers.\n\nEvery task starts with:\n\nHere's the architecture...\n\nHere's how our tests work...\n\nRemember that this module...\n\nWe don't use that library...\n\nHere's the Jira description...\n\nHere's the relevant code...\n\nTheir repository already contains:\n\n```\nAGENTS.md\nCLAUDE.md\n.github/copilot-instructions.md\nspecs/\ntests/\nREADME.md\n```\n\nThe agent can discover most of that itself.\n\nDeveloper B isn't necessarily using a smarter model.\n\nThey're using a **better environment**.\n\nThat's the part I find most interesting.\n\nWe're entering a phase where generating a reasonable first implementation is becoming increasingly cheap.\n\nThat doesn't mean software engineering is becoming trivial.\n\nIt means the expensive parts are moving.\n\nFrom:\n\n**Writing code**\n\ntowards:\n\n**Understanding the problem**\n\n**Providing the right context**\n\n**Making architectural decisions**\n\n**Defining constraints**\n\n**Building reliable feedback loops**\n\n**Reviewing the result**\n\n**Knowing when the AI is wrong**\n\nAnd perhaps most importantly:\n\n**Turning every correction into knowledge that the next AI session can use.**\n\nThat's why I think the next generation of developer tooling isn't just going to be about better models.\n\nIt will be about **better coding environments for those models**.\n\nThe winning setup won't simply be:\n\nDeveloper + LLM\n\nIt will be:\n\n**Developer + Codebase + Context + Tools + Tests + AI agent**\n\nThe model is only one component.\n\nThe **harness around it** is what makes it useful.\n\nAnd once writing code stops being the bottleneck, that's where the interesting engineering work begins.", "url": "https://wpnews.pro/news/ai-coding-changed-the-bottleneck-it-isn-t-writing-code-anymore", "canonical_source": "https://dev.to/piyushatghara/ai-coding-changed-the-bottleneck-it-isnt-writing-code-anymore-4o", "published_at": "2026-10-02 04:56:00+00:00", "updated_at": "2026-10-02 05:14:37.611789+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols", "artificial-intelligence"], "entities": ["GitHub", "GitHub Copilot", "Claude Code", "VS Code", "Jira"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ai-coding-changed-the-bottleneck-it-isn-t-writing-code-anymore", "markdown": "https://wpnews.pro/news/ai-coding-changed-the-bottleneck-it-isn-t-writing-code-anymore.md", "text": "https://wpnews.pro/news/ai-coding-changed-the-bottleneck-it-isn-t-writing-code-anymore.txt", "jsonld": "https://wpnews.pro/news/ai-coding-changed-the-bottleneck-it-isn-t-writing-code-anymore.jsonld"}}