ATDD Assistant

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2026-01-19 Applicability: Claude Code Skills

Purpose

This skill guides teams through the Acceptance Test-Driven Development workflow, helping them:

Conduct effective Specification Workshops
Write testable acceptance criteria in Given-When-Then format
Convert criteria to executable acceptance tests
Ensure proper collaboration between PO, Dev, and QA
Integrate ATDD with BDD and TDD for complete workflow

Quick Reference

ATDD Workflow Checklist

┌─────────────────────────────────────────────────────────────────┐
│  🤝 SPECIFICATION WORKSHOP Phase                                 │
│  □ Product Owner presents user story                            │
│  □ Team asks clarifying questions                               │
│  □ Acceptance criteria defined together                         │
│  □ Concrete examples written for each AC                        │
│  □ Edge cases and error scenarios discussed                     │
│  □ Out of scope explicitly documented                           │
├─────────────────────────────────────────────────────────────────┤
│  🧪 DISTILLATION Phase                                           │
│  □ Examples converted to executable tests                       │
│  □ Ambiguity removed from tests                                 │
│  □ Tests in executable format (Gherkin, FitNesse, etc.)         │
│  □ Product Owner signs off on tests                             │
├─────────────────────────────────────────────────────────────────┤
│  💻 DEVELOPMENT Phase                                            │
│  □ Acceptance tests initially fail (RED)                        │
│  □ BDD used for feature tests, TDD for unit tests               │
│  □ Incremental progress toward passing ATs                      │
│  □ All acceptance tests pass (GREEN)                            │
│  □ Code refactored and clean                                    │
├─────────────────────────────────────────────────────────────────┤
│  🎬 DEMO Phase                                                   │
│  □ All acceptance tests passing                                 │
│  □ Demo environment prepared                                    │
│  □ Key stakeholders present                                     │
│  □ Product Owner validates functionality                        │
│  □ Story accepted or criteria refined                           │
└─────────────────────────────────────────────────────────────────┘

Acceptance Criteria Quick Reference

| Element | Format | Example | |---------|--------|---------| | User Story | As a / I want / So that | As a customer, I want to reset my password, so that I can regain access | | AC Format | Given / When / Then | Given I'm on the login page, When I click "Forgot Password", Then I should see a reset form | | Out of Scope | Bullet list | - SMS reset, - Admin reset capability | | Technical Notes | Bullet list | - Token expires in 24 hours |

INVEST Criteria

| Principle | Description | Check | |-----------|-------------|-------| | Independent | Can be developed independently | No blocking dependencies | | Negotiable | Details can be discussed | Not a contract | | Valuable | Delivers business value | PO can explain the "why" | | Estimable | Can be estimated | Team understands scope | | Small | Fits in one sprint | < 1 week of work | | Testable | Can be verified | Clear acceptance criteria |

Workflow Assistance

Specification Workshop Guidance

When conducting a specification workshop:

Story Presentation (5 min)

User Story: [Title]

As a [role]
I want [feature]
So that [benefit]

Business Value: [Why this matters]

Clarifying Questions (10 min)
- Business: "What's the value?", "Who are the users?"
- Development: "What's the impact?", "Dependencies?"
- Testing: "What could go wrong?", "Edge cases?"

AC Definition (20 min)

### AC-1: [Criterion name]
**Given** [precondition]
**When** [action]
**Then** [expected result]

Out of Scope (10 min)
- Explicitly list what is NOT included
- Prevents scope creep during development
Technical Notes (5 min)
- Implementation hints
- Known constraints
- Dependencies

Distillation Guidance

When converting AC to executable tests:

Review Each AC
- Is it unambiguous?
- Can it be automated?
- Does it verify business value?
Choose Test Format | Format | Best For | |--------|----------| | Gherkin | Behavior-focused, business-readable | | FitNesse | Data-driven, wiki tables | | Robot Framework | Complex workflows | | Code (xUnit) | Technical teams |

Write Executable Tests

# For AC-1: Password reset request
Scenario: Request password reset
  Given I am on the login page
  And I have a registered account
  When I click "Forgot Password"
  And I enter my email address
  Then I should see "Reset link sent"
  And I should receive an email within 5 minutes

Get PO Sign-off
- PO confirms tests represent requirements
- Sign-off before development starts

Demo Guidance

