🧪 TDD and BDD: how to write strong specifications

---

🌍 Language pair / Par de idioma

• English: 12-tdd-and-bdd-how-to-write-specs.md
• Español: ../es/12-tdd-y-bdd-como-escribir-specs.md

🗣️ Friendly prompt (copy/paste)

Use this when you are not technical and want the AI to do setup + guidance end-to-end:

Using https://github.com/juanklagos/spec-driven-development-template, create everything needed to carry out my project end-to-end.
My project is: [describe your project in plain language].

If my project is new, initialize it with this template and GitHub Spec Kit.
If my project already exists, adapt it to idea/specs/bitacora without breaking current behavior.
Guide me step by step for my level (beginner/intermediate/advanced), using simple language.
Do not skip specification, plan, tasks, refinement trace, logbook, and validation.

[!TIP] For startup instructions and prompts, use:

• AI_START_HERE.md
• Prompt matrix
• Validated prompt bank

This section is a repository bonus to connect specification-first development with quality practices.

1) Simple difference between TDD and BDD

Approach	Meaning	Main question	Expected output
TDD	Test-Driven Development	How do we validate technical behavior?	Tests that drive implementation
BDD	Behavior-Driven Development	How should the system behave for users?	Clear business scenarios

2) Relation with this template

• spec.md defines expected behavior (strong BDD alignment).
• tasks.md can include explicit technical test tasks (strong TDD alignment).
• contracts/ provides verifiable rules for both.

3) How to write a strong spec for TDD

Recommended structure

1. In spec.md, define precise, measurable rules.
2. In plan.md, define technical test strategy.
3. In tasks.md, include test tasks before implementation tasks.

TDD checklist

• Every requirement has a technical validation.
• Test tasks are explicit and executable.
• Failure criteria are clear before implementation.
• Test results are logged in the logbook.

4) How to write a strong spec for BDD

Recommended structure

1. In spec.md, write scenarios using:
   • Given
   • When
   • Then
2. Describe observable behavior, not internal code details.
3. Use language understandable by business and technical audiences.

BDD checklist

• Scenarios are clear and verifiable.
• Language is unambiguous.
• Every scenario maps to a requirement.
• Behavior can be demonstrated in a functional review.

5) Quick scenario template

Given [initial context]
When [action or event]
Then [expected result]

6) EARS: verifiable acceptance criteria (industry standard)

EARS (Easy Approach to Requirements Syntax) is the notation the SDD industry consolidated for acceptance criteria — AWS Kiro generates its requirements.md in EARS, and each line maps almost 1:1 to a test case. Use it inside the acceptance criteria section of spec.md.

Base patterns:

Pattern	Template	Use for
Ubiquitous	THE SYSTEM SHALL [behavior]	Rules that always apply
Event-driven	WHEN [trigger], THE SYSTEM SHALL [behavior]	Responses to events
State-driven	WHILE [state], THE SYSTEM SHALL [behavior]	Behavior during a state
Unwanted behavior	IF [error condition], THEN THE SYSTEM SHALL [behavior]	Error handling
Optional feature	WHERE [feature is enabled], THE SYSTEM SHALL [behavior]	Configurable features

Example (login feature):

THE SYSTEM SHALL store passwords hashed, never in plain text.
WHEN the user submits valid credentials, THE SYSTEM SHALL create a session and redirect to the dashboard.
IF the user submits invalid credentials 5 times, THEN THE SYSTEM SHALL lock the account for 15 minutes.

How EARS and Given/When/Then work together:

• Given/When/Then describes an example in business language (great for conversation and review).
• EARS states the rule in verifiable language (great for testing and for AI agents).
• A strong spec uses both: scenarios for understanding, EARS lines for verification.

EARS checklist:

• Every EARS line has exactly one SHALL and one observable behavior.
• No vague words (“fast”, “easy”, “intuitive”) without a measurable value.
• Every acceptance criterion maps to at least one test task in tasks.md.

7) Recommended combined strategy (TDD + BDD + EARS)

1. Define behavior in spec.md (BDD scenarios).
2. Write acceptance criteria as EARS lines in spec.md.
3. Translate behavior into technical tasks in tasks.md (TDD).
4. Implement in short iterations.
5. Register findings and updates in history.md and bitacora/.

8) Common mistakes

• Writing vague specs without verifiable criteria.
• Mixing business scope and technical detail in one section.
• Not updating history.md when scenarios change.
• Implementing without confirming the spec is still current.

💡 Quick tips

• Start from a simple one-paragraph project description.
• Ask the AI to confirm the active spec before coding.
• Close every session with validation and a clear next step.

📊 Visual flow

flowchart LR
  A["Project idea"] --> B["Spec approved"]
  B --> C["Plan aligned"]
  C --> D["Tasks prioritized"]
  D --> E["Implementation"]
  E --> F["Validation + Logbook"]