Howdoyouwriteagoodsystempromptforacodingagent?

What should a coding agent’s system prompt contain?

A system prompt for a coding agent should hold what the model cannot infer from the code and what it must not get wrong, and very little else. Most agent harnesses (Claude Code, Codex, Cline, Aider, OpenCode) already ship a long built-in prompt that defines the tools and the edit format. What you write is usually a layer on top of it: a repo file such as AGENTS.md or CLAUDE.md, a rules folder, or a custom system message if you build your own agent.

The checklist below is the overlap between Anthropic’s prompting best practices, OpenAI’s GPT-4.1 and GPT-5 guides, and the AGENTS.md format:

• Commands. How to build, run tests, lint and type-check, written as exact commands.
• Conventions a model would get wrong. The library you use instead of the obvious one, the minimum language version, where migrations come from. Generic advice (“write clean code”) adds tokens and nothing else.
• Tool and action rules. When to read before answering, which edits are fine without asking, which actions need confirmation.
• Scope rules. How far a change may go: no unrequested refactors, no new dependencies without a reason.
• A definition of done. What the agent must run and check before it reports success.
• Pointers, not payloads. Paths to the docs that matter, so the agent reads them when relevant instead of carrying them in every request.

What do model makers’ prompting guides recommend?

Both major model makers recommend explicit, structured instructions with a reason attached, and both warn against shouting and contradictions.

Anthropic. The Claude guide says to be clear and explicit, and to add the motivation behind an instruction because it helps the model generalize. It recommends XML tags to separate instructions, context and examples. For agentic coding it gives sample prompt blocks for: reading files before answering (“Never speculate about code you have not opened”), avoiding overengineering, not hard-coding to pass tests (“Tests are there to verify correctness, not to define the solution”), cleaning up temporary files, and confirming before destructive or shared-system actions such as git push --force or posting to PRs. It also warns that current models are more responsive to the system prompt, so “CRITICAL: You MUST use this tool” style language from older prompts now causes overtriggering. Write “Use this tool when…” instead.

OpenAI. The GPT-4.1 guide gives three agentic reminders: keep going until the task is resolved, use tools to read files instead of guessing, and plan before each call and reflect after it. OpenAI says these raised its internal SWE-bench Verified score by close to 20%, with explicit planning adding about 4%. The same guide recommends passing tools through the API’s tools field, not pasting tool descriptions into the prompt, and placing instructions at both the start and end of long context. The GPT-5 guide, now marked archived, adds that contradictory instructions cost the model reasoning tokens. It also documents Cursor’s tuning: a “maximize thoroughness” instruction caused excess tool calls and was softened, and structured XML-style sections improved adherence.

Where the two guides meet: say what to do (not just what to avoid), give the reason, separate sections clearly, tell the agent when to act and when to ask, and ask it to verify before finishing.

What are AGENTS.md and similar repo context files?

AGENTS.md is a plain Markdown file at the repo root that coding agents load as standing instructions, described on agents.md as “a README for agents”. It has no required fields. The site suggests a project overview, build and test commands, code style, testing instructions and security notes. In a monorepo you can nest files per package: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” The format is now stewarded by the Agentic AI Foundation under the Linux Foundation, and the site lists support in Codex, Jules, Gemini CLI, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Windsurf, Cursor, Junie, Amp, Kilo Code and GitHub Copilot’s coding agent, among others.

Tool-specific equivalents work the same way:

Two measured results should shape how much you put in these files. An ETH Zurich and LogicStar study (arXiv 2602.11988, revised September 2026) found that context files “do not generally improve task success rates” across several agents and models, and raised inference cost by over 20%. Agents did follow the files. The authors concluded the files earn their place mainly for non-standard practices, and that LLM-generated files should be skipped for now. Augment Code’s internal evaluation (April 2026) found the opposite spread rather than a contradiction: the best files gave a jump it compared to a model upgrade, 100 to 150 line files with a few focused reference docs gave 10 to 15% gains, and longer files or long architecture overviews reversed them. One overview led an agent to load about 80K tokens for a two-line config change.

Vercel’s January 2026 eval on Next.js 16 APIs points the same way: a compressed 8 KB docs index in AGENTS.md, pointing to local doc files, reached a 100% pass rate, against 53% with no docs and 79% with a skill plus explicit instructions.

The lesson across the three: a short file of commands, non-obvious rules and pointers helps; a long description of what the code already shows costs money and can hurt.

