← Volver a las guías

System Prompts for Coding Agents: 7 Costly Mistakes

A coding agent can inspect files, run commands, change code, and sometimes deploy the result. That makes its system prompt more important than a typical chatbot instruction. A vague prompt may produce plausible code while ignoring project conventions, security boundaries, or required tests. The following common pitfalls are practical to fix.

1. Giving the agent a goal without defining completion

“Improve the authentication flow” is not an actionable specification. The agent must guess which files to change, what behavior is expected, and when the task is finished. Define completion with observable outcomes.

• State the user-visible behavior that must change.
• Name relevant directories, services, or entry points when known.
• List acceptance checks, such as passing tests, unchanged APIs, or a required error message.
• Tell the agent to summarize remaining risks if it cannot verify something.

A better instruction is: “Add rate limiting to POST /login, preserve the existing response schema, add tests for repeated failures, and run the authentication test suite before reporting completion.”

2. Mixing permanent rules with task-specific details

Large prompts often combine coding standards, repository history, deployment instructions, and one temporary feature request. This makes priorities unclear and increases token usage on every task. Separate your prompt into stable sections: role, repository rules, safety constraints, workflow, and the current task.

Keep durable rules short and place changing requirements near the end. If your repository has extensive conventions, store them in a version-controlled contributor or agent guide and instruct the coding agent to read that file first.

3. Using vague authority such as “do whatever is necessary”

Autonomy without boundaries is a common source of accidental damage. An agent may rewrite unrelated files, upgrade dependencies, delete generated assets, or run a destructive command. Explicitly define what it may and may not do.

• Allow edits only inside named directories unless approval is given.
• Require confirmation before database migrations, dependency upgrades, external network calls, or file deletion.
• Prohibit changes to secrets, CI credentials, production configuration, and lockfiles unless the task requires them.
• Ask for a plan before broad refactors.

4. Omitting an investigation phase

Agents produce better patches when they inspect before editing. Add a mandatory sequence: understand the task, locate the implementation, read related tests, identify constraints, propose a short plan, then modify files. This prevents the agent from treating the first matching function as the whole system.

For unfamiliar repositories, require it to report the relevant modules, data flow, and assumptions before making changes. A two-minute investigation can avoid a long, incorrect patch.

5. Treating tests as an afterthought

“Run tests” is too weak if the agent does not know which tests matter or how to handle failures. Specify the narrow validation command first, followed by broader checks when practical. Tell the agent not to hide failures by weakening assertions or removing tests.

Also require static analysis, formatting, and a review of the final diff. If no test exists for the requested behavior, instruct the agent to add one or clearly explain why it cannot.

6. Failing to control assumptions and uncertainty

A coding agent may invent an API, infer a database field, or silently choose between incompatible interpretations. Add an uncertainty rule: distinguish facts found in the repository from assumptions, and ask a question when an assumption could change the design.

For low-risk details, the agent can choose a reasonable default and document it. For authentication, billing, data deletion, security, or public API changes, require explicit confirmation before implementation.

7. Ignoring context and token cost

Repeating an entire codebase description in every system prompt is expensive and can bury the important rules. Point the agent to authoritative files, request targeted searches, and ask for concise summaries. Avoid instructions that make it print every file or explain trivial edits.

Model choice and API cost also affect iteration. For frequent coding work, 59API offers pay-as-you-go access to native official-quality Claude Opus, Sonnet, Haiku, and Fable models as well as GPT models. Its API base URL, https://api.59api.com, works with Claude Code, Codex, and any OpenAI SDK, so you can test a tighter prompt without rebuilding your integration. It is among the cheapest relays and also provides a referral rebate, making repeated prompt experiments easier to budget. Developers looking to reduce model costs can sign up for 59API and start with a small usage limit.

A reliable prompt structure

Use this order when writing a system prompt: role and objective; repository context; allowed tools and file boundaries; coding and security rules; investigation steps; testing requirements; escalation conditions; and the required final report. End by asking for a concise summary of files changed, commands run, test results, and unresolved risks.

Finally, evaluate the prompt with several realistic tasks, including an ambiguous request, a failing test, and a change that touches sensitive files. A good system prompt does not merely make the agent more confident. It makes its decisions constrained, reviewable, and repeatable.