Coding agents become much more useful when you stop treating the prompt as a request for code and start treating it as a specification for a change.
A request such as:
Fix the login problem.
contains almost none of the information required to review the resulting implementation.
Which login problem?
Which files may change?
What behavior must remain unchanged?
How will we know the fix actually works?
For work inside an existing repository, a simple four-part framework is usually more useful:
Task → Context → Scope → Acceptance Criteria
Start with the smallest useful description of what should change.
Instead of:
Add filtering.
Try:
Task:
Add a Completed / Incomplete filter to the task-list page.
Expected behavior:
- "Completed" shows only completed tasks.
- "Incomplete" shows only incomplete tasks.
- "All" remains the default.
- The filter must work together with the existing text search.
The agent now has a behavior to implement instead of a vague direction.
You usually do not need to paste half the codebase.
Ask the agent to inspect the relevant project files first:
Context:
- Read src/components/TaskList.tsx.
- Read src/hooks/useTasks.ts.
- Follow the patterns already used by the project.
- Check the project's existing instructions before making changes.
The goal is not to dictate the implementation.
The goal is to make the agent learn the local conventions before inventing new ones.
Permanent conventions are better stored in project-level instructions when your coding tool supports them.
For example:
- Use the package manager already configured in the repository.
- Do not edit generated files.
- Discover validation commands from project configuration.
- Preserve unrelated changes.
This keeps individual prompts focused on the task.
A coding agent can solve the right problem in the wrong way.
One common failure mode is unnecessary expansion of scope: changing an API, introducing another dependency, restructuring adjacent modules, or “cleaning up” unrelated code.
Explicit constraints reduce that risk:
Scope:
- Modify only src/components/ and src/hooks/.
- Do not change the backend API.
- Do not add a dependency without asking.
- Do not refactor unrelated code.
This has another benefit: smaller diffs are easier for humans to review.
“Make sure it works” is not an acceptance criterion.
Use an observable check:
Acceptance criteria:
- Existing task-list behavior still works.
- Filtering and text search work simultaneously.
- Add a test for the combined behavior if this project has automated tests.
- Run the relevant validation command.
- If the command is unknown, inspect project configuration instead of guessing.
- If validation cannot be run, say so explicitly.
The last two lines matter.
An agent should not infer that a repository uses npm test, pytest, cargo test, or any other command purely because that command is common.
Let the repository define the verification process.
A bug-fixing prompt should give the agent enough information to distinguish a diagnosis from a guess.
A useful shape is:
Problem:
[What the user sees]
Steps to reproduce:
1. [...]
2. [...]
3. [...]
Expected:
[...]
Actual:
[...]
Evidence:
[error message or relevant log]
Task:
Identify the most likely root cause from the code and evidence.
If the cause cannot be confirmed, state what information is missing.
Apply the smallest change that addresses the root cause.
Run the relevant checks afterward.
The important sentence is not “fix the bug.”
It is:
Identify the root cause from the available evidence.
That discourages patches that merely hide the symptom.
A refactoring prompt is different because the goal is internal change without external change.
Define what must remain invariant:
Goal:
Refactor [module] without changing observable behavior.
Must remain unchanged:
- Public API.
- Existing outputs.
- Known edge-case behavior.
- Existing tests.
Allowed changes:
- Internal organization.
- Function extraction.
- Naming.
- Removing duplication.
- Simplifying conditions.
Do not:
- Add features.
- Fix unrelated bugs.
- Change tests merely to make the refactor pass.
This makes the distinction between “better internals” and “different software” explicit.
A useful mental model is:
Feature work: specify the new behavior.
Bug fixing: specify the evidence.
Refactoring: specify the invariants.
All three still need scope and verification.
After the change, ask the agent to return something short and auditable:
When finished, report:
1. Files changed.
2. What changed.
3. Validation commands actually executed.
4. Results.
5. Any assumption you had to make.
6. Anything you could not verify.
This is more useful than asking for a long description of the model's internal reasoning.
You want evidence about the work product.
The best coding prompt is not necessarily the longest one.
A 500-word prompt with no acceptance criteria can still produce a risky change.
A much shorter prompt containing:
can be substantially easier to trust.
Coding agents do not remove the need for review.
They make it more important to define what should be reviewed.
The practical goal is therefore not to write a “perfect AI prompt.”
It is to create a task that is constrained enough to implement and specific enough to verify.
Full Arabic guide and reusable prompt templates:
[[AICodeSmart](https://www.aicodesmart.com/cursor-claude-code-prompts/)]