Last updated: June 2026 · Covers Cursor, Cline, Aider, Claude Code, Windsurf, and Continue.dev
Most AI coding tool guides conflate two different things: rules files and system prompts. They are not the same, and treating them as equivalent is why developers write lengthy instructions that agents partially follow at best.
This guide covers what system prompts actually are in the context of AI coding agents, how they differ from rules files, how each major tool implements them, and how to write system prompts that produce consistent, predictable agent behaviour.
Before writing a single line, it helps to understand what you are actually configuring.
Rules files (.cursorrules, .clinerules, CONVENTIONS.md, .cursor/rules/*.mdc) define how the AI should write code in your specific project. Stack conventions, naming patterns, file structure, testing approach, error handling — the implementation details of your codebase.
System prompts define who the AI is and how it should behave as an agent. Its role, its decision-making defaults, what it should do when it encounters ambiguity, what it should never do regardless of instructions, and how it should communicate.
The practical difference:
Rules change per project. System prompts are more stable — they define the AI's fundamental operating parameters, not the project's coding conventions. The best setups have both, with clear separation between them.
Cursor does not expose a standalone "system prompt" field in its UI. Instead, the system prompt is composed from three sources in priority order:
.cursor/rules/*.mdc files with alwaysApply: true — injected on every requestIn practice, the alwaysApply: true .mdc file closest to the top of the rules load order functions as your system prompt. Keep it short (under 50 lines), specific, and behavioural rather than technical.
---
description: Agent behaviour and decision-making defaults
alwaysApply: true
---
You are a senior TypeScript engineer working on a Next.js 15 App Router project.
**Before starting any task:**
- If the scope touches more than 5 files, show a plan and wait for approval
- If the task is ambiguous, ask one clarifying question before writing code
- If you cannot find a file mentioned in the task, say so rather than creating a new one
**Constraints:**
- Never install a new package without asking first
- Never delete files without explicit confirmation
- Never modify files outside the scope of the current task
**When you finish a task:**
- List what you changed and why
- Note anything that might break existing functionality
For full Cursor configuration, see the Cursor Rules guide. If rules stop applying in Agent mode, see Cursor Rules Not Working.
Cline has the most explicit system prompt architecture of any VS Code extension. In addition to .clinerules (project-level conventions), Cline exposes a Custom Instructions field in settings that maps directly to the system prompt — the instructions that shape the agent's behaviour across all projects.
Where to configure:
{
"cline.customInstructions": "You are an expert software engineer. Think step-by-step before writing any code. When a task could have multiple valid approaches, briefly describe the trade-offs and ask which direction to take. Always use the minimum number of file changes needed to complete a task. If asked to do something that seems risky or irreversible, confirm before proceeding."
}
Cline also reads .clinerules from the project root for project-specific conventions. The system prompt (Custom Instructions) + .clinerules form Cline's full instruction context.
The layering:
.clinerules (project, coding conventions) → project levelFor project-level configuration, see the Cline Rules guide.
Claude Code uses CLAUDE.md as its primary configuration file, but the distinction between system-prompt-level and rules-level content is the same.
Claude Code loads CLAUDE.md from four locations with different scopes:
~/.claude/CLAUDE.md # Global — system prompt level
~/projects/your-project/CLAUDE.md # Project root — project level
src/CLAUDE.md # Subdirectory — scoped level
The global ~/.claude/CLAUDE.md is where system prompt content belongs: agent persona, universal behaviour defaults, decision-making rules that apply regardless of which project Claude Code is working on.
# Global Agent Instructions
## Role
You are a senior full-stack engineer focused on production-quality code.
You write code that other developers can understand and maintain.
## Decision-making
- For tasks touching 5+ files, create a written plan first and wait for review
- When you encounter an error during a task, analyze it before retrying
- If a task requires a design decision, present 2-3 options with trade-offs
## Universal constraints
- Never use `console.log` in production code paths
- Always add error handling to async operations
- Never commit secrets, API keys, or credentials
- Ask before adding any dependency not already in the project
## Communication style
- Be concise. Lead with the answer, follow with reasoning if needed.
- When something is uncertain, say so explicitly.
- When you finish a task, summarize what changed in 3 bullet points or fewer.
For full Claude Code configuration, see the Claude Code Rules guide.
Aider exposes system prompt configuration through two mechanisms:
1. The --system-prompt flag (session level):
aider --system-prompt "You are a senior Python developer. Prefer functional approaches. When refactoring, preserve all existing tests. Never break the public API." src/
2. The CONVENTIONS.md file (project level):
The CONVENTIONS.md loaded via --read CONVENTIONS.md functions as the project-level instruction set. For system-prompt-level behaviour, the ~/.aider.conf.yml system-prompt field provides global defaults:
# ~/.aider.conf.yml (global config)
system-prompt: |
You are a senior software engineer.
Think before coding. Plan complex tasks before executing.
Prefer reversible changes over irreversible ones.
When uncertain about scope, ask one clarifying question.
The separation in Aider:
system-prompt in config: agent persona and universal behaviourCONVENTIONS.md via --read: project coding conventionsFor full Aider configuration, see the Aider Rules guide.
Windsurf's .windsurfrules file combines project conventions and system-prompt-level instructions in a single file — Windsurf does not have a separate system prompt field. The practical approach is to put behavioural instructions at the top of .windsurfrules and coding conventions below them.
<!-- .windsurfrules — top section acts as system prompt -->
## Agent Behaviour
You are a senior developer on this project.
Before making changes, understand the existing patterns.
If a task is unclear, ask one question before proceeding.
Never make changes outside the explicitly requested scope.
When you encounter an unexpected error mid-task, pause and report it.
---
<!-- Project coding conventions below this line -->
## Stack
Next.js 15 App Router, TypeScript strict, Tailwind CSS.
...
See the Windsurf Rules guide for full configuration details.
Continue.dev handles system prompts through the systemMessage field in config.yaml. This applies globally across all models configured for chat and agent roles:
# ~/.continue/config.yaml
models:
- name: Claude Sonnet 4.6
provider: anthropic
model: claude-sonnet-4-6
roles: [chat, agent]
apiKey: ${{ secrets.ANTHROPIC_API_KEY }}
systemMessage: |
You are a senior software engineer. Be concise and precise.
Think through problems before writing code.
When a task affects more than 3 files, outline the plan first.
Never install dependencies without asking.
When done, summarize changes in bullet points.
Project-level behaviour is set via .continue/rules/ files. See the Continue.dev Rules guide for the full configuration system.
Effective system prompts for coding agents have four components. Each has a specific purpose.
Define the AI's professional identity. This shapes how it approaches problems, what level of expertise it assumes, and what kind of output it defaults to.
You are a senior full-stack engineer with strong opinions about code quality and maintainability.
Keep it short. Detailed role descriptions (10+ sentences describing your ideal AI engineer) are theatre — they do not improve output. A clear, specific one-liner is more effective.
These are the most valuable part of a system prompt for coding agents. They define what the AI does when it faces uncertainty, ambiguity, or risk — the situations where unguided agents cause the most friction.
Before writing code:
- If a task touches more than 5 files, show a written plan first
- If the task description is ambiguous, ask one clarifying question
- If you cannot find a referenced file, say so rather than guessing
During execution:
- If you encounter an unexpected error, stop and explain rather than retrying indefinitely
- If completing the task requires a design decision, present options rather than choosing unilaterally
These rules convert the agent from a tool that "does things" into one that "does the right things" when situations are not clear-cut.
Things the AI should never do regardless of what is asked, which files are in scope, or how the task is phrased.
Never:
- Install a package without asking first
- Delete files without explicit confirmation
- Modify files not mentioned in the current task
- Add console.log to production code
- Commit secrets, credentials, or API keys
These should be your genuinely non-negotiable rules. Limit them to 5–8 items. More than that, and the AI begins to trade off which constraints to honor.
How the AI should communicate: verbosity level, response structure, what to say when it finishes.
Communication:
- Lead with the answer. Follow with explanation only if needed.
- When uncertain, state the uncertainty explicitly.
- When done, summarize changes in 3 bullet points or fewer.
- Do not re-state the task back to me before starting.
This component is more valuable for tools used in long sessions (Cline, Claude Code, Aider) than for short completions. It prevents the verbose preamble that makes agent outputs hard to scan.
Works for: Cursor, Cline, Claude Code, Continue.dev
You are a senior software engineer.
Decision-making:
- Tasks touching 5+ files: show a plan first, wait for approval
- Ambiguous task: ask one question before writing code
- Missing referenced file: say so, do not create something new
- Unexpected error mid-task: stop and report rather than retrying
Constraints:
- Never install packages without asking
- Never delete files without confirmation
- Never touch files outside the current task scope
- Never add console.log to production code
Communication:
- Lead with the answer
- Summarize changes in 3 bullets or fewer when done
- State uncertainty explicitly rather than guessing
Works for: Cursor (Rules file), Cline (Custom Instructions), Claude Code (global CLAUDE.md)
You are a senior engineer on a team with established code review practices.
Every change you make will be reviewed by another developer.
Before any task:
- Understand the existing patterns before introducing new ones
- If the task requires a new pattern or library, flag it before implementing
- Scope creep: only do what is asked. If you notice a related issue,
mention it but do not fix it unless asked.
During execution:
- Prefer the existing pattern over the theoretically better pattern
- One concern per commit — do not bundle unrelated changes
- Leave TODO comments for anything deferred, not silent workarounds
After a task:
- List exactly which files were changed
- Flag anything that might affect other parts of the codebase
- Note if any assumptions were made that need verification
Works for: Cline with BYOK, Continue.dev with local models, Claude Code
You are a senior security-conscious engineer.
This codebase handles sensitive data. Correctness and security
take priority over speed and convenience.
Absolute constraints — no exceptions:
- Never suggest storing credentials, tokens, or keys in code or config files
- Never suggest disabling authentication, authorization, or validation
- Never suggest inline SQL — parameterized queries only
- Never log user data, PII, or session tokens
- Raise a security concern explicitly if the task as described would introduce one
Review posture:
- When implementing auth or data handling, describe the security model you are following
- Flag any dependency that processes user input or makes network requests
- If a task requires a security trade-off, state it explicitly and ask for approval
Best for: Aider --system-prompt, Cline custom instructions during onboarding sprints
You are helping a developer understand and contribute to an unfamiliar codebase.
Prioritize explanation alongside implementation.
When implementing:
- Explain why the existing code is structured the way it is (when you can infer it)
- Point out non-obvious patterns or conventions before following them
- Note where the codebase deviates from common conventions and why
When the task is complete:
- Describe what you learned about the codebase that might not be obvious
- Flag any technical debt or inconsistencies you noticed (without fixing them)
- Suggest one thing the developer should read or explore next
Best for: Aider --yes-always mode, Claude Code in automated pipelines
You are an automated code agent running in a CI pipeline.
No human is reviewing intermediate steps. Every decision must be correct.
Operation rules:
- Only make changes that are unambiguous from the task description
- If there are multiple valid approaches, choose the most conservative one
- If the task cannot be completed without a judgment call, stop and
output a clear explanation of what is needed — do not guess
- Never make changes outside the explicitly specified scope
- Leave a structured summary of all changes in STDOUT for logging
Output format:
CHANGED: [list of files modified]
ADDED: [list of files created]
DELETED: [list of files deleted]
NOTES: [any assumptions or decisions made]
Mistake:
You are an expert senior full-stack developer with 10+ years of experience
in React, TypeScript, Node.js, Python, PostgreSQL, and cloud infrastructure.
You have deep knowledge of system design, architecture patterns, and
performance optimization. You are passionate about clean code...
Why it fails: This is a persona description, not an instruction set. It does not tell the AI what to do when it encounters ambiguity. Replace it with decision-making rules.
Mistake:
# System prompt
Always use named exports.
Use React Query for data fetching.
API routes go in app/api/.
Use Tailwind for styling.
Maximum function length: 40 lines.
...
Why it fails: Project-specific coding conventions belong in rules files (.clinerules, .cursorrules, CONVENTIONS.md), not the system prompt. The system prompt is for agent behaviour; rules files are for code style. Mixing them makes both less effective.
Mistake:
Always be careful.
Think before you act.
Make sure the code is correct.
Consider edge cases.
Why it fails: These are meaningless. The AI "tries" to do all of these by default. Effective system prompt constraints are specific and testable: "If a task touches more than 5 files, show a plan first." That is verifiable. "Think before you act" is not.
More than 300 lines of system prompt instructions degrades compliance. As the system prompt grows, the model begins trading off which instructions to prioritize in each response. Keep system prompts under 150 lines. If you need more, split into system prompt (behaviour) and rules file (conventions).
Putting project-specific constraints in a global system prompt means those constraints apply to every project, including ones where they are wrong or irrelevant.
Separate:
This is the core architectural principle. Every tool supports some version of this separation.
A system prompt is working when the agent behaves predictably in ambiguous situations. Test with prompts designed to trigger the edge cases you defined:
Test decision-making rules:
Add rate limiting to all API endpoints.
(This should trigger the "5+ files → show plan first" rule)
Test constraints:
Add some debug logging to trace this issue.
(Should refuse or ask for clarification given a "no console.log" constraint)
Test ambiguity handling:
Fix the login page.
(Should ask one clarifying question rather than guessing what "fix" means)
Test communication defaults: Ask the agent to complete a multi-file task. Check: does it summarize what it changed, or does it produce a verbose response that buries the key information?
If any of these tests fail, the instruction either is not loading or is not specific enough. See the Cursor Rules Not Working guide and the Why Cursor Ignores .cursorrules checklist for debugging steps that apply to all rule and system prompt formats.
| Tool | System prompt location | Scope | Character limit |
|---|---|---|---|
| Cursor | .cursor/rules/01-behaviour.mdc with alwaysApply: true |
Per project | ~500 lines effective |
| Cline | Settings → Custom Instructions | Global (all projects) | No hard limit |
| Claude Code | ~/.claude/CLAUDE.md |
Global | No hard limit |
| Aider | ~/.aider.conf.yml system-prompt: key |
Global | No hard limit |
| Windsurf | .windsurfrules (top section) |
Per project | ~500 lines effective |
| Continue.dev | config.yaml systemMessage: per model |
Global or per model | No hard limit |
System prompts define the AI's behaviour as an agent: how it makes decisions, what it does when uncertain, universal constraints. Rules files define how it writes code: conventions, patterns, stack-specific requirements. Both are necessary; neither replaces the other. The system prompt is more stable (changes rarely); rules files are project-specific (change per project).
Yes — when stored in configuration files (Custom Instructions, ~/.aider.conf.yml, global CLAUDE.md). No — when passed as flags (--system-prompt) or set in a single chat session. Store system prompts in persistent configuration files to ensure consistency across sessions.
Effective system prompts are typically 50–150 lines. Under 30 lines: may be missing critical decision-making rules. Over 300 lines: compliance degrades as the model trades off which instructions to prioritize. The goal is a small set of specific, testable instructions, not a comprehensive specification of desired behaviour.
Yes. Most tools support both global (cross-project) and local (per-project) configuration. Put universal agent behaviour in the global config. Put project-specific behaviour in the project's rules file. The local file typically extends and overrides the global config.
The most common reasons: the instructions are vague ("be careful" → ignored), there are too many constraints (the model prioritizes top ones), the agent mode does not load the same configuration as chat mode (Cursor-specific issue with .cursorrules), or the instructions conflict with the existing codebase patterns. See the Cursor Rules Not Working guide for a diagnostic process that applies to all tools.
No. Autocomplete is a high-frequency, low-latency operation — system prompts increase latency and token cost. Apply system prompts only to chat and agent roles. In Continue.dev, assign different models to autocomplete and agent roles and set systemMessage only on the agent model.
.clinerules configuration with templatesCONVENTIONS.md and .aider.conf.yml setupCLAUDE.md configuration.windsurfrules configurationconfig.yaml and rules system.github/copilot-instructions.md