How to Prompt Coding Agents Without Losing Control of Your Codebase

Samir Sobhy — Tue, 08 Sep 2026 18:46:14 +0000

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

1. Task: define observable behavior

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.

2. Context: make the repository part of the prompt

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.

3. Scope: control the size of the diff

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.

4. Acceptance criteria: make verification part of the task

“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.

Debugging requires evidence

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.

Refactoring needs the opposite constraint

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.

Feature, bug fix, and refactor are three different conversations

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.

The final prompt should request a report

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.

Prompt quality is not prompt length

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:

a precise task,
relevant context,
strict scope,
and a real verification method

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/)]

From LLM to AI Agent: What Actually Happens When an Agent Uses a Tool?

Samir Sobhy — Fri, 04 Sep 2026 19:20:55 +0000

An LLM can generate an answer.

But an AI Agent needs to do something beyond generating text.

The important distinction is the layer around the model:

LLM → Instructions → Tools → State/Memory → Permissions → Control Loop

For example, imagine an agent that needs to retrieve the current weather.

The LLM itself does not magically call the weather API.

A typical flow looks like this:

The application defines an available tool.
The model decides that the tool is required.
The model returns a structured tool call.
The application executes the actual API request.
The API result is returned to the model.
The agent evaluates the result.
It either finishes the task or chooses another action.
So the architecture is closer to:

User
↓
Goal + Instructions + Context
↓
AI Agent
↓
LLM chooses next action
↓
Tool required?
├── No → Continue / Finish
│
└── Yes
↓
Tool / API
↓
Observation
↓
Agent evaluates result
↓
Next action / Final answer

This is also why I would not start every project by building a sophisticated autonomous agent.

If the workflow is predictable, a traditional workflow can be simpler,cheaper, and easier to debug.

Use an Agent when the path itself needs to change according to the context and the results of previous actions.

Another important engineering decision is permissions.

If an agent can send emails, modify records, access databases, or trigger external APIs, its capabilities should be limited to what the task actually requires.

For production systems, I would also consider:

Maximum iterations
Execution timeouts
Tool failure handling
Logging
Human approval for sensitive actions
Cost limits
Prompt-injection defenses

The interesting part of AI Agents isn't simply giving an LLM more tools.

It's designing the system around the model so that decision → action → observation → next decision happens safely and predictably.

I wrote a practical Arabic guide covering the architecture, Agent vs Workflow, Single-Agent vs Multi-Agent, Function Calling, Python/CrewAI, testing, cost, and security:

https://www.aicodesmart.com/ai-agents-explained-how-to-build/

Developer takeaway:
Don't ask "How can I make this an Agent?" first.

Ask:

"Does this problem actually require dynamic decision-making?"

ai #programming #agents #python #automation

DEV Community: Samir Sobhy