Technical Specification (Opus 级)

A spec exists to align everyone on what is being built before any code is written. It should be precise enough that two engineers would build the same thing after reading it.

What to include

Work through each section. Skip a section only if it genuinely does not apply.

Overview

One paragraph: what this feature is, why it exists, and who it is for.

Goals

Bulleted list of what this spec achieves. Be specific.

• Good: "Users can reset their password via email within 10 minutes of the request"
• Bad: "Improve auth UX"

Non-goals

What this spec explicitly does NOT cover. This prevents scope creep.

Background

Context a new engineer would need: existing behavior, related systems, constraints, prior decisions and why they were made.

Design

Data model New fields, tables, or types. Use actual type notation.

interface PasswordResetToken {
  id: string;
  userId: string;
  token: string;       // bcrypt hash of the raw token
  expiresAt: Date;
  usedAt: Date | null;
}

API / Interface New endpoints, functions, or components. Include signatures and behavior contracts.

POST /auth/password-reset
Body: { email: string }
Response: { message: string }

Behavior Step-by-step description of what happens. Include error states.

Testing strategy

What tests are needed and at what level (unit, integration, e2e).

Open questions

Anything not yet decided that could affect implementation.