# Turn a rough request into a task spec a coding agent can run > Convert a one-line feature request into an agent-ready spec with testable acceptance criteria, file boundaries, verification commands and stop conditions. - **Author:** [Oliver Hughes (@oliver_hughes)](https://promptabide.com/oliver_hughes) - **Tested on:** Claude · Opus 5.5 - **You fill in:** `request`, `context` - **Published:** 2026-09-11 - **Updated:** 2026-09-24 - **Tags:** `ai-agents`, `product-management`, `coding`, `prompt-engineering` - **Keywords:** how to write a task for a coding agent, prompt spec for codex or claude code, acceptance criteria for ai coding agent, delegate feature to ai agent, agent ready ticket template - **Views:** 1598 - **Likes:** 58 **Best for:** Developers and PMs delegating features to Claude Code, Codex or background agents who want fewer wrong turns and follow-up questions. ## Prompt ``` Turn my rough request into a task spec a coding agent can carry out without coming back to me. Rough request: {{request}} Repo context: {{context}} First, ask me up to 3 questions, but only if the answer would change what gets built. Where a reasonable default exists, pick it and list it under Assumptions instead of asking. Then write the spec, addressed to the agent in the second person: - Goal: one sentence describing the user-visible outcome. - Assumptions - Acceptance criteria: numbered, each one checkable by a command or a click path. - Files likely involved (paths), and files that must not change. - Constraints: allowed dependencies, performance, backwards compatibility. - Verification: the exact commands to run, whose output the agent must paste into its final report. - Stop conditions: when to stop and report instead of pushing on. Keep the spec under 350 words. ``` ## Variables - `{{request}}` — Your rough, one-line request (e.g. Add dark mode to the dashboard, it should remember the user's choice) - `{{context}}` — Stack, where things live, and how tests run (e.g. Vite + React 19 + Tailwind v4; preferences saved via PATCH /api/me/preferences) ## Example input ``` request: add dark mode to the dashboard, it should remember the user's choice context: Vite + React 19 + Tailwind CSS v4, no state library. User settings are saved through PATCH /api/me/preferences (stored in a JSON column). Dashboard pages live in src/pages/dashboard; shared layout in src/components/AppShell.tsx; global CSS in src/index.css. Tests: Vitest + Testing Library (`pnpm test`), Playwright smoke tests in e2e/ (`pnpm e2e`). ``` ## Output *Produced by Claude · Opus 5.5.* ```` No blocking questions. I've made the defaults explicit below; change any you disagree with before handing this over. **Goal** Users can switch the app between light, dark and system themes, and their choice persists across reloads and devices. **Assumptions** - The theme applies to the whole app, not just the dashboard, since the dashboard shares `AppShell`. - There are three options: Light, Dark and System (default). - The toggle lives in the `AppShell` header. **Acceptance criteria** 1. Choosing Dark adds the `dark` class to ``, and the dashboard renders with dark styles. 2. System follows the OS setting and updates live when the OS setting changes. 3. The choice is saved with `PATCH /api/me/preferences { "theme": "light" | "dark" | "system" }` and restored after login on another browser. 4. The choice is also stored in `localStorage` and applied by an inline script in `index.html` before React mounts, so there's no light flash on reload. 5. Text and interactive elements meet WCAG AA contrast in dark mode on the dashboard pages. 6. The toggle is keyboard-operable and has an accessible label. **Files** - Likely: `src/index.css`, `index.html`, `src/components/AppShell.tsx`, a new `src/theme/` module, and dashboard components that hard-code colors. - Must not change: the API server code, or the preferences schema beyond adding the `theme` key. **Constraints** - No new dependencies. - Use Tailwind v4's class-based dark variant, declared in `src/index.css`. - Replace hard-coded hex colors in the dashboard with theme-aware classes. Don't restyle anything else. **Verification** Run these and paste their output into your final report: ```bash pnpm test pnpm e2e pnpm build ``` Add a unit test for the theme module (it reads the stored value, falls back to system, and applies the class) and one Playwright test: switch to Dark, reload, and assert that `html.dark` is present. **Stop conditions** Stop and report instead of continuing if: - the preferences endpoint rejects the new key; - more than 15 components need color changes (list them instead); - any existing test fails for a reason unrelated to theming. ```` ## Why it works **"Default and list under Assumptions instead of asking"** keeps the model from firing ten questions at you while still exposing every choice it made. **Acceptance criteria checkable by a command or a click path** give the agent a finish line. The **must-not-change files** and **no new dependencies** rules cut down the most common kinds of agent sprawl. **Stop conditions** are the part people forget: they tell the agent when to hand back to you instead of pushing ahead on a wrong assumption. The no-flash criterion encodes something agents usually miss on theme work. ## When not to use it If you don't know yet what you want (an exploration or a design question), a spec gives false precision. Prototype or discuss first. The spec is only as good as the repo context you give it, and a missing detail becomes a confident assumption. For tiny tasks, one clear sentence to the agent is enough. --- Canonical HTML: https://promptabide.com/bides/write-task-spec-for-coding-agent Agent guide: https://promptabide.com/llms.txt · https://promptabide.com/agent-instructions.md Sitemap: https://promptabide.com/sitemap.xml