Module 2: How To Write A Good Spec

Start With A Brief And Let The Agent Draft The Spec

Anthropic engineer Addy Osmani’s first principle is to begin with a clear goal statement and a few requirements, then let the agent expand that brief into a detailed spec. Review the draft before any code. Agents excel at elaboration when they have a clear mission, and they drift off course without one.

Osmani asks the agent to write the result to a file such as spec.md. That file anchors the agent when a session restarts or the history grows too long.

The draft usually comes back structured, with an overview, a feature list, tech stack suggestions, and a data model. Review it, correct any hallucination or off-target detail, and only then move to code.

Osmani gives one exception. This works well unless you already have very specific technical requirements that must hold from the start.

Keep The Brief About What And Why

A high-level brief focuses on what and why, not on how, at least at first. Ask three questions. Who is the user, what do they need, and what does success look like?

Osmani’s example brief for a to-do app reads, “Build a web app where users can track tasks (to-do list), with user accounts, a database, and a simple UI.”

His success criteria follow the same style. “User can add, edit, complete tasks; data is saved persistently; the app is responsive and secure.”

Spec Kit’s docs say the same. Describe what you build and why, and let the agent write the spec around user experience and success criteria. That is the what-and-how split covered earlier.

Make The Agent Restate The Task, List Assumptions, And Flag Ambiguity

Larridin CTO Ameya Kanitkar recommends that when an agent helps write the spec, you force it to restate the task, list its assumptions, and flag any ambiguity.

The check catches the details the model would otherwise pick silently. Anything still open after it gets its own investigation before the spec is final. The lesson on the spike-first workflow shows how Larridin does that.

Osmani runs the same check in a read-only planning mode, such as Claude Code’s Plan Mode. The agent analyzes the codebase and drafts the spec, but writes no code.

Ask it to question you about the plan, then to review the plan for architecture, best practices, security risks, and testing strategy. Refine until there is no room for misinterpretation, and only then let the agent execute.

You are an AI software engineer. Draft a detailed specification for [project X]
covering objectives, features, constraints, and a step-by-step plan.

Before you finalize the spec: restate in your own words what needs to be built,
list every assumption you made, and flag anything in the brief that is ambiguous.
Ask me about each open point. Do not choose an answer yourself.

The Six-Section Spec Template

Larridin CTO Ameya Kanitkar says to write the smallest spec that unambiguously specifies the system. If a section feels like fluff, cut it. If a decision feels obvious, write it down anyway, because “obvious to you” is not the same as “obvious to the model.”

The bar for detail is that the spec should be enough to hand to a junior engineer or a small model.

The Six Sections

Larridin’s reference implementation is a promoted spike; the lesson on the spike-first workflow covers how they build one. The lesson on test plans covers the sixth section in full.

Blend A PRD With An SRS

Osmani’s second principle is to treat the spec as a structured document with clear sections, not a loose pile of notes. A formal document gives a “literal-minded” agent a blueprint.

Osmani blends two document types. The Product Requirements Document (PRD) side keeps the user-centric “why” behind each feature. The Software Requirements Specification (SRS) side nails down specifics such as which database or API to use.

Use a consistent format. Many developers use Markdown headings or XML-like tags to mark sections, because models handle well-structured text better than free-form prose.

Be specific about your stack. Say “React 18 with TypeScript, Vite, and Tailwind CSS,” not “React project,” and include versions and key dependencies. Vague specs produce vague code.

Osmani warns that “minimal does not necessarily mean short.” Do not shy away from detail where it matters, but keep the spec focused.

Six Things Every Spec Must Cover

GitHub’s analysis of more than 2,500 agent configuration files found that the most effective specs cover six areas. Osmani turns them into a completeness checklist:

1. Commands. Full commands with flags, early in the file, such as npm test, pytest -v, npm run build. The agent references these constantly.
2. Testing. How to run tests, which framework, where test files live, and what coverage you expect.
3. Project structure. Where source code, tests, and docs live, stated explicitly.
4. Code style. One real code snippet that shows your style beats three paragraphs that describe it. Include naming conventions and formatting rules.
5. Git workflow. Branch naming, commit message format, PR requirements.
6. Boundaries. What the agent should never touch, such as secrets, vendor directories, production configs, and specific folders.

These six areas belong to the codebase-scoped layer, and Osmani blends them into one Project Spec document. The lesson on boundaries covers them in full.

Two Skeletons To Copy

Larridin’s six sections as a blank template:

# Spec: [feature or system]

## Problem statement
## Non-goals
## Assumptions
## Reference implementation
## Architecture
## Test plan

Osmani’s skeleton for the config-side areas, from his guide:

# Project Spec: My team's tasks app

## Objective
- Build a web app for small teams to manage tasks...

## Tech Stack
- React 18+, TypeScript, Vite, Tailwind CSS
- Node.js/Express backend, PostgreSQL, Prisma ORM

## Commands
- Build: `npm run build` (compiles TypeScript, outputs to dist/)
- Test: `npm test` (runs Jest, must pass before commits)
- Lint: `npm run lint --fix` (auto-fixes ESLint errors)

