The Convention Generation Experiment: Why AI Can't Build What I Hoped It Could #

After discovering the power of conventions in my VibeTDD experiments, I had a beautiful dream: What if AI could generate custom convention files for any technology stack?

Imagine a configurator where you select:

• Platform: Backend, web, mobile
• Language: Kotlin, TypeScript, Python
• Framework: Spring Boot, Vue.js, React
• Architecture: Monolith, microservices, serverless

And outcomes a perfectly tailored convention file with examples in your exact stack.

I spent a couple of days trying to understand if it's possible to build this system. Here's why it spectacularly failed, what I learned about AI's limitations, and the much simpler solution I'm building instead.

The Dream: Universal Convention Generation #

The Vision #

My idea was elegant in its simplicity:

Layer 1: Universal Principles

• Hexagonal architecture concepts
• Dependency injection patterns
• API design standards
• Testing strategies

Layer 2: Platform-Specific Conventions

• Backend validation patterns
• Frontend state management
• Mobile architecture guidelines

Layer 3: Technology Implementation

• Language idioms (Kotlin extensions, TypeScript types)
• Framework specifics (Spring annotations, Vue composition)
• Build tool configuration (Maven, Gradle, Vite)

The Magic: AI would read universal principles, combine them with technology specifics, and generate perfect convention files for any stack combination.

The Expected Workflow #

User selects: Backend + Kotlin + Spring Boot + Maven + Modular Monolith

AI combines:
- hexagonal-architecture.md
- backend-validation.md  
- kotlin-idioms.md
- spring-boot-patterns.md
- maven-configuration.md
- modular-monolith-structure.md

Output: a folder like 'spring-boot-kotlin-maven-modular-conventions' with the stack specific conventions

Beautiful, right? One system, infinite combinations.

The Reality Check #

Experiment 1: API Design + Kotlin #

I started simple. I had:

• api-design: REST standards, response patterns, error handling
• kotlin-common: Language idioms, null safety, extension functions

The Task: "Generate API design conventions for Kotlin projects"

My Strict Prompt:

- Carefully Read ALL Core Pattern principles
- Carefully Read Attached Language Conventions and check GOOD and BAD examples
- Create one file where you put:
    - The description of each point. Important to copy all crucial conventions, like naming conventions, endpoints names etc
    - Code example in the selected language. It's important to follow each rule that you found in language conventions. All examples should follow these rules to have consistency between different conventions. Use GOOD examples only.
- Build minimal and simple examples that should be enough for AI to understand the pattern

What I Got:

• Mixed API concepts with random Kotlin features
• Added testing patterns I didn't ask for
• Included Spring Boot annotations (not mentioned in source files)
• Created its own error handling patterns ignoring my specifications

The Verdict: AI couldn't stay focused on the specific combination I requested.

Experiment 2: Project Skeleton Generation #

The Task: "Create a project skeleton following these conventions and zip it (Yeah, I forgot Claude is a text-based model)"

What I Expected: File structure with basic classes implementing the patterns

What I Got:

"I'll create the complete project as an HTML artifact that generates all the files!"

Then Claude generated a complete HTML-based Spring Boot project generator - a full web application with form inputs, JavaScript, and dynamic file generation.

Wait, what? I asked for a simple project structure, not a project generator web app! If you cannot provide it, just say it...

The Focus Problem #

Every time I asked AI to generate conventions for a specific aspect, it would:

• Add unrelated concerns ("Let me also include testing patterns...")
• Mix abstraction levels (universal principles with framework specifics)
• Invent new patterns instead of using provided ones
• Create overly complex examples

My Ideas Why AI Can't Generate Flexible Conventions #

Discovery 1: Context Mixing Is Inevitable #

When AI reads multiple convention files, it tries to combine everything rather than extracting relevant parts. Give it API design + Kotlin basics, and it will create "API design conventions that also cover Kotlin language features" instead of "API design patterns implemented in Kotlin."

Discovery 2: AI Loves Feature Creep #

AI constantly adds features I didn't request:

• Mention validation → It adds complete validation frameworks
• Show project structure → It includes testing, logging, security
• Request Kotlin examples → It adds Spring Boot, reactive programming, coroutines

The Pattern: AI optimizes for completeness, not focus.

Discovery 3: True Expertise Still Matters #

The Critical Insight: You can't mechanically translate universal principles into technology-specific implementations without deep domain knowledge.

Creating good Spring Boot + Kotlin conventions requires understanding:

• How Kotlin null safety affects Spring validation
• Which Spring features work best with Kotlin idioms
• Maven dependency conflicts specific to this combination
• Testing patterns that leverage both Spring and Kotlin strengths

This knowledge exists in the heads of experienced developers, not in composable text files.

The Simpler Solution: Technology-Specific Templates #

Instead of flexible generation, I wanted to try focused project templates:

Backend/Kotlin/Spring Boot/Maven/Monolith #

backend-kotlin-spring-boot-maven-monolith/
├── docs/
│   ├── basic-conventions.md    # Complete, focused basic conventions
│   ├── architecture.md         # Project-specific architecture
│   └── development-workflow.md # How to work with this stack
├── src/main/kotlin/           # Basic project structure
├── src/test/kotlin/           # Testing setup
├── pom.xml                    # Pre-configured dependencies
└── README.md                  # Getting started guide

Frontend/Vue/TypeScript/Vite/SPA #

frontend-vue-typescript-vite-spa/
├── docs/
│   ├── basic-conventions.md   # Vue + TypeScript specific
│   ├── component-patterns.md  # Vue composition patterns
│   └── state-management.md    # Pinia/Vuex guidelines
├── src/                       # Vue project structure
├── package.json               # Pre-configured dependencies
└── README.md

Instead of generating conventions, the workflow becomes:

1. Choose template based on your exact stack
2. Clone the template with complete setup
3. Adapt to your project using AI assistance

For adaptation, AI excels at:

• Renaming domains (Payment → User)
• Adjusting business rules
• Adding specific features following established patterns
• Updating configuration for your environment

Why Templates Work Better #

✅ Expert Quality: #

Built by developers who actually use that stack, not generated combinations.

✅ Complete Setup: #

Everything you need in one place - no missing pieces.

✅ Proven Patterns: #

Real patterns that work in production.

✅ Easy Updates: #

Update one template, not a complex generation system.

The Trade-offs I Accept #

❌ Duplication: #

Multiple templates will have similar validation patterns, error handling, etc.

But: Conventions don't change often, and technology-specific nuances matter more than avoiding duplication.

❌ More Templates to Maintain: #

Each stack combination needs its own template.

But: Better to maintain 10 focused, working templates than one complex generation system that produces mediocre results.

❌ Less "Magical": #

No configurator that generates infinite combinations.

But: Practical beats magical. Developers want solutions that work, not impressive demos.

What This Means for VibeTDD #

The convention generation experiment taught me that AI amplifies expertise, it doesn't replace it. You still need humans who deeply understand Spring Boot + Kotlin, or Vue + TypeScript, to create quality conventions.

But AI is excellent at:

• Adapting proven patterns to new domains
• Maintaining consistency across similar components
• Implementing established conventions in new code
• Helping developers follow existing guidelines

The Road Ahead #

I'm going to test this template approach with Backend/Kotlin/Spring Boot/Maven/Modular Monolith.

I'll use the same simple payouts project from my previous experiments (create and validate payout), but this time add API and database layers to make it more realistic.

The goal is to create a complete working template that demonstrates how VibeTDD conventions work across all layers of a real application.

The Meta-Lesson #

Sometimes the most valuable experiments are the ones that fail. This convention generation experiment revealed a fundamental truth about AI-assisted development:

AI is best at following established patterns, not creating new combinations.

The future of VibeTDD isn't about AI generating infinite variations of conventions. It's about AI helping developers implement proven, expert-curated patterns efficiently and consistently.

Next up: Building the first VibeTDD project template with a complete backend stack. The dream of universal generation is dead, but the reality of practical, focused templates is much more promising.