How I Built a Documentation-Driven Development Workflow with Claude Code

Source: Dev.to

GitHub:
Docs:

The Problem

In most teams:

• PM writes requirements somewhere (Notion, Jira, Google Docs)
• Developer reads it, makes assumptions, builds something
• QA tests against… what exactly?
• Bugs get filed, fingers get pointed

The documentation drifts from reality. Nobody knows what’s correct anymore.

The Solution: Docs as Code

What if the spec file is the source of truth, and AI reads it directly?

PM/BA: /write-spec user-export     → creates docs/user-export/spec.md
Dev:   /develop-feature user-export → Claude reads spec, builds feature

That’s it. No telephone game. Claude reads the same spec the PM wrote.

How It Works

• PM runs /write-spec – Claude asks questions, generates a structured spec.
• Dev runs /develop-feature – Claude reads the spec and builds the feature with full context.
• GitHub Actions notify – The team stays in sync when specs change.

No back‑and‑forth. No “what did you mean by X?”

Get Started in 30 Seconds

npx create-ai-team

This scaffolds:

• .claude/commands/ – The workflow commands
• docs/example-feature/spec.md – A template to follow
• .github/workflows/ – Optional automation

The Commands

Why This Works

• Single source of truth – The spec file is canonical.
• AI reads context – No copy‑pasting requirements into prompts.
• Structured format – Mermaid diagrams, error codes, test cases.
• Version controlled – Specs live in Git, changes are tracked.

Open Source

The whole thing is open source:

• Repo:
• Docs:
• NPM: npx create-ai-team

Try It

If you’re tired of requirements getting lost in translation, give it a shot:

npx create-ai-team

Then run /write-spec my-feature and see how it feels to have AI understand your full context.

What’s your current workflow for keeping specs and code in sync? I’d love to hear how other teams handle this.