Installation
Claude Code Integration

Claude Code Integration

Integrate fspec with Claude Code for AI-driven ACDD workflows using slash commands.

What is Claude Code?

Claude Code is Anthropic's official CLI tool for Claude AI that helps with software engineering tasks. It provides a conversational interface where you can use slash commands to trigger specialized workflows.

Why Integrate fspec with Claude Code?

fspec provides a powerful slash command for Claude Code:

  • /fspec - ACDD workflow (both forward and reverse)

This command enables Claude to:

  • ✅ Manage work through Kanban states
  • ✅ Conduct Example Mapping discovery
  • ✅ Generate validated Gherkin specifications
  • ✅ Follow ACDD methodology rigorously
  • ✅ Track progress with persistent state

Installation

Prerequisites

  1. Install fspec globally (see Local Installation)
  2. Install Claude Code from Anthropic

Initialize fspec in Your Project

cd /path/to/your/project
fspec init

This creates:

  • .claude/commands/fspec.md - ACDD slash command for Claude Code
  • spec/CLAUDE.md - Specification guidelines for AI

Verify Installation

In Claude Code, type / to see available commands. You should see:

  • /fspec - Manage specifications and work units using ACDD (forward and reverse)

Using /fspec (Forward ACDD)

The /fspec command helps Claude manage specifications and work units following ACDD workflow.

When to Use

Use /fspec when:

  • Starting a new feature from scratch
  • You want Claude to follow ACDD methodology
  • Managing work units and specifications together
  • Need collaborative discovery (Example Mapping)

Example Workflow

User: /fspec Create a user authentication feature

Claude:
I'll help you create a user authentication feature using ACDD workflow.

Creating work unit...
$ fspec create-work-unit AUTH "User authentication"
✓ Work unit AUTH-001 created

Moving to specifying phase...
$ fspec update-work-unit-status AUTH-001 specifying

Let's start with Example Mapping. What are the key rules for authentication?

User: Email and password required, must validate format

Claude:
Adding rules...
$ fspec add-rule AUTH-001 "Email and password required for authentication"
$ fspec add-rule AUTH-001 "Email must be valid format"

Let me add some concrete examples...
$ fspec add-example AUTH-001 "user@example.com with password 'secret123' succeeds"

I have a question: Should we support OAuth providers like Google?
$ fspec add-question AUTH-001 "Should we support OAuth providers like Google/GitHub?"

[... workflow continues ...]

What /fspec Does

The command guides Claude to:

  1. Create work units with proper prefixes and epics
  2. Conduct Example Mapping by asking questions, capturing rules and examples
  3. Generate Gherkin scenarios from discovery artifacts
  4. Manage Kanban workflow through all states
  5. Link coverage between specs, tests, and implementation
  6. Follow ACDD phases strictly (no skipping)

Using Reverse ACDD with /fspec

Reverse ACDD mode helps Claude reverse engineer existing codebases to create specifications using the fspec reverse command.

When to Use

Use Reverse ACDD when:

  • You have existing code without specifications
  • Want to document what the system currently does
  • Transitioning a legacy project to ACDD
  • Need to understand inherited code

Example Workflow

User: Analyze the authentication system in src/auth/ using fspec reverse

Claude:
I'll reverse engineer the authentication system using fspec reverse.

Analyzing codebase...
[Reads src/auth/login.ts, src/auth/register.ts, etc.]

Found 3 user-facing features:
1. User Login (POST /api/login)
2. User Registration (POST /api/register)
3. Password Reset (POST /api/reset-password)

Creating epic...
$ fspec create-epic user-management AUTH "User authentication and management"

Creating work unit for User Login...
$ fspec create-work-unit AUTH "User login feature" --epic=user-management
$ fspec update-work-unit-status AUTH-001 specifying

Inferring scenarios from code...
$ fspec create-feature "User Login"
$ fspec add-scenario user-login "Login with valid credentials"
$ fspec add-scenario user-login "Login with invalid password"

Creating skeleton test file...
[Creates src/__tests__/auth-login.test.ts]

Linking existing implementation...
$ fspec link-coverage user-login --scenario "Login with valid credentials" \
  --test-file src/__tests__/auth-login.test.ts --test-lines 13-27 \
  --impl-file src/auth/login.ts --impl-lines 45-67 \
  --skip-validation

[... continues for all features ...]

What fspec reverse Does

The fspec reverse command guides Claude to:

  1. Analyze existing code to identify user-facing features
  2. Create work units for each discovered feature
  3. Infer scenarios from code behavior
  4. Generate feature files with best-guess acceptance criteria
  5. Create test skeletons (structure only, not implemented)
  6. Link coverage to existing implementation
  7. Document ambiguities for human clarification

Command Prompts

The slash commands load comprehensive prompts that guide Claude through ACDD workflows. These prompts include:

/fspec Prompt Includes

  • Complete ACDD workflow steps
  • fspec command reference
  • Example Mapping guidance
  • Gherkin best practices
  • Coverage tracking instructions
  • Error handling patterns

Reverse ACDD Mode Includes

  • Code analysis strategies
  • Scenario inference patterns
  • Test skeleton generation
  • Coverage linking for existing code
  • Ambiguity documentation
  • Transition to forward ACDD

Customizing Commands

You can customize the slash command by editing:

  • .claude/commands/fspec.md - Modify ACDD workflow
  • spec/CLAUDE.md - Update specification guidelines

Best Practices

For Forward ACDD (/fspec)

  1. Start with discovery - Don't skip Example Mapping
  2. Answer questions - Red cards must be answered before proceeding
  3. Trust the workflow - Let Claude follow ACDD phases
  4. Review generated specs - Always validate Claude's Gherkin

For Reverse ACDD (fspec reverse)

  1. Provide context - Tell Claude which directories to analyze
  2. Clarify ambiguities - Review and answer ambiguous scenarios
  3. Implement skeletons - Use generated test skeletons as templates
  4. Validate coverage - Check that all code is mapped

General Tips

  1. Use explicit prefixes - AUTH, API, UI, etc. for clear organization
  2. Create epics first - Group related work for better tracking
  3. Check the board - Run fspec board to visualize progress
  4. Trust coverage tracking - Keep specs, tests, and code linked

Troubleshooting

Commands not appearing

If /fspec doesn't appear in Claude Code:

  1. Verify file exists:

    ls -la .claude/commands/
# Should show fspec.md

  2. Restart Claude Code

  3. Re-run fspec init if files are missing

Claude not following workflow

If Claude skips phases or doesn't use fspec commands:

  1. Remind Claude about the workflow:

    Please follow the ACDD workflow and use fspec commands

  2. Reference the documentation:

    Check spec/CLAUDE.md for the correct process

  3. Use explicit commands:

    Run: fspec update-work-unit-status AUTH-001 testing

Next Steps

Local DevelopmentACDD Methodology