About OpenTalks.Ai

OpenTalks.AI is an international, independent Open conference on Artificial Intelligence. Started in 2018 with 600 participants, now it is a well-known conference on AI/ML in Western Europe, gathering 1000+ participants with a community of 5,000+ professionals.

Listen or watch on YouTube

Spec-driven development enables developers to:
• Care about specs at 1/10 the cognitive complexity
• Control and predict code changes through spec changes alone
• Collaborate effectively at the level of specs

LLMs are amazing at writing code. But writing code is not the same as developing software. If developers need to review generated code, 10x productivity remains out of reach.

The real leverage isn’t faster typing, but it’s raising the level of abstraction.

Listen or watch on YouTube

A common objection to this approach is that natural language is inherently ambiguous. Source code, the argument goes, has a single, well-defined interpretation, while prose does not. If specifications are written in natural language, how could they ever function as an unambiguous source of truth for software behavior?

This post describes a syntactic feature of the ***plain specification language which addresses that concern. The :Concept: notation, together with a small set of accompanying rules, provides a disciplined way to define, reuse, and validate key concepts — without turning specifications into formal ontologies or rigid schemas. Where ambiguity would materially change the resulting software, it strengthens specifications by making critical meanings explicit and stable, while allowing natural language to remain expressive everywhere else.

Ambiguity in Practice

Let’s say a developer writes the following specification:

Write a task manager app.

Without additional context, at least two interpretations of this specification are possible:

“Write a task manager app for an individual user that organizes concrete to-do items. Tasks should have priorities, deadlines, and a clear done/not-done state.”

“Write a task manager app that manages tasks as executable system processes. Tasks should be schedulable, observable, and capable of running concurrently.”

While the first interpretation is more probable in most contexts, the second interpretation is admissible and may be picked by an LLM when generating software code. If we want to avoid surprises during code generation and have specifications truly be the source of truth for the software’s functionality, we need to address such situations and reduce ambiguity in specifications.

Looking closely at this specification, we can see that a large part of its meaning hinges on the single word “task”. We can remove most of the ambiguity in the specification if we explicitly define the meaning of the word “task” as:

- Task describes an activity that needs to be done by the user.

With this definition in place, the specification now strongly indicates that the developer’s intention is to describe a personal productivity application rather than a system for managing computational processes.

By explicitly defining the meaning of “task,” we have reduced ambiguity — but not eliminated it entirely. For example, the following interpretations are still both valid:

“Write a Node JS task manager web application for an individual user that organizes concrete to-do items. Tasks should have priorities, deadlines, and a clear done/not-done state.”

“Write a console task manager app in Python for an individual user that organizes concrete to-do items. Tasks should have priorities, deadlines, and a clear done/not-done state.”

We can address this other ambiguity in the specification in the same way, by explicitly defining the meaning of the word “app” as:

- App is a Python console application.

But now imagine a longer specification containing dozens of words whose meanings materially affect the resulting software. How would a developer — or an automated tool — know which words have already been explicitly defined and which still carry implicit, potentially ambiguous meaning?

In text written for humans, a common way to draw attention to key concepts is to capitalize or bold them. However, overloading Markdown syntax1 for bold text — indicated using ** — with additional semantic meaning would be confusing for developers and fragile for automated tools

Instead, ***plain introduces a dedicated notation for concepts like “task” and “app” that need meaning explicitly defined. After evaluating several alternatives with respect to readability, ease of parsing, and low collision with natural language, we adopted a notation in which concept names are enclosed in colons at both the beginning and the end.

Using this convention, our running example becomes:

- :App: is a Python console application.

- :Task: describes an activity that needs to be done by the user.

Write :App: for managing :Task: items.

Concept names must not contain spaces and may include only letters, digits, and a limited set of special characters such as dots and underscores2. This constraint ensures that concepts are easy to recognize programmatically while remaining readable to humans.

The goal of :Concept: notation is not to eliminate natural language or replace it with a formal ontology, but to provide a mechanism for anchoring meaning where ambiguity is costly. It is a precision tool rather than a requirement: words like “console,” “describes,” or “activity” may appear without special notation when the developer does not intend to constrain their interpretation.

Reducing Ambiguity with :Concept: Notation

