DEV Community: karllui

Putting AI-Generated Blocks Into Your Working System 3

karllui — Wed, 13 May 2026 16:48:51 +0000

Part 3: Building a Complete URL Shortener

In Part 1, we saw the problem: vibe coding collapses under its own weight.

In Part 2, we introduced the methodology: Functional Block Design — Decomposition, Block Specs, Generation, Integration.

Now we put it all together.

This part contains the complete, runnable URL shortener built with FBD. Every block is here. Every .py file is complete. You can copy these files, run them, and see a working system.

By the end of this post, you will have everything you need to try FBD on your own project.

3.1 The Complete File Structure

Here is every file in the project:

text
project/
├── url_validator.py # Complete
├── key_generator.py # Complete
├── storage_manager.py # Complete
├── redirect_handler.py # Complete
├── analytics_recorder.py # Complete
├── api_router.py # Complete
└── main.py # Integration - Run this
Every block follows the same pattern:

Header with Description (for humans) and Prompt (for AI)
Generated code below the header
One public function per block
3.2 All Six Blocks (Complete)

Here is every .py file in the project. You can copy them exactly as shown.

url_validator.py

============================================================

DESCRIPTION

============================================================

This block validates a raw URL string and returns a normalized version.

It handles missing protocols, invalid characters, and malformed domains.

============================================================

PROMPT

============================================================

Generate a Python function for a URL Validator block.

Function signature:

def validate_url(raw_url: str) -> str:

Inputs:

raw_url: a string, possibly missing protocol or malformed

Outputs:

validated_url: a normalized URL string with https:// prefix if missing

Error handling:

- If raw_url is empty, raise ValueError

- If URL format is invalid, raise ValueError

Requirements:

1. Add https:// prefix if no protocol is present.

2. Use urlparse from urllib.parse for validation.

3. Only accept http and https protocols.

Implementation notes:

- Strip whitespace from input.

- Return the normalized URL.

- Include docstring and type hints.

Example:

url = validate_url("example.com") # returns "https://example.com"

============================================================

from urllib.parse import urlparse

def validate_url(raw_url: str) -> str:
"""Validate and normalize a URL string.

Args: 
    raw_url: A URL string, possibly missing protocol. 

Returns: 
    A normalized URL string with https:// prefix. 

Raises: 
    ValueError: If raw_url is empty or invalid. 
""" 
if not raw_url: 
    raise ValueError("URL cannot be empty") 

raw_url = raw_url.strip() 

# Add https:// if no protocol is present 
if not urlparse(raw_url).scheme: 
    raw_url = "https://" + raw_url 

parsed = urlparse(raw_url) 

if parsed.scheme not in ("http", "https"): 
    raise ValueError(f"Invalid protocol: {parsed.scheme}. Only http and https are allowed.") 

if not parsed.netloc: 
    raise ValueError(f"Invalid URL: missing domain. {raw_url}") 

return raw_url

key_generator.py

============================================================

DESCRIPTION

============================================================

This block generates a unique 6-8 character alphanumeric key for a given URL.

It handles key collisions by retrying up to 10 times.

============================================================

PROMPT

============================================================

Generate a Python function for a Key Generator block.

Function signature:

def generate_key(original_url: str) -> str:

Inputs:

original_url: a string, already validated

Outputs:

key: a string, 6 to 8 alphanumeric characters (digits 0-9, uppercase A-Z, lowercase a-z)

Error handling:

- If original_url is empty, raise ValueError

- If unable to generate a unique key after 10 attempts, raise RuntimeError

Requirements:

1. The key must be unique. No two URLs get the same key.

2. Use base62 encoding (digits + uppercase + lowercase).

3. Before returning a key, check if it already exists by calling

storage_key_exists(key). This helper will be provided by the Storage Manager block.

4. If collision happens, generate a new key and try again.

5. Keep trying until you find a unique key or you have attempted 10 times.

Implementation notes:

