Spec Kit + Claude Code Integration: End-to-End Golang Project Setup

Spec Kit + Claude Code Integration: End-to-End Go Project Setup

We’ve installed the specify CLI (Article 02) and understood its output structure (Article 03). Now it’s time to bring everything together: integrating Spec Kit with Claude Code in one cohesive workflow for the Santekno Shop project.

This article is “zero to working” — from an empty directory to a workflow you can run every single day. If your goal is spec kit claude code integration golang without guesswork, this is the end-to-end blueprint.

04.1 Integration Architecture

Spec Kit and Claude Code are not competing tools — they operate at different layers, and understanding that separation is what makes the integration click. The diagram below stacks the three layers so you can see who owns what.

 1Layer 1: SPEC KIT (specify CLI)
 2  Manages spec lifecycle: create → clarify → plan → implement
 3  Output: committable .md files
 4
 5Layer 2: CLAUDE CODE (claude CLI)
 6  AI that executes instructions based on context
 7  Output: .go files, tests, documentation
 8
 9Layer 3: CODEBASE
10  The Go project following the constitution

The takeaway: Spec Kit is the orchestrator that manages what to build, Claude Code is the executor that decides how, and the codebase is the final artifact. When specify implement runs, Spec Kit collects context → builds a structured prompt → sends it to Claude Code → receives the result → saves it to the correct files.

04.2 Project Initialization

Every integration starts from a clean project skeleton that already matches Clean Architecture, so Spec Kit and Claude Code both see a predictable layout. The commands below scaffold the Go module and the .specify/ directory in one pass.

1mkdir santekno-shop && cd santekno-shop
2git init
3go mod init github.com/santekno/santekno-shop
4mkdir -p internal/{product,order,user}/{domain,usecase,repository,handler}
5mkdir -p cmd/server migrations api .specify/{features,history,_templates}

After this runs you have a repository whose structure already tells the AI where domain, usecase, repository, and handler code belongs — half the “conventions” battle is won before you write a line of Go.

04.3 specify.config.json Setup

The specify.config.json file is the contract that tells Spec Kit which model to call, where specs live, and what to run after every implement. The configuration below is the minimal viable setup for Santekno Shop.

1{
2  "version": "1",
3  "project": { "name": "Santekno Shop", "language": "go", "architecture": "clean" },
4  "ai": { "default_model": "claude-sonnet-4-20250514" },
5  "paths": { "spec_dir": ".specify", "source_dir": "internal" },
6  "hooks": { "post_implement": "go build ./... && go vet ./..." }
7}

The single most valuable line here is the post_implement hook: every generated phase is immediately compiled and vetted, so a broken build is caught the moment it appears rather than three commits later.

04.4 How specify CLI Calls Claude Code

Understanding what happens “under the hood” makes troubleshooting far easier, because you can see exactly which files Spec Kit reads and how big the prompt gets. Running with --verbose prints the whole interaction.

1# Verbose mode shows the full interaction
2specify plan product-service --verbose
3
4# Output:
5# [VERBOSE] Reading constitution.md (1,245 chars)
6# [VERBOSE] Reading spec.md (2,341 chars)
7# [VERBOSE] Calling Claude API (claude-sonnet-4-20250514)...
8# [VERBOSE] Response received (15.2s, 2,891 tokens)

The key insight: the prompt sent to Claude is assembled in a fixed order — system prompt → constitution → specification → existing code → generation instructions. When output drifts from your conventions, the culprit is almost always one of those upstream inputs, not Claude itself.

04.5 Branch Strategy

Spec Kit works best when spec review and implementation live on separate branches, so a reviewer can approve what before anyone debates how. The tree below shows the two-branch pattern per feature.

1main (protected)
2├── develop (integration)
3│   ├── spec/SHOP-456-product-service  ← Spec PR
4│   └── feat/SHOP-456-product-service  ← Implementation PR

That structure gives you a clean audit trail: the spec PR is small and readable, and the implementation PR references it. In practice the two branches map to two short command sequences, shown next.

 1# Spec workflow
 2git checkout -b spec/SHOP-456-product-service develop
 3specify feature product-service && specify clarify product-service
 4specify plan product-service && specify tasks product-service
 5git add .specify/ && git commit -m "spec(SHOP-456): add product service specification"
 6# Create PR → review → merge
 7
 8# Implementation workflow
 9git checkout -b feat/SHOP-456-product-service develop
10specify implement product-service --phase=1
11git add . && git commit -m "feat(product): implement domain layer [SHOP-456]"
12# Continue per phase...

Notice the discipline this enforces: specs are committed and merged before a single .go file is generated, so implementation always starts from an approved contract rather than an assumption.

04.6 Pre-commit Hook for Spec Validation

