Summary
A coding agent system prompt defines who the agent is and its decision-making defaults. It is a stable, agent-wide instruction layer distinct from per‑project rules files (e.g., .cursorrules, CONVENTIONS.md), which instead encode stack, naming, and testing conventions. Well‑structured system prompts significantly improve agent effectiveness, reduce structural failures (ambiguous goals, missing stop conditions, unverifiable acceptance criteria), and can serve as a double‑win when also injected into the agent’s own self‑improvement loops (e.g., yoyo issue #577).
Key Points
- The system prompt is the stable identity layer – it does not change per project.
- Rules files are the per‑project layer – they capture project‑specific conventions.
- A craft system prompt should include five recurring sections (see Concepts).
- Agent failures are often structural, not technical: unclear goals, no halt condition, wrong context, unverifiable success.
- Sharpening the system prompt benefits both product safety and agent self‑improvement.
Concepts
System prompt vs. Rules file
| Layer | Scope | Content |
|---|---|---|
| System prompt | Agent‑wide, always active | Role, identity, decision‑making defaults, anti‑fabrication rules |
| Rules file (.cursorrules, CONVENTIONS.md) | Per‑project | Stack, naming, testing conventions, file‑specific patterns |
Five recommended sections
- Role / Identity – Define the agent’s persona and core responsibility (e.g., “You are a senior software engineer focused on minimal, correct changes”).