:Concept: notation helps developers reduce ambiguity in specifications. Without explicit rules, however, concept annotations would risk becoming purely decorative, adding visual emphasis without enforceable semantic guarantees. To avoid this, and to ensure that explicit concepts can function as reliable anchors of meaning, ***plain defines a small set of rules that govern how concepts written in :Concept: notation are introduced and used. These rules are intentionally minimal. Their purpose is not to constrain how specifications are written in general, but to establish the conditions under which ambiguity around key concepts can be detected and addressed explicitly.

In ***plain, concepts written using :Concept: notation are governed by the following rules:

1. Concepts must be defined before they can be used.

2. Definitions must begin with a concept name.

3. Concepts must not be redefined.

4. Concept names are case sensitive.

5. Concepts must not change meaning through use.

Together, these rules establish the conditions under which concepts written in :Concept: notation can be reliably checked by automated tools and consistently used by software developers, making ambiguity in specifications easier to detect in practice.

A detailed discussion of these rules and the reasoning behind them is available in the whitepaper On the Concept of :Concept:.

From Incremental Prompts to Coherent Concepts

Consider a developer who already has an initial version of the task manager app and now wants to refine it based on user feedback. When using agentic AI development tools such as Claude Code, this refinement typically happens through a sequence of incremental prompts. For example, the developer might issue prompts like:

1. “Task must have a name.”

2. “Task has a due date”.

3. “Name is a required attribute.”

4. “Add notes to a task.”

5. “The name must be at least 3 characters long.”

6. “Due date is optional.”

7. “Name is a short description of the task.”

8. “Notes store additional details about the task.”

Each prompt is reasonable in isolation and, taken together, they fully describe the intended behavior of a task. However, neither the human developer nor the AI generating code ever sees a single, consolidated definition of what a task is in this system.

Instead, the meaning of “task” accumulates implicitly over time. Its structure, constraints, and semantics emerge indirectly from scattered instructions and are eventually encoded across constructors, validation logic, database schemas, and UI components. There is no authoritative place where the concept itself is defined. This is especially problematic given the limited context window of LLMs: when a concept is defined only implicitly, parts of its effective definition may fall outside the active context or receive insufficient attention during code generation.

For humans, implicit concept definitions increase cognitive load and fragility. When a concept has no explicit definition, its meaning must be reconstructed from scattered fragments across code and specifications, rather than consulted in a single authoritative place, making inconsistencies and accidental divergence more likely over time.

In ***plain, this pattern is replaced by an explicit, consolidated concept definition. A concept can be defined with as much precision as necessary, and that definition becomes the authoritative source of truth for its meaning.

Returning to our example, all of the requirements previously scattered across incremental prompts can be captured in a single definition of :Task:3

- :Task: describes an activity that needs to be done by the user.
  - :Task: has the following attributes:
    - Name - a short description of :Task:
      - This is a required attribute.
      - The name must be at least 3 characters long.
    - Notes - additional details about :Task:
    - Due Date - optional date by which to complete :Task:

Rather than extending the concept implicitly through a sequence of prompts, this definition extends it explicitly and holistically. All essential properties, constraints, and relationships are visible in one place. This allows developers to reason about the concept as a whole, detect inconsistencies early, and evolve requirements without fragmenting meaning across prompts or code.

Explicit concept definitions also provide a much stronger semantic signal to automated tools. Instead of inferring structure and invariants from scattered instructions, an AI system can derive them directly from the concept definition itself. From the :Task: definition above, an implementation naturally follows, for example, a Python data class with clearly defined attributes.

Real software systems often contain dozens or even hundreds of such concepts, each with its own structure, constraints, and relationships. If these concepts are specified only implicitly through sequences of incremental prompts and represented only in generated code, the likelihood of misunderstanding grows steadily. Meaning becomes distributed, incomplete, and increasingly difficult to reconstruct, both for humans and for automated systems.

The :Concept: notation in ***plain addresses this problem directly. By giving concepts explicit names and dedicated definitions, it provides stable places where meaning can be accumulated intentionally rather than inferred indirectly. Concepts are not merely disambiguated, but progressively enriched, capturing structure, constraints, and relationships in a single authoritative form. As specifications grow, meaning becomes more precise rather than more fragile, remaining centralized in a single definition and avoiding semantic drift or silent forking across the system.

Explicit concept definitions also help coordinate understanding in larger software development projects, where specifications grow beyond what any single person can fully grasp. When concepts are defined only implicitly, different team members inevitably form different mental models based on the parts they work on. A single, authoritative definition provides a shared reference point, allowing teams to align on meaning, discuss changes precisely, and detect divergences early before they are encoded inconsistently into the software code4.

Conclusion