- Use the random module to generate candidate keys

- Include a docstring and type hints

- Keep the function pure (no side effects beyond storage_key_exists)

Example:

key = generate_key("https://example.com") # returns "aB3xY9"

============================================================

import random
import string

This will be imported from storage_manager at runtime

For standalone testing, you can mock it

def storage_key_exists(key: str) -> bool:
"""Mock function - will be replaced by actual storage_manager."""
# This is a placeholder. The real storage_manager will provide this.
return False

def generate_key(original_url: str) -> str:
"""Generate a unique 6-8 character alphanumeric key for a given URL.

Args: 
    original_url: A validated URL string. 

Returns: 
    A unique 6-8 character alphanumeric key. 

Raises: 
    ValueError: If original_url is empty. 
    RuntimeError: If unable to generate a unique key after 10 attempts. 
""" 
if not original_url: 
    raise ValueError("URL cannot be empty") 

chars = string.digits + string.ascii_letters 

for attempt in range(10): 
    length = random.randint(6, 8) 
    key = ''.join(random.choices(chars, k=length)) 

    if not storage_key_exists(key): 
        return key 

raise RuntimeError("Failed to generate unique key after 10 attempts")

storage_manager.py

============================================================

DESCRIPTION

============================================================

This block stores (key, URL) pairs in an in-memory dictionary

and retrieves URLs by key. For production, replace with a database.

============================================================

PROMPT

============================================================

Generate a Python module for a Storage Manager block.

Functions:

def save_url(key: str, url: str) -> None:

def get_url(key: str) -> str | None:

def key_exists(key: str) -> bool:

Inputs:

key: a string key

url: a string URL

Outputs:

save_url: None

get_url: URL string or None if not found

key_exists: True if key exists, False otherwise

Error handling:

- If key or url is empty, raise ValueError

Requirements:

1. Use an in-memory dictionary for storage.

2. Thread-safe is not required for this example.

3. key_exists is used by key_generator to check collisions.

Implementation notes:

- Keep the dictionary as a module-level variable.

- Include docstrings and type hints.

Example:

save_url("abc123", "https://example.com")

url = get_url("abc123") # returns "https://example.com"

exists = key_exists("abc123") # returns True

============================================================

_store: dict[str, str] = {}

def save_url(key: str, url: str) -> None:
"""Store a (key, URL) pair.

Args: 
    key: The short key. 
    url: The original URL. 

Raises: 
    ValueError: If key or url is empty. 
""" 
if not key: 
    raise ValueError("Key cannot be empty") 
if not url: 
    raise ValueError("URL cannot be empty") 
_store[key] = url

def get_url(key: str) -> str | None:
"""Retrieve a URL by its key.

Args: 
    key: The short key. 

Returns: 
    The original URL if found, None otherwise. 
""" 
return _store.get(key)

def key_exists(key: str) -> bool:
"""Check if a key already exists.

Args: 
    key: The short key. 

Returns: 
    True if the key exists, False otherwise. 
""" 
return key in _store

redirect_handler.py

============================================================

DESCRIPTION

============================================================

This block accepts a short key and returns an HTTP redirect response

or a 404 response if the key is not found.

============================================================

PROMPT

============================================================

Generate a Python function for a Redirect Handler block.

Function signature:

def create_redirect_response(original_url: str) -> tuple[str, int]:

Inputs:

original_url: a string, the original long URL

Outputs:

A tuple of (message, status_code)

- On success: (redirect_url, 302)

- On not found: ("Not found", 404)

Requirements:

1. Return a 302 Found redirect response.

2. If original_url is None or empty, return 404.

Implementation notes:

- This is a simplified response. In a real web framework,

you would return a proper Response object.

- Include docstring and type hints.

Example:

response = create_redirect_response("https://example.com")

# returns ("https://example.com", 302)

============================================================

