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

Ever had a PM write requirements in Slack, a developer interpret them differently, and QA test against something else entirely? I got tired of this chaos, so I built a workflow that makes documentation the single source of truth—and Claude Code does the heavy lifting.

GitHub: github.com/quochuydev/workflow
Docs: quochuydev.github.io/workflow

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

1. PM runs /write-spec - Claude asks questions, generates structured spec
2. Dev runs /develop-feature - Claude reads the spec, builds with full context
3. GitHub Actions notify - 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

Command	Who	What
/write-spec	PM/BA	Create spec via guided conversation
/develop-feature	Dev	Build feature from spec
/fix-issue	Dev	Fix bugs with doc context
/trace-flow	Dev	Understand code flow

Why This Works

1. Single source of truth - The spec file is canonical
2. AI reads context - No copy-pasting requirements into prompts
3. Structured format - Mermaid diagrams, error codes, test cases
4. Version controlled - Specs live in git, changes are tracked

Open Source

The whole thing is open source:

• Repo: github.com/quochuydev/workflow
• Docs: quochuydev.github.io/workflow
• 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.