When specifications are treated as informal guidance, ambiguity is tolerable and often ignored. But when specifications become the source of truth for software behavior and the primary input to automated code generation, ambiguity becomes a liability. What was once a matter of interpretation turns into a source of silent and compounding divergence between intent, implementation, and outcome.

The :Concept: notation in ***plain is a pragmatic response to this shift. It does not attempt to formalize all meaning or replace natural language with rigid schemas. Instead, it provides a lightweight mechanism for anchoring meaning where precision matters most. By making key concepts explicit, stable, and reusable, it allows developers to commit to intent early, detect ambiguity where it is costly, and retain the expressive power of natural language everywhere else.

As specifications grow and evolve, explicit concepts offer a coherent place to accumulate understanding, reason about change, and integrate new requirements without fragmenting meaning across prompts, files, or generated code. For humans, they serve as shared reference points. For automated tools, they provide reliable semantic anchors that reduce guesswork and improve correctness.

Making meaning explicit is not an exercise in formalism. It is a recognition that when software is generated from specifications, meaning directly shapes the result — and must be handled with the same discipline as code.

*codeplain will soon release the first version of its platform based on the **plain specification language. If you want to be among the first to use :Concept: notation in practice, you can join the waitlist to get early access and updates.

Join the waitlist

With the rise of vibe coding and spec-driven development, the boundaries between roles are shifting. Product designers are now using vibe coding tools to build entire features and screens directly in code, exploring behavior instead of just using static interfaces. Engineers, meanwhile, shifted the focus from writing code to describing the system so that machines could build it reliably.

This makes a fundamental change in how teams plan, design, and execute work—one that aligns closely with Marty Cagan’s idea of empowered product teams, where design, product, and engineering operate as peers defining outcomes, not just deliverables.

At *codeplain, we saw these ideas come to life most vividly in our work with DevRev. Their journey from manual integration development to automated specification-based development became a live demonstration of this shift.

Inside the DevRev Partnership

Six months ago, our team at *codeplain partnered with DevRev, an AI-first product company that connects customer support, product management, and engineering into a single workflow. Their powerful AirSync integration platform powers hundreds of connections to third-party tools like Slack, Jira, GitHub, Salesforce, Google Drive, and Microsoft Outlook — ensuring that data flows seamlessly between teams and systems.

Our goal was to introduce a specification-driven approach to integration development — replacing manual coding with structured, executable definitions written in ***plain specification language. In this new model, integrations could be implemented and tested entirely through specifications, with *codeplain automatically generating production-ready, test-covered code.

From my perspective as a product designer at *codeplain, this partnership wasn’t just about code automation, but about redefining how teams collaborate with AI and with each other. I wanted to understand how engineers experience that shift: how it changes debugging, testing, and even the sense of ownership over the system they’re building.

Throughout the six-month collaboration, we worked closely with two DevRev engineers, Patricija and Gašper, who became our closest partners in shaping this new process. Patricija was the first to adopt *codeplain for integration development, exploring how acceptance tests1 could serve as both validation and debugging tools through implementing Wrike. Gašper, meanwhile, focused on observability through implementing Aha! by building a custom command-line interface to better understand how the ***plain rendering and generation pipeline behaved in real time.

Together, we created a repeatable and scalable process for integration development using specifications. What follows is the story of that transformation: how DevRev moved from hand-coded integrations to fully automated, specification-driven systems — and what that change looked like from the inside.

Developing a repeatable and scalable process

When we began working with DevRev, we decided to introduce spec-driven development incrementally. We wanted to verify, at each stage, that *codeplain could meet DevRev’s engineering standards for structure, reliability, and maintainability.

The process unfolded in five distinct phases, each validating a core principle of spec-driven development.

1. Reimplementing an Existing Integration

Our starting point was to prove functional equivalence. The engineers reimplemented one of the existing integrations, Asana, using ***plain specification language. The goal wasn’t innovation, but verification: could a spec-driven workflow replicate the logic, SDK structure, performance, and integration framework of manually written code?

We started by decomposing the entire integration into a set of functional requirements, each representing a small, testable unit of behavior. Every integration begins with making API calls to a third-party service, processing the response, and mapping data to DevRev data models. In ***plain, we captured each of these as a reusable building block, defining inputs, outputs, and validation conditions explicitly.

Here’s an example of how to fetch a list of projects in the Asana workspace in ***plain:

- Implement the :Function: that fetches the :ListofProjects: using the projects endpoint of the :API:.