When preparing for demo:

Pre-Demo Checklist

□ All acceptance tests passing
□ Demo environment ready
□ Test data prepared
□ Stakeholders notified

Demo Structure (15-30 min)
- Context (1 min): Remind story and AC
- Tests (2 min): Run acceptance tests live
- Feature (5-10 min): Walk through each AC
- Feedback (5 min): Gather feedback, Q&A
Possible Outcomes
- ✅ Accepted: Story complete
- 🔄 Refinement: Return to workshop
- ❌ Rejected: Identify gaps

User Story Template

## User Story: [Title]

**As a** [role]
**I want** [feature]
**So that** [benefit]

## Acceptance Criteria

### AC-1: [Happy path]
**Given** [precondition]
**When** [action]
**Then** [expected result]

### AC-2: [Error scenario]
**Given** [precondition]
**When** [invalid action]
**Then** [error handling]

### AC-3: [Edge case]
**Given** [edge condition]
**When** [action]
**Then** [appropriate result]

## Out of Scope
- [Feature 1 not included]
- [Feature 2 deferred to future]

## Technical Notes
- [Implementation constraint]
- [Dependency information]
- [Performance requirement]

## Questions / Assumptions
- [Open question 1]
- [Assumption 1]

Integration with Other Workflows

ATDD → BDD → TDD Flow

ATDD Level (Business Acceptance)
  │
  │  User Story + Acceptance Criteria
  │  PO Sign-off
  │
  ▼
BDD Level (Behavior Specification)
  │
  │  Feature Files (Gherkin)
  │  Three Amigos collaboration
  │
  ▼
TDD Level (Implementation)
  │
  │  Unit Tests
  │  Red → Green → Refactor
  │
  ▼
Verification (Demo)
  │
  └──▶ PO Acceptance

ATDD + SDD Integration

# Link ATDD to SDD Spec

## User Story: US-123

**Spec Reference**: SPEC-001

### AC-1: Implements SPEC-001 Section 3.1
**Given** [from spec requirements]
**When** [action per spec]
**Then** [expected per spec]

Configuration Detection

This skill supports project-specific configuration.

Detection Order

Check CONTRIBUTING.md for "Disabled Skills" section
Check CONTRIBUTING.md for "ATDD Standards" section
Check for existing acceptance test patterns
If not found, default to standard ATDD practices

First-Time Setup

If no configuration found:

Ask: "This project hasn't configured ATDD preferences. Which acceptance test format do you prefer?"
- Gherkin (Cucumber, SpecFlow)
- FitNesse tables
- Code-based (xUnit)
After selection, suggest documenting in CONTRIBUTING.md:

## ATDD Standards

### Acceptance Test Format
- Gherkin (Cucumber.js)

### User Story Template
- INVEST criteria required
- Given-When-Then format for AC

### Workflow
- Specification workshop required for all stories
- PO sign-off before development
- Demo for each completed story

Detailed Guidelines

For complete standards, see:

For related standards:

Anti-Patterns Quick Detection

| Symptom | Likely Problem | Quick Fix | |---------|----------------|-----------| | Features marked done but PO rejects | AC not validated with PO | Mandatory PO sign-off | | Long dev with no progress | AC too large or vague | Break into smaller criteria | | Acceptance tests always pass first time | Tests written after implementation | Tests before dev | | Endless scope discussions | No "out of scope" definition | Explicit out-of-scope | | AC can't be automated | QA/Dev not involved in AC definition | Technical perspective in workshop |

RACI Matrix

| Activity | Product Owner | Developer | QA/Tester | |----------|--------------|-----------|-----------| | Define user story | R/A | C | C | | Specification workshop | R | C | C | | Define acceptance criteria | A | R | R | | Write executable tests | C | R | R/A | | Implement feature | C | R/A | C | | Execute acceptance tests | I | R | R/A | | Accept/reject feature | R/A | I | I |

Legend: R = Responsible, A = Accountable, C = Consulted, I = Informed

Related Standards

Acceptance Test-Driven Development - Core ATDD standard
Behavior-Driven Development - BDD standard
Test-Driven Development - TDD standard
Spec-Driven Development - SDD workflow
Testing Standards - Testing framework
BDD Assistant - BDD skill
TDD Assistant - TDD skill

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-01-19 | Initial release |

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards