Coding Agent Task Brief with Guardrails, Test Plan, and Rollback Steps

Creates a scoped brief for an AI coding agent that limits file changes, defines tests, and includes a rollback plan and review checklist.

You get: Agent brief, test plan table and rollback plan

More like this

The prompt

coding-agent-task-brief-with-guardrails-test-plan-and-rollback-steps.md
Role: You are a staff engineer writing a task brief for an autonomous coding agent and a reviewer.Context: The agent will work in the repository for {project} to deliver {change_request}. The decision this answer must support: whether the brief is safe and clear enough to hand to the agent, and what the human must review before merge.
Task: Convert the request into an agent-ready brief with scope limits, a step plan, tests, and rollback.Constraints: Ask for missing inputs before writing the brief. Keep assumptions separate. Do not assume files, commands, or frameworks I did not mention; mark guesses as 'to verify'. Never include secrets. Do not claim code has been run.

Inputs:
- Project and stack: {project}
- Change request and motivation: {change_request}
- Relevant files or directories (allowed to edit): {allowed_paths}
- Files or areas off limits: {forbidden_paths}
- Test and lint commands: {test_commands}
- Definition of done: {done_criteria}
- Deployment or migration risks: {risks}

Workflow:
1. List missing inputs and ask.
2. Restate the change in one paragraph and list non-goals.
3. Define an investigation phase: files to read first, questions to answer before editing.
4. Define an implementation plan in small commits, each independently testable.
5. Specify tests to add or update, and the commands to run after each commit.
6. Set stop conditions: when the agent must stop and ask (failing tests after {max_attempts} attempts, need to touch forbidden paths, ambiguous requirement).
7. Write rollback steps and a reviewer checklist.

Output format:
1. Assumptions and missing information
2. Agent brief (copy-ready): Goal | Scope | Non-goals | Allowed paths | Forbidden paths | Steps | Stop conditions
3. Test plan table: Test | Type | Command | Expected result
4. Rollback plan (numbered)
5. Reviewer checklist (checkbox list)
6. Risks and next actions

Acceptance criteria:
- Scope and forbidden paths are explicit.
- Each commit step has a verification command.
- Stop conditions cover repeated failure and scope expansion.
- The rollback plan can be followed without the agent present.

Quality checks:
- Confirm every command comes from {test_commands} or is marked 'to verify'.
- Confirm no step requires editing forbidden paths.
- Confirm done criteria are testable.

Platform notes: For Cursor, format the agent brief so it can be saved as a rules file or pasted into Agent mode, and mention files with @ references. For Claude Code, write the brief as a CLAUDE.md-style section with a plan-first instruction. For GitHub Copilot agent mode, keep the brief within one issue description and use a checklist.

Example output

AI-written example
# 1. Assumptions and missing information

**Provided inputs**
- Project: orders-service (Node.js 20, TypeScript, Express, PostgreSQL)
- Change: add per-API-key rate limiting to `POST /api/v1/orders` to stop burst traffic from a partner integration causing DB connection exhaustion
- Allowed: `src/routes/orders/`, `src/middleware/`, `tests/orders/`, `tests/middleware/`
- Forbidden: `migrations/`, `infra/`, `.github/workflows/`, `src/auth/`, `.env*`
- Test commands: `npm run lint`, `npm run typecheck`, `npm test`
- Max attempts: 3

**Assumptions (to verify)**
- Requests carry an API key in a header already parsed by existing auth. Header name: to verify.
- Limit of 60 requests/minute per key is acceptable. Confirm with the product owner.
- Runs on multiple instances, so an in-memory counter may under-enforce. Shared store choice: to verify.

**Missing, answer before starting**
1. Is a shared store (e.g. Redis) already available to the service? If not, is per-instance limiting acceptable for v1?
2. Should the response include `Retry-After`?

# 2. Agent brief (copy-ready)

**Goal:** Reject excess `POST /api/v1/orders` requests with HTTP 429 once a single API key exceeds 60 requests per 60 seconds.

**Scope:** One rate-limit middleware, wired only to the orders create route, behind an on/off config flag.

**Non-goals:** Rate limiting other routes, changing auth, adding infrastructure, schema changes, refactoring unrelated code.

**Allowed paths:** `src/routes/orders/`, `src/middleware/`, `tests/orders/`, `tests/middleware/`

**Forbidden paths:** `migrations/`, `infra/`, `.github/workflows/`, `src/auth/`, `.env*`. Do not read or print secrets.

**Steps**
0. Investigate (no edits): read the orders route file, existing middleware, and the config loader. Answer: where is the API key available on `req`? How are existing middleware tested? Report findings before editing.
1. Commit 1: add the middleware with an in-memory counter and unit tests. Verify: `npm run typecheck && npm test`
2. Commit 2: wire it to the orders create route behind a config flag, default off. Verify: `npm run lint && npm test`
3. Commit 3: add integration tests for 429 behavior and flag-off behavior. Verify: `npm run lint && npm run typecheck && npm test`

**Stop conditions.** Stop and ask if:
- the same test or lint failure persists after 3 attempts
- any change is needed in a forbidden path
- the API key cannot be found without editing `src/auth/`
- the requirement is ambiguous or the diff grows beyond the allowed paths
- a new dependency seems necessary

# 3. Test plan

| Test | Type | Command | Expected result |
|---|---|---|---|
| Allows requests under the limit | Unit | `npm test` | Pass |
| Returns 429 on the 61st request in a window | Unit | `npm test
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Fill in forbidden paths carefully, since this is the main guardrail. Review the agent's plan before it edits files. Adjust {max_attempts} to match your risk tolerance, typically 2 or 3.

Questions about this prompt

More in Agentic AI

Conventional Commit and PR Description from a Diff and Ticket

Produces a Conventional Commits message and a reviewer-ready PR description covering what changed, why, how to test it, and the risks, based on your diff and ticket.

Rewrite a Vague Issue into a Copilot Coding Agent-Ready Issue

Turns a vague GitHub issue into a self-contained task with context, testable acceptance criteria, files to touch, and tests to add, so the Copilot coding agent can finish it.

Agent Run Pre-Mortem and Self-Correction Loop Designer

Designs verification checks, error handling, and a self-correction loop for an agent task before it runs, based on likely failure modes.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Checkable Guardrail Rules for a Coding Agent: Blocked Commands, Approvals, Secrets and Hooks

Produces a set of testable guardrail rules for your coding agent, covering blocked commands, approval gates, secret handling and hook checks.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Dependency Graph Planner for a Multi-Agent Software Release Workflow

Turns a list of release tasks into a dependency graph with parallel batches, critical path, shared-resource conflicts, and agent assignments. Supports the decision on what to run now versus wait on.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Design an AI Agent With Tools, Guardrails and Eval Cases Before You Build It

Turns an agent idea into a build-ready design: the job, the tools with their inputs and permissions, guardrails, failure handling and a set of evaluation cases to test it.

Pull Request Review with Merge Recommendation

Reviews a diff against your standards and returns a merge, merge-with-changes, or do-not-merge recommendation. Findings are ranked by severity, with evidence, suggested fixes, and open questions.

20-Case Agent Eval Set with Pass/Fail Rubric for Normal, Edge and Unsafe Requests

Builds 20 test cases for your agent's task, with expected behavior, failure signals and a pass/fail rubric covering normal, edge and unsafe requests.

Agent Tool Names, Descriptions and JSON Schemas from API Docs

Turns pasted API docs or a function list into agent-ready tool names, descriptions, JSON input schemas and when-to-use and when-not-to-use notes.