By defining integrations this way, the developer stayed in control of the high-level architecture and behavior, while *codeplain handled the implementation details and boilerplate. It shifted engineers’ attention to architectural decisions, leaving the repetitive implementation details to the code renderer.

The results demonstrated that *codeplain could generate functionally equivalent, production-ready code — delivering the same behavior, reliability, and maintainability as the manually built version, while eliminating repetitive boilerplate work.

2. Implementing a New Integration

After proving that *codeplain could reproduce an existing integration, we moved on to the real test: could we build a brand-new integration and do it with enterprise-level precision?

DevRev chose Trello as the first new integration to build with ***plain, since it’s a core part of DevRev’s AirSync platform. Engineers defined the integration entirely in specifications—data mappings, event triggers, API endpoints, and expected behavior—leaving *codeplain to generate the implementation.

Here’s an example of how to fetch boards in the Trello workspace in ***plain:

- Implement the :Function: that fetches the :ListofBoards: using the boards endpoint of the :API:.

Just like in Asana, the integration boiled down to the same basic pattern: call the third-party API, process the response, and map the data into DevRev’s models. The specifics differed, but the structure was almost identical.

That similarity turned out to be important. Seeing Asana and Trello expressed as sets of functional requirements made it clear that most of the integration follows a repeatable shape. The only thing that really changes is the third-party service itself—a realization that would shape the next phase.

This step demonstrated that *codeplain could deliver new integrations that met DevRev’s engineering standards for performance, structure, and reliability. It also showed that engineers could now focus on defining intent and specifications instead of writing and reviewing code line by line.

3. Creating an Integration Template

After completing Asana and Trello, we had enough evidence that the approach worked: *codeplain could generate integrations that behaved the way DevRev expected, and the workflow held up across multiple services.

With two specs to compare, a pattern started to emerge. Even though Asana and Trello are very different products, the structure of the integration was largely the same. The team kept seeing the same building blocks repeat:

• Standardized credentials

• Boilerplate API schema definitions

• Authentication and metadata synchronization logic

• Reusable data-fetching

These similarities pointed to a simple conclusion: most of the integration doesn’t change. Only the third-party API does.

To accelerate integration development, DevRev pulled the shared pieces into a modular integration template. All the common logic moved into the template, while each new integration kept only the service-specific parts—its endpoints, authentication parameters, and API payloads. The rest was handled automatically.

This shift created a scalable process for AirSync development. Engineers no longer wrote integrations line by line; they defined how the integration should behave, and the system generated the implementation around that intent. It turned what had been a repetitive engineering workflow into a consistent, repeatable process—while keeping engineers in control of the architecture.

4. Testing the Template on New Integrations

Once the integration template was stable, DevRev set out to test its scalability across different APIs and authentication models. Engineers Patricija and Gašper worked independently, each implementing a new integration in parallel. Both integrations confirmed that integrations could be built, tested, and deployed in under two days using ***plain.

As more of the workflow became automated, a new issue surfaced: engineers needed better visibility into what the system was actually doing. When rendering, testing, and validation all happen behind the scenes, it can be hard to understand where something failed or why a run took longer than usual.

To address this, Gašper built a lightweight command-line tool that visualized each stage of the generation pipeline with timestamps. It replaced a stream of raw logs with a clearer view of the rendering flow, making debugging faster and helping engineers trust the system’s behavior. This tool became the foundation for improving developer observability inside automated workflows, something we’ve been improving at *codeplain ever since.

By the end of this step, the engineering workflow itself was fast and repeatable. Once a developer had a clear ***plain specification, they could generate and validate an integration without touching boilerplate code.

But this only solved the engineering side of the process. Engineering could now move quickly, but product inputs were too often still arriving through ad-hoc conversations, Slack threads, and scattered notes. In other words, the product organization now needed to provide requirements faster and in a more structured way. That gap is what ultimately led to the introduction of a PRD-driven workflow.

5. Introducing a PRD-Driven Workflow

As DevRev’s engineering speed increased, a new challenge emerged — the bottleneck had shifted upstream. Specs could now be generated and deployed in days, but only after someone had precisely defined what the system should do. The faster engineering moved, the more the product had to catch up.

To make that alignment part of the process, DevRev is restructuring around a Product Requirements Document (PRD). The PRD sits at the same abstraction level as an integration specification — it defines what the system should do, how it behaves, and what external dependencies it touches.

