Vokt Workflow Examples
Real-world scenarios showing how Vokt catches behavior changes before they ship
See what your system did before vs after — at the behavioral level, not just syntax. These examples demonstrate behavior-level validation in action.
Table of Contents
Features Demonstrated
The scenarios below cover the complete Vokt feature set. Here's how each phase maps to CLI commands and MCP tools:
| Phase | Feature | CLI Command | MCP Tool |
|---|---|---|---|
| 1 | Project setup | vokt init | — |
| 2 | Cold start specs | vokt generate | vokt_modify_start |
| 3 | Context analysis | vokt generate-context | vokt_modify_start + use_context |
| 4 | Module synthesis | vokt synthesize-module | CLI via Claude |
| 5 | New file creation | vokt generate | vokt_create |
| 6 | Modify with drift | vokt drift check | vokt_modify_complete |
| 7 | Test generation | vokt generate-tests | generate_tests |
| 8 | Review queue | vokt review | vokt_review_queue |
| 9 | Analytics | vokt report | CLI via Claude |
| 10 | Doc export | vokt export | CLI via Claude |
| 11 | LSP Server | vokt lsp serve | Real-time via VS Code extension |
Feature Checklist
After working through the scenarios, verify you've exercised these core features:
Setup & Generation
- Project initialization (
vokt init) - IDE integration (
.mcp.json) - Cold start spec generation
- Context-aware analysis with dependencies
- Module synthesis
Modification & Validation
- New file creation (spec-first)
- Modification with drift detection
- Drift resolution
- Test generation from specs
- Review queue management
Reporting & Export
- Analytics report (HTML/Markdown)
- Documentation export
- PR description generation
IDE Integration
- LSP server for real-time feedback
- VS Code extension commands
1. Legacy Code: First Touch
Scenario
You inherit a 50,000 line payment processing system. Zero tests. No documentation. Original developers gone. Boss says: "Add refund support by Friday." You have Claude Code to help, but how do you ensure it doesn't break existing payment flows?
❌ Without Vokt:
AI modifies code blindly, no context on constraints. Breaks fraud detection. Ships to production. 😱
✅ With Vokt:
Vokt documents constraints, AI preserves them, tests verify safety. Ships confidently. ✅
First-Time Setup
Workflow (Auto Mode)
Key Outcomes
- ✅Shipped on time - No stopping work to add tests
- ✅Built quality - Specs + tests generated automatically
- ✅Documented behavior - Spec shows "Stripe v1, USD only, $10k max"
- ✅Safe for next time - Future changes check against spec
- ✅1 of 500 files - Covered the one you touched (0.2% → 100% on that file)
This is the Vokt approach: Build quality where you work.
2. The 80/20 Rule in Action
Scenario
Legacy 50,000 line codebase. Team of 3 developers. 6 months of feature work.
Reality: 20% of code changes 80% of the time.
Vokt Strategy: Build specs + tests for the 20% you actually touch.
Month-by-Month Progression
Month 1: Payment Features
Team touches:
- • payment-processor.js (add refunds)
- • stripe-gateway.js (update API version)
Vokt auto-generates:
- ✓ 2 specs documenting existing + new behavior
- ✓ 27 tests covering edge cases
Coverage: 2/500 files (0.4%)
But these are the files you modify monthly!
Month 2: Authentication Updates
Team touches:
- • auth-middleware.js (add 2FA)
- • jwt-validator.js (add refresh tokens)
- • session-manager.js (extend timeout)
Vokt auto-generates:
- ✓ 3 specs documenting existing + new behavior
- ✓ 34 tests covering edge cases
Coverage: 5/500 files (1%)
These files change every sprint.
Month 3: User Management
Team touches:
- • user-service.js (add soft delete)
- • permissions.js (add role inheritance)
Vokt auto-generates:
- ✓ 2 specs documenting existing + new behavior
- ✓ 18 tests covering edge cases
Coverage: 7/500 files (1.4%)
Month 6: The Result
Total files touched: 15/500 (3%)
Files with full specs + tests: 15 (100% of touched files)
Total tests: 143 auto-generated
Files never touched: 485 (97% - still no tests, and that's FINE)
The critical 3% now has:
- ✅ Full specification documentation
- ✅ Comprehensive test coverage
- ✅ Version history explaining changes
- ✅ Drift protection enabled
The Reality Check
❌ Old approach: "We need to add tests to 50,000 lines!"
- • Time: 6 months
- • Cost: 3 developers full-time
- • Result: Never happens
✅ Vokt approach: "We'll add tests to code we touch"
- • Time: 0 extra (built while shipping)
- • Cost: Free
- • Result: Critical 3% has enterprise-grade quality
The 97% with no tests? Hasn't been touched in years. Doesn't need tests.
3. Catching Security Vulnerabilities
Scenario
Claude Code is refactoring your authentication middleware. It accidentally removes the rate limiting check. Vokt catches it before you even commit.
❌ Without Vokt:
Security regression ships to production. Hackers find it in hours. You spend the weekend firefighting.
✅ With Vokt:
Vokt detects spec violation immediately. Claude fixes it. You never even notice.
The silent failure mode:
Tests passed. CI was green. But rate limiting was removed. This is a semantic regression — the kind that ships to production undetected.
Workflow Example
Key Outcomes
- ✅Security guardrail - Spec caught critical requirement removal
- ✅Self-healing AI - Claude fixed its own mistake automatically
- ✅Zero human intervention - You never saw the security bug
- ✅Documented constraints - Rate limiting now explicit in spec
- ✅Safe refactoring - Implementation changed, behavior preserved
Vokt is your safety net when AI refactors critical code.
4. Living Documentation
Scenario
New developer joins your team. Asks: "How does the payment processor work?" You point them to the spec file. It's always accurate because it's enforced by Vokt.
❌ Traditional docs:
README says "Supports Stripe v1". Code uses Stripe v3. Doc is 2 years stale. New dev gets confused.
✅ Vokt docs:
Spec file is generated from code and enforced on every change. Always accurate. Always up to date.
Workflow Example
Why This Matters
- ✅Always accurate - Spec enforced on every code change
- ✅Zero maintenance - Auto-generated, auto-updated
- ✅Onboarding is instant - New devs read specs, understand system
- ✅Human-readable - YAML format, not cryptic code comments
- ✅AI-friendly - Claude reads specs before making changes
Documentation that can't lie to you.
5. Team Inheritance Scenario
Scenario
Sarah wrote the email service 3 years ago. She left the company. Now you need to add SMS support. Vokt has the complete behavioral contract she left behind.
❌ Without Vokt:
Spend 2 days reading code, guessing what's safe to change. Break retry logic accidentally. Users complain.
✅ With Vokt:
Read spec in 5 minutes. Understand all requirements. Add SMS without breaking email. Ship confidently.
Workflow Example
Key Outcomes
- ✅Understood legacy behavior - Spec showed retry logic, rate limits, critical notes
- ✅No regression - Email code preserved, all tests still pass
- ✅Consistent patterns - SMS inherited same retry/rate-limiting approach
- ✅Knowledge transfer - Sarah's decisions documented in spec forever
- ✅Future-proof - Next dev will inherit v6 spec with both email + SMS
Specs are the institutional memory of your codebase.
6. Understanding Complex Modules
Scenario
You're assigned to optimize the authentication system. It spans 8 files across 3 directories. You need to understand how it all fits together before making changes.
❌ Without Vokt:
Open 8 files in tabs. Manually trace function calls. Miss a dependency. Break something unexpected.
✅ With Vokt:
Vokt resolves dependencies, shows relationships, synthesizes module-level view. Understand in minutes.
Context-Aware Analysis
routes.js ──┐
├──▶ middleware.js ──┬──▶ jwt.js
users.js ───┘ ├──▶ session.js
└──▶ permissions.jsIf using Vokt without Claude Code:
Key Outcomes
- ✅Dependency resolution - Automatically traced all 8 files and their relationships
- ✅Module contracts - Understood public interface without reading implementation
- ✅Cross-file awareness - Saw how middleware connects to jwt, session, permissions
- ✅Invariants documented - Critical rules like rate limiting and token expiry captured
- ✅Safe to modify - Now know exactly what can change vs. what must be preserved
Understand complex systems in minutes, not days.
7. New Feature Development
Scenario
You're building a brand new API endpoint. Vokt guides you through creating specs first, then implementing with AI, then generating tests. True spec-driven development.
❌ Traditional flow:
Write code, realize you forgot edge cases, add them, tests break, fix tests. Messy iteration.
✅ Vokt guided:
Define behavior spec, Claude implements it, tests auto-generated, all edge cases covered upfront.
Guided Spec Creation
Key Outcomes
- ✅Spec-driven development - Defined behavior before writing code
- ✅All edge cases upfront - Duplicate check, payment failures covered in spec
- ✅Complete test coverage - 18 tests generated from spec automatically
- ✅Clear API contract - Spec documents all inputs, outputs, error codes
- ✅Future-proof - Next dev reads spec, understands complete behavior
Think about behavior first. Let AI handle the implementation.
8. Handling Drift Conflicts
Scenario
Your teammate merged a hotfix directly to production, bypassing CI/CD. Now the code and spec are out of sync. Vokt detects it and helps you resolve the conflict intelligently.
❌ Without Vokt:
Silent drift. Production code differs from repo. Tests pass locally, fail in prod. Mystery bugs.
✅ With Vokt:
Drift detected immediately. Vokt shows exact differences. You choose: update spec or revert code.
Workflow Example
What this looks like in a PR
This is what appears in every PR when Vokt detects behavior changes.
If using Vokt without Claude Code:
Key Outcomes
- ✅Drift detected immediately - Production hotfix caught before it spread
- ✅Security preserved - Unsafe fraud check removal caught and reverted
- ✅Clear diff analysis - Exactly what changed shown side-by-side
- ✅Safe re-implementation - Feature added properly with security intact
- ✅Spec as source of truth - When conflict arose, spec won
Vokt prevents spec drift from becoming production disasters.
9. End of Sprint Cleanup
Scenario
It's Friday. Your team shipped 12 PRs this week. Before you leave, you want to review what Vokt caught and ensure everything is clean.
❌ Without Vokt:
Hope nothing broke. Check Slack on Saturday for angry messages. Start the weekend anxious.
✅ With Vokt:
Review queue shows exactly what changed. Approve/reject items. Generate report. Leave confident.
Review Queue Management
If using Vokt without Claude Code:
Key Outcomes
- ✅Complete visibility - Saw all 7 spec changes from the week at a glance
- ✅Prioritized review - Critical items surfaced first, minor auto-approved
- ✅Audit trail - Approval reasons documented for compliance
- ✅Team communication - Weekly report shared with engineering team
- ✅Risk awareness - High-churn files identified for extra attention
Leave for the weekend knowing exactly what changed and why.
10. Preparing for Audit
Scenario
Your company is undergoing SOC2 audit. Auditors want documentation of your payment processing system's behavior. You have 2 hours.
❌ Without Vokt:
Scramble to write docs. Copy-paste from code comments. Hope it's accurate. Auditor finds inconsistencies.
✅ With Vokt:
Export specs as documentation. Generate compliance report. Everything matches code. Auditor impressed.
Documentation Export
If using Vokt without Claude Code:
What Gets Exported
Each markdown file contains the full spec: functions, constraints, invariants, and version history.
Key Outcomes
- ✅Instant documentation - Exported 5 spec files in seconds, not hours
- ✅Always accurate - Generated from code, enforced on every change
- ✅Incremental updates - SHA256 comparison skips unchanged files
- ✅Audit-ready - HTML dashboard shows quality metrics and history
- ✅Compliance proof - Auditor verified docs can't drift from code
Documentation that proves itself accurate.
Summary: The Vokt Philosophy
What We've Learned
Vokt transforms how you work with legacy code and AI assistants. Instead of choosing between shipping fast and building quality, you get both.
Why existing tools miss semantic regressions
| Tool | Validates | Misses |
|---|---|---|
| Tests | Known scenarios | Unknown behavior changes |
| Code review | Implementation | System-level effects |
| QA | User paths | Hidden business logic |
| Vokt | System behavior | — |
For Legacy Code
- →Build quality incrementally as you ship
- →Focus on the 20% of code you actually touch
- →Never write tests for dormant files
- →Specs auto-generate on first touch
For AI Safety
- →Catch AI mistakes before commit
- →Detect security regressions automatically
- →Self-healing when spec violations occur
- →Specs guide Claude's code generation
For Documentation
- →Living docs that can't go stale
- →Zero-maintenance specification
- →Instant onboarding for new developers
- →Institutional memory preserved forever
For Teams
- →Inherit knowledge from departed developers
- →Prevent drift from hotfixes
- →Consistent patterns across codebase
- →Spec-driven development for new features
The Core Principle
Don't boil the ocean. Build quality where you work.
Vokt meets you where you are: shipping features on legacy code with AI assistance. It doesn't force you to stop and write tests. It builds them automatically as you work, making your codebase better with every change.
Next Steps
Ready to try Vokt?
Install Vokt
Follow the Quick Start Guide to set up Vokt in your project
Pick one file to start
Don't try to spec your entire codebase. Start with one file you're actively working on
Enable Auto Mode
Let Vokt generate specs automatically as Claude Code makes changes
Ship with confidence
Watch as specs and tests build up organically, file by file, as you ship features