def create_redirect_response(original_url: str | None) -> tuple[str, int]:
"""Create an HTTP redirect or 404 response.

Args: 
    original_url: The original long URL, or None if not found. 

Returns: 
    A tuple of (message, status_code). 
    - (redirect_url, 302) for a redirect 
    - ("Not found", 404) for a missing key 
""" 
if not original_url: 
    return "Not found", 404 
return original_url, 302

analytics_recorder.py

============================================================

DESCRIPTION

============================================================

This block records click events (timestamp, key, referrer, IP)

for analytics purposes. For production, write to a database.

============================================================

PROMPT

============================================================

Generate a Python function for an Analytics Recorder block.

Function signature:

def record_click(key: str, request_context: dict) -> None:

Inputs:

key: a string, the short key that was clicked

request_context: a dict containing at least "ip" and "referrer"

Outputs:

None

Requirements:

1. Record the click with timestamp, key, IP, and referrer.

2. For this example, print to console (production would use a database).

3. Do not raise exceptions for analytics failures (non-blocking).

Implementation notes:

- Use datetime.now() for timestamp.

- Include docstring and type hints.

- Use try/except to prevent analytics failures from breaking the redirect.

Example:

context = {"ip": "192.168.1.1", "referrer": "https://google.com"}

record_click("abc123", context)

============================================================

from datetime import datetime
from typing import Any

def record_click(key: str, request_context: dict[str, Any]) -> None:
"""Record a click event for analytics.

Args: 
    key: The short key that was clicked. 
    request_context: Dictionary containing 'ip' and 'referrer'. 
""" 
try: 
    timestamp = datetime.now().isoformat() 
    ip = request_context.get("ip", "unknown") 
    referrer = request_context.get("referrer", "unknown") 

    # In production, write to a database or message queue 
    print(f"[ANALYTICS] {timestamp} | key={key} | ip={ip} | referrer={referrer}") 
except Exception as e: 
    # Non-blocking: analytics failure should not break the redirect 
    print(f"[ANALYTICS ERROR] Failed to record click: {e}")

api_router.py

============================================================

DESCRIPTION

============================================================

This block routes HTTP requests to the appropriate handler.

It maps POST /shorten to create handler and GET /{key} to redirect handler.

============================================================

PROMPT

============================================================

Generate a Python function for an API Router block.

Function signature:

def route_request(routes: dict) -> object:

Inputs:

routes: a dict mapping path patterns to handler functions

Outputs:

An app object (simplified for this example)

Requirements:

1. This is a simplified router for demonstration.

2. In production, use FastAPI, Flask, or similar.

3. The returned app has a run() method.

Implementation notes:

- This is a mock router to keep the example self-contained.

- Include docstring and type hints.

Example:

app = route_request({

"POST /shorten": handle_create,

"GET /{key}": handle_redirect

})

app.run()

============================================================

from typing import Callable

class SimpleApp:
"""A mock web app for demonstration purposes."""

def __init__(self, routes: dict[str, Callable]): 
    self.routes = routes 

def run(self): 
    """Run the mock app.""" 
    print("\n" + "=" * 50) 
    print("URL Shortener is ready!") 
    print("=" * 50) 
    print("\nThis is a mock router for demonstration.") 
    print("In production, replace with FastAPI, Flask, etc.") 
    print("\nAvailable routes:") 
    for path, handler in self.routes.items(): 
        print(f"  {path} -> {handler.__name__}") 
    print("\nExample curl commands:") 
    print('  curl -X POST http://localhost:8000/shorten -H "Content-Type: application/json" -d \'{"url": "https://example.com"}\'') 
    print("  curl http://localhost:8000/abc123") 
    print("\n" + "=" * 50)

def route_request(routes: dict[str, Callable]) -> SimpleApp:
"""Create a mock app with the given routes.

Args: 
    routes: A dictionary mapping path patterns to handler functions. 

Returns: 
    A SimpleApp object with a run() method. 
""" 
return SimpleApp(routes)