Instead of writing specs first and adjusting decisions afterward, teams iterated on the PRD until it captured the complete intent. From there, engineers could automatically generate most of the ***plain specification, refine any missing details, and validate it through automated tests.

This change didn’t just speed things up, but also created a shared foundation between product and engineering. The PRD turned intent into something concrete, making specification-driven development a natural extension of how teams already plan and design features.

Why Teams Like DevRev Are Adopting Spec-Driven Development Now

Working with DevRev over the past six months has made one thing clear: spec-driven development isn’t just a new engineering technique, but a structural necessity for AI-powered organizations.

Modern product teams can’t keep growing headcount every time complexity increases. The old model — growing engineering headcount in proportion to product ambition — no longer works. The constraint is no longer code; it’s collaboration. As systems multiply, so do handoffs, reviews, and the time it takes to align on intent. Automation helps, but abstraction is what truly unlocks scale.

Spec-driven development gives teams that abstraction. By capturing intent in structured specifications, engineers focus on architecture and validation rather than boilerplate, while product and design define behavior upfront. Designers and product managers define behavior and constraints upfront, ensuring alignment before a single line of code is generated.

The quiet shift we saw at DevRev is part of a broader change: teams are learning to collaborate with AI at the intent layer, not compete with it at the implementation layer. What started as an experiment in automation has evolved into a new foundation for building software — where the specification, not the codebase, is the real source of truth.

One of those moments came up in a Node.js project I was working on, where I realized the LLM had hard-coded testing secrets into my repo. Manually patching each file felt tedious and error-prone. Instead, I saw an opportunity to automate it: Build a CLI that takes a target folder and a YAML secrets mapping, then recursively replaces real secrets with mocked ones. I called it Search-and-Replace CLI.

My goal was to build the CLI quickly and reliably without spending too much time writing code by hand. Vibe coding — building by chatting with an AI and iterating in natural language — is my usual way to get projects off the ground fast. However, I also wanted to see if a structured, test-backed approach could save me from the trial-and-error loop I usually hit with vibe coding.

So I built the same CLI twice — once by vibes, once by specs — to find out.

Approach (a): Vibe Code the CLI

My first approach was vibe coding. I wrote a prompt for Cursor, hoping for a one-shot solution.

Goal: Recursively replace secrets in all text files of a target folder

Inputs:
  --target-folder <path> (validate path exists)
  --secrets-file <yaml>. See secrets_config.yaml for the schema.

Rules:
  - Python CLI
  - Read YAML mappings (real → mock)
  - Skip binaries
  - Overwrite files in place
  - Log processed files and replacement counts for every file to stdout

Cursor produced a runnable draft in two minutes. In order to validate the produced code, I manually created test folder fixtures (e.g., example1-no-replace/, example2-replace-secret2/), ran the CLI while inspecting the diffs between outputs and fixtures.

The first snag was incorrect YAML schema validation of the produced code. Fixing it took a few iterative passes with the LLM and hand checks to confirm the mapping rules. Once “working,” I tried a refactor for readability, which broke earlier cases and sent me back into the generate → test → fix loop. After a couple of attempts, I reverted to the “working” version and retried the refactoring step.

Regenerations weren’t stable either. In one run, Cursor scaffolded test folders for me; in the next, it dropped them entirely. YAML validation appeared in some versions and disappeared in others. This variability meant I had to rely on manual testing for every change, since I couldn’t assume consistency between generations.

In short, vibe coding gave me speed up front — I had a running CLI in minutes — but without guardrails to ensure consistency, each edit risked breaking what was already working. Manual testing became the only way to build trust in the tool, and that quickly turned into the bottleneck.

Approach (b): Spec‑Driven

For the second attempt, I built the search-and-replace CLI with ***plain specification language we’re developing at *codeplain. Unlike vibe coding, where the AI generates code directly from a prompt, ***plain starts from a specification written in extended Markdown1.

I broke the work into three verifiable units:

1. CLI scaffold — set up the entry point and command structure. ***plain supports templating, so this will be automatically added with the “include” statement below.

2. Arguments & config — parse --target-folder and --secrets-file

3. Recursive replace engine — walk the directory tree and replace in place

In ***plain, we refer to each “building block” as a functional requirement. The decomposition in smaller units converts to the following ***plain specification2:

{% include “python-console-app-template.plain”, main_executable_file_name: “search_and_replace.py” %}

# Search and replace recursively

***Definitions:***

- The Secrets File is a YAML file that contains a mapping from the real secrets to the mock secrets.
- The Target Folder is a folder that contains the files in which to replace secrets.