Automating spec validation at commit time stops malformed specs from ever entering history. The hook below validates any feature whose spec files changed in the staged set.

1#!/bin/bash
2SPEC_CHANGES=$(git diff --cached --name-only | grep "^\.specify/features/")
3if [ -n "$SPEC_CHANGES" ]; then
4    FEATURES=$(echo "$SPEC_CHANGES" | grep -oP '\.specify/features/\K[^/]+' | sort -u)
5    for FEATURE in $FEATURES; do
6        specify validate --feature="$FEATURE" || exit 1
7    done
8fi

With this hook in place, a spec that fails validation blocks the commit — the quality gate runs whether or not the developer remembers to run it manually.

04.7 VS Code Integration

If your team lives in VS Code, wiring Spec Kit commands into tasks removes the friction of switching to a terminal. The tasks.json below exposes plan and implement as one-click commands with prompted inputs.

 1// .vscode/tasks.json
 2{
 3  "tasks": [
 4    {
 5      "label": "Spec Kit: Run Plan",
 6      "type": "shell",
 7      "command": "specify plan ${input:featureName}"
 8    },
 9    {
10      "label": "Spec Kit: Implement Phase",
11      "type": "shell",
12      "command": "specify implement ${input:featureName} --phase=${input:phaseNumber}"
13    }
14  ]
15}

The payoff is adoption: when running a plan is a menu selection rather than a memorized command, the whole team actually uses the workflow instead of falling back to ad-hoc prompting.

04.8 Daily Workflow Summary

Once setup is done, the day-to-day rhythm collapses into a short, repeatable loop. The outline below is the exact sequence a developer runs from ticket to PR.

1# 1. Create spec branch from develop
2# 2. specify feature + clarify + plan + tasks (15 min total)
3# 3. Commit .specify/ → spec PR → review → merge
4# 4. Create feat branch
5# 5. specify implement --phase=1 → review → commit
6# 6. specify implement --phase=2 → review → commit
7# 7. go test ./... → implementation PR

The thing to internalize: spec work and implementation work are separate PRs with separate reviews. That separation is what keeps diffs small and keeps the AI anchored to an approved spec.

04.9 Team Onboarding

Because all project context lives in the repository, onboarding a new engineer is mostly a matter of installing tools and reading existing specs. The commands below take a fresh clone to a working setup.

1git clone git@github.com:santekno/shop.git
2npm install -g @github/spec-kit
3go mod download
4export ANTHROPIC_API_KEY="..."
5specify info  # See all existing specs immediately

The result is a sub-15-minute onboarding: specify info surfaces every existing spec, so there is no lengthy knowledge-transfer session — the constitution and specs are the documentation.

04.10 Cost Monitoring

Token cost is real but easy to keep in check when you mine the history logs Spec Kit already writes. The two commands below report total spend and rank the most expensive commands.

