My Workflow with Claude: Spec-Driven Development with AgentSpec

Source: Author

Not a medium member? Read here!

Everyone changed his workflow since AI begins in our daily work.

Some started with Copy and Pasting in ChatGPT, then evolve to Vibe Coding. But both of these approaches have a problem: context and memory.

The main problem of every setup and AI workflow is that the AI don’t have enough context of what needs to be done, so he basically solve a problem in a box.

That’s the problem Spec-Driven Development (SDD) comes to solve.

SDD is a software engineer methodology that breaks the problem into specs and serve these specs to the AI as the source of truth.

So in the specs we should identify the what and why needs to be done, the AI will discover how.

We have different Open-Source SDD projects:

• https://github.com/github/spec-kit
• https://github.com/Fission-AI/OpenSpec
• https://github.com/bmad-code-org/bmad-method

But the one I adapted to best and gives me the most confidence to rely on AI during the process is AgentSpec:

• https://github.com/luanmorenommaciel/agentspec

Workflow with AgentSpec

AgentSpec runs in 05 phases, different than the Traditional Workflow that you give a full prompt or description of what needs to be done.

In the AgentSpec you iterate in the process and understand exactly what AI will do in 05 phases:

Source: Author

Brainstorm (/brainstorm): You clarify the scope and the approach, and close the remaining gaps in your architecture or PRD. The AI asks you questions to pin down the request. It's literally a brainstorming session.

Define (/define): The requirements phase. You capture the context the AI needs, plus the quality gates: how confident is the AI that it can actually build this?

Design (/design): The full architecture the AI will work from. How the folders are structured, and what each agent needs to build.

Build (/build): Where the magic happens. The agent builds everything agreed in the documents above, the full architecture and the code. So take your time in the phases before this one. Read, change, and update the documents until they say exactly what you mean.

Ship (/ship): The deployment phase. If you built something meant to run on AWS and you have the CLI configured, Ship handles the whole deployment for you. You just have to define it in the documents first: whether you're using IaC or the CLI itself.

Source: Author

And if the PRD changes, or you spot a gap during Build, you can update the whole chain with Iterate (/iterate):

Source: Author

Here’s what I like most about all of this: you always have living artifacts. Your documentation and your agreements never go stale, and they stay easy to find. Anyone who’s inherited a project knows how rare that is.

Agents, Memory and Knowledge Base

AgentSpec ships 58 specialist agents across 8 categories, 5 skills, 31 slash commands, and 23 knowledge-base (KB) domains. The Build agent reads your DESIGN doc’s file manifest and auto-delegates each file to the matching specialist.

Source: Author

Every agent follows the same cognitive contract:

• KB-first: check the local KB before reaching for external sources.
• Confidence-scored: compute confidence from retrieved evidence instead of self-asserting.
• Escalation-aware: hand off when the task is out of domain.
• Quality-gated: run a pre-flight checklist before answering.

You can also build your own agent with the Context7 MCP, following the same architecture AgentSpec uses.

Working on a C# project? Spin up an agent that knows C#, and point its knowledge base at Context7 so it always pulls current docs instead of guessing.

To always have the most updated docs, you can create your knowledge base from Context7 MCP. Also, every time you need to update something you will have the Context7 as second source of truth and your knowledge base as primary.

Want to learn with a real example? Check this medium article: https://medium.com/@lorenzouriel/how-i-master-claude-code-with-spec-driven-development-b7c1de15ff9b

Enjoying the content?

Support me saying thanks by buying me a coffee! ☕