***Functional Requirements:***

- The App should accept options `--target-folder` (The Target Folder) and `--secrets-file` (The Secrets File). The Secrets File [secrets_config.yaml](secrets_config.yaml) contains the expected schema of The Secrets File.

- The App should replace all original secrets with mock values recursively across The Target Folder.

For each functional requirement (FR), *codeplain generates not only the implementation code but also unit and conformance tests, and then runs them. It doesn’t proceed to the next FR until the current tests pass. When starting a new FR, all previously generated tests are run to catch regressions early.

For example, if the generation of FR3 (“replace recursively”) breaks the FR2 (“reading --target-folder and --secrets-file”), its tests fail and halt progress until corrected — a guardrail that matters more as the project grows.

In ***plain, both implementation and conformance tests come from the same specification, but the conformance tests are generated independently. They treat the program as a black box and verify only observable outcomes — exit codes, logs, and file changes — against the spec, not its implementation code.

This all happens with the specification as the source of truth: The implementation is derived from the spec, so understanding the spec maps directly to understanding the program’s behavior.

After about ten minutes of generation and tests, I ran the CLI on example1-no-replace/ and example2-replace-secret2/ and it produced the expected replacements on the first run.

Building with specs takes a bit more upfront investment to write and render, but results in more reliable code generation and less time-consuming iterations.

Updating the Search-and-Replace CLI

After testing both versions on sample folders, I tried running both CLIs on my Node.js project. Both versions immediately got stuck replacing strings in node_modules/ — a folder that should clearly be ignored.

With vibe coding, the codebase is the source of truth, so every fix triggers regeneration and a full manual diff review. Even though I accepted 95% of the generated code as-is, I still had to review the entire 100%. Excluding node_modules/ meant regenerating, reviewing the diff, and manually rerunning fixtures to verify the change.

With spec-driven development, the spec is the source of truth: update the spec and rerender only the affected parts. Instead of “prompt-and-pray”, we update the relevant functional requirement (FR3) and rerender just that portion.

- The App should replace all original secrets with mock values recursively across The Target Folder, excluding the node_modules/ directory.

Automatically generated conformance tests assert that files under node_modules/ are never modified. With that constraint in place, the tool did what I intended: safely search-and-replace secrets without touching the node_modules/ folder.

To summarize, here’s how steering the expected behaviour differs between vibe coding and spec-driven development:

• Vibe coding: New prompt → update implementation → review a large diff → run manual tests for regressions.

• Spec-driven: Update/add a FR → rerender impacted FRs → proceed with confidence.

  

Building the same tool twice — once with vibes and once with specs — turned out to be a valuable learning experience in itself. This experiment showed me that vibe coding and spec-driven development aren’t opposites—they’re complementary approaches with different trade-offs.

While building the CLI, vibe coding gave me speed up front: I had a working CLI in minutes and could explore quickly. But without guardrails, every edit risked breaking something, and manual testing soon became the bottleneck.

Spec-driven development took a little more upfront effort, but once the specification was in place, the generated functionality was deterministic. Automatically generated tests provided guardrails that the generated code fully conforms to the specs. When I needed to exclude node_modules/, I only had to update the spec, while the tests gave me confidence that nothing else broke.

The trade-off is clear: vibe coding is great for hacking together ideas or prototypes, while spec-driven development shines when reliability, collaboration, and trust matter. Think Python: interactive mode when you’re exploring, but shifting to scripting mode when the idea matures. The point isn’t either/or — it’s choosing the right tool at the right time.

Subscribe now