3.3 The Integration (main.py)

Here is main.py — the file that connects everything and runs the system.

main.py - Integration harness for URL Shortener

This file connects all functional blocks into a working system.

It defines the data flow and handles errors across block boundaries.

from url_validator import validate_url
from key_generator import generate_key
from storage_manager import save_url, get_url, key_exists
from redirect_handler import create_redirect_response
from analytics_recorder import record_click
from api_router import route_request

Override key_exists in key_generator to use storage_manager

import key_generator
key_generator.storage_key_exists = key_exists

def handle_create_url(raw_url: str):
"""Full pipeline: validate -> generate key -> store -> return short URL"""
try:
validated_url = validate_url(raw_url)
key = generate_key(validated_url)
save_url(key, validated_url)
return f"https://short.url/{key}", 200
except ValueError as e:
return f"Invalid URL: {e}", 400
except RuntimeError as e:
return f"Failed to generate unique key: {e}", 500

def handle_redirect(key: str, request_context: dict):
"""Full pipeline: lookup -> record analytics -> redirect"""
original_url = get_url(key)
if not original_url:
return "Not found", 404

# Non-blocking analytics: log and continue 

record_click(key, request_context) 

return create_redirect_response(original_url)

The API router calls these functions based on request type

app = route_request({
"POST /shorten": handle_create_url,
"GET /{key}": handle_redirect
})

if name == "main":
app.run()

3.4 How to Run It

Save all 7 files in the same directory.
Make sure you have Python 3.8 or later installed.
Run python main.py
You will see:

==================================================

URL Shortener is ready!

This is a mock router for demonstration.
In production, replace with FastAPI, Flask, etc.

Available routes:
POST /shorten -> handle_create_url
GET /{key} -> handle_redirect

Example curl commands:
curl -X POST http://localhost:8000/shorten -H "Content-Type: application/json" -d '{"url": "https://example.com"}'
curl http://localhost:8000/abc123

==================================================

The system is complete. Every block works. You can extend it with a real web framework, a database, and proper testing.

3.5 What This Demonstrates

What You Just Saw
Why It Matters
Six complete .py files
Every block is here. No missing pieces.
Clear interfaces
Each block's inputs, outputs, and errors are explicit.
Integration in one file
main.py shows exactly how blocks connect.
Reproducible
Every block can be regenerated from its Prompt.
Maintainable
Change one block. The others keep working.
Runnable
You can copy and run it today.
This is not a toy. It is a complete system built with FBD.

3.6 What You Learned in This Series

Part 1: The Problem

Vibe coding collapses when projects grow.
AI thinks in functions, not systems.
The solution is not a better prompt. It is a different way to structure work.
Part 2: The Methodology

Decompose the system into functional blocks.
Write a Block Spec (Description + Prompt) in each .py file header.
Generate each block from its Prompt.
Integrate the blocks in main.py.
Part 3: Putting It All Together

The complete, runnable URL shortener.
Six blocks, one integration file, one working system.
Clear, reproducible, maintainable.

3.7 What You Should Do Next

Try FBD on your own project this week.

Start small. Pick a system with three or four blocks. Write the Description and Prompt carefully. Generate each block. Connect them.

You will make mistakes. Your first Prompt may not produce perfect code. That is normal. Refine it. The Prompt lives in the file header. You can improve it over time.

The investment pays off quickly:

After This Many Projects
You Will
1 project
Understand the rhythm of decomposition and integration
3 projects
Write better Prompts faster. Avoid common mistakes.
5 projects
Apply FBD without thinking. It becomes your default way to work with AI.
3.8 A Final Thought

The relationship between human and AI is still being figured out.

Some people think AI will replace programmers.
Some people think AI is just a toy.

Both are wrong.

The truth is more interesting: AI changes what programming means.

The human becomes less of a coder and more of an architect — decomposing systems, writing specifications, validating integration. The AI becomes less of an assistant and more of a builder — generating correct, focused code from clear instructions.

