Your Coding Agent Doesn't Need Better Prompts

The Real Danger Isn't Broken Code — It's Plausible Code

Every engineering team experimenting with AI coding agents has encountered the same insidious problem. The agent doesn't crash. It doesn't throw errors. It produces something that looks right, passes tests, and ships — only to quietly expand the product surface in a direction nobody approved.

No bug. No crash. Just drift.

This is the argument at the center of a growing conversation among developers working with agentic coding workflows: the most dangerous failure mode isn't incompetence. It's competence applied without constraint. And the fix isn't a better prompt. It's a contract.

Why Better Prompts Don't Solve the Problem

The instinct, when an AI agent drifts off-course, is to refine the prompt. Add more detail. Be more explicit. Specify edge cases. Developers have spent months iterating on increasingly elaborate system instructions, trying to box in tools like GitHub Copilot Workspace, Cursor Agent, Devin, or OpenAI's Codex.

But prompt engineering hits a ceiling fast in agentic contexts. Unlike a single-turn code completion, an agentic workflow involves multiple steps: reading files, planning changes, writing code, running tests, and iterating. At each step, the model makes micro-decisions — which file to modify, what abstraction to introduce, whether to add a helper function. These micro-decisions compound. By the time the final pull request appears, the cumulative drift can be significant, even if each individual choice seemed reasonable.

The core issue is that prompts are suggestions. They lack enforceability. They don't define boundaries the agent can't cross — they define intentions the agent might follow.

The Contract-Based Approach

The emerging alternative is to treat AI agent governance the way teams already treat API governance: with explicit, machine-readable contracts.

In practice, this means structuring a repository so that drift becomes visible before code ships, not after. Several patterns are gaining traction among early adopters:

1. Architectural Decision Records (ADRs) as Agent Context

Teams are placing ADR files directly in the repo — often in a /decisions or /docs/adr directory — and instructing agents to read them before making changes. These records define why certain patterns exist, not just what they are. When an agent proposes a change that contradicts an ADR, the violation is structurally detectable.

2. Scope Manifests

A scope manifest is a lightweight file (often YAML or JSON) that explicitly declares what a given task or feature is allowed to touch. It lists permitted files, modules, and dependencies. If the agent's diff touches anything outside the manifest, the PR is automatically flagged. Think of it as a allowlist for agent behavior.

3. Contract Tests for Product Surface

Beyond unit tests and integration tests, teams are writing contract tests that assert on the product's external surface area. New API endpoints, new CLI flags, new configuration options — any expansion of the product surface triggers a test failure unless explicitly approved. This catches the exact class of drift that functional tests miss.

4. Pre-Commit Boundary Checks

Git hooks and CI checks that validate structural constraints before code even enters review. These aren't linting rules — they're architectural boundary assertions. Tools like ArchUnit (for Java/Kotlin) and dependency-cruiser (for JavaScript/TypeScript) are being repurposed as agent guardrails.

Why This Matters Now

The shift from AI-assisted coding to AI-agentic coding is accelerating. GitHub reported that Copilot now generates nearly 46% of code in files where it's enabled. Cognition's Devin, Factory's Droids, and Google's Jules are pushing toward fully autonomous development workflows. OpenAI's Codex launched in May 2025 as a cloud-based agent that operates asynchronously in sandboxed environments.

As these tools gain autonomy, the governance gap widens. A developer reviewing a Copilot suggestion in-line can catch drift in real time. A developer reviewing a 47-file PR generated by an autonomous agent at 2 AM cannot.

'The failure mode shifts from 'the AI wrote bad code' to 'the AI wrote good code that we didn't ask for,'' as one developer framed it in a widely shared post. 'And that's a product management problem disguised as an engineering problem.'

The Organizational Dimension

Contract-based agent governance also addresses a team dynamics challenge. When an AI agent introduces a new abstraction layer or refactors a module boundary, it's making an architectural decision. Traditionally, those decisions go through tech leads or architecture review. Agentic workflows bypass that process entirely — unless the repo structure enforces it.

This is why the contract approach resonates beyond individual developers. Engineering managers and CTOs are recognizing that uncontrolled agent drift creates technical debt that's harder to detect and harder to reverse than the human-generated variety. At least when a junior developer over-engineers a solution, the code review conversation creates shared understanding. When an agent does it, there's no conversation at all.

Practical Starting Points

For teams looking to implement contract-based agent governance, the entry points are surprisingly low-friction:

• Start with surface-area tests. Write tests that assert on your public API, CLI interface, or configuration schema. These catch the highest-impact drift with minimal setup.
• Add a BOUNDARIES.md file. Define module ownership and permitted dependencies in a human-readable format that also serves as agent context.
• Use scope manifests for agent tasks. Before assigning work to an agent, declare the allowed blast radius in a structured file.
• Review diffs structurally, not just functionally. Add CI checks that flag new files, new exports, or new dependencies for mandatory human review.

Looking Ahead

The prompt-versus-contract debate mirrors an older tension in software engineering: convention versus configuration. Prompts are conventions — they work until they don't. Contracts are configuration — explicit, testable, enforceable.

As coding agents grow more capable throughout 2025, the teams that ship reliably won't be the ones with the best prompts. They'll be the ones whose repos make drift structurally impossible to ignore. The agent doesn't need to be smarter. The environment needs to be more opinionated.

The era of 'just trust the AI and review the PR' is already ending. What replaces it won't be more elaborate instructions. It will be better-structured repos — ones where the contract is the code, and the code is the contract.