Spec Kit as an AI Pipeline Contract in Golang: Bridge to the Next Topic

Spec Output as a Contract in the AI Pipeline

Treating Spec Kit output as an AI pipeline contract in Golang is the final shift in perspective and, at the same time, the bridge to what comes next. This is the closing article of Topic 2 — and here we see how the specs we have built are not just passive documentation, but also a formal contract that can be consumed by more complex AI pipelines.

From LLM-powered validation to RAG and AI agents, a well-structured spec becomes machine fuel — not merely something for humans to read.

20.1 A Shift in Perspective: Spec as a Machine-Readable Contract

Throughout Topics 1 and 2, we built specs to be read by humans and consumed by Claude Code. But there is a far more powerful perspective: a structured spec is a machine-readable contract. The table below maps each Spec Kit output to the AI system that can consume it.

1Spec Kit Output                     Consumed By
2─────────────────────────────────────────────────
3spec.md (ACs, ECs)          →       AI validator
4plan.md (architecture)      →       AI code reviewer
5tasks.md (work units)       →       AI orchestrator
6constitution.md (rules)     →       AI guardrails
7.specify/contracts/         →       AI schema validator

This mapping is the heart of the entire article: every artifact you produce from the SDD workflow turns out to have an AI “consumer” in a more advanced pipeline — added value you don’t pay extra to obtain.

20.2 Spec as Input to LLM-Powered Validation

After implementation, a spec can become the input for a more sophisticated AI validator. The Go code below shows a SpecValidator that sends the ACs from the spec as ground truth to an LLM to validate endpoint behavior.

 1// Example: an AI validator that uses the spec as ground truth
 2// (preview of Topic 6: LLM-Powered Applications)
 3
 4package validator
 5
 6type SpecValidator struct {
 7    anthropicClient *anthropic.Client
 8    spec            Spec
 9}
10
11func (v *SpecValidator) ValidateEndpointBehavior(
12    ctx context.Context,
13    endpoint string,
14    request, response json.RawMessage,
15) (ValidationResult, error) {
16
17    // Send the spec ACs as context to the LLM
18    prompt := fmt.Sprintf(`
19        Given this spec for endpoint %s:
20        %s
21
22        Given this request:
23        %s
24
25        And this response:
26        %s
27
28        Does this response comply with all ACs?
29        Return JSON: {"compliant": bool, "violations": [{"ac": "AC{n}", "reason": "..."}]}
30    `, endpoint, v.spec.ACsForEndpoint(endpoint), request, response)
31
32    result := v.anthropicClient.Complete(ctx, prompt)
33    return parseValidationResult(result)
34}

This pattern raises validation from “match the string” to “does the response semantically satisfy the intent of the AC?” — something only possible once the spec becomes a formal input to the LLM.

20.3 Spec as an OpenAPI Contract

spec.md can also be transformed into a machine-readable OpenAPI spec. The command below exports a feature into openapi.yaml along with a list of its downstream uses.

1# Convert the spec to OpenAPI (covered in more detail in Topic 3)
2specify export --feature product-review --format openapi
3
4# Output: .specify/features/product-review/openapi.yaml
5# Which becomes:
6# - Source of truth for API documentation
7# - Input for API gateway configuration
8# - Schema for request/response validation middleware
9# - Contract for consumer-driven contract testing

Once exported, a single spec.md gives rise to many derivatives — API documentation, gateway configuration, even contract testing — all originating from the same source of truth.

20.4 Tasks as Orchestration Input

tasks.md can become the input for a more autonomous AI orchestrator. The Go code below shows an orchestrator that identifies groups of parallel tasks and then executes them concurrently with errgroup.

 1// Preview of Topic 8: AI Agents + MCP
 2// Tasks from spec kit → an AI agent that executes them in parallel
 3
 4type SpecKitOrchestrator struct {
 5    tasks      []Task
 6    aiClient   *anthropic.Client
 7    toolClient *mcp.Client
 8}
 9