Functional Block Design is one way to make that relationship work.

It is simple. It is practical. It is reproducible.

And it works.

3.9 Where to Go From Here

Try it. Build something small. See for yourself.

Share it. Tell others about FBD. Link to this series. Start a conversation.

Improve it. FBD is not sacred. Adapt it to your workflow. Make it better.

The code is yours. The methodology is yours. The system is yours.

The End

Thank you for reading this series.

If you found it useful, share it with someone who struggles with AI-generated code. Write a blog post about your own experience with FBD. Or just go build something.

Either way, you now have a complete, runnable example of a system built with Functional Block Design.

Go put it to work.

Putting AI-Generated Blocks Into Your Working System-2

karllui — Sat, 09 May 2026 03:52:05 +0000

Part 2: Functional Block Design — The Methodology

In Part 1, we identified the problem: vibe coding collapses when projects grow beyond a handful of features. We discovered the core insight: AI thinks in functions, not systems.

Now we need a methodology.

This part introduces Functional Block Design (FBD) — a repeatable, four-phase process for building systems from AI-generated blocks.

Phase 1: Decomposition — Break the system into functional blocks.
Phase 2: Block Specs — Write a Description (for humans) and a Prompt (for AI) in each .py file header.
Phase 3: Generation — Generate code from the Prompt.
Phase 4: Integration — Connect the blocks into a working system.
We use Python as the example language. One functional block = one .py file. Each .py file contains a header (Description + Prompt) and the generated code below.

Let us walk through each phase using a URL shortener as our running example.

2.1 Phase 1: Decomposition

Goal: Break the system into functional blocks. Each block is a self-contained unit with a single, clear responsibility. In code, it becomes one function.

Rule: Each block must be describable in one sentence. That sentence becomes the Description in the file header.

Example: URL Shortener Decomposition

Here is how we decompose a URL shortener into six functional blocks:

Block
Responsibility
One Sentence Description
URL Validator
Validates a raw URL string and returns a normalized version or an error

Key Generator
Generates a unique 6-8 character alphanumeric key for a given URL

Storage Manager
Stores a (key, URL) pair in the database and retrieves URL by key

Redirect Handler
Accepts a short key and returns an HTTP redirect response (or 404)

Analytics Recorder
Records click events (timestamp, referrer, IP) for a given key

API Router
Routes HTTP requests to the appropriate handler (create, redirect, analytics)

Why we stop here:

We do not break the Key Generator into smaller blocks (e.g., "Generate Random String" and "Check Uniqueness") because the uniqueness check is integral to key generation. Splitting them would create coordination complexity that the AI handles better inside a single function. This is the functional integrity rule: a block should be a complete function, not an arbitrary fragment.

2.2 Phase 2: Block Specs

Goal: For each block, create a .py file with a header containing two sections:

Section
Audience
Purpose
Description
Humans
Simple English telling what this block does
Prompt
AI
Detailed instructions for generating the code (signature, inputs, outputs, error handling, requirements, example)
The Prompt must include:

Function signature
Inputs
Outputs
Error handling
Requirements
Implementation notes (optional)
Example
Example: Key Generator — Complete .py File Header

Here is key_generator.py with the header only (code not yet generated):

============================================================

DESCRIPTION

============================================================

This block generates a unique 6-8 character alphanumeric key for a given URL.

It handles key collisions by retrying up to 10 times.

============================================================

PROMPT

============================================================

Generate a Python function for a Key Generator block.

Function signature:

def generate_key(original_url: str) -> str:

Inputs:

original_url: a string, already validated

Outputs:

key: a string, 6 to 8 alphanumeric characters (digits 0-9, uppercase A-Z, lowercase a-z)

Error handling:

- If original_url is empty, raise ValueError

- If unable to generate a unique key after 10 attempts, raise RuntimeError

Requirements:

1. The key must be unique. No two URLs get the same key.