## Project Structure
- `src/` – Application source code
- `tests/` – Unit and integration tests
- `docs/` – Documentation

## Boundaries
- ✅ Always: Run tests before commits, follow naming conventions
- ⚠️ Ask first: Database schema changes, adding dependencies
- 🚫 Never: Commit secrets, edit node_modules/, modify CI config

How To Set Boundaries The Agent Will Respect

Osmani’s fourth principle is that the spec is both coach and referee. A good spec anticipates where the agent might go wrong and sets up guardrails. It also uses what you know, such as domain knowledge, edge cases, and gotchas, so the agent does not operate in a vacuum.

The Three Tiers: Always, Ask First, Never

GitHub’s study of 2,500 agent files found that the most effective specs use a three-tier boundary system rather than a flat list of do’s and don’ts.

The tiers tell the agent when to proceed, when to pause, and when to stop:

• ✅ Always do
• ⚠️ Ask first
• 🚫 Never do

“Never commit secrets” was the single most common helpful constraint in the study.

Put Your Domain Knowledge In The Spec

Your spec should reflect insights that only an experienced developer, or someone with context, would know. Osmani’s phrase for it is to pour your mentorship into the spec.

If you build an e-commerce agent and you know that products and categories have a many-to-many relationship, state that clearly. Do not assume the agent will infer it, because it might not.

If a library is notoriously tricky, mention the pitfalls to avoid. The spec can hold advice such as “when using library X, watch out for the memory leak issue in version Y and apply this workaround.”

Encode your style preferences too, such as “use functional components, not class components in React,” and the agent will emulate your style.

A small example anchors the agent to the exact format you want. Many engineers include one in the spec, such as “All API responses should be JSON,” followed by the error shape {"error": "message"}.

A Boundaries Block To Copy

Osmani’s three tiers with his example lines, as one block for your rules file or constitution, the codebase-scoped layer:

## Boundaries

✅ Always do
- Always run tests before commits.
- Always follow the naming conventions in the style guide.
- Always log errors to the monitoring service.

⚠️ Ask first
- Ask before modifying database schemas.
- Ask before adding new dependencies.
- Ask before changing CI/CD configuration.

🚫 Never do
- Never commit secrets or API keys.
- Never edit node_modules/ or vendor/.
- Never remove a failing test without explicit approval.

How To Write Test Plans The Agent Cannot Misread

Larridin CTO Ameya Kanitkar makes the test plan part of the spec. Once you know what the system does, write the test plan before the implementation plan, not after. Test-driven development and spec-driven development fit together. Go over it and adjust it if something is wrong or missing.

There is no need to implement the tests yet. List them, name each one, and specify inputs and expected outputs. That list is a clear definition of done, and you measure the implementation plan against it.

Watch out for “ambiguous tests.” The two pairs at the end of this lesson show Ojstersek’s fix.

Keep What BDD Taught: Plain Language And Given/When/Then

Thoughtworks Technology Director Liu Shangqi argues that experience from behavior-driven development (BDD) is still valid, and this new technology should not change much in this area.

Specifications should still:

• Use domain-oriented ubiquitous language to describe business intent, not tech-bound implementations.
• Have a clear structure, with a common style to define scenarios with Given/When/Then.
• Strive for completeness yet conciseness, and cover the critical path without an enumeration of all cases. With AI, that also saves tokens.
• Aim for clarity and determinism. LLMs do not generate deterministic code, but clear specifications still reduce hallucinations.

Liu adds that the spec-by-example we use in BDD is essentially the few-shot prompt technique.

Put Tests In The Success Criteria, Or In A Conformance Suite

Anthropic engineer Addy Osmani advises that you incorporate a test plan, or even actual tests, into your spec and prompt flow. In the spec’s success criteria, say “these sample inputs should produce these outputs” or “the following unit tests should pass.”

He also relays Simon Willison’s case for conformance suites, which are language-independent tests, often YAML-based, that any implementation must pass. A conformance suite is more rigorous than ad-hoc unit tests, because it derives directly from the spec, and you can reuse it across implementations.

Willison sums it up. A robust test suite is “like giving the agents superpowers,” because they can validate and iterate quickly when tests fail.

Precise Tests, And A Scenario Skeleton To Copy

Ojstersek’s two pairs, side by side:

The standard Given/When/Then form Thoughtworks recommends for each scenario, as a blank skeleton:

Scenario: [what the user does, in the domain's own words]
  Given [the starting state]
  When  [the action]
  Then  [the observable result]

Osmani’s one-line conformance reference, for the spec’s success criteria:

Must pass all cases in conformance/api-tests.yaml

Reverse Engineering A Real Spec

This lesson walks one real spec in its own order. The spec is on the left. Step through it, and the note beside each section says what it does for the agent and which rule it applies.

The spec is the zero-dependency brainstorm server design by Jesse Vincent, author of the superpowers skills library for coding agents. It is about 860 words and changes an existing system, not a greenfield one.