1# Total cost
2grep "Cost estimate:" .specify/history/*.log | awk '{gsub(/\$/, ""); sum += $NF} END {print "Total: $" sum}'
3
4# Most expensive commands
5grep "Cost estimate:" .specify/history/*.log | sort -t$ -k2 -rn | head -5

Run these monthly and you’ll usually find specify plan is the priciest command — which is your cue to consider a lighter model for cheaper commands like specify tasks.

04.11 go.mod Setup

Before Spec Kit can generate compilable code, the dependencies it references in the constitution must actually exist in go.mod. The commands below pull in the canonical Santekno Shop stack.

1go get github.com/labstack/echo/v4
2go get github.com/jackc/pgx/v5
3go get github.com/redis/go-redis/v9
4go get github.com/google/uuid
5go get github.com/stretchr/testify
6go get go.uber.org/mock/gomock

Keep this list and the constitution in sync — the AI can only use a library it has been told exists, and a missing dependency here means generated code that won’t build.

04.12 Complete Setup Checklist

Before you run Spec Kit against your first real feature, it pays to confirm every prerequisite is in place. The checklist below is the go/no-go gate for the whole integration.

 1✅ Node.js 18+ installed
 2✅ specify CLI installed globally
 3✅ ANTHROPIC_API_KEY set as environment variable
 4✅ Go module initialized
 5✅ Directory structure: clean architecture
 6✅ specify.config.json at root
 7✅ .gitignore excludes .specify/history/
 8✅ CLAUDE.md written
 9✅ specify info shows correct project info
10✅ go build ./... succeeds

If every box is ticked — especially the last two, where specify info reads your project correctly and go build passes — your integration is ready for production use.

04.13 Troubleshooting

Most integration problems fall into three recurring buckets, each with a fast fix. The snippets below address inconsistent output and timeouts.

1# Inconsistent code output → add scan exclusions
2{ "paths": { "scan_exclude": ["vendor/", "*.pb.go", "*_mock.go"] } }
3
4# Timeout on complex features → raise the budget
5specify plan complex-feature --timeout=120

For file overwrites there is no flag to save you: always confirm you are on the correct feat/ branch before running specify implement, because it rewrites existing files without warning.

04.14 Manual Claude Code Session for Complex Tasks

Sometimes you want tighter control than specify implement gives — for those cases you can export Spec Kit’s context and feed it to a manual Claude Code session. The commands below show both ways to hand off that context.

1# Export context for manual session
2specify context product-service --output=/tmp/product-context.md
3
4# Use in Claude Code session
5cat /tmp/product-context.md | claude
6
7# Or inject directly
8claude --context=/tmp/product-context.md

Reach for this when you need to iterate on one specific section or steer the AI conversationally — you keep Spec Kit’s assembled context while gaining the flexibility of an interactive session.

04.15 Jira/Linear Integration

Spec Kit can bridge to your project-management tool so specs and tickets stay in lockstep. The commands below create a feature from a Jira ticket and auto-transition its status.

1# Create feature from Jira ticket
2jira view SHOP-789 | specify feature search-by-sku --from-stdin
3
4# Update Jira status after spec
5specify hooks add post-specify "jira transition SHOP-789 'In Review'"

Wiring these hooks means your ticket board reflects reality automatically — the moment a spec is written, the ticket moves to review with no manual bookkeeping.

04.16 The Post-implement Hook in Action

The post_implement hook from Section 04.3 is what guarantees each phase ends in a buildable state. The console trace below shows it firing after a phase completes.

1[specify] Phase 1 implementation complete.
2[specify] Running post_implement hook: go build ./... && go vet ./...
3[go build] ok
4[go vet] no issues
5[specify] All checks passed. Files committed to phase-1 changes.

If go build fails here, Spec Kit reports the error and asks you to fix it before continuing — which is precisely why per-phase implementation never leaves the repository in a broken state.

04.17 The .gitignore for Spec Kit Projects

You want to commit your specs but never the transient history, cache, or local secrets. The .gitignore fragment below draws that line.

# Spec Kit: keep specs, ignore history and cache
.specify/history/
.specify/temp/
.specify/.cache/

# Local config overrides (may contain API key paths)
specify.config.local.json

The rule of thumb: version the specs (they are the contract), ignore the logs and caches (they are byproducts). This keeps the repository clean while preserving the audit trail you actually care about.

04.18 Tips & Gotchas

Hard-won lessons compress into a handful of tips and gotchas worth internalizing before you scale this up. The list below captures the ones that most often bite teams.

1💡 Tip 1: Set up .specify/ before writing any code — even for existing projects.
2💡 Tip 2: Use --dry-run to preview before large executions.
3💡 Tip 3: Commit after each phase — a 50-line PR reviews far easier than 500.
4💡 Tip 4: Review history logs for cost optimization.
5⚠️ Gotcha 1: Never use --all on large projects — the context window can overflow.
6⚠️ Gotcha 2: specify implement overwrites existing files without warning.
7⚠️ Gotcha 3: New libraries in go.mod don't auto-update the constitution.
8⚠️ Gotcha 4: Different models produce different output styles — standardize one.

If you remember only one line, make it Gotcha 2: always verify your branch before specify implement, because there is no undo prompt for an overwrite.

04.19 Integration with Code Review

The implementation PR is far more reviewable when it links straight back to the spec it fulfills. The template below gives reviewers everything they need to verify compliance at a glance.

1## Implementation via Spec Kit
2
3**Spec:** `.specify/features/product-service/spec.md` (v1.2)
4**Plan:** `.specify/features/product-service/plan.md`
5**Tasks completed:** Phase 1-4 (all)
6
7**Spec compliance:** All ACs from spec verified.
8**Test coverage:** 91.3% (usecase layer)

With this block in the PR description, a reviewer can open the spec, check each acceptance criterion against the diff, and approve with confidence — spec-to-code traceability becomes part of the review, not an afterthought.

04.20 Summary

Spec Kit + Claude Code integration is a layered architecture: Spec Kit manages the spec lifecycle and automates prompt engineering, Claude Code performs the AI execution, and the codebase is the final output.

Recommended daily workflow: spec branch → specify feature/clarify/plan/tasks → spec PR → feat branch → specify implement per phase → implementation PR.

Key integration points: specify.config.json defines models and hooks, CLAUDE.md and constitution.md work together as context, and history logs provide the audit trail.

Critical practice: Always run specify implement per phase (--phase=N), never --all for projects with existing code. Review after each phase is integral to the workflow.

In the next article, we deep-dive into the first and most fundamental command: speckit.constitution — the project constitution every other command reads.