# Write product and tech specs with agents

> Use agents to turn a ready-to-implement issue into a product spec and a tech spec — the blueprints that guide implementation and anchor code review.

- 网址：https://funcoding.ai/agents/warp/guides/agent-workflows/write-product-and-tech-specs-with-agents/
- 来源：Warp 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.warp.dev/guides/agent-workflows/write-product-and-tech-specs-with-agents/

---
Once your [triage agent](https://funcoding.ai/agents/warp/guides/agent-workflows/build-a-triage-agent/) is labeling issues as `ready-to-spec`, use agents to turn those issues into two spec files: a product spec that describes what the feature should do from the user's perspective, and a tech spec that describes how to implement it.

Implementation agents use these specs as blueprints; reviewers use them as acceptance criteria. The agent does the drafting while you do the reviewing.

Specs give implementation agents the context they need to make good decisions, and they also give human reviewers a benchmark to judge the result against. With a spec, the agent implements against an explicit contract you've approved, instead of what it inferred from the issue.

## Prerequisites

* A Warp account (<a href=https://www.warp.dev/get-started>get started with Warp</a>)
* A triaged issue labeled `ready-to-spec` or equivalent ([set up triaging](https://funcoding.ai/agents/warp/guides/agent-workflows/build-a-triage-agent/))
* `common-skills` installed globally from [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills):

  ```bash
  npx skills@latest add warpdotdev/common-skills --skill write-product-spec --agent warp --global
  npx skills@latest add warpdotdev/common-skills --skill write-tech-spec --agent warp --global
  ```

## 1. Write the product spec

A product spec defines what the feature should do from the user's perspective, including user stories, acceptance criteria, and edge cases. It is the "what," not the "how."

1. Open the issue you want to spec in Warp and run:

   ```bash
   /write-product-spec
   ```

2. Review the generated `PRODUCT.md` in `specs/[issue-number]/`. The file includes:
   * A summary of the feature
   * User stories in the format "As a [user], I want [behavior] so that [outcome]"
   * Acceptance criteria the implementation agent and reviewers can verify
   * Edge cases and constraints

   Correct any misunderstandings before moving to the tech spec. A wrong product spec leads to a correct implementation of the wrong thing.

## 2. Write the tech spec

A tech spec defines how the feature will be implemented, including architecture decisions, relevant code locations, API shapes, and implementation notes. It is the "how."

1. After reviewing the product spec, run:

   ```bash
   /write-tech-spec
   ```

2. Review the generated `TECH.md` in the same `specs/[issue-number]/` directory. The file includes:
   * An overview of the implementation approach
   * The specific files and functions that need to change
   * Any new data structures, API endpoints, or interfaces
   * Testing strategy
   * Known risks or tradeoffs

   An accurate `TECH.md` reduces the number of implementation iterations and gives reviewers context for why the code looks the way it does.

## Productivity tips

* **Spec before you code, not after** — The biggest value from specs is catching misaligned assumptions before any code is written. Running `/write-product-spec` first forces that alignment to happen early, when fixing it is cheap.
* **Attach Figma mocks** — If your feature has a UI component, attach a Figma screenshot or mockup to your prompt when running `/write-product-spec`. The agent incorporates visual context into the acceptance criteria.
* **Use `/plan` for smaller tasks** — For changes that don't warrant full specs, use Warp's built-in [planning feature](https://funcoding.ai/agents/warp/agents/capabilities/planning/). Plans can be saved, versioned, and attached to PRs without a full spec workflow.

## Next steps

* [Warp Factories overview](https://funcoding.ai/agents/warp/factories/) — Warp's product for running this same loop without the manual wiring.
* [Factory agents](https://funcoding.ai/agents/warp/factories/factory-agents/#spec) — The Spec agent role, gating implementation the same way.
* [Set up your software factory](https://funcoding.ai/agents/warp/guides/agent-workflows/set-up-a-software-factory/) — Connect the spec role to implementation and review.
* [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`.
* [Planning](https://funcoding.ai/agents/warp/agents/capabilities/planning/) — Warp's built-in planning feature for smaller tasks.
* [Skills](https://funcoding.ai/agents/warp/agents/capabilities/skills/) — How skill files work in Warp and the Automation Platform.