Your First Spec in 10 Minutes

The best way to learn Intent Engineering is to do it. You don't need Pathmode for this — just a text editor and an AI coding agent (Claude Code, Cursor, or Windsurf).

The Goal: We're going to specify a simple feature — a "Copy to Clipboard" button. Small enough to finish in ten minutes, real enough to show why intent beats a one-liner.

We'll write the parts of an IntentSpec a feature this size needs — objective, outcomes, constraints, and verification. The full eight matter once the work gets bigger.

Start with the naive request, in a new file called spec.md:

## Objective
Add a copy button to the code snippets on the blog.

If you stopped here, the agent would guess the icon, the position, and the feedback behavior — and might pull in a third-party library you don't want. The objective says what; the rest of the spec says enough that the agent stops guessing.

Add the observable states — what's true after success. Don't write prose; write true/false statements an agent (or you) can check.

## Outcomes
- [ ] A button appears in the top-right corner of every `pre` code block
- [ ] Icon is `Clipboard` from `lucide-react` (matching our system)
- [ ] Default state shows the `Clipboard` icon
- [ ] On click: content is written to the clipboard, icon swaps to `Check`, label reads "Copied!"
- [ ] State reverts to default after 2000ms

Now the animation timing and states are explicit. You haven't made the agent obey a contract — you've handed it the judgment it would otherwise have to guess at, so it spends its reasoning on the code, not on what you meant.

Tell the agent where it's working — and what it must not do.

## Context
- File: `components/CodeBlock.tsx` (create if it doesn't exist)
- Stack: React, Tailwind CSS, `lucide-react` for icons

## Constraints
- No new dependencies — use the native `navigator.clipboard`
- Must be accessible — add an `aria-label`

Constraints are the guardrails. The "no new dependencies" line is what stops the classic "I installed a 50kb library to do a 3-line function" problem.

This is the step most one-liners skip — and the reason "looks done" and "is done" drift apart. State how you'll prove it worked before the agent writes a line:

## Verification
- Fastest check: clicking the button copies the snippet, shows "Copied!", then reverts
- Edge case: clicking twice quickly doesn't leave the label stuck on "Copied!"
- Must not regress: code blocks still render and scroll as before

You don't need a test runner for a button this small — but naming the check, the edge case, and what must not break is what makes the spec agent-ready, not just written. (For anything bigger, the verification feedback loop is the full version of this step.)

Now the payoff.

1. Open your AI code editor.
2. Open your spec.md file.
3. Type: "Implement this spec."

Because you defined the states (default/active), the timing (2000ms), the tools (navigator.clipboard), and how you'll verify it, the agent writes near-correct code on the first try — and can check its own work against your verification.

The Comparison

Without a spec:

• You ask: "Add a copy button."
• Agent builds it.
• You review: "It doesn't show feedback."
• Agent fixes.
• You review: "Wait, use the check icon — and the right library."
• Agent fixes.
• Total: ~15 minutes of back-and-forth.

With a spec:

• You write the spec (~8 minutes).
• Agent builds the right version (~1 minute).
• Total: ~9 minutes — and you caught the double-click edge case before it shipped.

That's the leverage. Intent Engineering shifts the effort left — from debugging code to defining behavior.

Hand-writing the spec teaches you the parts. When you'd rather have the spec crystallize from a conversation — with evidence, constraints, and verification pulled in automatically — open Pathmode →.