Skip to content

Article

Best Practices for Coding With Agents

Cursor Team

Source ↗ ← All highlights
  • Coding agents are changing how software gets built. Models can now run for hours, complete ambitious multi-file refactors, and iterate until tests pass. But getting the most out of agents requires understanding how they work and developing new patterns.
  • An agent harness is built on three components:
    1. : The system prompt and rules that guide agent behavior
    2. : File editing, codebase search, terminal execution, and more
    3. : Your prompts and follow-ups that direct the work
  • The harness matters because different models respond differently to the same prompts. A model trained heavily on shell-oriented workflows might prefer over a dedicated search tool. Another might need explicit instructions to call linter tools after edits. Cursor’s agent handles this for you, so as new models are released, you can focus on building software.
  • Keep rules focused on the essentials: the commands to run, the patterns to follow, and pointers to canonical examples in your codebase. Reference files instead of copying their contents; this keeps rules short and prevents them from becoming stale as code changes.
  • What to avoid in rules: • Copying entire style guides (use a linter instead) • Documenting every possible command (the agent knows common tools) • Adding instructions for edge cases that rarely apply

    Start simple. Add rules only when you notice the agent making the same mistake repeatedly. Don’t over-optimize before you understand your patterns.

  • The most impactful change you can make is planning before coding.
  • Press in the agent input to toggle Plan Mode. Instead of immediately writing code, the agent will:
    1. Research your codebase to find relevant files
    2. Ask clarifying questions about your requirements
    3. Create a detailed implementation plan with file paths and code references
    4. Wait for your approval before building Plans open as Markdown files you can edit directly to remove unnecessary steps, adjust the approach, or add context the agent missed.
  • Skills package domain-specific knowledge, workflows, and scripts that agents can invoke when relevant. Skills are defined in files and can include: • : Reusable workflows triggered with in the agent input • : Scripts that run before or after agent actions • : Instructions for specific tasks the agent can pull in on demand
  • One powerful pattern is using skills to create agents that run for extended periods, iterating until they achieve a goal. Here’s how you might build a hook that keeps an agent working until all tests pass. First, configure the hook in : The hook script () receives context from stdin and returns a to continue the loop: This pattern is useful for: • Running (and fixing) until all tests pass • Iterating on UI until it matches a design mockup • Any goal-oriented task where success is verifiable
  • Sometimes the agent builds something that doesn’t match what you wanted. Instead of trying to fix it through follow-up prompts, go back to the plan. Revert the changes, refine the plan to be more specific about what you need, and run it again. This is often faster than fixing an in-progress agent, and produces cleaner results.
  • One of the most common questions: should I continue this conversation or start fresh? • You’re moving to a different task or feature • The agent seems confused or keeps making the same mistakes • You’ve finished one logical unit of work • You’re iterating on the same feature • The agent needs context from earlier in the discussion • You’re debugging something it just built
  • When you start a new conversation, use to reference previous work rather than copy-pasting the whole conversation. The agent can selectively read from the chat history to pull in only the context it needs.
  • Cloud agents work well for tasks you’d otherwise add to a todo list: • Bug fixes that came up while working on something else • Refactors of recent code changes • Generating tests for existing code • Documentation updates
  • Here’s how cloud agents work under the hood:
    1. Describe the task and any relevant context
    2. The agent clones your repo and creates a branch
    3. It works autonomously, opening a pull request when finished
    4. You get notified when it’s done (via Slack, email, or the web interface)
    5. Review the changes and merge when ready
  • The developers who get the most from agents share a few traits: The agent’s success rate improves significantly with specific instructions. Compare “add tests for auth.ts” with “Write a test case for auth.ts covering the logout edge case, using the patterns in and avoiding mocks.” Start simple. Add rules only when you notice the agent making the same mistake repeatedly. Add commands only after you’ve figured out a workflow you want to repeat. Don’t over-optimize before you understand your patterns. AI-generated code can look right while being subtly wrong. Read the diffs and carefully review. The faster the agent works, the more important your review process becomes. Agents can’t fix what they don’t know about. Use typed languages, configure linters, and write tests. Give the agent clear signals for whether changes are correct. Ask for plans. Request explanations. Push back on approaches you don’t like.