How should you adapt prompts for small local models?

For a local model, the first job is to make sure the system prompt reaches the model at all, then to cut it down and move hard rules out of it. Smaller models lose instructions sooner, and local runtimes truncate quietly.

1. Check the context window first. A 2024 Aider issue shows the classic failure: Qwen2.5-Coder-32B on Ollama described changes but never produced edit blocks, because Ollama’s 2,048-token default at the time pushed Aider’s system prompt out of the window. Raising num_ctx fixed it. Current Ollama defaults depend on VRAM, and its docs recommend at least 64k tokens for coding agents. The context length guide covers how to set and verify it.
2. Use the harness’s small-context mode. Cline added a compact system prompt for LM Studio and Ollama in version 3.26.3, “optimized for smaller context windows (8k or less)” per its changelog.
3. Use the prompt the model was tuned with. Mistral’s Devstral Small card recommends the OpenHands scaffold and loads a SYSTEM_PROMPT.txt shipped with the weights. When a coding model comes with a reference prompt, start from it.
4. Fewer, positive, front-loaded rules. The IFScale benchmark (arXiv 2507.11538) found instruction-following falls as instruction count grows, with even the best frontier models at 68% accuracy at 500 instructions, and a bias toward earlier instructions. Put the rules that matter first and delete the rest.
5. Enforce what must hold. Claude Code’s docs say plainly that memory files are “context, not enforced configuration” and point to hooks for anything that must be blocked. The same applies to every agent: sandboxing, permission prompts and pre-commit checks hold where a sentence in a prompt may not. This is also the main defense against prompt injection in coding agents.

Sampling settings matter too but are a separate topic; see LLM temperature for coding. For the full local stack, see local LLM coding agents.

What does an annotated template look like?

The template below follows the AGENTS.md layout and the patterns from the guides above. Replace every line with your project’s facts and delete what doesn’t apply; a short, accurate file beats a complete generic one.

# AGENTS.md

## Commands                          <- exact commands, so the agent can verify itself
- Install: pnpm install
- Test one file: pnpm test path/to/file.test.ts
- Full check before finishing: pnpm check   (lint, types, tests)

## Conventions                       <- only what a model would get wrong
- Use httpx, not requests. Python >= 3.12.
- DB migrations are generated with `pnpm db:migrate:new`; never hand-write them.
  Reason: hand-written migrations break the schema snapshot.

## How to work                       <- tool and scope rules, phrased positively
- Read the relevant files before proposing changes.
- Change only what the task needs. Ask before adding a dependency.
- Fix root causes. If a test looks wrong, say so instead of editing it.

## Ask first                         <- actions with outside effects
- git push, force operations, deleting files you didn't create,
  anything that touches shared infrastructure or sends messages.

## Done means                        <- verification step
- `pnpm check` passes, `git diff` contains only intended changes,
  temporary files are removed.

## Where to look                     <- pointers, not payloads
- API conventions: docs/api.md
- Payments module has its own AGENTS.md in packages/payments/

For a small local model, cut this to the Commands, Ask first and Done means sections and test whether it still produces edit blocks reliably.

What do developers report in practice?

Practitioners mostly report that less, earlier and enforced beats more. These are community reports, not controlled tests.

• Add rules only after a failure. In the Hacker News thread on the ETH study, one developer said they add a line to AGENTS.md only when the agent fails a task, then revert and re-run to confirm the line helped (HN comment). Another said they only add corrections like which tool creates DB migrations (HN comment).
• Positive phrasing. A commenter on a widely shared agent.md post argued that “don’t do X” seeds X into context, and that “Do Y, for these reasons” works better (HN comment). That matches Anthropic’s advice to say what to do and why.
• Constraints drift as context fills. An r/LocalLLaMA user running qwen2.5:14b in an agentic loop for three weeks reported that a formatting rule in the system prompt was ignored once the context was 60 to 70% full, and fixed it by pruning context between phases (thread). Another commenter there saw agentic coding success drop 60k to 90k tokens into a session and restarts sessions instead.
• Small models need more than a file. In an r/LocalLLaMA thread about giving up on local coding models, the author’s AGENTS.md rules failed with a 27B model, and replies recommended plan-then-execute workflows and avoiding “IF” and “DON’T” phrasing (thread).
• A healthy repo needs less prompt. One HN commenter said most of their projects have no AGENTS.md, and that starting a session with the test command is often enough for the agent to pick up the project’s style (HN comment).

FAQ