10func (o *SpecKitOrchestrator) Execute(ctx context.Context) error {
11    // Identify parallel tasks
12    parallelGroups := o.identifyParallelGroups()
13
14    for _, group := range parallelGroups {
15        // Execute parallel tasks concurrently
16        g, ctx := errgroup.WithContext(ctx)
17        for _, task := range group {
18            task := task
19            g.Go(func() error {
20                return o.executeTask(ctx, task)
21            })
22        }
23        if err := g.Wait(); err != nil {
24            return fmt.Errorf("parallel group failed: %w", err)
25        }
26    }
27    return nil
28}

Because tasks.md already maps the dependencies between tasks, the orchestrator can safely execute independent tasks in parallel — the spec structure directly becomes a concurrent execution plan.

20.5 Constitution as AI Guardrails

constitution.md can become guardrails that attach to every LLM call. The Go function below injects the contents of the constitution into the system prompt as an absolute constraint for all generated code.

 1// System prompt from constitution.md
 2func buildSystemPrompt(constitution string) string {
 3    return fmt.Sprintf(`
 4        You are a Go developer working on this project.
 5
 6        ABSOLUTE CONSTRAINTS (from constitution.md):
 7        %s
 8
 9        You MUST follow these constraints in ALL code you generate.
10        If asked to violate them, explain why you cannot and suggest alternatives.
11    `, constitution)
12}
13
14// Every Claude Code session uses this as its foundation

With the constitution injected as an absolute constraint, the project’s architecture rules are applied consistently in every code generation — a guardrail that runs automatically, not one that depends on a developer’s memory.

20.6 Spec as a RAG Document

A structured spec is ideal for RAG (Retrieval Augmented Generation). The Go code below indexes all spec files into a vector store and then answers questions with the relevant spec context.

 1// Preview of Topic 7: RAG + Vector DB
 2// spec.md, plan.md, constitution.md → vector store → an AI assistant that "knows" the codebase
 3
 4type SpecRAGSystem struct {
 5    vectorStore *pgvector.Store
 6    embedder    *anthropic.Embedder
 7}
 8
 9func (s *SpecRAGSystem) IndexSpec(ctx context.Context, specDir string) error {
10    // Index all spec files into the vector store
11    specs, _ := filepath.Glob(filepath.Join(specDir, "**/*.md"))
12    for _, spec := range specs {
13        content, _ := os.ReadFile(spec)
14        embedding, _ := s.embedder.Embed(ctx, string(content))
15        s.vectorStore.Insert(ctx, spec, embedding, string(content))
16    }
17    return nil
18}
19
20func (s *SpecRAGSystem) AskAboutSpec(ctx context.Context, question string) (string, error) {
21    // Retrieve relevant specs based on the question
22    embedding, _ := s.embedder.Embed(ctx, question)
23    relevant := s.vectorStore.Search(ctx, embedding, 5)
24
25    // Answer the question with context from the relevant specs
26    return s.answerWithContext(ctx, question, relevant)
27}

With the spec indexed in a vector store, you get an AI assistant that genuinely “knows” your codebase — questions like “why was feature X designed this way?” can be answered from the spec, not from guesswork.

20.7 Event Contracts as a Schema Registry

The .specify/contracts/ folder can become the source of truth for Kafka schemas. The Go code below validates an event payload against its contract before publishing, so that a non-conforming event fails early.

 1// Event contract from spec kit → schema registry → validation in producer/consumer
 2
 3func ValidateEvent(event OrderCancelled, contractPath string) error {
 4    contract, _ := os.ReadFile(contractPath)
 5    schema := parseContractSchema(contract)
 6
 7    // Validate the event payload against the schema
 8    return schema.Validate(event)
 9}
10
11// If the event doesn't match the contract → fail fast before publishing to Kafka