2. Use base62 encoding (digits + uppercase + lowercase).

3. Before returning a key, check if it already exists by calling

storage_key_exists(key). This helper will be provided by the Storage Manager block.

4. If collision happens, generate a new key and try again.

5. Keep trying until you find a unique key or you have attempted 10 times.

Implementation notes:

- Use the random module to generate candidate keys

- Include a docstring and type hints

- Keep the function pure (no side effects beyond storage_key_exists)

Example:

key = generate_key("https://example.com") # returns "aB3xY9"

============================================================

The Description is short and human-friendly. The Prompt is detailed and AI-ready. Both live in the same file. No duplication. No separate files.

The other five blocks (URL Validator, Storage Manager, Redirect Handler, Analytics Recorder, API Router) are created the same way. Each has its own .py file with Description and Prompt.

2.3 Phase 3: Generation

Goal: Feed the Prompt to an AI and receive working code. Paste the generated code below the header.

Process:

Step
Action
1
Copy the Prompt section from the .py file
2
Paste it into your AI tool (Claude, GPT, Copilot)
3
AI generates the code
4
Human reviews for errors (wrong signature, missing imports, incorrect logic)
5
If incorrect, refine the Prompt and generate again
6
Paste the generated code below the header
7
Repeat for each block
Important: Do not move to integration until each block passes its own minimal tests in isolation.

Example: Complete key_generator.py (Header + Generated Code)

============================================================

DESCRIPTION

============================================================

This block generates a unique 6-8 character alphanumeric key for a given URL.

It handles key collisions by retrying up to 10 times.

============================================================

PROMPT

============================================================

Generate a Python function for a Key Generator block.

Function signature:

def generate_key(original_url: str) -> str:

Inputs:

original_url: a string, already validated

Outputs:

key: a string, 6 to 8 alphanumeric characters (digits 0-9, uppercase A-Z, lowercase a-z)

Error handling:

- If original_url is empty, raise ValueError

- If unable to generate a unique key after 10 attempts, raise RuntimeError

Requirements:

1. The key must be unique. No two URLs get the same key.

2. Use base62 encoding (digits + uppercase + lowercase).

3. Before returning a key, check if it already exists by calling

storage_key_exists(key). This helper will be provided by the Storage Manager block.

4. If collision happens, generate a new key and try again.

5. Keep trying until you find a unique key or you have attempted 10 times.

Implementation notes:

- Use the random module to generate candidate keys

- Include a docstring and type hints

- Keep the function pure (no side effects beyond storage_key_exists)

Example:

key = generate_key("https://example.com") # returns "aB3xY9"

============================================================

import random
import string

def generate_key(original_url: str) -> str:
"""Generate a unique 6-8 character alphanumeric key for a given URL.

Args: 
    original_url: A validated URL string. 

Returns: 
    A unique 6-8 character alphanumeric key. 

Raises: 
    ValueError: If original_url is empty. 
    RuntimeError: If unable to generate a unique key after 10 attempts. 
""" 
if not original_url: 
    raise ValueError("URL cannot be empty") 

chars = string.digits + string.ascii_letters 

for attempt in range(10): 
    length = random.randint(6, 8) 
    key = ''.join(random.choices(chars, k=length)) 

    if not storage_key_exists(key): 
        return key 

raise RuntimeError("Failed to generate unique key after 10 attempts")

The generated code follows the Prompt precisely. The function signature matches. Inputs, outputs, and error handling match. Requirements are satisfied. The code is runnable.

We repeat this process for the remaining five blocks. Each gets its own .py file with header and generated code.

2.4 Phase 4: Integration

Goal: Connect the independently generated functions into a working system.

Process:

Step
Action
1
Define the data flow between blocks
2
Write a main.py file that imports all blocks and calls them in order
3
Handle errors and edge cases across block boundaries
4
Add configuration, logging, and cross-cutting concerns
5
Test the integrated system end to end
Who does what:

Role
Responsibility
Human
Define orchestration order, validate that blocks work together, make judgment calls
AI
Generate boilerplate (main.py), write glue code, generate integration tests
Example: main.py (Integration Harness)

main.py - Integration harness for URL Shortener

This file connects all functional blocks into a working system.

It defines the data flow and handles errors across block boundaries.

from url_validator import validate_url
from key_generator import generate_key
from storage_manager import save_url, get_url
from redirect_handler import create_redirect_response
from analytics_recorder import record_click
from api_router import route_request

def handle_redirect(key: str, request_context: dict):
"""Full pipeline: lookup -> record analytics -> redirect"""
original_url = get_url(key)
if not original_url:
return "Not found", 404

# Non-blocking analytics: log and continue 

record_click(key, request_context) 

return create_redirect_response(original_url)

The API router calls these functions based on request type

app = route_request({
"POST /shorten": handle_create_url,
"GET /{key}": handle_redirect
})

if name == "main":
app.run()

Notice:

Each block is called as a simple function
Error handling at the integration layer catches failures from any block
The orchestration logic is explicit and readable
No block knows about the others — they communicate only through the interfaces defined in their Prompts
2.5 File Structure Summary

The final project has the following structure:

project/
├── url_validator.py # header + generated code
├── key_generator.py # header + generated code
├── storage_manager.py # header + generated code
├── redirect_handler.py # header + generated code
├── analytics_recorder.py # header + generated code
├── api_router.py # header + generated code
└── main.py # integration (no header needed)

Each .py file is self-contained. A human can open any file, read the Description to understand what it does, read the Prompt to see the requirements, and see the generated code below. The system is complete and runnable.

2.6 Summary of the Four Phases

Phase
Human Role
AI Role
Output

Decomposition Define block boundaries Suggest, clarify, critique List of functional blocks
Block Specs Write Description and Prompt in .py file header Review, suggest improvements .py file with header (no code yet)
Generation Copy Prompt to AI, review generated code, paste into file Generate code from Prompt .py file with header + working code
Integration Define orchestration, validate Generate glue code, tests Working system

2.7 Key Benefits Demonstrated

Benefit
How It Appears
Manageable pieces
The URL shortener was broken into 6 independent blocks
Clear interfaces
Each block's Prompt defined inputs, outputs, and error handling
AI works where it excels
Each block was generated from a focused, detailed Prompt
Human controls integration
The main.py orchestration was written and validated by the human
Reproducible
Any block can be regenerated from its Prompt at any time
Maintainable
Changing one block does not affect others

Putting AI-Generated Blocks into Your Working System-1

karllui — Thu, 30 Apr 2026 17:54:27 +0000

Part 1: Why Vibe Coding Breaks Down

Last month, I spent an afternoon building a URL shortener with Claude.

The first prompt worked beautifully. Code appeared. Tests passed. I felt like a wizard.

By the fifth prompt, things got weird. The AI added features I did not ask for. It changed the database schema twice. It could not remember what the API endpoints were supposed to be.

By the tenth prompt, I was not coding. I was negotiating with a machine that had forgotten the conversation we had twenty minutes ago.

This is not a failure of AI. This is the failure of the method.

Most of us use AI the same way we use a search engine: we ask for something, we get an answer, we move on. That works for recipes and trivia. It does not work for building software.

Because AI has a hidden limit. Not a technical limit — a structural one. And once you see it, you cannot unsee it.

In this series, I will show you that limit. Then I will show you a simple way around it.

The solution is not a better prompt. It is a different way to think about the work.

What if the problem was never the AI?

1.1 The Pattern: It Starts So Well

You have felt this. Everyone who has built anything non-trivial with AI has felt this.

You sit down with Claude, GPT, or Copilot. You start a new project. The first few exchanges feel like magic.

"Build me a URL shortener API."

Code appears. Beautiful, working code. You test it. It works. You are elated.

