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_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()
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
Top comments (0)