Show HN: SpecMind – AI architecture tool for vibe coding

[mushgev]

I built SpecMind, an open source developer tool for spec driven vibe coding. It keeps architecture and implementation aligned from the first commit instead of letting them drift apart.

With AI assistants writing more of our code, projects move faster but architectural consistency is often lost. Each developer or AI can introduce new patterns, and after a few sprints, the structure becomes fragmented. SpecMind helps prevent that by generating and maintaining living architecture specs directly from your code.

It works in three steps: 1. analyze – scans your codebase and generates .specmind/system.sm with architecture diagrams and relationships, 2. design – creates a spec describing how the feature will change the system, 3. implement – applies the spec, updates diagrams, and logs what changed

All specs are plain text files with Markdown and Mermaid diagrams, stored alongside your code. A VS Code extension lets you preview them visually.

Supports TypeScript, JavaScript, Python, and C#, with Go and Rust coming next. Works with Claude Code and Windsurf today, Cursor and Copilot soon.

Demo: https://www.youtube.com/watch?v=4-9gQxw8DQU

Repo: https://github.com/specmind/specmind

Would love to get feedback from engineers working on large or complex codebases.

[mushgev]

SpecMind works by combining static code analysis with AI generated specs. It uses Tree-sitter to parse the entire codebase and build a structured model of services, layers, entities, and dependencies.

When you run analyze, it creates .specmind/system.sm which includes multiple diagram types such as system view, per service architecture, sequence flows, and entity relationships.

design <feature> creates a spec showing proposed changes, and implement <feature> updates the architecture once the feature is built, keeping the spec and code aligned.

All files are text based and versioned in the repo. The goal is to make architecture a living part of the codebase rather than something updated later in Confluence or diagrams.

Next steps include code-to-spec validation, PR diff integration, and more language support.

Happy to answer any technical questions or hear how others deal with architecture drift in fast moving projects.

[elma22]

As someone who has worked on long-lived enterprise codebases, I can confirm that architecture drift is a silent killer. Having a tool that continuously generates specs and diagrams from actual code is extremely useful. The Mermaid diagrams in plain text are a big plus. Excited to see Go and Rust support.

[mushgev]

Thanks for this. Architecture drift was exactly what pushed me to build it. I wanted a way to keep the system picture accurate without anyone needing to manually update diagrams. Keeping everything in plain text with Mermaid felt like the simplest way to make it fit naturally into long-lived projects. Go and Rust support are high on the list.

[zniturah]

This is great. Wondering what was author's experience using this framework for real projects.

[mushgev]

Thanks! I started building this after running into the problem myself. On one project we had five developers, each using AI tools, and everyone ended up structuring things differently. After a few weeks the codebase felt like five mini-projects stitched together.

I wanted something that kept the architecture consistent without everyone having to stop and redraw diagrams all the time. That’s how SpecMind started. We’ve been using it in real projects, and it’s been much easier to keep track of how everything fits together.

[artak_papikyan]

Curious how it works with AI tools like Claude or Cursor in practice. Does it stay lightweight?

[mushgev]

Integration with AI tools like Claude and Cursor is core to how SpecMind works. It runs as slash commands inside those tools, so you can analyze, design, and implement features directly through your AI coding assistant without any heavy setup. Everything stays lightweight since the logic runs through the CLI, and the AI just triggers those commands.

[NarHar]

Checked the repo. How hard is it to plug this into an existing project?

[mushgev]

It is straightforward. You run npx specmind setup <your-ai-tool> in your project so the slash commands are added, then open your AI assistant and run the /analyze command. The CLI parses the entire codebase with Tree-sitter and generates the system.sm file from what already exists. No code changes or prep work needed.

[kolobolo]

Great concept. Can you use it without the VS Code extension, just from the CLI?

[mushgev]

Yes, absolutely. The VS Code extension is only for previewing the .sm files since they use Markdown and Mermaid diagrams. Everything else works through the CLI and slash commands, so you can use SpecMind completely without VS Code.