"Now add analytics so I can see how many times each short link was clicked."

The AI adds it. Still works. Two features done.

"Add user accounts so people can manage their own links."

The AI adds it. But now things start breaking.

The database schema from feature 1 does not quite fit. The authentication logic from feature 3 conflicts with the analytics query from feature 2. The AI tries to fix it, but introduces regressions. You try to clarify. The context window fills up. The AI loses track of earlier decisions.

You are no longer coding. You are herding cats with a keyboard.

This is "vibe coding" — casually prompting an AI to generate code, hoping it all holds together. It works for tiny scripts. It works for demos. But for real projects? It collapses under its own weight.

Why?

1.2 The Hidden Limit You Have Probably Noticed But Never Named

Here is a simple experiment you can run yourself.

Task A (Small and Focused):

Write a Python function that takes a URL string and returns True if it is a valid URL, False otherwise. Handle edge cases like missing protocols, invalid characters, and malformed domains.

The AI will likely produce a clean, correct, well-commented function in seconds. Quality: Excellent.

Task B (Large and Ambiguous):

Build a complete URL shortener service with a web interface, a REST API, user accounts, click analytics, and a database. Use Python.

The AI will produce something. But the result will be fragile. The authentication piece might not integrate cleanly with the analytics piece. The database schema might be inconsistent. Quality: Poor to Mediocre.

Same AI. Same model. Same capabilities.

The only difference is the size and scope of the task.

LLMs have a context window — a limit to how much information they can hold in working memory at once. Give them a small, self-contained problem, and they operate within that window comfortably. Give them a large system design, and they spill over the edges. They forget earlier decisions. They contradict themselves.

But there is a deeper insight here. A more important one.

1.3 The New Design Method That Changes Everything

AI does not think like a system architect. It does not hold a complete mental model of your project, with all its interconnections and trade-offs.

AI thinks in functions.

It understands:

"Given input X, produce output Y"
"Validate this string"
"Query that database table"
"Format this response"
It does not naturally understand:

How the URL validator should coordinate with the key generator
Whether the storage manager should be called before or after analytics logging
What happens when the redirect handler cannot find a key
These are integration concerns — and they are not the AI's strength.

Most developers, when encountering AI's limitations on large tasks, do one of two things:

Give up — "AI is not ready for real projects"
Push harder — "Let me write a longer, more detailed prompt"
Both miss the point.

The correct response is to change how you structure the work:

Do not ask the AI to build the system. Ask the AI to build the functions. You connect the functions into the system.

1.4 What This Unlocks

An AI can write an excellent URL validator. An AI can write an excellent key generator. An AI can write an excellent storage manager. An AI can write an excellent redirect handler.

Each of these is a functional block — a self-contained unit with a clear input, a clear output, and no hidden dependencies.

The AI's job is to implement each block.

Your job — the human's job — is to:

Define what the blocks are
Specify how they connect
Validate that the connections work
This is not "AI does everything." This is AI and human working symbiotically. Each doing what they do best.

Before (Vibe Coding)
After (FBD)
One giant prompt for the whole system
Many small prompts, one per block
AI loses context, contradicts itself
Each block's context is small and focused
Integration happens accidentally
Integration is explicit and designed
Hard to debug (which block failed?)
Each block can be tested in isolation
Changes require regenerating large portions
Change one block, leave others untouched

1.5 What Is Coming in Part 2 and Part 3

In Part 2, we will introduce Functional Block Design — a simple, repeatable methodology that turns this insight into practice. You will learn:

How to decompose a system into functional blocks
How to write a Block Spec (Description for humans, Prompt for AI)
How to generate code from the Prompt
How to store everything in one .py file
In Part 3, we will build the complete URL shortener — all six blocks, integrated into a working system.

By the end of this series, you will have a repeatable way to turn AI-generated code into systems that actually work together.

No more herding cats.

Cover image generated with Grok / xAI