Skip to main content

Specify Phase - Writing Complete Specifications

Welcome to the most important phase: Specification. This is where you translate your vague ideas ("I want a calculator") into crystal-clear requirements that AI can build from.

Here's the paradigm shift: In AI-native development, your ability to write a clear specification is more valuable than your ability to write code. Bad code can be refactored - but a bad spec breaks everything downstream. In this lesson, you’ll learn how to collaborate with AI to define success and turn it into a complete, testable specification.

Thinking What Success Looks Like​

Before writing a specification, professional teams define criteria for evaluating whether the solution succeeds. This is NOT a formal phase; it's an informal human-AI conversation that clarifies intent.

Not "does it compile?" or "do tests pass?" (those are technical validation). Real evals are business/user criteria that define success:

  • For a calculator:

    • ✅ "Can perform basic arithmetic (add, subtract, multiply, divide)"
    • ✅ "Handles edge cases without crashing (division by zero, negative exponents)"
    • ✅ "Results are accurate to 6+ decimal places"
    • ✅ "Error messages are clear enough for users to understand what went wrong"

  • For a user-facing feature:

    • ✅ "Users can complete the task in < 30 seconds"
    • ✅ "Error messages help users recover without contacting support"
    • ✅ "Experienced and new users succeed at same rate"

Use Pre-Specification Conversation to Build Specification V0​

Here's how professionals work:

Step 1: YOU Drive the Exploration Through Questions

Critical: YOU ask the questions to explore the problem space. The AI doesn't interview you; you use the AI to think through requirements.

You: "I want to build a calculator. What operations should a basic calculator include?"

AI: "Common operations are add, subtract, multiply, divide, and power (exponentiation).
     Those five operations cover most basic arithmetic needs."

You: "What edge cases do I need to consider for these operations?"

AI: "Key edge cases:
     - Division by zero (should error)
     - 0^0 (mathematically undefined)
     - Type mixing (int and float inputs)"

You: "How precise do the results need to be?"

AI: "For a basic calculator, 6 decimal places minimum is standard:
     - Enough for most practical calculations
     - Avoids floating-point display noise
     - Matches calculator conventions"

You: "So what success looks like?"

Step 2: Formalize Into Specification

That conversation becomes the specification's acceptance criteria. The spec says, "Here's what the calculator must do" (derived from the conversation you just had). Now you can Specify (The WHAT):

  • Purpose: Define what users need in plain English
  • Focus: User journeys, acceptance criteria, success metrics
  • Avoid: Technical details, code structure, implementation
  • Output: spec.md file
You: "/sp.specify Build Basic Calculator -Let's formalize our discussion into a specification."

💬 AI Colearning Prompt​

"Explain the difference between 'evals' (business success criteria) and 'acceptance criteria' (testable requirements). Why do we define evals informally before writing the formal specification?"

🎓 Expert Insight​

In AI-native development, the specification IS your code. A vague spec produces broken implementations—no amount of AI intelligence can fix ambiguous requirements. Professional developers spend 70% of their time clarifying specifications and 30% validating implementations, not typing syntax. The clearer your spec, the faster your AI generates correct code. This is why "specs are the new syntax."

Write Your Calculator Specification​

Now it's your turn. Use the structure above to write your complete calculator specification.

Step 1: Start the Conversation​

Open your AI companion (Claude Code) in your calculator-project directory and have this conversation:

I'm writing a specification for a calculator Python library.
Let me clarify what success looks like with you:

1. What operations should my calculator support?
2. What edge cases should I handle?
3. What's my definition of "correct" for floating-point results?
4. How should the calculator interface work? (Library vs CLI?)
5. What should happen with invalid inputs?

[Have the conversation with your AI companion]

Step 2: Create Your Specification File​

/sp.specify Basic calculator operations with full testing. Let's formalize our discussion into a specification.

