Why a Coding Agent Needs More Than a Good Prompt

There is a natural instinct when using a coding agent:

If the result is weak, improve the prompt.

Often that works.

A clearer prompt gives the agent better context. Better context produces better implementation.

But there is a point where the problem is no longer prompt quality.

The problem is that a feature contains more knowledge than a single instruction can reasonably express.

Prompts are good at intent

Consider:

Add role-based access control to this app. We have organisations, users can belong to multiple organisations, and we need owner, admin and member roles.

That is already much better than:

Add permissions.

A capable agent can inspect the codebase and produce a substantial implementation.

But important decisions remain.

For example:

• Can a user have multiple roles in one organisation?
• Can owners be removed?
• Can the final owner leave?
• Can admins invite other admins?
• Are permissions evaluated server-side everywhere?
• What happens to active sessions after a role is revoked?
• Do historical audit records preserve the old role?
• What migration is required for existing members?

You can keep adding these details to the prompt.

Eventually the prompt becomes a specification.

That is not a failure of prompting.

It is recognition that the software capability itself contains domain knowledge.

Architecture is not merely wording

Some implementation decisions interact.

If you decide:

roles are organisation-scoped

then:

• schema design changes;
• permission checks change;
• invitations change;
• tests change;
• admin UI changes.

A good capability definition preserves those relationships.

A collection of disconnected prompt tips does not necessarily do that.

The agent needs a coherent model.

Failure modes need deliberate treatment

Happy paths are naturally prominent in prompts because humans describe what they want to happen.

Production software also needs descriptions of what happens when things do not go as planned.

Examples:

What if the same webhook arrives twice?
What if an invitation has expired?
What if two users book the final slot concurrently?
What if a user's role changes during an active session?
What if an external signing provider sends callbacks out of order?

These cases are easy to omit because they are not the feature's headline.

They are often where the engineering lives.

Tests are executable instructions

One of the most valuable ways to communicate with a coding agent is not prose.

It is a test.

A test can say:

When the last organisation owner attempts to leave, reject the operation.

That is simultaneously:

• requirement;
• example;
• acceptance criterion;
• regression protection.

This is why we think reusable software capabilities should contain both explanation and executable verification.

The prose tells the agent what the system means.

The tests tell it what must remain true.

Repository context still matters

A reusable capability should not force every application into the same shape.

An existing codebase may use:

• server actions;
• REST;
• GraphQL;
• row-level security;
• application-layer authorisation;
• different ORM conventions;
• different UI systems.

A coding agent is good at adaptation.

The capability should therefore separate:

Behaviour that must be preserved

from:

Implementation details the agent can adapt.

This is a major advantage of coding agents over traditional copy-and-paste implementation templates.

A good package for an agent contains layers

Conceptually, useful implementation context might include:

1. Scope

What is included and explicitly excluded?

2. Domain model

Which entities and states exist?

3. Invariants

What must always remain true?

4. Architecture

How should major responsibilities be separated?

5. Edge cases

Which non-happy paths deserve deliberate behaviour?

6. Implementation sequence

What order reduces integration risk?

7. Acceptance tests

How will we know the result is correct?

8. Repository adaptation instructions

What should the agent inspect before changing anything?

That is more than a clever prompt.

It is reusable implementation knowledge.

The prompt is the entry point

None of this makes prompting obsolete.

Quite the opposite.

The final interaction may still begin with a simple instruction:

Install this capability into my existing application.

The difference is that the instruction points to a body of structured knowledge the agent can use rather than forcing it to recreate that knowledge in the conversation.

As argued in You Can Ask Claude to Build It. The Question Is Why You Should Have To., this is a natural consequence of coding becoming less expensive.

The agent can do more.

That makes it more valuable to give the agent better things to work from.