Why spec-sync?: spec-sync docs

Getting started

How SpecSync compares to other documentation validation approaches.

The Documentation Problem

Every team has experienced it: someone renames a function, the docs still reference the old name, and nobody notices for months. Or worse --- an AI agent reads your stale docs and generates code against an API that no longer exists.

Traditional documentation tools fall into two camps:

1. Auto-generated docs (JSDoc, rustdoc, Godoc) --- accurate but shallow. They tell you what exists, not why it exists or how pieces fit together.
2. Hand-written docs (Notion, Confluence, markdown) --- rich context but drift from reality within days of being written.

SpecSync occupies a third space: validated hand-written specs. You write the spec, SpecSync ensures it stays true.

Comparison Matrix

Detailed Comparisons

vs. Spec Kit and OpenSpec

Spec Kit provides guided SDD plus configurable, resumable workflows and human gates. OpenSpec provides an action-based artifact graph, semantic deltas, agentic verification, synchronization, and archival. The comparison below was verified against their official documentation on 2026-07-11 and distinguishes deterministic blocking enforcement from configurable or agentic workflows:

Sources: Spec Kit workflows, Spec Kit recommended workflow, OpenSpec commands, and OpenSpec workflows.

For evaluator-ready detail, see SpecSync vs Spec Kit, SpecSync vs OpenSpec, using them together, and the adversarial drift proof.

SpecSync does not attempt to win by generating more Markdown. Its differentiator is that an approved specification becomes a deterministic executable CI contract: code, exports, requirements, tests, deltas, approvals, and archival state must agree before the change can close.

vs. OpenAPI / Swagger

OpenAPI is excellent for HTTP APIs --- it defines request/response schemas and can generate client SDKs. But it only covers the API boundary. It doesn't validate that your internal modules match their documentation, doesn't catch renamed helper functions, and doesn't track database schema drift.

Use OpenAPI when: You need to define and document REST/GraphQL APIs for external consumers.

Use SpecSync when: You need to ensure internal module documentation stays accurate across your entire codebase --- not just the API surface.

Use both when: You have a large project with both public APIs and complex internal architecture.

vs. TypeDoc / JSDoc / rustdoc

Auto-generated documentation tools extract comments from source code. They're always accurate (by definition), but they only document what's there --- not architectural decisions, invariants, behavioral constraints, or cross-module relationships.

Use auto-doc tools when: You want API reference docs generated from code comments.

Use SpecSync when: You need specs that capture why something works the way it does, what invariants must hold, and how modules relate to each other --- and you want those specs validated against the real code.

vs. Architecture Decision Records (ADRs)

ADRs document decisions --- why you chose Postgres over MongoDB, or why the auth middleware uses JWTs. They're valuable but static: once written, they don't get validated against the codebase.

Use ADRs when: You want to record architectural decisions and their rationale.

Use SpecSync when: You want living documentation that stays synchronized with your code. SpecSync specs can include ADR-like context in companion files (context.md) while the core spec stays validated.

vs. Notion / Confluence

Wiki-style tools are great for onboarding docs, runbooks, and team knowledge bases. But they have no connection to source code --- documentation rot is inevitable.

Use wikis when: You need free-form collaborative documentation for processes, onboarding, and team knowledge.

Use SpecSync when: You need technical specs that are provably accurate. If it's in the spec, it's in the code.

What Makes SpecSync Different

Bidirectional Validation

Most tools check in one direction --- either "does the code match the docs?" or "do the docs describe the code?" SpecSync checks both:

• Spec references something missing from code -�� Error (your spec is lying)
• Code exports something not in the spec -�� Warning (your spec is incomplete)

Language Agnostic

One tool, one format, 33 languages --- the same *.spec.md contract and lifecycle across polyglot repositories.

AI-Native

SpecSync was built for the AI-assisted development era:

• MCP server mode lets AI agents query your specs, check coverage, and generate new specs in real time
• Agent-native enrichment lets your existing coding agent refine deterministic scaffolds without moving credentials into SpecSync
• Structured output (JSON mode) integrates cleanly with agent workflows
• AGENTS.md generation produces instruction files for Claude Code, Cursor, and Copilot

Verified Change Lifecycle

Specs aren't static documents --- they have a lifecycle:

draft -�� approved -�� implementing -�� verifying -�� accepted -�� archived

SpecSync manages this lifecycle with deterministic interviews, adaptive artifacts, semantic deltas, two human approval gates, requirement/test traceability, effective-contract validation, and immutable archives. Canonical module maturity remains separate.

Zero Dependencies

SpecSync is a single Rust binary. No Node.js runtime, no Python virtualenv, no Docker container. Download it and run it. Installs via cargo install specsync, a GitHub Action, or a VS Code extension.

When NOT to Use SpecSync

SpecSync is not the right tool if:

• You only need API reference docs --- use auto-doc tools (TypeDoc, rustdoc) instead
• Your project has < 3 modules --- the overhead isn't worth it for tiny projects
• Your team doesn't write specs --- SpecSync validates specs and scaffolds the structure, but humans or their coding agents still own the contract
• You need runtime API contract testing --- use OpenAPI + contract testing tools instead

Getting Started

Ready to try it?

# Install
cargo install specsync

# Initialize in your project
specsync init

# Generate specs for all modules
specsync generate

# Validate
specsync check

Or see the full workflow guide for a guided walkthrough.