def func_A(n):
   return 2 if n == 1 else n * func_A(n // 3 + 1)

than in words:

Write a function that multiplies n by smaller and smaller integers obtained by integer-dividing by 3 and adding 1 each time, until it reaches 1, at which point it uses 2 instead of 1 in the multiplication.

When precision and control are essential, code gives the developer ultimate power.

But such power is rarely needed. Outside of the domain of non-standard algorithms and mathematical expressions, specifying by coding is cumbersome and inefficient in describing the desired functionality. For example, the code below:

def fetch(limit=100):
   headers = {"Authorization": f"Bearer {API_KEY}"}
   cursor = None
   users = []

   while True:
       params = {"limit": limit}
       if cursor:
           params["cursor"] = cursor

       r = requests.get(f"{BASE_URL}/v1/users", 
               headers=headers, params=params)
       r.raise_for_status()

       payload = r.json()
       users.extend(payload.get("data", []))
       cursor = payload.get("next_cursor")
       if not cursor:
           break

   return user

is much harder for a human to write and understand than this natural language specification:

Fetch the list of users from the API.

Even if we want to be more specific in guiding the implementation, it is more efficient to specify the preferred approach (e.g., implement paging using cursors) than to code it ourselves.

Only in computer programming have we turned to a fully artificial language to express intent. Even in mathematics, most of a paper or proof is written not in formulas but in words. Laws, too, are composed in natural language, and attempts to formalize them have succeeded only in the simplest of cases. No programming language approaches the expressiveness of natural language or the way it aligns with how the human mind works.

Inefficiency is not the only issue with specifying software functionality through code. To increase productivity and improve maintainability, developers naturally strive to reuse code and share logic. However, when reuse happens at the level of shared code, it leads to functionality blending, that is, it becomes difficult to isolate in code where one functionality ends and another begins. Because multiple functionalities are intertwined, modifying the implementation code can lead to unintended side effects — software bugs in other functionalities that share the same code paths. Cross-cutting concerns (e.g., logging, validation, error handling) further complicate the codebase, making software maintenance increasingly difficult.

While coding, developers also clarify in their mind the intent behind their decisions. But once the code is written and the mental model behind the code fades, recovering that intent can be difficult — even when the code is well-documented with semantic identifiers and comments. This becomes especially challenging when functionality is distributed across multiple locations in the codebase. A developer looking to fix a bug or implement a new functionality must first reconstruct the original intent to avoid introducing new issues. The loss of intent is a major reason why developers dislike maintaining legacy systems and why it takes so long to become productive in a new codebase.

Vibe Coding: Fix One Thing, Break Ten Others

Vibe coding1 is the practice of building software by chatting with the AI — nudging features, fixing bugs, and shaping the app — instead of hand-coding everything yourself. The value of vibe coding over classical coding is that it leverages the full expressivity of the natural language for specifying intended functionality. In most cases, this is much more efficient than specifying by coding.

Vibe coding operates in a task-oriented2 mode: the developer describes a task in natural language, and the AI generates code to implement it. Once the code has been generated, the natural language instructions become obsolete, leaving the code as the sole source of truth for how the software behaves.

If it turns out that an earlier task was incorrectly specified or implemented, the developer must either attempt to correct it by submitting new tasks or fix the issue directly in the code. If these approaches fail or take too long, the only remaining option may be to revert to a previous working version of the code, losing all the work made in subsequent steps.

Fixing issues by submitting new tasks often feels like playing whack-a-mole — resolve one bug, and two more appear3. The root problem is that vibe coding lacks a reliable way to rescind or alter the result of a previous task, short of rolling back to an earlier working version. Even if you instruct the AI to “undo” a change, there’s no guarantee it will fully comply. Functionality blending makes this even worse: once subsequent instructions layer new logic on top of the old, the code becomes so intertwined that reversing specific changes without collateral damage is nearly impossible.

Compounding the problem is that vibe coding lacks tools to detect and resolve ambiguities in specifications or conflicts between specifications issued across different tasks. This becomes especially problematic in team settings. Vibe coding provides no support for cooperation between developers at the specification level, leaving them instead to rely on code reviews to resolve differences and conflicts in understanding the specifications.

If the developer must resort to code to fix the issue, most of the advantages of vibe coding disappear. First, the developer must be versed in the implementation technology. Second, to fix the issue without introducing new bugs the developer must understand the code base. Third, instead of doing the most valuable part of coding (implementing new functionality), the developer is left with the most tedious and least enjoyable task — fixing issues.

Spec-Driven Development: The Mature Way Forward

Vibe coding brings the efficiency of natural language to programming, but for control and precision, modular reuse, teamwork and clarity, developers still need to turn to code. To move beyond vibe coding and unlock the full potential of using natural language to specify software, developers must be able to fix any issue entirely within the specifications — without ever touching the underlying code. Spec-driven development delivers on this promise by making a key shift: instead of treating code as the source of truth — as is the case with task-oriented vibe coding — spec-driven development uses specifications as the source of truth for the software’s functionality4.

This represents a major paradigm shift in programming, and understandably, developers are very skeptical about whether it’s even possible. The two objections most frequently raised against using specifications as the source of truth are the inherent ambiguity of natural language and functionality flickering5.

Source code written in a programming language does not exhibit ambiguity; there is only one valid interpretation of a C program or a Python script. By contrast, natural language is inherently ambiguous, and there is always a possibility that someone will misinterpret a statement. But in the vast majority of cases, this is not a problem — humans understand each other quite well.

The solution to the problem of ambiguity in natural language is well established: when a reasonable person might perceive ambiguity, the specification should be strengthened to eliminate it. Humans have refined this for at least 4,000 years6 in codified legal systems — through interpretation and precedent — where it’s proven durable and effective.

In spec-driven development, ambiguity first needs to be detected — either through automated detection or by a developer noticing that the software is not behaving as intended. Once identified, the developer can respond in one of two ways: (i) by refining the specification to eliminate the ambiguity, or (ii) adding a special case to define how the software should handle the particular situation.

The other argument against using specifications as the source of truth is functionality flickering, that is, an undesirable phenomenon in spec-driven software development where underspecification makes generated functionality vary between code generations. For example, if the color of a button is left undefined, one generation might produce a green button and the next a red one, confusing users and undermining their trust.

Functionality flickering is not a new phenomenon — it only became noticeable with the rise of AI-powered code generation, which can produce multiple implementations from the same specification quickly and at low cost. The same effect appears with human developers: when given identical specifications, the end result will also look and feel very different. This variation arises because developers make many micro-decisions during coding, each influencing the functionality of the software. For example, if the color of a button is unspecified, one developer may choose yellow while another selects blue. From a functionality standpoint, the color is irrelevant (and therefore left unspecified). From a user’s perspective, however, the inconsistency can be confusing — for instance, if one version of the software presents an orange button while another shows a gray one7.

To prevent functionality flickering, it is necessary to detect and record the micro-decisions made during coding that affect software behavior. In subsequent code generations, these records must be reconsidered to ensure the software retains exactly the same functionality as before.

Introducing ***plain, the Language of Spec-Driven Development

To realize the vision of spec-driven development, *codeplain today announces ***plain — a specification language that combines the efficiency of natural language with the control and precision of code. Built on Markdown, ***plain introduces new syntax that allows developers to express intent at any level of detail. This enables ***plain renderer to consistently and reliably generate software code from specifications.

The core idea behind ***plain is that software can be specified as a union of (partially) overlapping functionalities, from which implementation code can always be generated from scratch. Developers are free to describe functionality in any way they choose, including using the full expressiveness of natural language, with the only limitation being that the description must be text-based. The functionalities can share concepts, thus enabling the building of complex functionality out of simpler functionalities.

In ***plain, specifications for overlapping functionalities must not contradict one another. If a conflict is found, it must be resolved by rewriting the specifications. Additionally, any complex functionality must be decomposed into simpler, more manageable parts. If decomposition is not possible, concrete examples must be provided in the form of acceptance tests8. These examples help the ***plain renderer generate code in small, testable increments, ensuring consistent and reliable output.

To ensure that the implementation code fully conforms to the specification, unit tests and conformance tests9 can be automatically generated from the same source specification. The specification can be further strengthened by additional acceptance tests written by the developer to disambiguate unclear specifications or address bugs in the implementation. Before new functionality is rendered or existing functionality is re-rendered, all tests must pass. Once functionality is implemented, the tests serve to detect regressions and verify that the implementation conforms to the specification.

Because ***plain specification is a collection of text files, all the powerful tooling that has evolved for coding can be fully reused. ***plain specification:

• Can be version controlled, enabling traceability and compliance

• Can use templates, enabling modular reuse of specifications

• Can be developed with AI-powered tools (e.g., Cursor)

• Enables concurrent teamwork with seamless merging

***plain also makes it easier for teams to share effective practices and successful patterns, much like they would with classical code. By expressing specifications in a standardized, structured form, developers can learn from one another’s approaches — for example, how to write clearer specifications or organize them into a coherent whole — without depending on informal, ad-hoc knowledge transfer.

The structure of the ***plain specification language — especially its syntax — is still under active development. Its first official release is planned for fall 2025, guided by the ***plain language working group.

We are now opening the group to a limited number of new members. The group’s initial members include Dusan Omercevic, founder of *codeplain, and Johan Rosenkilde, creator of SpecLang10 and a former member of the original GitHub Copilot team.

If you’re interested in contributing, please reach out to us at lang@plainlang.org.

The development of ***plain is made possible through the support of *codeplain, an AI-powered code generation service that produces production-ready software from specifications written in the ***plain language. For more information, visit www.codeplain.ai or email info@codeplain.ai.