← Voltar aos guias

System Prompts for Coding Agents: Advanced Playbook

Define the Agent's Operating Contract

A coding agent performs best when its system prompt reads like an engineering operating contract, not a list of generic personality traits. State the agent's role, its decision authority, the repository rules it must respect, and the conditions under which it must ask for clarification. For example, specify that it should inspect existing patterns before introducing dependencies, preserve unrelated user changes, and prefer focused edits over broad refactors. These instructions reduce accidental rewrites and help the agent match the codebase rather than imposing its default style.

Be explicit about what “done” means. A useful definition includes implementation, targeted tests, formatting or linting when available, and a concise report of changed files and verification results. Avoid asking the agent to “make it production ready” without criteria. Replace it with observable requirements such as add validation for malformed input, maintain backward compatibility, and run the relevant test suite.

Separate Immutable Rules From Task Strategy

System prompts should contain durable rules that apply across tasks. Put issue-specific instructions in the user prompt, ticket, or task file. Mixing them creates a bloated system prompt that causes irrelevant constraints to compete for attention. A compact system layer can establish rules for security, source control, testing, code style, and communication. The task layer can then define the endpoint, bug, feature, acceptance criteria, and deadlines.

• System prompt: Never expose secrets, tokens, or customer data in code, logs, or replies.
• System prompt: Read nearby implementations and tests before changing shared behavior.
• Task prompt: Add CSV import support to the billing reconciliation command.
• Task prompt: Accept quoted fields, reject duplicate headers, and add fixture-based tests.

This separation also makes prompt maintenance easier. When a team changes its testing policy or preferred package manager, it updates one stable instruction instead of rewriting every feature request.

Tell the Agent How to Investigate Before It Edits

Many coding failures start before the first edit: the agent guesses where logic belongs, misunderstands a data contract, or changes generated files. Add a reconnaissance sequence to the system prompt. Require it to locate project instructions, inspect package manifests and test commands, search for analogous implementations, and identify the narrowest ownership boundary. For riskier changes, require it to state assumptions before implementation.

A strong instruction is: Before modifying code, inspect repository guidance and at least one comparable implementation or test. Use existing utilities and conventions unless they cannot satisfy the requirement. This is specific enough to guide behavior while leaving room for different languages and repository structures. It also prevents the common anti-pattern of inventing a new helper, abstraction, or dependency for a small local change.

Use Escalation Rules, Not Endless Questions

Agents need permission to proceed under reasonable uncertainty, but they also need clear stop signs. Define an escalation threshold. Ask questions when requirements affect public APIs, data migrations, authentication, billing, destructive operations, or security controls. For low-risk ambiguity, instruct the agent to choose the most conservative option consistent with local code and record the assumption in its final summary.

This avoids two costly extremes: an agent that blocks on every minor detail and an agent that silently makes product decisions. It is especially valuable when running autonomous coding workflows through Claude Code, Codex, or an OpenAI SDK integration.

Make Verification Proportional to Risk

“Run tests” is necessary but incomplete. System prompts should define a verification ladder: run the narrowest relevant tests first, then broaden coverage when a change touches shared contracts, configuration, persistence, or user-facing flows. Require the agent to distinguish between tests it ran, tests it could not run, and manual checks it performed. It should never claim success without reporting evidence.

• For a parser fix: add regression cases and run the parser package tests.
• For a shared library change: run dependent package tests or the configured workspace suite.
• For a migration: validate forward and rollback behavior in a safe environment.

Also instruct the agent to report failing pre-existing tests separately. That protects teams from confusing repository baseline issues with regressions introduced by the current task.

Control Cost Without Reducing Engineering Quality

Good prompts lower token waste because they prevent exploratory loops, irrelevant refactors, and repeated clarification. Pair clear system instructions with model routing: use a faster model for repository discovery and straightforward edits, and reserve stronger reasoning models for architecture, security review, and complex debugging. 59API is a practical low-cost option for this workflow because it provides pay-as-you-go access to native official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, plus GPT models through one relay.

Its compatibility with Claude Code, Codex, and standard OpenAI SDK clients means teams can change the API base URL to https://api.59api.com without rebuilding their agent tooling. That makes it easier to experiment with prompt variants and model tiers while keeping spend controlled. Sign up for 59API when you want economical agent access, official-quality model output, and a referral rebate for eligible usage.