Prompt To Task Spec — Claude Code Guide

Task spec — the task's working contract

An unclear request leaves Claude room for assumptions: it may choose the files itself, touch adjacent logic, or expand the scope of work. A task spec turns a wish into a short working contract for a coding agent.

`CLAUDE.md` describes stable repository rules, while `TASK_SPEC.md` defines the boundaries of a specific task. An issue explains the business need to the team, whereas a task spec additionally defines a controlled way to work with the code.

Choose the specification scale

A small local fix may need a tiny spec: one goal, a narrow file, and a simple check. A change that crosses the UI, backend, database, and events needs a fuller specification with explicitly named boundaries and compatibility.

Fix the label text on the return form button.
Change only the text in the relevant component; do not touch
logic, styles, or other files.
The result is a small diff and a check of the related UI test.

A full task spec for an end-to-end change

• Add an optional notes field to the return creation form.
• Pass the value through the backend flow and save it with the refund.
• Show the note on the details page.
• Add the field to the refund.created event.
• Update the form, persistence, and event tests.
• Do not change auto/manual approval rules, payment processing, or third-party formatting.

Do not confuse the task blocks

Output artifacts

• a short analysis or a confirmed hypothesis;
• a plan before making changes;
• a list of affected files;
• code with tests and a reviewable diff;
• a description of checks and residual risks.