DEV TOOLS December 7, 2025

# Why We Built Interview-Driven API Development

Claude Code is incredible, but it has a problem: it skips steps. It hallucinates APIs. It marks things "done" without checking. We fixed that with Python hooks that enforce a 10-phase workflow. Here's why research-first beats code-first every time.

[>]

#### Listen to this article

AI-generated audio narration - 8 min read

0:00 / 8:24
[*]

WORKFLOW VISUALIZATION

The 10-phase interview-driven workflow enforced by Python hooks

## The Problem With AI Code Assistants

We love Claude Code. It's genuinely incredible at understanding context, writing clean code, and solving complex problems. But there's a pattern we kept seeing over and over:

1. Ask Claude to implement an API endpoint
2. Claude writes the code immediately (without researching the actual API)
3. The code looks perfect but uses hallucinated parameters
4. Tests fail (or worse, Claude skips them)
5. "Done!" says Claude, marking the task complete

This isn't Claude's fault - it's how most AI assistants work. They're trained to be helpful, which means they want to give you answers fast. But with API development, fast answers are often wrong answers.

The Core Insight

The best developers don't start coding - they start researching. They read the docs. They look at examples. They understand the problem before writing a single line of code. We needed to teach Claude this workflow.

## Five Gaps We Had to Close

### Gap 1: AI Paraphrasing Instead of Quoting

When Claude researches something, it tends to paraphrase what it found rather than using exact terms. This matters because API parameters are case-sensitive, specific strings that must match exactly.

    // What Claude might say:
    "The endpoint supports standard authentication"

    // What the docs actually say:
    "Use X-Api-Key header with Bearer token"

### Gap 2: Claiming Updates Without Verification

Claude would say "I've updated the file" without showing a git diff or verifying the change actually happened. Our hooks now require proof.

### Gap 3: Skipped Tests Accepted As-Is

When tests fail, Claude often marks them as "skipped" and moves on. But skipped tests aren't passing tests - they're potential bugs hiding in your codebase.

### Gap 4: Tasks Marked Complete Without Verification

The workflow wasn't actually done just because Claude said it was. We needed checkpoints that verify each phase is truly complete.

### Gap 5: Environment Variable Mismatches

Test environments and production environments often use different API keys and configurations. Claude would test with one and deploy with another.

## The Solution: Python Hooks

Claude Code has a hook system that lets you intercept tool calls. We built three Python hooks that enforce our workflow:

    hooks/
      enforce-interview.py   # Blocks writing until interview is complete
      track-tool-use.py      # Logs all research activity
      api-workflow-check.py  # Prevents "Stop" until phases are done

These hooks create a 10-phase workflow that Claude must follow:

1. Scope - Define what we're building
2. Research Initial - Find official documentation
3. Interview - Ask the user questions
4. Research Deep - Dive into edge cases
5. Schema Creation - Define TypeScript interfaces
6. Environment Check - Verify API keys exist
7. TDD Red - Write failing tests first
8. TDD Green - Make tests pass
9. TDD Refactor - Clean up the code
10. Documentation - Update all the docs

## Why Interview-Driven?

The interview phase is the key innovation. Instead of Claude making assumptions, it's forced to ask you questions with multiple-choice options:

    "Which AI provider should this endpoint support?"
    1. OpenAI (GPT-4o)
    2. Anthropic (Claude)
    3. Google (Gemini)
    4. All of the above
    5. Type something else...

The options come from the research phase, so they're real choices - not hallucinated possibilities. And your answers are tracked in a state file, so Claude can reference them during implementation.

Key Benefit

When you answer "Anthropic", Claude won't accidentally implement OpenAI instead. The decision is recorded and enforced throughout the workflow.

## Getting Started

    npx @hustle-together/api-dev-tools

That's it. The installer sets up everything: commands, hooks, state file, and MCP server recommendations. Start your next API endpoint with `/api-create endpoint-name` and experience the difference.

[?]

#### Quick Answers

Ask questions about this article

AI
Hi! I can answer questions about interview-driven API development, the hook system, or how to get started. What would you like to know?
Quick Questions

### Did you find this article helpful?

Your feedback helps us create better content

42 people found this helpful

[HT]

#### Hustle Together Team

We're a small team obsessed with building tools that actually work. We experiment, we iterate, and we share what we learn. No corporate BS - just useful stuff for developers.

### RELATED POSTS

AI

#### Gemini Pro 2.5 vs Claude for Widget Generation

WORKFLOW

#### TDD is Dead, Long Live TDD