Making the contract a publish gate applies the fail-fast principle at the event layer: the schema recorded in the spec prevents a malformed event from spreading across the entire event-driven system.

20.8 Topic 2 Recap: What We Have Learned

We have now covered all 20 articles of Topic 2, which can be grouped into four major parts:

Part 1 (Articles 1-4): Setup and Introduction

• What Spec Kit is and its place in the SDD ecosystem
• Installation and configuration for a Golang project
• Anatomy of the .specify/ folder
• Integration with Claude Code

Part 2 (Articles 5-10): The Six Core Commands

• constitution, specify, clarify, plan, tasks, implement
• Each command with a production Golang example

Part 3 (Articles 11-15): Real Workflow

• End-to-end CRUD API case study
• Branching strategy and Git workflow
• Automatic CLAUDE.md updates
• Debugging spec deviation

Part 4 (Articles 16-20): Scale and Integration

• Team collaboration and onboarding
• Go monorepo
• Automatic audit as continuous validation
• GitHub Actions integration
• Spec as an AI pipeline contract (this article)

These four parts form a clear curve: from “what is Spec Kit” to “spec as the foundation of the AI pipeline” — a journey from tooling to architecture.

20.9 The Journey: From Spec Kit to a Deeper AI Pipeline

To see the big picture, it is important to understand where Topic 2 sits in the overall series. The diagram below maps how each topic builds on the one before it, with the spec as the connecting thread.

 1Topic 1: SDD + Claude Code
 2  ↓ Mindset: spec-first development
 3
 4Topic 2: GitHub Spec Kit (← we are here)
 5  ↓ Tooling: automate the SDD workflow
 6  ↓ Output: structured spec, plan, tasks, audit trail
 7
 8Topic 3: AI Coding Tools Comparison
 9  ↓ Broadening: Claude Code vs Cursor vs Copilot vs Kiro
10
11Topic 4: AI-Assisted DevOps
12  ↓ Pipeline: spec-driven CI/CD, quality gates
13
14Topic 5: E2E SDD Project
15  ↓ Integration: a full project with all the tools
16
17Topic 6: LLM-Powered Apps    ← spec as a contract for AI features
18Topic 7: RAG + Vector DB      ← spec as a knowledge base
19Topic 8: AI Agents + MCP      ← tasks as agent orchestration input
20Topic 9: LLMOps               ← spec as an observability contract
21Topic 10: AI at Scale         ← spec as a system contract

Notice that the spec appears at every layer — from the mindset in Topic 1 to the system contract in Topic 10 — confirming that the investment in writing a good spec pays off throughout the series.

20.10 Key Takeaways from Topic 2

1. Spec Kit is a multiplier, not a replacement

Spec Kit automates the execution of SDD — it does not replace the ability to think. You still need to understand the domain, answer business questions, and review the output.

2. Six commands = one pipeline

constitution → specify → clarify → plan → tasks → implement is not six separate tools, but one cohesive pipeline. Skipping a single step reduces the overall value.

3. Audit is a safety net, not an afterthought

specify audit after every implementation turns the spec from passive documentation into an active test — the difference between “we wrote a spec” and “the spec is always satisfied”.

4. Git history is the audit trail

14 commits per feature, each traceable to a spec and a task, gives visibility that does not exist in a single “feature/SHOP-789” commit.

5. Spec Kit scales with the team

From a solo developer to a team of 30+ people, the constitution + shared templates + CI enforcement framework keeps working — only the process is adjusted.

20.11 Final Tips for the Spec Kit Journey

Start small: one feature with Spec Kit, not the entire backlog at once.

The constitution is an investment: 2-3 hours writing a good constitution saves hundreds of hours of corrections down the road.

Audit early, audit often: don’t wait for a PR to run an audit — run it after every task is finished.

Update CLAUDE.md after every feature: a 15-minute investment prevents drift that affects all subsequent features.

