Skip to content

Using SpecBase with Claude Code — 5-Minute Quickstart

This guide gets you from zero to a working SpecBase integration in Claude Code in under five minutes. By the end, your agent will be able to call get_standard_docs, list_archetypes, and generate_stubs natively — without you providing any manual context about what documentation a project needs.

Step 1: Install SpecBase

The fastest path is Homebrew:

brew install aallbrig/tap/specbase
specbase --version  # should print the version

If you’re on Linux or prefer Go:

go install github.com/aallbrig/specbase/cmd/specbase@latest

Or grab a pre-built binary from GitHub Releases for your platform (Linux, macOS, Windows — arm64 and amd64).

Step 2: Configure the MCP Server in Claude Code

Claude Code reads MCP server configuration from .mcp.json in your project root, or from ~/.claude/.mcp.json for a global setup.

Add SpecBase to your project’s .mcp.json:

{
  "mcpServers": {
    "specbase": {
      "command": "specbase",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

Restart Claude Code (close and reopen the terminal session, or run /mcp to refresh). You can verify SpecBase is connected by asking:

“Use the specbase MCP to list all available project archetypes.”

Claude Code will call list_archetypes and show you the 11 supported types.

Step 3: Query the Knowledge Base

Now you can ask Claude Code to look up what documents your project needs. For example, if you’re starting a backend service with GDPR requirements:

“Use specbase to get the required documents for a backend service with gdpr and async_jobs features.”

Claude Code calls get_standard_docs(type="backend_service", features=["gdpr", "async_jobs"]) and gets back structured JSON: a prioritized list of 12 documents, each with a title, category, rationale explaining why it’s required, and a prompt snippet Claude can use as a checklist item.

The response looks like this in the agent’s context:

{
  "archetype": { "id": "backend_service", "name": "Backend Service" },
  "resolved_features": ["gdpr", "async_jobs"],
  "documents": [
    {
      "id": "architecture_overview",
      "title": "Architecture Overview",
      "priority": "P0",
      "category": "engineering",
      "rationale": "Maps external service dependencies, data flows, and failure domains..."
    },
    {
      "id": "gdpr_compliance_checklist",
      "title": "GDPR Compliance Checklist",
      "priority": "P1",
      "category": "legal",
      "rationale": "Ensures all GDPR obligations are tracked..."
    }
  ]
}

Claude Code can use this list to tell you which docs are missing from your repo, generate stub files, or build a project awareness context for future conversations.

Step 4: Generate Stub Files

Once you know what documents you need, use generate_stubs to create starter Markdown files for each one:

“Use specbase to generate stubs for a backend service with gdpr and async_jobs features. Use ‘acme-api’ as the project name.”

Claude Code calls generate_stubs(type="backend_service", features=["gdpr", "async_jobs"], project_name="acme-api") and receives Markdown file contents. It can then write those to disk in your docs/ folder.

You can also do this directly from the CLI:

specbase init acme-api --type backend_service --features gdpr,async_jobs --out ./docs

This creates one .md file per required document, pre-filled with the project name, archetype, and active features. Each stub also includes a reminder of what the document should cover.

Step 5: Use the System Prompt

One of the most useful outputs is the agent system prompt — a pre-built context block that tells Claude Code exactly what documentation your project requires and what to verify. In the runner’s “System Prompt” tab, or via the CLI:

specbase query backend_service --features gdpr,async_jobs --format prompt

Output:

You are working on a Backend Service project.

The following specification documents are required for this project:

1. Architecture Overview [Required] — Verify the project has an architecture overview mapping all external service dependencies, data flows, and failure domains.
2. GDPR Compliance Checklist [Recommended] — Ensure GDPR obligations are tracked and assigned owners.
3. Data Subject Request Flow [Recommended] — Verify the project has a documented process for handling erasure, portability, and access requests.
...

Active features: gdpr, async_jobs

Paste this into your Claude Code CLAUDE.md or use it as a system prompt. Every time Claude Code works on your project, it has a clear picture of what documentation standards apply.

Alternatively: Use the Remote MCP (No Install)

If you can’t install a binary or just want to try it out, connect to the hosted MCP at mcp.specbase.net:

{
  "mcpServers": {
    "specbase": {
      "type": "streamable-http",
      "url": "https://mcp.specbase.net/mcp"
    }
  }
}

The remote service is free, requires no authentication, and runs the same KB as the local binary. The tradeoff: ~200ms latency vs. ~5ms local, and a rate limit of 60 requests/minute. For daily use, the local install is better; for quick experiments or CI environments, the remote is fine.

See the full MCP integration guide for Cursor and VS Code Copilot setup, the full tool reference, and troubleshooting tips.