Spec-Driven vs Code-First vs Chat-to-Code: Three Philosophies for Teaching AI About Your Business

There are three ways to teach an AI agent about your business. Each inverts who — or what — is the source of truth.

GitHub’s Spec Kit (122k stars) says the specification is truth: write the spec, the spec generates the code. OpenWiki and Mintlify say the code is truth: read the codebase, write the docs, agents consume the docs. QuotyAI says the domain expert is truth: chat your business rules, get executable code back.

Each approach works. Each breaks differently. And the failures aren’t random — they follow predictable patterns tied to who authored the knowledge, when it was written, and how it gets consumed.

---

The Three Philosophies

Spec-Driven: The Specification Is the Source of Truth

GitHub Spec Kit inverts traditional development. Specifications don’t serve code — code serves specifications. The PRD isn’t a guide for implementation; it’s the source that generates implementation. Technical plans aren’t documents that inform coding; they’re precise definitions that produce code.

The workflow is four commands:

/speckit.specify  →  /speckit.plan  →  /speckit.tasks  →  /speckit.implement

A feature description becomes a structured spec with user stories and acceptance criteria. The spec becomes an implementation plan with technology choices and rationale. The plan becomes an executable task list. The task list becomes code.

Spec Kit ships with a constitution — nine immutable articles (library-first principle, test-first imperative, simplicity gates) that every generated implementation must follow. Templates constrain the LLM’s output with checklists, forced uncertainty markers ([NEEDS CLARIFICATION]), and phase gates that block progress unless architectural principles are satisfied.

The ecosystem around spec-driven development is substantial:

• Specmatic turns API specifications (OpenAPI, AsyncAPI, gRPC) into executable contracts with service virtualization and backward compatibility checking
• Speakeasy pivoted from API spec tooling to an AI control plane for MCP and Skills governance
• Stoplight/Spectral provides API design-first linting with governance rulesets
• OpenAPI/Swagger generates API clients and server stubs from specs across 40+ languages

The bet: if the specification is precise enough, the gap between intent and implementation disappears.

Code-First: The Codebase Is the Source of Truth

OpenWiki, built by LangChain AI, reads a codebase and writes markdown documentation for coding agents. A GitHub Action runs openwiki --update daily. The agent diffs git, identifies affected pages, and rewrites only those pages. The AGENTS.md and CLAUDE.md files in the repository root point coding agents to the wiki as their entrypoint.

But OpenWiki is one tool in a much larger ecosystem:

• Mintlify powers docs for Anthropic, Coinbase, and Vercel. Its Agent Score tool tests documentation against 29 checks for agent readiness. A controlled experiment by a large engineering org showed structured docs give 64% more precise answers, ~50% fewer tokens, and 1.5x faster task completion versus no docs.
• GitBook offers Git Sync (branch/review/merge docs like code) and an Agent that proactively detects stale content. Their core pitch: “Agents turn small docs errors into big problems.”
• ReadMe proposes doc updates on PRs via an AI Writer, with an MCP server for agent read/write access.
• Swimm uses deterministic static analysis plus GenAI to build validated knowledge bases for AI tools, SOC 2 compliant, 100M+ lines analyzed.

The in-repo config file ecosystem is equally large:

