An agent's system prompt shapes how it approaches every task. Good agent instructions differ from chatbot prompts.
What to Include
- Role and goal: what the agent is for.
- Environment: what it's working with — a codebase, a database, a set of documents.
- Tool guidance: when to prefer which tools, and common pitfalls.
- Working style: investigate before acting; make small changes; verify results.
- Boundaries: actions that need confirmation or are forbidden.
- Reporting: how to summarise work, including failures and uncertainty.
Explain the Why
Instructions with reasons generalise better. "Run tests after changes, because the CI pipeline will reject failing code" beats "Always run tests".
Avoid Over-Constraining
Capable models do best with clear goals and principles, not exhaustive rules for every situation. Too many rigid instructions can conflict or cause over-cautious behaviour.
Project-Specific Context
Files describing conventions, commands and architecture help agents work in a specific environment; keep them concise and current.
Test and Iterate
Watch agents on real tasks. When they misbehave, find the missing or confusing instruction and fix it, then re-test.