Embrace deviation: when an audit finds a deviation, that is valuable information about an ambiguous spec, missing context, or an unaddressed edge case.

20.12 What’s Next?

In Topic 3, we will broaden the horizon: not just Claude Code, but the entire ecosystem of AI coding tools for Golang developers in 2026 — Cursor, GitHub Copilot, AWS Kiro, Windsurf, and how they all work together (or compete) within a single workflow.

The Spec Kit we learned in Topic 2 will become the foundation — every tool compared in Topic 3 will be evaluated from the perspective of “how well does it support the SDD workflow?”

20.13 Final Tips & Gotchas

💡 Tip 1: Document spec evolution — keep the version history of the spec in git. When requirements change next month, you can see why the original decision was made.

💡 Tip 2: Spec as onboarding for other AI tools — when switching from Claude Code to another tool, the spec remains valid. constitution.md + spec.md + plan.md can be consumed by Claude, Cursor, or Copilot — a tool-agnostic format.

💡 Tip 3: Celebrate spec quality — when a spec audit scores 95+ or coverage hits 90%+, that is an achievement worth sharing with the team. Positive reinforcement drives adoption.

💡 Tip 4: Spec Kit is a journey, not a destination — your workflow will keep evolving; week-1 constitution.md differs from month-6 constitution.md, and that’s good.

⚠️ Final Gotcha: Don’t over-spec — not every feature needs a 20-section spec. A “show me X” task that finishes in 30 minutes doesn’t need the full speckit workflow. Pragmatism is key.

20.14 Spec Kit Maturity Levels

To measure where you stand, it helps to map the maturity levels of Spec Kit usage. The diagram below arranges five levels, from basic usage to becoming the foundation of an AI pipeline.

 1Level 1: Basic Usage
 2- Running the 6 commands sequentially
 3- Spec is written, code is generated
 4- No audit or enforcement
 5
 6Level 2: Workflow Integration
 7- Spec Kit becomes part of the standard workflow
 8- specify audit is run before a PR
 9- Constitution.md exists and is followed
10
11Level 3: Team Adoption
12- All developers use Spec Kit
13- CI enforcement (spec audit in GitHub Actions)
14- CLAUDE.md is always up-to-date
15
16Level 4: Organization Scale
17- Shared templates for feature types
18- Cross-team spec review process
19- Metrics tracking and data-driven retrospectives
20
21Level 5: AI Pipeline Foundation ← this is the long-term goal
22- Spec as a machine-readable contract
23- Audit as continuous validation in the AI pipeline
24- Spec Kit integrated with LLM-powered validation

Most teams realistically settle at Level 2-3; Level 5 is the long-term goal that in fact becomes the theme of the subsequent AI topics in this series.

20.15 Community and Contribution

Spec Kit is open source, and contributions from the Go community will make it better for everyone. The commands below show a few ways to contribute — from reporting issues to donating Go-specific templates.

 1# Report a bug or feature request
 2gh issue create --repo github/spec-kit --title "Support for Indonesian language in constitution"
 3
 4# Contribute Go-specific templates
 5git clone github.com/github/spec-kit
 6# Add a template at: templates/go/crud-api.md
 7# Add examples at: examples/go/
 8
 9# Share your constitution.md
10# Community repo: github.com/spec-kit-community/constitutions

Donating Go-specific templates and examples yields compounding benefits: your contribution saves setup time for hundreds of other Go developers who use Spec Kit.

20.16 Final Comparison: Before and After Spec Kit

The clearest way to see the value of Spec Kit is to compare the state before and after it. The diagram below places where each artifact “lives” under both conditions side by side.

 1BEFORE Spec Kit:
 2├── Spec: "in a Confluence page last edited 6 months ago"
 3├── Clarification: "a Slack thread that's already archived"
 4├── Plan: "in the developer's head"
 5├── Tasks: "will be done later"
 6├── Implementation: "straight to coding"
 7├── Review: "a PR the reviewer has no context for"
 8└── Audit: "none"
 9
