Coding Agent Harness in Practice: Plans, Rules, Skills & Hooks That Keep Agents on Track

In January 2026, Cursor's head of engineering, Lee Robinson, published 'Best practices for coding with agents' — the most practical guide yet to making coding agents genuinely useful. The core insight: models can now run for hours, complete ambitious multi-file refactors, and iterate until tests pass, but whether you unlock that power depends on understanding the agent 'harness' and mastering four practices: plans, context, rules, and skills. This post turns the official guidance into runnable examples so you can upgrade your agent from toy to teammate.

Plans, context, rules, and skills

1. Understand the Harness: Instructions + Tools + Model

Any agent harness, Robinson argues, is built on three components: instructions (system prompt and rules), tools (file editing, codebase search, terminal execution), and the model you pick for the task. Different models respond differently to the same prompt — a model trained heavily on shell workflows might prefer grep over a dedicated search tool; another needs explicit instructions to call linters after edits. Once you see this, 'switching models broke everything' stops being mysterious: the harness wasn't tuned, not the model.

2. Start with Plans: The Single Highest-Impact Change

The most impactful practice in the guide is planning before coding. A University of Chicago study found experienced developers are more likely to plan before generating code — planning forces clear thinking and gives the agent concrete goals. In Cursor, Shift+Tab toggles Plan Mode: the agent researches your codebase, asks clarifying questions, and creates a detailed implementation plan with file paths, then waits for your approval. Plans open as editable Markdown, and saving them to .cursor/plans/ turns them into team documentation and makes interrupted work easy to resume.

# Start with a plan — Plan Mode research prompt
# Ask the agent to research before touching code
"""
Research the authentication flow in this repo.

1. Find every file that touches login, session, or token refresh.
2. Identify the current auth pattern (JWT, cookie, OAuth?).
3. Propose an implementation plan with exact file paths
   and the changes each file needs.
4. Ask me clarifying questions before writing any code.

Save the plan as a markdown file under .cursor/plans/.
"""

3. Managing Context: Let the Agent Find It, Don't Force It

As you get comfortable with agents writing code, your job becomes giving each agent the context it needs. But you don't need to manually tag every file. Modern agents have powerful search tools and pull context on demand: ask about 'the authentication flow' and the agent finds relevant files via grep and semantic search, even without those exact words. The principle: if you know the exact file, tag it; if not, let the agent find it. Including irrelevant files pollutes the context window and degrades output.

4. Rules: Team Conventions Checked Into Git

Rules are project conventions that stay in context permanently — commands, patterns, and pointers to canonical examples. The key is keeping them lean: write the commands to run, the patterns to follow, and pointers to canonical files, rather than copying entire style guides (that's what a linter is for). Code sample 2 shows a solid rules file. Check your rules into git so the whole team benefits; every time the agent repeats a mistake, update the rule — you can even tag @cursor on a GitHub issue or PR to have the agent update it for you.

# .cursor/rules — keep rules short, point at canonical examples
# Checked into git so the whole team benefits
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: import { foo } from 'bar'
- See components/Button.tsx for the canonical component structure
- Always run typecheck after a series of code changes
- API routes go in app/api/ following existing patterns

5. Skills & Hooks: Dynamic Capabilities and Long-Running Loops

Unlike always-loaded Rules, Skills load dynamically: a SKILL.md packages domain knowledge, custom commands, and scripts that the agent invokes when relevant — keeping the context window clean. Code sample 3 shows a PR-review skill. The advanced move is Hooks: code samples 4 and 5 build a long-running loop where a stop hook keeps the agent iterating until all tests pass, capped at five iterations. It's the perfect pattern for 'don't stop until green' goals.

# skills/check-pr/SKILL.md — dynamic capability, loaded only when relevant
---
name: check-pr
description: Review a pull request against repo conventions
---

When reviewing a PR:
1. Run the linter and typecheck first.
2. Check imports follow the ES module rule.
3. Flag any file over 400 lines for refactoring.
4. Output a short checklist, not a wall of prose.

Usage: /check-pr <branch>

# .cursor/hooks.json — long-running agent loop until tests pass
{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

// .cursor/hooks/grind.ts — keep the agent working until green
import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message:
      "[Iteration " + (input.loop_count + 1) + "/" + MAX_ITERATIONS + "] " +
      "Fix the remaining failing tests, update scratchpad.md, keep going.",
  }));
}

6. Your Agent Workflow Upgrade Checklist

Turn the official best practices into four steps: one, write a lean rules file for your project and check it into git; two, route complex tasks through Plan Mode and save plans to .cursor/plans/; three, package high-frequency operations (PR review, dependency bumps) as SKILL.md skills; four, configure hook loops for 'tests must pass' tasks. Keep the core mindset: not every task needs a detailed plan — quick changes can go straight to the agent, but for large refactors the plan is your brake and your steering wheel.