User journeys:
- Add two numbers (positive, negative, zero, decimals)
- Subtract two numbers (all combinations)
- Multiply two numbers (including edge cases)
- Divide two numbers (we'll handle division by zero later)

Acceptance criteria:
- All operations work with whole numbers and decimals
- All operations return correct results
- All operations have full test coverage
- All functions use Python 3.12+ type hints
- All functions have clear docstrings

Success metrics:
- 100% test coverage for all operations
- Type checking passes with mypy
- Code follows our constitution rules

Step 3: Review the Specification in New Branch​

Use the above command Agent:

  • Creates new feature branch automatically
  • Generates comprehensive spec file
  • Defines user scenarios and edge cases
  • Establishes acceptance criteria
  • Sets up testing requirements

In SDD, we think at the FEATURE level (what user needs), not the FUNCTION level (code details).

Step 4: Verify Completeness​

Check that your specification:

  • Has clear overview explaining the calculator
  • Clearly states in-scope (5 operations, error handling) and out-of-scope
  • Includes 5+ user stories
  • Documents edge cases (at least 3-4 per operation)
  • References Constitution constraints
  • Is written clearly enough that another developer could implement from it

Validation: The Cascade Effect​

Now test your specification's quality by asking: Will this spec produce a good plan?

A good spec has:

  • ✅ Crystal-clear operations (no ambiguity)
  • ✅ Explicit edge cases (no surprises during planning)
  • ✅ AI can build acceptance tests directly from them
  • ✅ Constraint alignment (specifications respect Constitution)

A bad spec has:

  • ❌ Vague operations ("should work correctly" - what's "correct"?)
  • ❌ Missing edge cases (surprises emerge during implementation)
  • ❌ Ambiguous criteria ("handle errors"-how?)
  • ❌ Ignores Constitution (specification asks for things Constitution forbids)

Action: Read your specification aloud. Does it sound clear? Would a developer understand exactly what to build?

Common Mistakes​

Mistake 1: Vague Acceptance Criteria​

The Error: "Calculator should work well" or "Results should be accurate"

Why It's Wrong: "Work well" and "accurate" are subjective. What does "accurate" mean? To what precision?

The Fix: Use SMART criteria (Specific, Measurable, Achievable, Relevant, Time-bound):

  • ❌ Vague: "Calculator should work correctly"
  • ✅ SMART: "Returns float with 6 decimal precision; handles division by zero with ValueError"

Mistake 2: Missing Edge Cases​

The Error: Only documenting happy path (add(5, 3) = 8) without edge cases

Why It's Wrong: Edge cases cause 80% of bugs. If you don't specify them, AI won't handle them.

The Fix: Document at least 3-4 edge cases per operation:

  • Division by zero
  • Negative exponents in power()
  • Type mixing (int + float)
  • Boundary conditions (very large/small numbers)

🤝 Practice Exercise​

Ask your AI: "I've written my calculator specification in specs/calculator/spec.md. Can you review it and tell me: (1) Are my acceptance criteria SMART (Specific, Measurable, Achievable, Relevant, Time-bound) or vague? (2) What edge cases did I miss for the 5 operations? (3) How does my spec align with the Constitution standards we set earlier? Then suggest 2-3 improvements before I move to the Clarify phase."

Expected Outcome: Your AI should identify vague criteria (e.g., "works correctly" → needs precision specification), suggest missing edge cases (e.g., power(0, 0), very large exponents), confirm Constitution alignment (type hints, testing requirements), and provide actionable improvements.

Try With AI​

Ready to write your first complete specification with AI collaboration? Practice the evals-first approach:

🔍 Explore Success Criteria:

"I want to build a calculator library with 5 operations (add, subtract, multiply, divide, power). Before I write the formal spec, help me define success: What does 'working correctly' mean for each operation? Ask me clarifying questions about edge cases, error handling, and acceptance criteria. Don't let me write vague requirements."

🎯 Practice SMART Criteria:

"Review my calculator specification at specs/calculator/spec.md. For each operation's acceptance criteria, check if they're SMART (Specific, Measurable, Achievable, Relevant, Testable). Identify any vague criteria (like 'works correctly' or 'handles errors well') and suggest specific, measurable alternatives with concrete examples."

🧪 Test Edge Case Coverage:

"Looking at my calculator spec, identify missing edge cases for each operation. For division, did I specify division by zero? For power, what about 0^0 or negative exponents? For all operations, what about type mixing (int + float) or very large numbers? Generate a list of 10+ edge cases I should add to my spec."

🚀 Apply to Your Feature:

"I need to write a specification for [describe your feature]. Help me work through the evals-first approach: (1) What does success look like for my feature? (2) What are the 5-10 most important acceptance criteria? (3) What edge cases am I likely to miss? (4) How can I make my criteria SMART? Walk me through the conversation before I write the formal spec."