10AFTER Spec Kit:
11├── Spec: .specify/features/product-review/spec.md (versioned, in git)
12├── Clarification: clarifications.md (5 Q&As, all answered)
13├── Plan: plan.md (APPROVED by @budi, risks identified)
14├── Tasks: tasks.md (14 tasks, parallel map, DoD for each)
15├── Implementation: 14 commits, each traceable to spec + task
16├── Review: PR with a full AC compliance table, coverage report
17└── Audit: specify audit — 16/16 ACs, 89% coverage, 93/100 score

The difference is not about “more documents”, but about the location of truth: before Spec Kit, context was scattered and easily stale; after it, everything is versioned in git and always traceable.

20.17 Thank You, and Welcome to Topic 3

Completing Topic 2 means you have:

• Mastered the 6 Spec Kit commands
• Understood the end-to-end workflow from spec to code
• Set up CI/CD integration for spec compliance
• Become ready to use the spec as the foundation for more complex AI pipelines

In Topic 3, we will look at a broader landscape: AI Coding Tools for Golang Developers — a comprehensive comparison between Claude Code, Cursor, GitHub Copilot, AWS Kiro, and others, evaluated through the lens of SDD.

20.18 Checklist Before Moving On to Topic 3

Before moving on, it is wise to make sure the Topic 2 foundation is truly in place. The checklist below summarizes the readiness requirements from the perspective of setup, workflow, integration, and team.

 1## Topic 2 Completion Checklist
 2
 3### Setup
 4- [ ] specify CLI installed and configured
 5- [ ] .specify/ folder exists in the project
 6- [ ] constitution.md has been written
 7
 8### Workflow
 9- [ ] Tried the full workflow: specify → clarify → plan → tasks → implement
10- [ ] Ran specify audit
11- [ ] Created a PR with specify pr
12
13### Integration
14- [ ] CLAUDE.md updated after feature implementation
15- [ ] CI/CD pipeline with spec audit (or a plan to set it up)
16- [ ] Branching strategy documented
17
18### Team (if applicable)
19- [ ] Team onboarding with Spec Kit done
20- [ ] Shared templates for common feature types
21- [ ] Spec review process defined

If most of the boxes are checked — especially the full workflow and specify audit — then you are ready to enter the broader discussion of the tools ecosystem in Topic 3.

20.19 Resources

To deepen the material, here is a collection of important links around Spec Kit and this series. The list below covers the official repository, documentation, and the case-study sample project.

 1GitHub Spec Kit:
 2- Repository: github.com/github/spec-kit
 3- Documentation: spec-kit.github.com
 4- Discord: discord.gg/spec-kit
 5
 6Santekno Blog:
 7- Topic 1: /tutorial/golang/ai-driven/specification-driven-development/
 8- Topic 2: /tutorial/golang/ai-driven/github-spec-kit/ (← you are here)
 9- Topic 3: /tutorial/golang/ai-driven/ai-coding-tools-golang/ (coming soon)
10
11Sample Project:
12- github.com/santekno/santekno-shop (case study from Topics 1 & 2)

Save the sample project link github.com/santekno/santekno-shop — the same case study will continue to be referenced as a concrete example in the topics that follow.

20.20 Topic 2 Summary

Topic 2 — GitHub Spec Kit: Automating the SDD Workflow — is complete.

We have journeyed from “what is Spec Kit?” to “how does the spec become the foundation for a more complex AI pipeline”. 20 articles, 6 core commands, one end-to-end case study, team workflow, monorepo, CI integration, and finally — the spec as a machine-readable contract.

Spec Kit is not the final destination. It is a solid foundation for the topics ahead in this series — LLM-powered applications, RAG, AI agents, LLMOps, and AI at scale.

With a structured spec that stays up-to-date, you are ready to build Golang applications that are truly AI-powered — not merely AI-assisted.