Tool	Config File	Key Detail
Claude Code	CLAUDE.md, .claude/rules/*.md	200-line recommended max; path-scoped rules load only for matching files
Cursor	.cursor/rules/*.mdc	Community plugin directory with 4k stars
Cline	.clinerules + .cline/skills/	64.7k GitHub stars
Aider	CONVENTIONS.md	Tree-sitter AST-based repo map
GitHub Copilot	.github/copilot-instructions.md	Project-level instructions
Windsurf	.windsurfrules	Cross-tool compatibility with Claude Code

The bet: if the documentation is comprehensive enough, agents will understand the codebase as well as the developers who built it.

Chat-to-Code: The Domain Expert Is the Source of Truth

QuotyAI lets a spa owner type “our deep tissue massage costs 90 for 60 minutes, 120 for 90 minutes, and we offer a 10% discount for members.” The platform generates a quoteOrder() function that returns $108 for a 90-minute member booking. Every time.

The architecture: business owner chats with a skills builder in natural language. The builder generates structured documents (JSON schemas, TypeScript types, reference data) and executable code (pricing functions, scheduling transformations, validation logic). The output runs in a sandboxed Node.js VM on every incoming customer message.

Why don’t existing products fill this niche? The chat-to-app landscape reveals a gap:

• Vercel v0, bolt.new, Lovable target non-technical users but generate UI and frontend applications. A “finance calculator” template is a simple calculator, not a pricing engine with tiered discounts, conditional add-ons, and member rules.
• Cursor, GitHub Copilot, Codex are powerful but require developers as the primary user. They don’t understand your business domain — the AI doesn’t know that confirmed_at is the right timestamp for revenue reporting, not created_at.
• Zapier, Make, Bubble automate simple workflows but cannot express complex business logic. “If this then that” is too simplistic for real pricing and quoting.

The missing category: a tool that understands your business domain and generates the specific code that implements your rules, without requiring you to write code or even think in code terms.

Adjacent products exist — DealHub and Salesforce CPQ for enterprise Configure-Price-Quote, Clay for AI sales enrichment, Voiceflow and Botpress for chatbot builders — but none let a non-technical domain expert describe complex pricing logic in natural language and get deterministic, auditable code back.

The bet: if the conversation is structured enough, the domain expert’s knowledge can be transformed directly into production logic.

---

Where Each Breaks Down

Spec-Driven: The Context Rot Problem

The spec-driven bet assumes comprehensive specifications improve agent performance. The data says otherwise.

Context rot is real. Anthropic’s research on context engineering for AI agents describes how “as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases.” This emerges from the transformer architecture’s fundamental constraint: every token attends to every other token, creating n² pairwise relationships that stretch thin as context grows.

The phenomenon is universal — all models exhibit it, though some degrade more gracefully than others. The implication is clear: every token loaded into context depletes the agent’s “attention budget,” and specs are token-heavy. A specification comprehensive enough to be useful may be too large to be effective.

Agent instruction bloat (ThoughtWorks Technology Radar Vol 34, April 2026, rated “Caution”):

“Context files such as AGENTS.md and CLAUDE.md tend to accumulate over time as teams add codebase overviews, architectural explanations, conventions and rules. While each addition is useful in isolation, this often leads to agent instruction bloat. Instructions become long and sometimes conflict with each other. Models tend to attend less to content buried in the middle of long contexts.”

The research paper “On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents” (arXiv:2601.20404, Jan 2026) found that hand-written AGENTS.md files reduce median runtime by 28.64% — but only when they stay lean. Bloated or poorly-written specs have the opposite effect.

The spec fatigue cycle follows a predictable pattern:

1. Initial enthusiasm: “Let’s write a comprehensive spec so the AI knows exactly what to do”
2. Spec grows: edge cases emerge, more rules and documentation added
3. Spec becomes unwieldy: so large it degrades agent performance
4. Maintenance burden: spec falls out of sync with the evolving codebase
5. Specification fatigue: team stops maintaining the spec
6. Dead documentation: agents follow outdated instructions with high confidence

Architecture drift persists even with specs. ThoughtWorks Radar flagged “Architecture drift reduction with LLMs” (Assess): “Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones.”

Code-First: The Staleness Tax

The code-first bet assumes documentation derived from code stays accurate. It doesn’t.

Staleness is the #1 challenge. The GitBook State of Docs Report 2026 found “keeping docs in sync with the product” is the biggest challenge for documentation teams — nearly double the runner-up. READMEs are “snapshots that decay into another source of stale information for agents to hallucinate from.”

Unlike human readers who can recognize and work around outdated docs, AI agents treat stale documentation as ground truth. An agent following a six-month-old README will confidently reference APIs, file paths, and workflows that no longer exist.

The “why” problem is unsolvable from code. Mintlify co-founder Han Wang:

“Code only tells you what got built, not why. The reasoning behind architectural decisions lives in old Slack threads and a couple people’s brains. An agent working from code doesn’t have the intent layer. Even a hammer is complex if you don’t know you’re supposed to hit nails with it.”

An agent can read that function X calls function Y, but it cannot know that Y exists because of a compliance requirement from 2023 or that X uses a specific algorithm because a performance benchmark demanded it.

The context window tax is brutal. Claude Code’s startup overhead — before you type anything — consumes roughly 8,000-10,000 tokens. Each file read adds 1,000-3,000 tokens. By the time an agent has read 5-6 source files, it may be past 50% of context. Documentation-heavy workflows accelerate this exhaustion.

Mintlify’s research found structured docs cut per-task token consumption by ~50%. For a company spending 1M/year on AI coding tokens, that's 500K saved. But the docs must be maintained to deliver that savings — which brings you back to the staleness problem.

The cost of getting it wrong is asymmetric. From GitBook: “Agents turn small docs errors into big problems.” A human developer reading an outdated doc might notice the inconsistency and work around it. An agent follows it blindly, producing broken code with high confidence.

Chat-to-Code: The Verification Gap

The chat-to-code bet assumes natural language is precise enough to generate correct code. It often isn’t.

The verification problem is the biggest unsolved challenge. No tool asks the user: “Here are 5 test cases. Does this output look correct?” A pricing function that looks correct might have off-by-one errors in boundary conditions. Rounding errors might be invisible until real money is involved. Edge cases — zero quantities, negative values, extreme values — may not be tested.

The Bun runtime rewrite (July 2026) solved this with “a language-independent test suite with a million assertions, adversarial code review and when something does go wrong, fixing the process that generates the code instead of hand-fixing the code.” But that required a team of expert engineers building conformance suites. A spa owner cannot do this.

Trust is fragile. A business owner trusting AI-generated pricing faces real barriers: financial risk (wrong pricing means lost revenue), audit requirements (many industries require explainable pricing logic), liability (if an AI-generated price is discriminatory, who is responsible?), and the fundamental inability to read code to verify correctness.

The xAI Grok Build incident (July 2026) demonstrated how fragile trust is: running the CLI in a directory uploaded the entire directory — SSH keys, password databases, documents — to Google Cloud. One privacy disaster can destroy confidence in an entire category.

The “vibe coding” problem applies. Andrej Karpathy’s term for code that looks right but has subtle bugs is especially dangerous for business logic. A pricing calculation that is off by $0.03 per transaction seems trivial until you multiply it by 10,000 transactions.

From the Pragmatic Engineer survey (170+ respondents): “Copilot can (and does!) produce incorrect code. When using Copilot, you need to assume it produces errors.” The tools work when the user already knows what the code should do. For non-technical users describing business rules they don’t fully understand in code terms, the risk is much higher.

Domain specificity limits the market. General-purpose AI coding tools have broad knowledge but shallow domain expertise. Domain-specific tools have deep expertise but limited scope. Building enough domain knowledge into the tool without making it so specialized it has no market is the fundamental tension.

---

The Convergence: What the Industry Is Actually Moving Toward

Here’s what’s interesting: all three approaches are converging on the same underlying pattern.

Structured markdown is winning as the knowledge layer. The Agent Skills format (agentskills.io) has been adopted by 40+ agent products — Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, Roo Code, Amp, Factory, and many others. The format uses a SKILL.md file with YAML frontmatter and markdown instructions, with progressive disclosure: agents load only the name and description initially, then the full content when a task matches.

MCP is becoming the tool protocol. The Model Context Protocol is the “USB-C of AI” — a universal connector for agents to access tools and data. The MCP community has formed a “Skills Over MCP” Working Group actively merging the two: an MCP server should serve both its tools AND the instructions for using them together.

ThoughtWorks Technology Radar April 2026 signals the direction:

Signal	Rating	Implication
Context engineering	Adopt	Treat the context window as a design surface, not a text box
Progressive context disclosure	Trial	Don’t front-load everything; let the agent pull what it needs
Agent instruction bloat	Caution	Long instructions degrade performance
Architecture drift reduction with LLMs	Assess	Even with specs, drift persists and compounds

The recommended approach is progressive context disclosure: start with a lightweight index of what’s available, let the agent determine what’s relevant, and pull in only what’s needed. This is the anti-pattern to spec-first — rather than writing comprehensive specs upfront, you build agents that dynamically discover what they need.

Hybrid retrieval beats pure vector search. The knowledge retrieval layer is converging on combining vector search (semantic similarity for unstructured content), structured queries (SQL/Cypher for aggregation and reasoning), and knowledge graphs (for relationship traversal). Neo4j’s GraphRAG pattern and Qdrant’s hybrid queries exemplify this.

The deeper insight: the format matters less than who authors it, when it’s written, and whether it stays current. A well-maintained SKILL.md file beats a stale OpenAPI spec. A live query beats a static Markdown file. A structured interview with a domain expert beats a prompt that guesses at business rules.

---

When to Use Each

Spec-Driven: For Technical Teams Building Greenfield Software

Use Spec Kit when you’re starting a new project with a technical team that can write and maintain specifications. The constitution, templates, and phase gates work best when the team has shared vocabulary, shared context, and the discipline to keep specs current.

Use Specmatic or OpenAPI when you need API contract design — typed interfaces between services where the spec is small, focused, and machine-enforceable.

Don’t use spec-driven approaches when your “domain expert” is a business owner who thinks in terms of prices and appointments, not user stories and acceptance criteria.

Code-First: For Existing Codebases With Developer-Facing Agents

Use Mintlify, GitBook, or OpenWiki when you have an existing codebase and need coding agents to understand it. Mintlify’s structured docs + MCP approach gives the best measurable results (64% more precise, 50% fewer tokens).

Use CLAUDE.md, .cursorrules, or .clinerules for project-specific agent configuration — but keep them under 200 lines and use path-scoped rules to minimize context overhead.

Don’t use code-first approaches when the knowledge you need isn’t in the code. Business rules, pricing logic, and domain expertise live in people’s heads, not in function signatures.

Chat-to-Code: For Domain Experts Who Don’t Code

Use QuotyAI when a non-technical domain expert needs production-ready business logic — pricing functions, validation rules, scheduling transformations — from natural language descriptions. The domain-specific approach works because it constrains the problem: the system knows what a pricing function looks like and can validate the output against typed contracts.

Don’t use chat-to-code approaches for general-purpose software development. The verification gap is too wide without domain-specific constraints.

---

The Deeper Pattern

The three philosophies aren’t really competing. They’re answering different questions:

• Spec-Driven answers: “How do we make sure the AI builds what we intended?”
• Code-First answers: “How do we make sure the AI understands what already exists?”
• Chat-to-Code answers: “How do we make sure the AI captures what the expert knows?”

The real failure mode isn’t choosing the wrong approach. It’s applying an approach to the wrong problem. Spec-driven development fails when the domain expert can’t write specs. Code-first documentation fails when the knowledge isn’t in the code. Chat-to-code fails when the domain is too broad to constrain.

The emerging stack uses all three: specifications at API boundaries, computed knowledge at runtime, and structured conversations for domain expertise. The common thread is that static, comprehensive, human-authored documents are the wrong unit. The right unit is whatever stays current, stays small, and stays relevant to the task at hand.

Build the deterministic runtime underneath the model, and the knowledge problem solves itself.

---

Frequently Asked Questions

What is the difference between spec-driven, code-first, and chat-to-code approaches? Spec-driven development (GitHub Spec Kit) inverts traditional development: specifications generate code, not guide it. Code-first documentation (OpenWiki, Mintlify) reads existing codebases and writes markdown for AI agents. Chat-to-code (QuotyAI) lets non-technical users describe business rules in natural language and generates executable TypeScript. Each targets a different user: developers, developer teams, and domain experts respectively.

Why do spec-driven approaches fail at scale? Three documented failure modes: (1) Context rot — Anthropic’s research shows model performance degrades as context windows fill, due to transformer architecture constraints stretching attention thin across more tokens. (2) Agent instruction bloat — ThoughtWorks Technology Radar flagged AGENTS.md files accumulating and conflicting, degrading agent performance. (3) Spec fatigue cycle — specs grow, become unwieldy, fall out of sync, and teams stop maintaining them.

Why don’t v0, bolt.new, or Lovable solve the chat-to-code problem for business logic? These tools target non-technical users but generate UI and frontend applications, not complex business logic. A pricing engine with tiered discounts, conditional add-ons, and member rules requires domain-specific understanding that general-purpose chat-to-app builders lack. No major product currently lets a business owner describe pricing rules in natural language and get production-ready, deterministic code.

What is the industry converging on for AI agent knowledge? The Agent Skills format (agentskills.io) has been adopted by 40+ agent products. MCP is becoming the standard tool protocol. The ThoughtWorks Technology Radar April 2026 recommends “context engineering” (Adopt) and “progressive context disclosure” (Trial) — treating the context window as a design surface and letting agents pull only what they need, rather than front-loading comprehensive specifications.

---

Related Reading

• Open Knowledge Format (OKF) vs Agent Skills — why deterministic execution beats static knowledge files
• OpenWiki vs QuotyAI — two LangChain DeepAgents projects, two architectures
• Determinism as Infrastructure — why AI platforms need deterministic execution
• Why I Picked Bun and Hono — the original decision breakdown for QuotyAI’s stack

---

Tags: spec-driven-development openwiki mintlify quotyai ai-agents agent-architecture context-engineering deterministic-ai spec-kit agent-skills MCP