In a professional kitchen, there is a concept called mise en place—everything in its place. You don’t start searing the scallops until every herb is chopped and every sauce is whisked. If you skip the prep to “save time,” you end up adjusting the recipe mid-sauté, usually resulting in a frantic mess, ruined ingredients, and a dish that takes twice as long to serve.

Modern software development has a similar “popular choice”: start coding the logic immediately to show “progress.” But when we skip the architectural prep—the interfaces and boundaries—we aren’t moving fast; we are just building a kitchen we’ll have to tear down while the customers are waiting. I’ve watched engineers lose sight of the goal in the pursuit of a “perfect flow” that wasn’t grounded in discipline. If everyone says they want “clean code,” why does the system feel like it’s fighting us the moment we add a new story?

𝗦𝘆𝘀𝘁𝗲𝗺 𝗚𝗲𝗼𝗺𝗲𝘁𝗿𝘆

The environment of this experiment is a standard Kotlin and Spring Boot stack. The landscape is defined by three distinct zones designed to minimize the “weight” of dependencies. To navigate this space, we use a rigid directory structure that acts as our map:

app

├── domain      <-- THE HEART (POKOs only)
│   ├── model
│   │   └── Data.kt     <-- Pure Kotlin Data Class
│   └── ports
│       └── outgoing    <-- Interfaces defining “What” we need
│           ├── DataPersistencePort.kt    <- SQL db
│           └── DataStoragePort.kt        <- Object storage
├── usecases    <-- THE ORCHESTRATOR
│   └── StoreDataUseCase.kt    <-- Feature logic
└── adapter     <-- THE “HOW” (Infrastructure)
    ├── web         <-- Inbound Adapter
    │   ├── DataController.kt
    │   ├── dto         <-- Request/Response DTOs
    │       └── WebMapper.kt    <-- DTO <-> Domain mapping
    ├── sqldb       <-- Outbound Adapter
    │   ├── entity
    │   │   └── DataJpaEntity.kt    <-- @Entity + JPA annotation
    │   ├── DataRepository.kt        <-- Spring Data/CrudRepository
    │   ├── PersistenceMapper.kt     <-- Entity <-> Domain mapping
    │   └── PersistenceAdapter.kt    <-- Impl DataPersistencePort
    └── cloud       <-- Outbound Adapter
        └── ObjectStorageAdapter.kt

➤ The Heart (Domain): Pure Kotlin Data Classes and business logic common to all usecases.

➤ The Orchestrator (Usecases): Where feature-specific logic lives and adapters are coordinated.

➤ The Infrastructure (Adapters): The “How” of the system—web controllers, JPA entities, and cloud storage clients.

The invisible boundary here is the Port. It’s an interface that defines “what” we need without caring “how” it’s done. In theory, this geometry should be light and flexible, yet many teams find it rigid because they misunderstand the direction of the signal.

𝗘𝗺𝗽𝗶𝗿𝗶𝗰𝗮𝗹 𝗘𝘅𝗽𝗹𝗼𝗿𝗮𝘁𝗶𝗼𝗻

I moved from the “theoretical path” of perfect architecture to the “actual terrain” of daily PRs. The system showed its breaking point not in a crash, but in a silent failure of discipline: the Domain Import Leak.

➤ The Breaking Point: It usually starts when an engineer adds a domain service that directly imports an adapter: import app.adapter.NewAdapter.kt.

➤ The Silent Failure: The code still passes tests. It still “works”. But the “Pure Domain” has been poisoned by infrastructure concerns.

➤ The Result: When the time inevitably comes to move that service to a usecase, the system reacts with extreme fatigue. We end up with PRs requiring the renaming of tens of files, leading to typos, package mismatches, and a massive mental load on reviewers.

𝗠𝗮𝗻𝗮𝗴𝗶𝗻𝗴 𝘁𝗵𝗲 𝗦𝗶𝗴𝗻𝗮𝗹

The handoff between layers is where the “spaghetti” starts or ends. In my exploration, I found that the clarity of intent is often lost because teams are afraid of the “complexity” of an extra interface.

➤ Cognitive Load: Trying to refactor architecture in the middle of a feature story creates a “refactoring nightmare”.

➤ Signal-to-Noise: If you are 100% sure a logic block belongs in the domain, put it there. If not, the “cleaner” signal is to start in a Usecase and extract downward only when the need is proven.

➤ Direct Translation: To keep the signal clear, I’ve found it’s even acceptable to call a Port directly from a controller for simple cases. This avoids 1:1 “pass-through” mapping while keeping the adapter decoupled through the interface.

𝗪𝗵𝗮𝘁 𝗘𝗮𝗿𝗻𝗲𝗱 𝗧𝗿𝘂𝘀𝘁?

After the stress test of “no time to decouple,” one principle remained standing: Mandatory Ports from the Start.

➤ Stability: The “price” of an interface at the start is effectively zero. It provides an immediate boundary that prevents the “import leak” and allows the domain to remain pure. ➤ The New Baseline: My trusted navigation strategy is now TDD-driven Hexagon.

• Step 1: Define the Domain Model.

• Step 2: Build the Adapter and verify it with Testcontainers (SQL or Object Storage).

• Step 3: Finally, orchestrate it all in the Usecase or Controller using the Port interface.

𝗔𝗰𝘁𝗶𝗼𝗻𝗮𝗯𝗹𝗲 𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀

➤ Backlog (Failed the Stress Test):

• “Refactoring-in-the-middle”: Changing architecture while delivering a story leads to mess and typos.

• Direct Adapter Imports: Any import app.adapter inside app.domain is a bug, not a feature.

➤ Merged (Trusted Toolkit):

• Ports First: Always create the interface for 3rd party services or repositories immediately.

• Adapter-First Testing: Use Testcontainers to prove your “How” works before you worry about the “What” in your orchestration.

• Minimum Layers: Only add a Usecase layer if there is actual orchestration; otherwise, call the Port from the Controller.

Final Wisdom: Clean architecture isn’t about having the most layers; it’s about having the most resilient boundaries. The “price” of an interface is nothing compared to the cost of a messy PR that no one wants to review.

Physically, he was ready. He’s tall for his age, and the metrics suggested he could handle the 24-inch wheels. But as any Tech Lead knows, just because the hardware supports the requirements doesn’t mean the operator is ready to push to production.

The System Architecture: Specialized Hotrock 24

In this migration, the hardware selection was about finding the right Long Term Support (LTS) release. We skipped the 20-inch version entirely; in our roadmap, a 20-inch bike was a short-term patch that would only serve us for a year or two before hitting its end-of-life.

We went straight for the 24-inch platform as our LTS. To make this high-performance hardware compatible with a 5-year-old’s geometry, I chose the Hotrock for its low-slung frame—think of it as a compatibility layer or a “shim” that allows a smaller user to interface with a much larger system architecture.

The Debugging Phase: Staging Environment (Weekend 1)

We didn’t head straight for the trails. That would be like deploying a refactored monolith to 100% of users without a staging environment. We set up a 3x3 meter “Sandbox” in a parking lot to run our first integration tests.

1. The Look-Ahead Buffer (The Square)

The first bug we encountered was Visual Latency. He was looking at his front wheel—the equivalent of a system only processing the data packet currently in the buffer.

The Fix: I implemented a new algorithm. Start at Cone 1, look at Cone 2. When the front wheel enters the zone between 1 and 2, immediately point the sensors (eyes) toward Cone 3. We were teaching him to process future state while executing current operations.

2. The I/O Interrupt v1.0 (Stop-on-Line)

We tested the “Stop” command with a simple line. At this stage, we kept the requirements low: just execute a HALT command exactly on the line. He passed this test without issues—the braking interface was working, even if it was still a bit binary.

Scaling the System (Weekend 2)

Once the basic “Look-Ahead” logic was cached, we increased the complexity of our tests.

2.1 The I/O Interrupt v1.1 (The “No-Touch” Constraint)

We refactored the stop-and-go drill. Now, he had to stop on the line and then resume driving without touching the floor. This was about refining balance and power delivery—moving from a simple halt to a complex state transition.

3. The Slalom (Logic Branching)

Finally, we introduced the Slalom. This was a true logic-branching exercise: navigating a sequence of four cones. It required high-frequency adjustments to his trajectory based on the “Look-Ahead” data he was now successfully processing.

The “Merged PR”: Managing the Developer Experience (DX)

The first weekend wasn’t a “success” by pure performance metrics. He failed several drills, the “build” felt shaky, and the cones remained largely un-navigated.

But here is the most important log entry: He didn’t get frustrated. In my day job, when a Junior Developer (or an AI agent like Jules) struggles with a new stack, the worst thing a Tech Lead can do is demand they stay until midnight to “fix the build.” That is how you accrue Human Technical Debt—you might get the code merged today, but you’ve poisoned the developer’s relationship with the codebase for tomorrow.

By applying a “Freedom of Decision” protocol and capping sessions at 15 minutes, we prioritized the Developer Experience. Because I didn’t push, he didn’t associate the new hardware with stress. We maintained a high “morale-to-output” ratio, ensuring he was excited to “reboot” the training the following weekend.

The Feature: By the end of the second weekend, something clicked. It wasn’t about completing the drills perfectly—it was about the feel. The “Look-Ahead” algorithm was finally running in the background, and he started to feel comfortable on the new hardware.

The Post-Deployment Cleanup: Ownership

The real sign that the migration was a success came after the training was over. Without being asked, he started cleaning the bike himself.

In engineering, we call this Full-Cycle Ownership. It’s the moment a developer stops just writing code and starts caring about the health of the system they operate. Seeing a 5-year-old wipe down his own “hardware” after a successful sprint in the sandbox is the ultimate proof of engagement. He wasn’t just using the tool; he was owning it.

The Log:

• Hardware: Specialized Hotrock 24 (LTS Migration).

• Total Training Time: Two 15-minute sprints.

• Bugs Fixed: Visual Latency (Front-wheel staring).

• Post-Deployment: Automatic system maintenance (he cleaned the bike).

• Emotional ROI: High. The goal isn't to go fast on day one—it's to make sure that when we finally hit the trails, the pilot feels like the system belongs to him.

In many legacy projects, the build is “Green,” the tests pass, and the console shows no errors. Yet, the moment the application hits production, it fails. The culprit is often a “Lying Test”—a suite that passes not because the code works, but because the errors have been carefully hidden, logged to a void, or suppressed by a generic catch-all block.

How do you turn a “politely silent” codebase into one that fails loudly enough to be fixed?

The ‘Before’ State: Setting the Context

In older Java applications (circa 2005), error handling was often synonymous with e.printStackTrace(). Developers used manual main() methods or early JUnit versions to “test” logic. When an exception occurred, the instinct was to keep the process running at all costs.

The “old way” of testing often looked like this:

• The Silent Swallow: Generic catch (Exception e) blocks that log a message but do not rethrow or signal failure.

• Exit Code 0: Build scripts (Ant) that encounter a runtime error but still report a successful exit code, tricking the developer into thinking everything is fine.

• Manual Verification: Tests that require a human to read the console output to see if it “looks right,” rather than asserting a specific outcome.

Introducing the Core Concept: Honest Testing

Honest Testing is the process of stripping away the “safety blankets” of legacy error handling to force the application to Crash Loudly.

What is it? It is a “Hardening Phase” where you replace swallowed exceptions with meaningful failures and migrate manual checks to automated assertions.

Why does it matter? You cannot refactor code you do not understand. If your tests are lying to you about the state of the system, any “improvement” you make is just a guess. Making the build RED is the first step toward making it truly GREEN.

Practical Applications & Use Cases

Use Case A: Exposing the Silent Swallow

The most common anti-pattern in legacy Java is the “Log and Forget” block. We must convert these into loud failures during the testing phase.

// BEFORE: The Lying Code
public void storeData() {
    try {
        // critical logic
    } catch (Exception e) {
        System.out.println("Error happened, but let's keep going!");
    }
}

// AFTER: Honest Code for Testing
public void storeData() {
    try {
        // critical logic
    } catch (Exception e) {
        // Re-throwing as a RuntimeException forces the test to fail
        throw new RuntimeException("Hardened Failure: Data storage failed", e);
    }
}

Benefit: The test suite will now immediately catch failures that were previously invisible.

Use Case B: From main() to JUnit 5

Legacy projects often have “test” classes that are just public static void main(String[] args) methods. These don’t integrate with CI/CD.

// Migrating to JUnit 5 Assertions
@Test
void testBackendConnection() {
    Backend b = new Backend("qbert.guba.com");
    // Instead of printing to console, we assert the state
    assertDoesNotThrow(() -> b.connect(), "Connection should be stable");
    assertNotNull(b.getStatus(), "Status should be initialized");
}

Benefit: Provides a quantifiable “Safety Net” that build tools like Gradle can interpret as a Pass/Fail signal.

Common Pitfalls & Misconceptions

The “Fear of Red” Pitfall: Many teams are terrified of a broken build. They think that if the build turns red, they’ve failed.

The Truth: In legacy refactoring, a Red Build is a victory. It means you’ve finally found the boundaries of the system. You’ve moved from “unknown-unknowns” to “known-knowns.” Don’t rush to fix the red; use it as a map to find where the code is truly broken.

Core Trade-offs & Nuances

• The “Crash” Period: When you start hardening tests, the project might not compile or pass for days. This requires stakeholder buy-in—you are breaking the “illusion of stability” to find the “reality of the debt.”

• Log Noise: Hardening exceptions often results in massive stack traces in your logs. This is necessary labor; you have to clean the noise to find the signals.

Forward-Looking Conclusion

A “Green Build” is only valuable if it is earned. By removing the “Silent Swallows” from your legacy Java project, you are performing a diagnostic surgery. It is painful, and it reveals the rot, but it is the only way to heal the codebase.

Once your tests are honest, you can finally apply modern AI tools and refactoring patterns with confidence. You aren’t just “hacking” anymore; you are Engineering.

Ever tried to migrate a massive, stateful legacy system to a new cloud region with zero downtime? That was my life in 2024. But here’s the thing about technical debt: it follows you.

My “Legacy System” wasn’t the physical tools—I’d sold those off before leaving Israel. The debt was in my head. My experience as a consultant in a small local MTB shop in Saint-Petersburg fifteen years ago had programmed me with a “pro-shop” bias. When we lived in Israel, I acted on that bias and built a monolith: a massive toolset, a wheel balancing stand, the works. It was classic Over-engineering.

Now, standing in my garage in Spain with two Merida Big Nine 60s and my son’s Specialized Hotrock 24, I realized I didn’t need to rebuild the data center. I needed to refactor for efficiency. I needed a modular set of microservices.

The “System Architecture”: A Modular Toolchain

Instead of a “buy-it-all” approach, I’ve decoupled the maintenance into three high-performance modules.

1. Edge Computing: The “On-The-Trail” Kit

This is for high-availability fixes. If this service fails, the “user” (my oldest son) has a total system crash 5km from the trailhead. I’ve packed this “payload” into a SKYSPER 20L backpack, organized in Zip-lock bags for modular access:

• The Processor: Crankbrothers M17 multi-tool.

• Error Handling: KMC Missing Links (9 and 7-speed) + 2x Pedro’s or Park Tool tire levers.

• Redundancy: Kenda tubes (29x2.2 and 24x1.95) + Park Tool GP-2 pre-glued patches.

• Hardware Peripherals: hand pump with manometer + 2x small microfiber towels (Dirty/Clean).

• On-the-fly Patches: Small 60ml Finish Line Dry Lube + a travel-size Teflon spray (MO-94/GT85).

2. Maintenance Scripts: The “Dry-Clean” Routine

Think of this as your cron jobs. It runs weekly to prevent system degradation. Here is the deployment logic:

1. Mechanical Cleaning: Back-pedal the chain through a dry rag to remove “big” grit.

2. Rinse (Optional): If you hear “sand grinding” in the gears, flush it with water.

3. Stanchion Wipe: Clean the shiny bits of the fork with a dedicated rag.

4. The Teflon Interface (Conditional Logic):

   • if (no_rinse): Spray Teflon onto a rag (not the bike) to wipe the chain/bolts.

   • else if (rinse_performed): Protect the brakes and spray Teflon directly onto the chain for water displacement.

5. The Wipe-Down: Use that Teflon-soaked rag to wipe the chain and bolt heads. This microscopic film stops the Spanish salt air from “bit-rotting” your hardware.

6. Re-Lube: Apply Finish Line Dry Lube to the rollers.

7. Final Wipe: Wait 60 seconds for penetration, then wipe off excess.

3. Core Infrastructure: The “Yearly Service”

This is the “bare metal” hardware needed for the deep dives.

• Health Monitoring: A Chain Wear Indicator. If it hits 0.75, the chain is “deprecated” and needs replacement.

• The Interface: A thin-profile 15mm Pedal Wrench. You can’t hack this with a standard DIY wrench.

• Environment Setup: A Floor-to-Frame Stand. I found one for €30 on Vinted—a small investment for a massive increase in “developer comfort.”

• JIT (Just-In-Time) Dependencies: Specialized tools like the Cassette Lockring Tool and Cable Cutters are in the “backlog.” I won’t buy them until the specific part needs a “version upgrade.”

The Bonus: “Season Deep Clean” (System Integrity Audit)

Once a season, we need more than a script; we need a full System Audit. This is where we check for “memory leaks” and hardware degradation.

The Audit Kit

• Garbage Collector: Bio-Degreaser (Finish Line EcoTech).

• The “Gherkin” Brush: A drivetrain detail brush with a “claw” for digging out grit.

• Linter Tool: Chain Wear Indicator.

The Protocol

1. Pre-Wash & Degrease: Remove the mud, then spray degreaser on the gears. Let the “Garbage Collector” run for 3 minutes.

2. Scrub & Rinse: Use the “Gherkin” claw to dig out grit. Rinse with low-pressure water.

3. Water Displacement: While wet, spray Teflon on the chain, bolts, and derailleur springs to prevent oxidation.

4. Dry: Use a microfiber towel. Crucial: If the chain isn’t dry, your lube won’t “deploy” correctly into the metal.

5. Re-Lubrication: Apply one drop of Line Dry Lube to each roller on the inside of the chain while back-pedaling.

6. The Wipe-Down: Wait 60 seconds for the lube to soak into the “inner pins.” Then, use a clean rag to wipe off the excess. The chain should be lubricated on the inside, but dry to the touch on the outside to prevent sand from sticking to the surface.

The Health Check (Static Analysis)

• Dependency Check: Use the Chain Wear Indicator. If it hits 0.75, the chain is deprecated—replace it.

• Brake Validation: Check for 1mm thickness. Safety is a non-negotiable fail-safe.

• Indexing: Shift through all gears. If it “clicks,” adjust the barrel adjuster by 0.5 turns (like fine-tuning a config file).

• Cable Integrity: Look for “blooming” silver wires. If a cable is untwisting, it’s about to crash. If shifting is “crunchy,” the cable is “dragging” in the housing—likely a rust/dirt bottleneck.

• Load Balancing: Spin the wheels. If they wobble >3mm, they need balancing (truing).

The Debugging Phase: Ego vs. Reality

The biggest “bug” I encountered was my own Professional Ego. Because I worked in that shop in Saint-Petersburg and maintained a “perfect” setup in Israel, I felt like a “junior” by not having every professional tool immediately.

I had to debug that thought process. In software, we call this YAGNI (You Ain’t Gonna Need It). For a Merida Big Nine 60, I can “debug” a wobbly wheel by watching it against the frame. I don’t need a $300 truing stand to verify a fix.

The real challenge is Onboarding the Junior Dev (my son). When his Hotrock 24 starts “clicking,” the latency between my coaching cue and his execution is high. Keeping his bike “clean” via these scripts reduces the “noise” in his learning process. A smooth drivetrain is just a better UI for a kid.

The “Merged PR”: Log Summary

The “monolith” workshop is officially decommissioned. It’s been replaced by a streamlined, purpose-built kit, neatly “containerized” in Zip-lock bags within a single backpack.

• Status: Healthy.

• Packaging: All trail tools isolated in Zip-locks for weatherproofing.

• Uptime: All family bikes are 100% operational.

• Backlog: Need to keep an eye on the brake pads; we’re approaching a “major version” update there.

How do you convince a digital “antique” that it’s still living in 2005?

The ‘Before’ State: Setting the Context

In the early days of Java development, “Environment Variables” and “Configuration as Code” were often ignored in favor of hardcoded assumptions. Developers wrote code that relied on:

• Static Network Topologies: Hardcoded hostnames in .properties files or even inside .class files.

• Personalized File Paths: Logic that pointed to /Users/ericlambrecht/data, making the code physically impossible to run on any other machine.

• Specific Hardware Quirks: Reliance on the way Intel processors handled certain operations, which breaks on modern ARM-based chips like Apple’s M-series.

The “old way” to fix this was a massive refactoring effort to externalize configuration. But when you have thousands of lines of “spaghetti” code, you risk introducing more bugs than you fix.

Introducing the Core Concept: Environment Emulation

Environment Emulation is the practice of using containerization to recreate a specific historical “reality” for your application. Instead of changing the code to fit the modern world, you change the world to fit the code.

What is it? It’s a “Time Capsule” strategy where Docker mimics the network, filesystem, and CPU architecture the application expects.

Why does it matter? It allows you to achieve a “Green Start” without touching a single line of legacy business logic. By stabilizing the environment first, you can verify that the code can work before you begin the dangerous work of refactoring it.

Practical Applications & Use Cases

Use Case A: Network Trickery (Docker Aliases)

If your legacy code is hardcoded to look for qbert.guba.com, you don’t need to hunt through the source code. You can use Docker’s network aliases to point that “ghost” hostname to a local container or a mock service.

# docker-compose.yml
services:
  legacy-app:
    image: my-ancient-app:latest
    networks:
      backend:
        aliases:
          - qbert.guba.com  # The app thinks it found its long-lost server
networks:
  backend:

Benefit: The application connects successfully without any code changes or /etc/hosts hacking on your host machine.

Use Case B: Filesystem Mimicry (Volume Mapping)

When code is locked to a specific path like /Users/eric/data, Docker volumes can “teleport” your modern project directory into that exact location inside the container.

docker run -v $(pwd)/data:/Users/ericlambrecht/data my-legacy-java-app

Benefit: You satisfy hardcoded file requirements immediately, allowing the app to boot and pass its initial I/O checks.

Use Case C: Hardware Realities (x86 on ARM)

Older binaries or specific versions of the JVM (like early Java 6 or 8 builds) may behave unpredictably on Apple Silicon (ARM64). You can force Docker to emulate the original Intel environment.

# Specify the platform to ensure 100% compatibility with legacy binaries
FROM --platform=linux/amd64 eclipse-temurin:8-jdk

Benefit: Eliminates subtle “Heisenbugs” caused by CPU architecture differences.

Common Pitfalls & Misconceptions

The "Config-First" Trap: Many engineers think they must "clean up" the configuration files before they can run the app in Docker.

The Fix: Don’t clean. Emulate. Use Docker to satisfy the app’s current (even if “ugly”) requirements. Once you have a running, testable container, you can then refactor the configuration into modern environment variables as a second, safer step.

Core Trade-offs & Nuances

• The “Magic” Burden: Environment emulation can feel like “magic” to new developers. If the docker-compose.yml isn’t well-documented, a newcomer won’t understand why the app is looking for a server that doesn’t exist.

• Performance: Running x86 images on ARM64 via emulation (QEMU) is slower than native execution. This is acceptable for refactoring and testing, but may not be ideal for high-performance production needs.

Forward-Looking Conclusion

Modernization is an act of engineering, not just coding. By using Docker as a “Time Machine,” you stop fighting the environment and start observing the application’s actual behavior.

Once the “Time Capsule” is built, you have achieved the ultimate goal of the software archaeologist: Reproducibility. From here, you can move forward with confidence, knowing that any changes you make to the code are being tested against a stable, predictable reality.

The ‘Before’ State: Setting the Context

In the early 2000s, Apache Ant was the industry standard. It was purely imperative: you wrote a “script” telling the computer exactly how to delete folders, copy files, and compile classes.

The problem isn’t just the age of the tool; it’s the lack of lifecycle. Unlike Maven or Gradle, Ant has no built-in concept of a “test” phase or a “package” phase unless someone manually scripted them. For many legacy projects, this resulted in a build process that is fragile, hard to replicate in CI/CD, and completely disconnected from modern dependency management.

Introducing the Core Concept: The Tooling Strangler

The Tooling Strangler applies the Strangler Fig pattern to your build infrastructure. Instead of attempting a “Big Bang” migration where you delete Ant and spend a week debugging a new Gradle script, you wrap the old logic.

What is it? Using Gradle’s ant.importBuild, you surface your legacy Ant targets as native Gradle tasks.

Why does it matter? It allows you to move to a modern CLI immediately. You get the benefits of the Gradle Wrapper (./gradlew), advanced caching, and build scans, while the actual heavy lifting is still performed by the original, proven Ant logic.

Practical Applications & Use Cases

Use Case A: The “Wrapper” Migration

By importing the build, you can start adding modern features (like dependency management) around the old Ant tasks without changing the Ant file itself.

// build.gradle
// Import the existing Ant logic
ant.importBuild 'build.xml'

// Add a modern dependency that Ant didn't know about
dependencies {
    implementation 'org.slf4j:slf4j-api:1.7.36'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.9.1'
}

// "Hook" a modern task into an old Ant target
tasks.named('compile') {
    doLast {
        println "Ant finished compiling. Gradle is now verifying the output..."
    }
}

Benefit: Risk-free modernization. Your build stays “green” throughout the entire transition.

Use Case B: The 7.6 “Goldilocks” Version

In my experiments, I found that Gradle 7.6 is the specific “sweet spot” for this work. Why?

1. JDK 8 Compatibility: It is the last major version that runs its own background processes (the daemon) natively on Java 8.

2. Modern Features: It still supports the latest JUnit 5 platforms and Docker-ready plugins.

3. The Bridge: It allows you to bridge the gap between a 2005 build logic and a 2026 deployment pipeline.

Common Pitfalls & Misconceptions

The "Pure Gradle" Obsession: A common mistake is trying to make the build.gradle file "perfect" from day one. Developers often get stuck trying to replicate a weird Ant copy task in Gradle's DSL.

The Fix: If the Ant task works, leave it in Ant. Use the Strangler Fig approach: only move tasks to Gradle when you actually need to change their logic or improve their performance.

Core Trade-offs & Nuances

• Dual Maintenance: For a period, you have both build.xml and build.gradle. You must treat the Gradle file as the new “entry point” for the team.

• Mindset Shift: You are moving from a “Scripting” mindset (Ant) to a “Task Graph” mindset (Gradle). Understanding how tasks depend on one another is more important than knowing the syntax.

Forward-Looking Conclusion

Modernizing a build system doesn’t require a “demolition and rebuild.” By using Gradle 7.6 as a wrapper for your legacy Ant scripts, you buy yourself the most valuable asset in refactoring: time. You get the project into a modern CI/CD pipeline on day one. Once the build is stabilized and automated, you can “strangle” the remaining Ant targets at your own pace.

How do you modernize a system that is too old to run, but too critical to fail?

The ‘Before’ State: Setting the Context

In the world of “Software Archaeology,” we often encounter projects stuck in the mid-2000s. These applications are often:

• Compiler-Locked: They rely on syntax (like certain raw-type configurations) that modern JDKs (11, 17, 21) simply won’t compile anymore.

• Environment-Fragile: They only “work on Bob’s machine” because Bob has a specific 2008-era Intel laptop and a prehistoric version of the JDK.

• Tooling-Limited: They use Ant or early Maven versions that don’t understand modern CI/CD pipelines or containerization.

The “old way” of fixing this was the Big Bang Migration: a grueling six-month rewrite where you try to jump 15 years of evolution in one go. Most of these attempts end in failure, reverted commits, and exhausted teams.

Introducing the Core Concept: The Golden Bridge

The Golden Bridge methodology uses Java 8 not as a final destination, but as a strategic "Field Hospital." What is it? It is the practice of migrating ancient code (Java 1.4 - 1.6) specifically to Java 8 first, rather than the current LTS.
Why does it matter? Java 8 sits at a unique historical intersection. It is the “Last of the Ancients” and the “First of the Moderns.” It provides a stable environment where you can fix the internal architecture of the code without the external environment fighting you.

How does it work?

1. Dual-Compatibility: It supports the -source 1.5 flag to compile ancient syntax while allowing you to use modern IDEs.

2. Architecture Neutrality: It is the first version that runs natively on Apple Silicon (ARM64) via Zulu or Temurin builds, ending the reliance on old hardware.

3. Tooling Support: It is fully supported by Gradle 7.6, which acts as the "Strangler Fig" for old Ant builds.

Practical Applications & Use Cases

Use Case A: Compiling the “Uncompilable”

Modern JDKs have removed many internal APIs and tightened the rules on source compatibility. Java 8 allows you to keep the old code running while you transition the build system.

// In your build.gradle, you can target the past while living in the present
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(8)
    }
}

Benefit: You get a green build in hours, not weeks.

Use Case B: The Docker “Time Machine”

By using Java 8, you can create a Docker image that mirrors the production environment exactly, but runs on a 2024 MacBook.

FROM eclipse-temurin:8-jdk
# Map the 20-year-old hardcoded file paths to modern volumes
VOLUME /Users/original_dev/data:/data 
COPY . /app
WORKDIR /app
CMD ["ant", "test"]

Benefit: Eliminates “Works on my machine” bugs immediately.

Common Pitfalls & Misconceptions

The "Destination" Trap: The biggest mistake is thinking that moving to Java 8 is "enough."

Java 8 is a bridge, not a home. If you stay there, you are still accumulating technical debt. The goal of the Golden Bridge is to get the code clean enough (removing raw types, fixing tests) so that the jump to Java 17 or 21 becomes a simple compiler flag change rather than a structural nightmare.

Core Trade-offs & Nuances

• The Cost: You have to maintain a specific legacy toolchain (like Gradle 7.6) because the newest versions of build tools have dropped support for Java 8.

• The Mindset: You must resist the urge to use Java 8 features (like Streams or Optionals) immediately. Your first goal is stabilization, not modernization. Adding new syntax to a “muddy” codebase only makes the archaeology harder.

Forward-Looking Conclusion

Java 8 is the unique “Goldilocks” zone of the Java ecosystem. It’s old enough to understand where the code came from, and modern enough to work with the tools of today.

By treating Java 8 as your Golden Bridge, you turn a high-risk “archaeological dig” into a controlled engineering project. Use it to stabilize your build, containerize your environment, and harden your tests. Once the mud is washed away, the path to Java 21 will be wide open.

We often sell AI adoption to our bosses (and ourselves) with the promise of speed. We imagine a future where we toss a vague request over the wall—”fix the build,” “export the data,” “optimize the query”—and the AI handles the rest while we grab a coffee.

But my recent experiments with Jules, Google’s new AI agent, suggest the opposite is true. The more “autonomy” I gave the AI, the more mediocre the code became. This leads to an uncomfortable question: Does effective AI delegation actually require more management overhead, not less?

2. Context & Tools

I’ve been experimenting with Jules, testing its ability to act as a “Junior Developer” in my Spring Boot repository, joyofenergy-java.

In my previous explorations, I looked at Pair-Authoring with an AI and the Context Window Paradox. This time, I wanted to test the difference between Abdication (lazy delegation) and Navigation (structured delegation) when asking an agent to build a feature from scratch.

3. The Failed Experiment: The “Friday Afternoon” Prompt

I set up a scenario we’ve all faced: It’s Friday afternoon, I want a new feature shipped, and I don’t want to think about the implementation details.

I gave Jules the “Lazy Manager” prompt:

“Jules, create an endpoint to export meter readings as a CSV file. Use the existing MeterReadingService.”

I intentionally withheld constraints. I didn’t mention memory usage, libraries, or formatting.

The Result?

Technically, it worked. Jules created a CsvService, updated the controller, and passed the tests. But structurally, it was a time-bomb.

• Memory Unsafety: It loaded the entire dataset into a List in memory before writing the response. For a smart meter with 100,000 readings, this is an OutOfMemoryError waiting to happen.

• Library Bloat: It generated a new service class (CsvService) where a simple stream in the controller would have sufficed.

• Junior Mistakes: It used standard Java formatting without considering how a user would actually open the file in Excel.

The “lazy” prompt produced “lazy” code: functional, but dangerous at scale. It validated my fear that More Powerful AI Doesn’t Always Mean Faster Fixes.

4. Principles That Actually Work: The “Brief”

I reset the experiment. This time, I treated Jules like a Senior Engineer would treat a Junior: I wrote a spec.

I uploaded a file named feature-csv-export.md containing strict constraints:

1. No New Dependencies: Do not add apache-commons or opencsv.

2. Memory Safety: Do not load lists into memory; stream directly to the HttpServletResponse.

3. Strict Formatting: Use yyyy-MM-dd HH:mm.

I then prompted:

“Jules, I’ve uploaded a spec file... Please refactor the implementation to strictly follow these constraints.”

The Outcome:

The difference was night and day.

• Architectural Safety: Jules implemented a streaming solution using PrintWriter, avoiding the memory bottleneck entirely.

• Dependency Management: It correctly added jakarta.servlet-api as a compileOnly dependency, respecting the “no runtime bloat” rule.

• Test Integrity: It initially failed to test the controller response correctly, but because I had defined the “correct” output in the spec, I could guide it to fix the assertion logic.

5. Unexpected Discovery: The “Spec” as a Guardrail

The most surprising insight was that Jules didn’t just follow the instructions—it used the spec file as a defense mechanism against bad code.

When I ran the “Lazy” experiment, Jules defaulted to the path of least resistance (loading data into memory). When I provided the “Brief,” Jules shifted behavior entirely. It didn’t just write code; it navigated the constraints.

This confirms a theory I touched on in Can We Make AI Code Assistants Smarter by Asking Them to Write Their Own Rules? The AI performs best not when it has “creative freedom,” but when it is boxed in by rigid technical constraints. The “Senior Engineer” input wasn’t the code I wrote, but the boundaries I set.

6. The Central Paradox

This brings us to the Delegation Paradox:

To get an AI agent to work autonomously, you must micromanage the requirements.

If you want to be “lazy” during the implementation phase (execution), you must be hyper-active during the definition phase (specification). You cannot abdicate both.

• Abdication (Vague prompt) -> Requires heavy code review and refactoring later.

• Navigation (Detailed spec) -> Requires heavy upfront thought, but produces near-production-ready code.

We aren’t thinking less with AI; we are shifting when we think.

7. Forward-Looking Conclusion

Tools like Jules are shifting the developer’s role from “writer of code” to “architect of constraints.”

If you treat your AI agent like a magic wand that reads your mind, you will build technical debt at record speeds. But if you treat it like a talented but literal-minded junior developer who needs a solid brief, it becomes a powerful force multiplier.

The future of engineering isn’t about writing the perfect function; it’s about writing the perfect spec.

Recently, some colleagues pitched me an idea: “Today, LLMs are so powerful, you can start exactly from implementation and it will work well. No need to use TDD or other more complicated XP techniques”.

It is a tempting thought. If an AI can generate a complete feature in seconds, is my approach—always start from a test—still relevant?.

I decided to check it. I ran an experiment to see if I could implement a complex feature by describing the task and letting GenAI create the application. My hypothesis was that TDD is still vital, but I wanted to see if the “Just Do It” method could prove me wrong.

The result? I confirmed exactly what I expected: TDD is one of the best ways to create context for an LLM.

Personal Context & Tools

For this experiment, I returned to a project I started in a previous article: “Does AI Need Clear Goals? My Experiment in Turning Vague Ideas into Code”.

My tool of choice was GPT-4.1 (via GitHub Copilot), utilizing its Agent mode to handle multi-file context. Usually, I treat the AI as a pair programmer, following structured collaboration methods I’ve discussed in “Pair-Authoring with an AI: A Case Study in Structured Collaboration”.

But for this session, I acted as a “manager,” giving requirements and approving plans, but explicitly skipping the “Red” phase of TDD. I let the AI write the code first.

The Failed Experiment

The task was Story #2346: Implement a “Day of Week Pricing Plan”. The requirements were clear: users needed to compare power usage costs based on the day of the week and rank price plans accordingly.

I approved the AI’s plan and let it generate the implementation. Here is where the “No TDD” approach started to show its cracks.

1. The “Ghost Method” Problem After the AI implemented the service layer, my IDE lit up with errors. The AI used a method getDayOfWeekMultiplier(DayOfWeek) that didn’t exist. It “hallucinated” a method on the domain object because it was writing the service in isolation. I am usually fine with “Red” code, but this wasn’t TDD “Red”—this was just broken code requiring immediate fixes.

2. The Regression Nightmare When we fixed the missing method, we broke the existing logic.

PricePlanTest > shouldReceiveMultipleExceptionalDateTimes() FAILED

Because we implemented the new logic over the old logic without a guiding test, the AI introduced regressions. We had to do several iterations just to get back to a baseline.

3. The Context Disconnect The real struggle happened during Functional Testing. I asked the AI to verify the endpoints. It generated a test that tried to hit the API, but it returned a 404 Not Found. Why? The AI created a test that queried a Smart Meter ID, but “it didn’t have a context!”. It forgot that in this application, a Smart Meter must be linked to a Price Plan via the AccountService first. The AI tried to guess the solution, attempting to call an API /account/link/{smart-metter-id} that didn’t even exist.

Principles That Actually Work

I eventually finished the task without TDD, but it required multiple rollbacks and context corrections. Through this struggle, I confirmed why TDD works:

Principle 1: Tests Are Context Anchors The reason the AI failed the functional test setup was a lack of context. If I had written the test first, I would have been forced to set up the AccountService association immediately. The failing test provides the AI with a strict “Context Window” of what is required, as I explored in “The Context Window Paradox”.

Principle 2: Small Steps Prevent “Imagination” When the AI doesn’t have enough context, it tries to imagine the answer. TDD forces small, verifiable steps. By skipping the test, I forced the AI to generate a large chunk of logic (Controller + Service) at once, increasing the surface area for hallucinations.

Unexpected Discovery

The most painful part of skipping TDD wasn’t the coding—it was the debugging.

When I finally added tests after the implementation to verify the logic, one failed with a confusing error:

Expecting actual: {FRIDAY=[...]} to contain key: MONDAY

This revealed a critical weakness of the “Test After” approach. When a test fails, you don’t know where the problem is: “In the tests or in the business logic.”. It turned out to be an error in the test data (the date provided was a Friday, not Monday). If I had written the test first, the AI would have generated the implementation based on that test data. We wouldn’t have had this problem at all.

The Central Paradox

We tend to think that as AI gets smarter, we can think less. I touched on this in “Can We Think Less with AI?”.

But this experiment confirmed a paradox: To move faster with AI, you must slow down enough to write the test.

Can we avoid the loops of small context errors? Yes. TDD reduces complexity and creates trust between us and the AI . The test acts as a contract. Without it, you are just hoping the AI guesses your architectural constraints correctly.

Forward-Looking Conclusion

So, can we skip TDD? Yes, but you will spend more time adding additional context manually.

The power of TDD is approaching a new peak in the AI era: tests create a POWERFUL CONTEXT for LLMs. Modern models like GPT-4 are powerful, but “better LLM, not exclude context from that function”.

If you want to get the most out of your AI teammate, don’t just ask it to write code. Give it a failing test.

Does that reality sound familiar?

When faced with this, we have two main choices. One way is to create tech debt, a task we’ll never really get to because we will always have more urgent priorities from the business. The other way was shown in the foundational book, Refactoring by Kent Beck and Martin Fowler. This path treats refactoring as a continuous action, not a tech debt item in the backlog.

But if we choose to refactor continuously, what does that really mean, and are our tools helping or hurting?

My Context and the “Easy” Button

Working in a Java/Kotlin environment, my tool of choice is IntelliJ IDEA. It’s an incredibly powerful IDE with a host of features designed to help.

When facing a 200-line monster method, the most obvious solution is right in the refactoring menu: “Extract Method”. It seems perfect. It makes the original method smaller, which is exactly what I want.

Right?

Introducing the Core Concept: Readability-Driven Refactoring

The main goal of refactoring shouldn’t just be “smaller methods.” For me, the main goals are readability and, secondarily, decoupling.

In fact, readability is arguably more important than adhering to a specific architecture or design pattern. While good architecture often improves readability, it’s not its primary goal. If I have a choice between perfect pattern adherence and readability, I will prefer readability. Working on a typical web application, it’s readability that helps me daily when I look at different parts of the code.

This is where the simple “Extract Method” tool falls short. It often just moves the mess, failing to improve readability.

A more powerful technique for guiding this process is Test-Driven Development (TDD). Instead of just extracting code, we use TDD to describe our expectations for the new, refactored code before we write it. This small shift in process fundamentally changes the quality of the refactoring.

Practical Application: A TDD-Led Refactoring

Let’s look at a practical example.

The Problem Code

Imagine we have this block of code in a method. It’s searching for properties, then mapping them to calculate Avios points, with error handling mixed in .

summaries =
    shc
    .psSearch(
        startDate = startDate,
        nights = nights,
        hotelCodes = it,
        adults = adultsParam,
        children = childrenParam,
        infants = infantsParam,
    ).toTypedArray()
    .mapNotNull { tbh ->
        kotlin
            .runCatching {
                aviosEarn = aviosAdapter.calculateAviosEarn(BigDecimal(tbh.summary!!.totalPrice!!))
                tbh.toAccommodationSummary(aviosEarn)
            }.onFailure { e ->
                SASAdapter.Companion.log.warn("Skipping", e)
            }
            .getOrNull()
    }.toList()

Common Pitfall: The ‘Extract Method’ Trap

If we use the “Extract Method” feature in our IDE, we get this:

Original method:

summaries = requestSummariesAndCalculateAviosEarn(startDate, nights, it, adultsParam, childrenParam, infantsParam)

New private method:

private fun requestSummariesAndCalculateAviosEarn(
    startDate: LocalDate,
    nights: Int,
    it: List<String>,
    adultsParam: String,
    childrenParam: String,
    infantsParam: String,
): List<AccommodationSummary> =
    shc
        .psSearch(
            startDate = startDate,
            nights = nights,
            hotelCodes = it,
            adults = adultsParam,
            children = childrenParam,
            infants = infantsParam,
        ).toTypedArray()
        .mapNotNull { tbh ->
            calculateAviosEarnAndMapToAccommodationSummary(tbh)
        }.toList()

private fun calculateAviosEarnAndMapToAccommodationSummary(tbh: TBH): AccommodationSummary? {
    var aviosEarn: Int 
    return runCatching { 
        aviosEarn =
            aviosAdapter.calculateAviosEarn(BigDecimal(tbh.summary!!.totalPrice!!)) 
        tbh.toAccommodationSummary(aviosEarn) 
    }.onFailure { e -> 
        log.warn(”Skipping”, e) 
    }
        .getOrNull() 
}

Is this good? Not exactly. It makes the original method smaller, but it doesn’t improve readability. We’ve just created a new private method that takes a mess of parameters.

The Better Way: The TDD-Led Flow

Instead of using the IDE tool, let’s use the TDD technique.

1. Describe Expectations: We start by writing a test for the logic we want to have. We don’t want to just test a private method; this logic feels like it belongs in its own service.

2. Define the “To-Be” Service: We’ll create a test for a new SummaryAdapter. At first, this service is “red” (it doesn’t exist).

3. Discover the Parameter Problem: As we write the test and describe the method we want to call, we see the problem clearly: it needs too many parameters.

4. The Solution: The test itself shows us what we need. Instead of passing 6 individual parameters, we should pass a single SearchCriteria object. We define this object as an expectation of our test.

5. Implement: We now implement the new service, moving the logic from the old method.

The Result:

By extracting the logic to a new service and passing a parameter object, the original code now looks like this:

summaries = SummaryAdapter.requestSummariesAndCalculateAviosEarn(searchCriteria, it)

Did we improve readability? Yes. And not just because the method is smaller, but because we are no longer passing an excessive number of parameters, as we were with the simple “Extract Method”.

A Technique Over a Tool

IDE tools are wonderful, and techniques like TDD are powerful.

Of course, we could have used the IDE tools to change the method signature, create a new class, and move the method there. What the tool can’t do is help us understand what we want to do in the first place. We can’t describe our expectations to the tool.

TDD gives us that option: we describe our expectations before the work. This key difference is what truly changes the quality of our refactoring.

By knowing different techniques, we can understand when and which tool to use. Don’t let the tool lead the refactoring; let your technique guide the tool.

But what if your job isn’t to execute a clear task, but to find the task?

In my current work, we do a lot of research. Goals are not clear. We receive highly abstract, one-sentence ideas that need to be explored. This research is a necessary, messy process of discovery, and it’s full of “boilerplate” actions.

This got me thinking. We assume AI is for execution, but can we use it for exploration? What happens when you feed an AI a problem that you, the engineer, don’t even fully understand yet?

I ran an experiment to find out, starting with nothing but a single, vague sentence.

My Setup: From Vague Idea to Boilerplate

My goal was to see if I could use Generative AI to shepherd a “one-sentence idea” all the way to a foundational, runnable piece of code.

My toolkit was straightforward:

• The Idea: A vague user story, “#2348: As an administrator I want to add a new tariff so that it can be advertised to users who may benefit”. This was perfect because it was so vague—what’s a “tariff”? How is it “advertised”?

• The “Analyst” AI: I used Gemini 2.5 Pro to act as a Product Owner and flesh out this vague idea.

• The “Developer” AI: I then used GitHub Copilot (CPT 4.1) in IntelliJ to write the boilerplate code.

• The Project: All this was done in the context of TW “Joy of Energy” project, a Java Spring Boot application.

The plan was a two-part workflow:

1. Part 1: AI as Business Analyst. Feed the vague story to Gemini and ask it to define the requirement.

2. Part 2: AI as Boilerplate Generator. Feed the AI-generated spec to Copilot and ask it to write the code.

The Failed Experiment (That Was Actually a Success)

My first attempts were a perfect illustration of the “AI is context-blind” problem. The “failure” wasn’t that the AI was useless; it’s that its first drafts were wrong in very specific, instructive ways.

Failure 1: The AI “Product Owner” Became a Tech Lead I asked Gemini to act as a Product Owner and flesh out the story . It made a “very popular mistake”: it skipped the “what” and “why” and jumped straight to the “how.”

The very first draft of the spec it gave me wasn’t a user story; it was a technical task. It immediately suggested a JPA @Entity and defined fields like id as a UUID. It was already designing the database schema.

This is exactly what you don’t want from a user story, and it’s a common trap where the AI tries to be the engineer, not the analyst. As I’ve written before, the AI’s job is to reflect our needs, not just give us a technical answer (you can read more on that idea here: How GenAI Helps Engineers Write Better).

I had to intervene, critique the output, and explicitly ask it to “Change database to more abstract system” to get the clean, implementation-agnostic user story and Acceptance Criteria (ACs) I actually needed .

Failure 2: The AI “Developer” Was a Clumsy New Hire After I had a clean spec, I gave it to GitHub Copilot with a clear prompt: generate a POJO, an in-memory Service, and a Controller .

The code it generated was not “copy-paste and run”.

• Wrong Package Structure: It invented a “by-feature” package structure (com.joi.energy.tariff). My project uses a “by-layer” structure (uk.tw.energy.domain, uk.tw.energy.service, etc.) .

• Missing Dependencies: It correctly suggested using jakarta.validation annotations —a great idea!—but my project didn’t have that dependency.

• Minor (Human) Errors: It even forgot the @Service annotation on the TariffService, a simple mistake I’ve made myself a dozen times.

If I were a junior engineer, I would have been blocked or, worse, just pasted it all in, breaking the project’s architecture.

Principles That Actually Work

These “failures” led me to the real principles of using AI for this kind of work.

1. The AI is a “Demultiplicator,” Not a Supercharger This was my single most important insight. A supercharger just makes the engine spin faster. A demultiplicator (like a reduction gear) changes the nature of the work, trading raw speed for torque.

The AI is a demultiplicator for my brain.

When I was iterating on the user story, I didn’t think about “how to write these words or if it sounds good”. I was 100% focused on the business goals. The AI handled the typing, and I handled the validating. This is a profound shift. It took me 30 minutes to get a solid user story, not because I typed fast, but because I thought fast, using the AI’s draft as a disposable starting point.

2. The Engineer’s New Job: Strategist and Context-Provider The AI’s mistakes weren’t stupid; they were context-blind. This reveals the engineer’s true role in an AI-augmented workflow: we are the “Reviewer and Strategist”.

My job wasn’t to write getters and setters. My job was to make two high-level strategic decisions:

1. “The AI is right, jakarta.validation is a good idea. I will add that dependency”.

2. “The AI is wrong about the package structure. I will correct it to follow our existing pattern”.

The AI’s “flawed” draft actually forced me to think strategically about my project’s architecture and dependencies.

3. Embrace the “90% Win” and the Iterative Loop The AI’s output doesn’t need to be 100% perfect to be valuable. The boilerplate it generated, despite its flaws, was a “90% win”. It saved me from the “boring boilerplate” and the hours I would have spent on Stack Overflow as a junior engineer.

More importantly, the AI’s mistakes are part of the value. That wrong package structure? It’s a great “recommendation for reorganizing your project” and a perfect topic to bring to a team huddle.

My Unexpected Discovery: “1:0 to AI”

The most surprising moment came during the boilerplate generation. I asked for three files (POJO, Service, Controller). The AI gave me four.

It proactively and correctly created a TariffType.java Enum (FLAT_RATE, TIME_OF_USE).

This was a perfect “micro-improvement”. I called it “1:0 to AI”. I was so focused on the “big picture” of the architecture that I missed this small, obvious detail. This “separating of responsibilities” is incredibly powerful : the AI handles the small details while I focus on the larger strategic goals.

The Central Paradox: AI’s Flaws Are Its Greatest Strength

This leads to the central paradox: The AI is terrible at handling vague, abstract ideas... and yet, it’s the best tool I have for the job.

Why? Because its value isn’t in giving you the right answer. Its value is in its ability to instantly turn a “blank page” into a flawed, tangible draft that you can critique.

The AI’s initial, flawed responses—the over-technical user story, the context-blind package structure—are its most valuable feature. They act as a mirror, forcing the engineer to define the context and make the strategic decisions. It can’t read your mind, so it forces you to figure out what’s in it.

Effective use doesn’t require a perfect prompt. It requires an engineer to stop acting like a typist and start acting like an editor, a critic, and a strategist.

Conclusion: From Vague to Validated

The AI didn’t solve my vague problem. It gave me the tools to solve it myself, faster and at a higher level of abstraction.

By delegating the “boring boiler plate code” , I was able to stay focused on the “big picture” and “business needs”. This workflow is a powerful way to accelerate research, allowing us to build, test, and throw away foundational ideas at a speed we couldn’t before.

The AI isn’t here to replace us. It’s here to take the routine work and free us to focus on the hard parts. It’s a “demultiplicator” that gives us the torque to move from a one-sentence idea to a validated, runnable foundation —flaws and all.

The initial results were promising. The AI produced working code that passed our tests. But then, our instincts as seasoned developers kicked in. We saw the AI’s implementation—a simple Map<String, Object>—and reflexively identified it as a “code smell”. We spent the next hour trying to refactor it into a “cleaner,” more object-oriented design using the Composite pattern.

That’s when we fell into a trap. Our pursuit of clean code was leading us toward a solution that was elegant, sophisticated, and completely wrong. This led us to our second major discovery: In AI-augmented development, the biggest risk isn’t bad AI code, but good human intuition applied to the wrong problem.

Our Setup: Aiming for a Bigger Step

Our team remained the same: I (Nik) acted as the driver for GitHub Copilot, while Javier served as the strategic navigator. Having stabilized our Java, Spring Boot, and Gradle environment in the last session, we were ready to test a new hypothesis: if we write strong, expectation-focused tests, we can trust the AI with a larger implementation scope and move much faster.

The flow was simple:

1. Human engineers write a small, focused test with clear assertions.

2. Let the AI generate the implementation code in a single, larger step to make the test pass.

3. Trust the tests to validate the AI’s work, rather than meticulously reviewing every line of generated code.

The Failed Experiment: Refactoring into a Corner

The first part of the experiment worked. We added two tests for our hierarchy API, one for a root-only employee and one for a simple employee-supervisor relationship. We then prompted the AI: “tests looks good, let’s make postHierarchy method for passing all of them”.

The AI’s implementation worked, save for one minor edge case we quickly fixed. But we weren’t satisfied. The code returned a Map<String, Object>, and our developer brains screamed for type safety and better design.

1. The “Code Smell” Diagnosis: We prompted the AI with our concern: “maybe, response object will make the readability of the code better and will reduce smell of code?”. This initiated a refactoring plan to introduce a dedicated HierarchyNode class.

2. Applying a Design Pattern: We pushed further, suggesting a more formal structure: “maybe we can apply composite pattern... to our response?”. The goal was to create a pure, object-oriented hierarchy and eliminate the Map entirely.

3. The Collision with Reality: Our final prompt revealed the fatal flaw in our logic: “can we avoid to use Map if we will use Spring Boot which we have in our project?”.

The AI’s response was the turning point. It patiently explained that given our requirement for dynamic JSON keys (e.g., “Jonas”: { “Sophie”: ... }), a Map or a structure that serializes like one was unavoidable with Spring Boot and its default Jackson serializer.

We had spent a significant part of our session chasing an elegant design that was fundamentally incompatible with the constraints of our framework and the explicit requirements of the kata. As I noted in my log, “we spend time trying to add something not workable to the code”. The AI’s initial, simpler solution wasn’t a code smell; it was the correct, pragmatic solution from the start.

Principles That Actually Work

This humbling experience confirmed our new hypothesis and revealed principles for a more effective human-AI workflow.

1. Focus on “What,” Not “How” (Test-Focused Development). Our initial strategy was correct. The most valuable role for the human developers is to define the behavior of the system through precise, comprehensive tests. When we focused on the expected JSON output, the AI produced correct code. When we focused on our preconceived notions of “good” internal implementation, we wasted time. The tests are the contract; the AI’s job is to fulfill it.

2. The AI is a Mirror for System Constraints. The AI is more than a code generator; it’s an interactive expert on the toolchain. It didn’t just reject our idea; it explained why it wouldn’t work within the Spring Boot ecosystem. This prevented us from going further down a dead-end path. Use the AI not just to write code, but to validate your architectural assumptions against the framework’s reality.

3. Codify Your Learnings into the System. A failed experiment is only a waste if you don’t learn from it. The most productive outcome of our refactoring dead-end was updating our .github/copilot-instructions.md file. We added an explicit refactoring protocol and guidance on when to challenge the AI’s use of patterns versus accepting framework constraints. This turns a session’s lesson into a permanent upgrade for the trio’s workflow.

Unexpected Discovery: AI Generalizes from Specifics

After our refactoring detour, we returned to our Test-Focused workflow. We added much more complex tests, including one with multiple employees reporting to the same supervisor and another with a full four-level hierarchy.

The surprising part? The AI’s existing implementation passed these complex tests without any modifications. This revealed a powerful insight: the AI is remarkably good at generalizing a solution. It needed a few simple, specific test cases to establish the core logic. Once that logic was in place, it was robust enough to handle more complex scenarios automatically. The “big step” works, but it needs to be built on a foundation of small, clear examples.

The Central Paradox of AI-Driven Speed

This leads to the central paradox we uncovered in this session: To move faster with big, AI-generated implementation steps, you must first slow down and write smaller, more precise human-guided tests.

Our desire for speed was not at odds with the discipline of TDD; it was enabled by it. The quality of the AI’s large-scale contribution was directly proportional to the quality of the small-scale expectations we defined. You cannot achieve reliable speed by simply telling the AI “build this feature.” You achieve it by saying “build something that satisfies these very specific, verifiable behaviors.”

Conclusion: We Are Architects of Behavior, Not Just Code

Our second session was a success, but not because we wrote code faster. It was a success because we learned how to trust our tests more than our own implementation habits. The “Test-Focused Development” rhythm—small tests by humans, big implementation by AI—feels right.

The dynamic is shifting. Our job is becoming less about crafting the perfect implementation and more about architecting the perfect set of expectations. We define the contract with rigorous tests, and the AI, our tireless third programmer, finds the most direct way to fulfill it—even if it’s not the way we would have written it ourselves.

Instead, we spent almost the entire session without writing a single line of business logic. The AI wrote plenty of code, but it was all in service of fixing a development environment that kept breaking. This led us to a counterintuitive conclusion: adding an AI to the team doesn’t accelerate feature development, it brutally exposes foundational weaknesses in your environment and workflow.

Our Setup: An Experiment in Trio Programming

Our team consisted of myself (Nik) acting as the “driver”—the one interacting directly with the AI—and my colleague Javier as the “navigator,” providing high-level direction and quality control. Our third programmer was GitHub Copilot, guided by a detailed set of custom instructions emphasizing a strict Test-Driven Development (TDD) cycle, small incremental changes, and explicit permissions before writing any code.

The plan was to tackle the “Hierarchy Kata” —a REST API for managing an employee hierarchy—using a pure stack: Core Java, JUnit 5, and Gradle. We wanted to keep things simple and avoid framework magic.

The Experiment That Failed: A Cascade of Configuration Errors

Our first mistake was idealism. We started with Core Java to avoid frameworks, but quickly realized the sheer amount of boilerplate needed for a simple REST endpoint was distracting us from the actual kata. We pivoted.

“Let’s delegate that work to Spring,” we decided, thinking it would get us back on track. This is where the real trouble began. Our session devolved into a frustrating, iterative battle with our own setup, guided by an AI that was helpful but lacked strategic oversight.

1. Missing Dependencies: We asked Copilot to generate a test for a Spring Boot controller. It correctly produced a test using @WebMvcTest and MockMvc . But when we ran ./gradlew build, the build failed spectacularly with dozens of cannot find symbol and package does not exist errors . Our build.gradle file had JUnit, but none of the required Spring Boot test dependencies.

2. Incorrect Dependency Configuration: We then asked Copilot to fix our Gradle file. It suggested adding the Spring dependencies, but the first attempt failed because we hadn’t defined a version number, leading to a Could not find org.springframework.boot:spring-boot-starter-web:. error . The next fix involved adding the dependencies to the subprojects block in our root build.gradle, as they weren’t being inherited by the kata’s module. Each step was a tiny, painful discovery.

3. Classpath and Package Structure Hell: After fixing the build file, the errors persisted. The problem? Our test file, HelloWorldControllerTest.java, was in src/main/java instead of src/test/java. The test dependencies weren’t on the main classpath. Once we moved it, we hit yet another wall: Unable to find a @SpringBootConfiguration. Our test in the com.kata.hierarchy package couldn’t find the main application class located in com.example.helloworld because of how Spring’s component scanning works.

The entire session was a cycle of: ask for code, watch the build fail, feed the error log back to the AI, and apply the suggested micro-fix. We weren’t programming; we were performing highly-structured, AI-assisted debugging on our own environment.

Principles That Actually Work

This frustrating experience revealed three principles that are critical for effective AI-augmented development.

1. The Environment is Non-Negotiable. An unstable or poorly understood development environment will completely derail any attempt at Trio Programming. The AI can suggest fixes, but it can’t reason about your setup holistically. Before you can ask an AI to write a feature, the entire team—humans and AI—must operate on a rock-solid foundation where builds, tests, and dependencies are flawless.

2. Human Navigation is Paramount. The session would have been a total failure without a human navigator. Javier’s role was crucial for steering the ship. He spotted issues in prompts, provided strategic direction (”let’s put it in a new package” ), and kept the focus on the larger goal while I was in the weeds prompting the AI. As I noted in my log, “Speak, not only think - it’s a very strong pattern”. The AI is a powerful tool, but it needs a human strategist to be effective.

3. Treat the AI as a System, Not Just a Coder. We started by giving the AI rules for writing code (TDD, small steps). But the real value came from using it as a diagnostic tool for a complex system that included our code, our build tool, and our framework. The prompts that worked best weren’t “implement this feature,” but rather “here is an error log, diagnose the problem and propose a minimal fix”.

The Unexpected Discovery: The AI Reshapes Human Roles

The most surprising insight was how the AI’s presence changed our own roles. My job as the “driver” became less about writing code and more about prompt engineering and AI flow control. I was focused on translating our navigator’s intent into precise instructions and context for the AI.

Javier’s “navigator” role expanded from guiding the code’s logic to managing the overall strategy and quality controlling both my prompts and the AI’s output. This division of labor was incredibly effective. Having one person focused on the high-level goal while the other managed the human-AI interface prevented us from getting stuck. The AI didn’t just add a third programmer; it created a new, more specialized dynamic between the two human programmers.

The Central Paradox of AI Collaboration

Herein lies the paradox: The goal of using an AI is to abstract away complexity, but its immediate effect is to surface hidden complexities you’ve been ignoring.

We thought we had a working Java setup. But the AI, by trying to follow our commands precisely and rapidly, immediately ran into every single flaw in our Gradle configuration and package structure. A human programmer might have found these issues slowly over time. The AI found them all at once, forcing a full stop.

Effective use of an AI programmer therefore requires:

• An impeccably configured and automated development environment.

• Deep human expertise in the underlying tools (Gradle, Spring), as the AI’s suggestions still need validation.

• A workflow where humans provide strategic intent, not just tactical instructions.

Conclusion: Build Your Pipeline Before You Start the Assembly Line

Our first Trio Programming session felt slow and, at times, unproductive. We wanted to build an API, but we ended up building a robust, multi-module Spring Boot Gradle configuration. But as Javier aptly put it, this process is like building a good CI/CD pipeline: it “reduces the price of mistakes” and gives you the confidence “to move forward faster”.

The lesson is clear. You can’t just drop an AI into an existing workflow and expect a productivity boost. You must first use the AI to stress-test and harden your foundations. The initial time investment is not spent on writing features, but on creating an environment so solid that the AI can finally be unleashed on the work you actually want it to do. We ended the day in a much safer, more robust place, ready for the real work to begin.

This article cuts through the noise to explain the core mechanics of Generative AI. We'll explore how these models "think," where they fail, and provide a set of practical heuristics for applying them in our work.

The 'Before' State: From Hard-Coded Rules to Learned Patterns

To understand today's Generative AI, we have to look at its conceptual ancestors. The original dream of Artificial Intelligence (beginning in the 1950s) was about logic and explicit rules. The idea was to encode expert knowledge into a series of IF <condition> THEN <action> statements. This approach is far from obsolete; it’s still the backbone of many complex systems.

For example, I previously worked on a phishing detection team at a global cybersecurity company, where our core detection engine was a sophisticated, rule-based AI. We analyzed an email’s characteristics, and if the combined weighted score of all rules triggered a threshold, we marked it as malicious. That was our production system.

The first major evolution of this paradigm was Machine Learning (ML), which gained traction in the 1980s. Instead of engineers hand-crafting every rule, we could feed a system massive amounts of data and let it discover the patterns on its own. We don't tell a spam filter every possible suspicious word; we show it thousands of examples, and it learns the statistical characteristics of spam. These two ideas—rules and learning—are often used together. Our plan at the cybersecurity company was to layer ML on top of our rule engine to automatically spot new threats, rather than waiting for an engineer to write a new rule.

Introducing the Core Concept: Generative AI

The next leap came with Deep Learning in the 2010s, a type of ML that uses complex, multi-layered "neural networks" to find incredibly subtle patterns in data. This is the technology that powered the huge advances we saw in image recognition and speech-to-text.

That brings us to today's breakthrough: Generative AI.

• What is it? Generative AI takes powerful Deep Learning models and flips their function. Instead of just recognizing patterns (e.g., "this image contains a cat"), it uses its understanding of those patterns to create new, original content (e.g., "generate a picture of a cat"). Large Language Models are a prime example of this capability.

• Why does it matter? The impact is massive because an estimated 80% of the world's data is unstructured text—emails, documents, support tickets, etc. LLMs are the first technology that can both process and generate human language at scale, creating a new human-computer interface where we can use natural language to express intent.

• How does it work? At its core, an LLM is a sophisticated pattern-matching machine built on a technology called the Transformer architecture. Its fundamental job is surprisingly simple: to predict the most statistically probable next word in a sequence. It's essentially a very powerful autocomplete. To do this, it relies on two key concepts:

  1. Tokens: The model doesn't see words; it sees "tokens". Text is broken down into these building blocks—which can be words, parts of words, or punctuation. For example, Generative AI is powerful might become ["Gener", "ative", " AI", " is", " powerful"]. A model's limits and API costs are all measured in tokens.

  2. The Context Window: This is the model's short-term memory. LLMs are stateless; they don't truly "remember" past conversations. With each prompt, the application sends the entire conversation history back to the model. This entire block of text must fit within the context window, which has a fixed token limit (e.g., 8k or 128k). If a conversation gets too long, the oldest messages are dropped, which is why the model seems to "forget" what was said earlier.

Practical Applications: Choosing the Right Tool for the Job

Different LLMs are trained with different goals, giving them unique strengths. Choosing the right one is a key engineering decision. The following list is not exhaustive, but it reflects the tools my team and I rely on for our daily work.

The main model families you'll encounter are:

1. OpenAI's GPT Series (GPT-4o, etc.): Best known as a powerful all-rounder, excelling at tasks requiring strong logical reasoning and complex code generation. This is often the go-to for debugging a tricky algorithm or scaffolding a new service.

2. Anthropic's Claude Series (Claude 3.5 Sonnet, etc.): Built with a heavy emphasis on safety and "Constitutional AI". Claude often produces more careful, nuanced writing and is a great choice for tasks like drafting detailed technical documentation or analyzing sensitive user feedback where tone and safety are paramount.

3. Google's Gemini Series (Gemini 1.5 Pro & Flash): This family offers a trade-off. Gemini Pro is the high-power version focused on top-tier reasoning and advanced multi-modal capabilities. Its sibling, Gemini Flash, is optimized for speed and cost-efficiency, making it ideal for high-volume, lower-complexity tasks like chatbots or data extraction where low latency is critical.

Common Pitfalls & Misconceptions

The architecture of LLMs leads to two fundamental limitations that every user must understand.

1. Hallucinations: Plausible vs. Truthful

Because an LLM's only job is to predict the next most probable token, it is optimized to generate text that is plausible, not text that is factually true. It has no internal knowledge base or concept of truth. If you ask it to find sources for a claim, it will generate a list of references that looks perfect—with authors, titles, and journals that fit the pattern—but the sources themselves may be completely fabricated.

How to avoid it: Be professionally skeptical. Treat all outputs as a first draft. Always verify facts, test all code, and check any sources it provides.

2. The Black Box Problem: Why vs. What

We can make an LLM's output deterministic by setting a parameter called "temperature" to zero, meaning it will give the same output for the same input every time. So we can see what it did. However, we can't see why it chose one token over another in a way that is humanly understandable. The decision is a result of calculations across billions of parameters, not a logical decision tree we can audit.

Why it matters: This makes it nearly impossible to debug why a model gives a strange answer. In high-stakes domains like finance or healthcare, it's difficult to trust a system when there is no transparent reasoning path.

Core Trade-offs: Free vs. Paid Models

The difference between free and paid AI tools is not just about features; it's about the entire engine. The primary trade-off is cost vs. capability.

• Underlying Model: Free tiers typically use older, smaller, and less powerful models. Paid tiers give you access to the flagship models.

• Context Window: Paid models have much larger context windows (e.g., 128k+ tokens vs. 4k-16k), allowing you to work with larger documents and maintain longer conversations.

• Reasoning Ability: Premium models are significantly better at following complex, multi-step instructions. Less capable models are more prone to "laziness"—giving simplified answers, writing placeholder code, or telling you to do it yourself.

For simple tasks, a free model may suffice. For complex development work, the limitations of a less capable model can become a significant bottleneck.

Conclusion: 4 Heuristics for Using AI Responsibly

Generative AI is a powerful tool, not magic. Understanding its mechanism—next-token prediction within a limited context window—is key to using it well. To ensure we are using these tools in a safe, effective, and responsible way, our team should always ask four questions before starting a task:

1. Do we have permission? Is the use of AI approved for this task by both the client and our company's policies? This is a non-negotiable first step.

2. Are we exposing sensitive data? Does the prompt contain any client secrets, personal information, or confidential data? The answer must be no.

3. How will we verify the output? What is our strategy for human review and testing? Whether it's a peer code review or a QA testing plan, a verification process is essential.

4. Is this the right tool for the job? Is the model's speed, cost, and capability a good fit for this task? This is about making a deliberate engineering trade-off.

By embracing professional skepticism and applying these simple heuristics, we can move beyond the hype and begin using Generative AI as what it is: a powerful, imperfect, but profoundly useful new tool in our professional toolkit.

I recently spent time experimenting with Google's Jules, an AI agent designed to operate with a high degree of autonomy. The initial assumption was that I could delegate a series of tasks to a "senior" AI, provide it with a well-documented repository and clear instructions, and expect efficient execution. The experiment, however, surfaced a different, more nuanced reality about the operational model required to work effectively with today's AI agents.

My plan was to partition the work for a new project, jules-foundation, in a collaborative way:

• Backend: Fully delegated to Jules.

• CI/CD: I would initiate the setup, and Jules would continue it.

• Frontend: A "ping-pong" approach where Jules would start, I would take over for a task using VSCode and GitHub Copilot, and then hand it back.

This process was underpinned by a detailed AGENTS.md file, which codified principles from foundational software engineering texts to guide the agent's behavior. The results were illuminating, but not for the reasons I expected.

The Experiment's Stumbles

The initial attempts at delegation quickly ran into issues that revealed the agent's limitations, not in its ability to write code, but in its judgment and awareness of context.

1. The Hallucinating Generalist

In the very first backend task—setting up a Kotlin and Micronaut project—Jules briefly defaulted to a completely different stack, attempting to implement the solution using Python and Poetry. It seemed to fall back on its generalized training data, where Python is a common choice for initial project setups. To its credit, the agent caught its own mistake and asked for confirmation before proceeding, but it was a stark reminder that even with specific instructions, the agent can be swayed by the statistical weight of its training data. It behaves like a junior developer who has a lot of theoretical knowledge but lacks the experience to apply it consistently in a specific context.

2. The Context Pollution Problem

My most significant error was continuing with the frontend task (Task 3) in the same chat I used for the backend (Task 1). After the first task was completed and merged, the main branch of the repository was updated. However, Jules, operating within its isolated chat context, was working off a stale version of the repository.

When asked to proceed, its lack of environmental awareness became clear. It stated: "I do not have a direct git pull command. My process is to complete the work and then use submit to propose the changes." Its proposed solution was to start over, re-implementing both the backend and frontend tasks from scratch. This demonstrated that long-running conversations spanning multiple, distinct tasks are unworkable. The context from previous work pollutes the agent's understanding of the current state.

3. The Over-Eager Assistant

During the frontend task, the instructions specified using simple HTML, Tailwind CSS, and Alpine.js, with Vite mentioned as an optional tool. Jules immediately planned to set up a full Vite project, concluding this was "the most professional and efficient way to approach this task." While a reasonable conclusion for a human engineer, it was a deviation from the core requirement of simplicity. It prioritized an optimized solution over adhering to the task's constraints, forcing me to update the AGENTS.md file with a strict "Technology Constraint Mandate" to prevent such deviations.

An Effective Operating Model

Through these failures, a more effective workflow emerged. It centered on providing a rigid, well-defined operational framework rather than relying on the agent's "senior" judgment.

1. One Task, One Context

The git pull fiasco taught me the most important lesson: every new task requires a new, clean context. The effective workflow is atomic and mirrors standard development practice:

1. Start a new "Jules task" for each new GitHub issue.

2. Provide the prompt, linking to the repository and the specific issue.

3. Let the agent fork the current main branch, implement the changes, and submit a pull request.

4. Review, merge, and close the task.

5. Repeat from step 1 for the next issue.

This approach prevents context pollution and also mitigates the risk of git conflicts, as the agent is never in a position where it needs to reconcile its work with other changes made in parallel. The tasks must be designed to be sequential and independent.

2. Define the Goal, Not Every Step

My most successful interaction was with the first task, where the goal was clear and concise: "Create a Kotlin-based Micronaut application with a single GET endpoint that returns 'Hello, World!'." I didn't over-specify the steps, which allowed the agent to complete the task in just 7 minutes.

In contrast, my more prescriptive frontend task created blind spots. By trying to detail the steps, I inadvertently omitted small but crucial details, leading to initial friction. The key is to provide a clear objective and firm constraints but grant the agent the autonomy to handle the implementation details within those boundaries.

3. The "Rules" Are the Scaffolding

The foundational AGENTS.md file, which summarized core software engineering principles, was critical. Much like a well-crafted context can steer GitHub Copilot's suggestions, these initial instructions act as a firm scaffolding for the agent's behavior. When failures occurred, I didn't just correct the agent in the chat; I updated the foundational rules. This ensures the learning is persistent and benefits all future tasks.

Unexpected Discovery: Simulating a Workflow

A fascinating insight was how to enforce quality gates without giving the agent direct access to our environment. Jules can't run a pre-commit hook, but it can be instructed to simulate one.

I created a "Pre-Flight Simulation" mandate in the rules. Before submitting code, the agent must:

1. Analyze the project's pre-commit configuration files.

2. Mentally review its generated code against every check defined in those files.

3. Provide a report confirming it performed the simulation.

This approach improves code quality and reduces the cost of failed CI runs by shifting quality checks earlier in the process, even if only in simulation.

The Core Insight: Constraints Unlock Autonomy

This leads to the core realization: to unlock the autonomy of an AI agent, you must constrain it with a rigid, machine-readable process.

You can't treat it like a senior engineer with whom you can have a nuanced conversation. You have to manage it like a brilliant, lightning-fast, but utterly naive junior developer. It needs a "manager" to provide:

• A Clear Definition of Done: The GitHub issue.

• Strict Rules of Engagement: The AGENTS.md file.

• An Isolated Work Environment: A new task for each new unit of work.

The agent's value isn't in its judgment or experience, but in its speed and its ability to flawlessly execute a well-defined process within a tightly controlled environment.

Conclusion: We Are Becoming Architects of AI Workflows

My experiment with Jules was a success, though not in the way I initially envisioned. The true leverage of these tools isn't just in code generation—it's in automating a workflow.

The real engineering work is shifting from pure implementation to architecting the system of rules, constraints, and processes that guide the AI. This has implications beyond just how developers work. It elevates the importance of the Business Analyst function, as creating well-defined, atomized, and unambiguous tasks is now a prerequisite for effective AI delegation. We must not only learn new skills for interacting with AI but also adapt our entire development workflow to match the capabilities of these new tools. The future isn't about replacing developers but about providing them with powerful new forms of leverage, provided we are willing to become the architects and managers of our new AI team members.

My Setup: The Final Polish

Our environment was standard: a React codebase, a Git workflow with peer reviews, and an integrated AI coding assistant. My goal was to rapidly work through a backlog of minor UI tickets. Any UI update is a form of refactoring, and for that, I strictly follow a philosophy of making changes in what Javi López aptly calls "a lot of tiny steps," a pattern also known in classic terms as Refactoring In Very Small Steps. This ensures each commit is atomic and easy for my teammates to review. I was relying on the AI’s "Agent mode"—its capability to autonomously modify the codebase—expecting it to align with this micro-step approach. The reality was quite different.

When 'Help' Became a Hindrance

The core problem was that the AI agent consistently over-engineered solutions for trivial problems. It treated every request for a small change as an invitation to refactor the entire component. This isn't a failure of intelligence, but a misalignment of goals: my goal was a minimal diff, whereas the agent's goal is often holistic file correctness, aiming to fix all potential issues it identifies in one pass. Crucially, even when I gave it explicit, TDD-style instructions to only perform a single, minimal action, it still defaulted to making broad, sweeping changes.

Example 1: A Simple CSS Tweak

I needed to make a submit button full-width on mobile devices. A straightforward task.

The fix that was actually needed:

CSS

@media (max-width: 50rem) {
  .formSubmitMobileWrapper button {
    width: 100%;
  }
}

I prompted the AI agent: "Only add a new media query for screens under 50rem to the .formSubmitMobileWrapper button class to set its width to 100%. Do not touch any other code."

Despite the clear instruction, the agent generated a massive diff, rewriting existing desktop styles and restructuring the entire CSS class.

• Time Wasted: I spent 15 minutes untangling the AI's suggestion, versus the 2 minutes it would have taken to write the CSS myself.

• Quality Issues: The generated code created a high cognitive load for code review. A teammate would have to ask, "Why did we refactor all the button styles just to change one mobile property?"

• Structural Problems: This approach created bloated commits, making our Git history noisy and directly violating the "very small steps" principle.

Example 2: A Minor Accessibility Improvement

Next, I picked up a ticket to improve the accessibility of our card components. Again, I gave a precise instruction: "Add a role='region' attribute to the parent div of the Card component."

Instead of a one-line change, the agent tried to rewrite half the component's JSX structure, arguing it was for "better semantic clarity" and completely ignoring my focused instruction.

Principles That Actually Work

This friction forced me to re-evaluate how I was using the tool. I realized the key is to match the tool's capability to the task's scope. This led me to two guiding principles.

1. Use AI Chat for Suggestions, Not Implementation

For micro-changes, the AI's "Chat mode" is far more effective. By treating it as a context-aware search engine, I can ask for targeted advice.

• Prompt: "What's the best CSS to make this button full-width on mobile?"

• Result: It gives me the precise, minimal code snippet I need. I copy, paste, and commit. The change is atomic and review is trivial.

This keeps the developer in control and prevents the AI from making unsolicited "improvements." The benefits are clear: smaller pull requests and faster review cycles. This aligns with research from Faros AI, which notes that while AI can boost individual developer throughput, it often leads to ballooning review queues. I've written more about this in my article, "Can we make AI code assistants smarter?".

2. Reserve AI Agents for Scaffolding and True Refactoring

The autonomous "Agent mode" is incredibly powerful, but its strength lies in larger, well-defined tasks, not surgical strikes.

• Good use case: "Create a new React component for a user profile page with an avatar, name, and bio section. Include Storybook stories and a basic test."

• Bad use case: "Add a margin-top to the avatar in the user profile component."

Using an agent is best when the expected outcome is a significant amount of new or changed code.

This simple matrix illustrates the core principle: for small-scoped tasks, a suggestion-based AI interaction is most effective, while large-scoped tasks are better suited for autonomous AI execution.

Unexpected Discovery: AI Forced Me to Define "Small"

The most surprising insight was that the AI forced me to be more precise in defining a "small change." My heuristic is now this: if the task's description is longer than the code I expect to write, it will be good to use Chat mode.

A task like "Make the button full-width on mobile" is a perfect example. The description is simple, and the code is just a few lines. The AI agent, however, interprets this as a symptom of a larger problem ("This component is not fully responsive") and tries to solve that instead. This mental checkpoint prevents me from accidentally turning a 5-minute task into a 30-minute ordeal.

The Autonomy vs. Precision Trade-Off

This leads to a central, counterintuitive truth: the more autonomy you grant an AI coding assistant, the less precision you may get for small, targeted tasks.

This isn't a paradox; it's a trade-off. Autonomous agents are optimized for holistic correctness. They don't just see the three lines of CSS you want to add; they see the entire file and its potential imperfections. Their goal is to bring the whole file into a state of grace, which directly conflicts with the goal of making a minimal, targeted change.

Effective use, therefore, requires the developer to:

• Explicitly define the scope of the change before starting.

• Choose the right mode for the job (Chat vs. Agent).

• Maintain control and view the AI as a suggester, not an infallible executor, for routine work.

A More Thoughtful Partnership

My journey through pre-release UI tweaks taught me a crucial lesson. AI coding tools aren't a simple "on/off" switch for productivity. They are a suite of capabilities, each with an appropriate use case. An autonomous agent is a powerful ally for building new things from the ground up, but for the delicate art of finishing and polishing, a simple chat-based suggestion is often faster, cleaner, and more respectful of my teammates' time. The real skill in this new era of software development is not just in writing clever prompts, but in having the wisdom to choose the right tool for the job.

My Setup: Crafting a Presentation with an LLM

For this experiment, I set out to create a new slide deck, "Introduction to Agents," using Gemini 2.5 Pro as my authoring partner. My methodology is rooted in agile principles—starting with a high-level outline and iteratively building out the content. The goal is to offload the heavy lifting of drafting, allowing me to focus on the core narrative and technical accuracy.

I began with a highly structured initial prompt. This approach, refined from my previous work on pair-authoring with AI, was designed to establish clear rules of engagement for our collaboration from the start.

Hello,

I need your help preparing a presentation. Here is the context and the way I would like to work with you.

1. The Goal:
My objective is to create a [e.g., 15-minute] presentation for [e.g., the AI For Software Delivery festival]. The final output should be a complete script, ready to be put onto slides.

2. Source Materials:
Here are the links and documents you should use...

3. Our Workflow (How We Will Work):
We will follow a structured, step-by-step process. I want to approve each step before we move to the next.
  Step 1: High-Level Plan...
  Step 2: Section Planning...
  Step 3: Slide-by-Slide Drafting...
  Step 4: Finalizing Sections...

4. Content Structure (What I Want for Each Slide):
A) On-Slide Text: ... minimalist and concise.
B) Accompanying Speech: ... comprehensive and explain the concepts...

5. Tone and Style:
... Professional and Neutral ... Not Promotional...

Your First Task:
Please review the source materials I provided and propose a high-level outline for the presentation.

This prompt was my attempt to front-load the process with as much structure as possible.

The Subtle Failure of a Well-Laid Plan

Even with this detailed plan, I began noticing a subtle degradation in quality as our conversation grew longer. The failure wasn't catastrophic, but it manifested as a slow accumulation of small inconsistencies and extra work.

My chat history filled up with micro-corrections. At one point, the AI generated speech that claimed I worked at Thoughtworks on a project I had explicitly described from a previous job at Mimecast. The fix was a simple prompt:

fix for B) Accompanying Speech (Revised):
###
For example, I previously worked on a phishing detection team here at Thoughtworks.
@@@
I worked in Mimecast, not in Thoughtworks.
###

Other times, I had to refine the AI's understanding of the scope: We analyzed an email, not We'd analyze a URL. While individually minor, the frequency of these small edits increased as the context grew. The AI's attention seemed to drift, anchored more by recent turns in the conversation than by the foundational context we had established. The presentation began to feel less like a single, coherent story and more like a collection of loosely related talking points that required my constant, vigilant correction.

Principles That Actually Work

This experience led me to refine my approach, focusing on two principles that proved to be more effective.

1. Enforce a Disciplined Pace (Decompose and Verify)

My initial prompt already specified a slide-by-slide workflow. However, I discovered that I had to actively enforce this pace. At times, the AI would try to rush ahead, offering to generate multiple slides or an entire section at once. I learned to be firm, using prompts like always wait my approve and before we will move to section 2, combine all approved slides and speeches for section 1.

The key insight here was that it wasn't enough to state the plan; I had to actively rein in the AI's eagerness to generate. This forced discipline kept each unit of work small and verifiable. By confirming the correctness of each individual slide before moving on, I ensured the foundation for the next one was solid.

2. Proactively Distill the Context

This was the most impactful change. Acknowledging the limitations of the AI's attention, I began a practice of "proactive context distillation." After completing and approving a section, I would instruct the AI to summarize what we had just created.

"Excellent. Please summarize the content of the two slides we just created for Section 1 into a concise overview."

This technique serves two purposes. First, it acts as a "context refresher" for the AI, collapsing the detailed turn-by-turn history into a dense, high-signal summary. As explained by IBM, a context window isn't a perfect memory; a clean summary places the most important information front and center. Second, it keeps the most relevant information active, preventing the model's attention from being diluted by the noise of a long conversation.

An Interesting Realization: It’s For Me, Not Just the AI

Initially, I viewed context distillation as a trick to manage the AI. But a valuable realization was how much it improved my own thinking. The act of requesting and reviewing these summaries forced me to constantly re-evaluate the presentation's narrative arc. Was Section 2 a logical continuation of Section 1? Did the key messages connect?

This process mirrors what we know about human cognition. Our own working memory is limited. By creating these summaries, I wasn't just helping the AI; I was building a better mental model for myself. The distillation process became a forcing function for clarity, ensuring that I, the human author, remained in firm control of the narrative.

Closing the Loop: Refining the Process with the AI

After the presentation script was complete, I tried one final experiment. I asked the AI to become my process consultant.

"Now, analyze our chat for understanding our pattern of communication and work under the presentation. After that, check my initial prompt... Do we need to improve the original prompt or does it look good enough?"

The AI analyzed our entire interaction and proposed an improved V2 of my starting prompt. The new version added subtle but important clarifications, such as describing the process as iterative and flexible. This idea of having the tool refine its own operating instructions isn't new to my workflow; I'd explored a similar pattern when getting Copilot to improve its own rules. Applying it to a conversational authoring process, however, felt like a significant step forward. It’s a powerful demonstration of using the tool not just to execute a task, but to reflect on and improve the very process of collaboration itself.

The Central Paradox of AI Collaboration

This leads to the central, counterintuitive truth I discovered: To effectively leverage an AI's massive context window for a complex project, you must actively manage and constrain the context you provide it.

This paradox exists because a large context window is not a perfect memory. It is a probabilistic field of attention. Without deliberate guidance, the AI can get lost in the details, overweighting recent conversation turns and losing the foundational plot.

Effective use, therefore, requires more than just good prompting. It requires:

• Active Context Management: You must act as the session manager.

• Enforced Discipline: A structured, step-by-step pace that you actively maintain.

• Strategic Summarization: Periodically compressing the state of the project to maintain focus.

Conclusion: From Prompter to Director

Treating a generative AI as a simple instruction-follower for complex work is a path to mediocre results. The initial promise of "thinking less" is a mirage. Instead, these tools invite us to think differently.

The real leverage comes from shifting our role from a mere prompter to that of a director. Our job is not just to provide instructions but to manage the state, curate the context, and guide the narrative. By enforcing a disciplined pace, proactively distilling the context, and even using the AI to refine our methods, we don't just mitigate the tool's weaknesses; we sharpen our own thinking. The AI provides the immense power of generation, but human oversight provides the coherence and intent that turns raw output into a valuable, finished product. This collaborative dance is the future of knowledge work.

This experiment was a continuation of my explorations into AI-assisted development, but it led me somewhere unexpected. The attempt to create a "plug-and-play" expert failed, but the lessons learned revealed a far more effective and collaborative way of working with AI.

Personal Context & Tools

My daily workflow is centered in Visual Studio Code. The key players in this experiment were:

• GitHub Copilot: The core AI assistant, used in both inline and chat modes.

• Copilot Instructions Feature: The ability to provide custom guidance via a .vscode/copilot-instructions.md file.

• My Goal: To make Copilot's suggestions adhere to my project's specific coding standards without constant manual correction.

I typically follow a pragmatic approach to development, valuing consistency and clarity over dogmatic adherence to any single methodology. The goal was to codify this pragmatism into rules for my AI partner.

The Failed Experiment: The "Universal Rulebook" Fallacy

My hypothesis was simple: a good set of rules for one AI agent should be good for another. I had been using the Cursor editor with the popular awesome-cursorrules repository, and it worked well in that environment. The rules helped Cursor generate clean, consistent code. I assumed I could port this success over to GitHub Copilot in VS Code.

I copied a large chunk of these proven rules directly into my .vscode/copilot-instructions.md file. The result was a lesson in context. Rules are not universally portable.

1. Context-Blind Enforcement: Even on a relatively fresh project, the agent became overly aggressive. I had a rule like "Always use arrow functions for React components." While my project did use arrow functions, Copilot began to apply this rule with a sledgehammer, suggesting aggressive refactors on any function it encountered, often in ways that broke the subtle stylistic patterns my team had established. It lacked judgment, creating noise and unnecessary churn.

2. Verbose and Noisy Suggestions: Another rule I implemented was, "Ensure all functions are documented with detailed JSDoc comments." When I then asked Copilot to help with a simple utility function, the output was technically correct but practically absurd. An illustrative example would look something like this:

   TypeScript

/**
 * @param {string} str The string to capitalize.
 * @returns {string} The capitalized string.
 */
const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);

1. The documentation, forced by the rule, was longer than the code itself. This added cognitive overhead for simple, self-explanatory functions.

This approach abandoned the core idea of context-aware assistance. The specific negative outcomes were clear:

• Quality issues: The AI-generated code felt alien. It followed the new, transplanted rules but ignored the project's existing patterns, creating a maintenance headache.

• Impact on iteration: Instead of accelerating development, the rigid rule set became a bottleneck. It was like working with an overzealous assistant who had memorized a textbook but had zero practical field experience.

• Quantifiable problems: I spent more time fighting, deleting, or manually editing Copilot's "helpful" but misguided suggestions than I would have spent just writing the code myself. My flow state was constantly broken.

Principles That Actually Work

After deleting the entire instruction file in frustration, I started over. This time, I discovered a couple of principles that transformed the AI from a dogmatic rule-follower into a genuine collaborator.

1. Co-Author Your Instructions with the AI

Instead of pasting in a foreign set of rules, I used a built-in VS Code feature. In my empty .vscode/copilot-instructions.md file, I used the "Generate instructions..." command. Copilot analyzed the code in my current workspace and then proposed a set of instructions tailored to my project's reality.

It identified existing patterns and suggested rules to reinforce them. It was the complete opposite of my first experiment: instead of forcing my code to conform to the rules, the rules were generated to conform to my code. This aligns with the core tenets of Test-Driven Development (TDD), where the desired outcome (in this case, the existing code style) defines the path forward.

Benefit: The rules are organic, project-specific, and context-aware from day one.

2. Use the AI to Refine Its Own Instructions

My initial mistake was treating instructions as a static document. The effective approach is to make the AI itself a partner in refining them. My new workflow is a continuous, AI-driven feedback loop:

After a pairing session with the agent, I switch from the inline mode to the Copilot Chat view. There, I prompt it to perform a self-assessment:

"Analyze our recent conversation. Based on the guidance and corrections I provided, suggest improvements to my .vscode/copilot-instructions.md file."

The AI then reviews our interaction—including the times I had to give it procedural hints like "let's make a short overview before writing the code"—and suggests new, more effective rules. This delegates the work of refining the instructions to the tool that will be using them. It's a powerful and efficient way to make the AI a better collaborator over time.

Example: My Evolved Instruction File

After a few of these refinement cycles, my .vscode/copilot-instructions.md file started to look less like a generic style guide and more like a practical collaboration agreement. It's a living document, but here’s a snapshot of what it contains:

# AWS Serverless Infrastructure as Code Guidelines

This project implements a serverless application using AWS Lambda and API Gateway, with infrastructure defined in Terraform. Follow these guidelines when making changes:

## Project Architecture

### Component Structure

```
src/              # Lambda function implementations
├── hello_world.py     # Example Lambda handler
└── [other_functions]  # Additional Lambda functions
terraform/        # Infrastructure definition
├── modules/      # Reusable Terraform modules
└── main.tf       # Main infrastructure configuration
tests/           # Integration tests
└── test_api.py   # API endpoint tests
```

### Key Design Patterns

1. **Lambda Function Structure**:

   ```python
   # Standard Lambda handler pattern - follow this structure
   def lambda_handler(event, context):
       logger.info("Processing request")  # Always log entry
       # ... function logic ...
       return {
           'statusCode': 200,
           'body': json.dumps(result)
       }
   ```

2. **Terraform Module Usage**:
   ```hcl
   # Follow this pattern when adding new Lambda functions
   module "my_function" {
     source = "./modules/lambda"
     function_name = "<service>-<action>"
     source_file   = "../src/<filename>.py"
     handler       = "<filename>.lambda_handler"
     runtime       = "python3.9"
   }
   ```

## Code Quality Standards

- Write explicit, descriptive variable names over short, ambiguous ones
- Follow the existing project's coding style for consistency
- Use named constants instead of hardcoded values
  Example:

```python
# Good
MAX_API_RETRIES = 3
is_api_healthy = retry_count < MAX_API_RETRIES

# Avoid
m = 3
healthy = n < m
```

# Development Approach

- Don't invent changes beyond what's explicitly requested
- Follow security-first approach in all code modifications
- Don't modify files outside the requested scope
- Don't suggest improvements to files not mentioned in the task
  Example of focused scope:

```typescript
// Request: "Add email validation to User class"
// Good - only modifying requested file
class User {
  validateEmail(email: string): boolean {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
  }
}

// Avoid - suggesting changes to other files
// ❌ "We should also update UserRepository.ts"
// ❌ "Let's improve the existing validation in Utils.ts"
```

# Communication Style & Protocol

## Step-by-Step Communication Pattern

```
1. User Request
   User: "Need to implement email validation"

2. Copilot Overview
   Copilot: "Overview: Adding email validation
   - Will create test for invalid email (15 lines)
   - Will implement validator (20 lines)
   Let's start with the test?"

3. User Approval
   User: "Looks good"

4. Implementation
   Copilot: *provides code in proper format*

5. Confirmation
   User: "OK" or "Looks good"
```

# Test-Driven Development Workflow

## TDD Cycle

```
┌── 1. Discuss Test Requirements
│   User: "Need password validation"
│   Copilot: "Let's test minimum length first"
│
├── 2. Write Test (Red)
│   describe('PasswordValidator', () => {
│     it('requires minimum 8 characters', () => {...}
│   });
│
├── 3. Implement Code (Green)
│   class PasswordValidator {
│     isValid(password: string): boolean {...}
│   }
│
├── 4. Optional: Refactor
│   - Improve naming
│   - Remove duplication
│   - Enhance readability
│
└── 5. Next Test or Complete
    - User approval required before proceeding
```

### Testing Instructions

### Test Guidelines

- Write focused, single-purpose API integration tests
- Always use `get_api_url()` to fetch endpoints dynamically
- Test edge cases explicitly and include proper delays
- Use descriptive test names
  Example:

```python
# Good test names
def test_endpoint_returns_200_on_valid_input():
def test_endpoint_handles_empty_payload():
def test_endpoint_returns_404_on_invalid_path():

# Good patterns
def test_new_endpoint():
    api_url = get_api_url()
    time.sleep(5)  # Allow API Gateway to propagate
    response = requests.get(f"{api_url}/path")
    assert response.status_code == 200
    assert "expected_value" in response.text
```

### Running Tests

```bash
cd tests
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pytest -v
```

Unexpected Discovery: Guidance Trumps Raw Power

Here's the most surprising insight: a well-instructed GitHub Copilot, even using the standard (and technically free) models, consistently produces more useful, contextually-aware code than a more advanced model like Claude 3.5 Sonnet working without instructions.

The raw power of a cutting-edge LLM often leads to more "creative" but less relevant code for the specific task at hand. My carefully curated instruction set, running on a standard model, was simply a better pair programmer for my project.

Why this matters: It proves that effective AI assistance is less about the raw intelligence of the Large Language Model and more about the quality of the guidance you provide. Thoughtful engineering and context-setting can be more valuable than simply paying for a more powerful brain.

The Central Paradox: To Think Less, You Must First Think More

This leads to the central paradox of using AI assistants effectively: to offload cognitive work to an AI, you must first do the meta-cognitive work of codifying your own development philosophy and collaboration style.

You can't just install a tool and expect it to read your mind. This paradox exists because AI assistants are not colleagues; they are incredibly sophisticated pattern matchers. Without your explicit context, they will default to the most generic patterns from their training data.

Effective use actually requires:

1. Self-Awareness: A clear understanding of your own coding patterns and project conventions.

2. Iterative Refinement: Treating the AI's instruction set as a project artifact that evolves over time.

3. Collaborative Mindset: Shifting from "commanding" the AI to "guiding" its process.

Forward-Looking Conclusion

The dream of a universal, plug-and-play rulebook for AI assistants is a dead end. As I found in my previous reflections on whether we can think less with AI, the answer is no—we must think differently.

The copilot-instructions.md file is not just a configuration; it's the DNA of your AI collaborator for a specific project. It should be checked into version control and evolve alongside your README.md and package.json.

Stop searching for the perfect list of rules to copy and paste. Start with an empty file, click "Generate instructions...", and then use the chat to refine them after each session. The most effective AI assistant isn't the one with the most powerful model, but the one you’ve taken the time to teach.

1. The Tempting Proposition: "Just Write the Presentation"

Every complex project begins with a familiar challenge: a folder full of raw material and a blank canvas. In my case, it was a collection of dense Google Docs, a GitHub repository, and a clear goal—to create a polished 15-minute presentation for an upcoming conference.

The temptation, of course, was to turn to a Large Language Model and use what I call a "lazy prompt": "Here are the documents, write me a 15-minute presentation."

But my past experiments in AI-assisted development have taught me a crucial lesson. This approach almost inevitably leads to what I've previously described as a

"structural mess" in a recent article Do developers need to think less with AI? The AI can generate content, but it cannot, on its own, generate a compelling structure from ambiguous source material.

Knowing this, I adopted a different role—not of a micromanager, but of a director and critic. My job wasn't to define every expectation in a vacuum. Instead, our process became a rapid, iterative loop: the AI would propose a draft, and I would review it, using my critique to constantly clarify and refine my expectations for the next generation, from the high-level outline down to the tone of a single sentence.

2. Two Principles for a Better Partnership

To avoid the disappointing results of lazy prompting, I applied a more disciplined approach based on two core principles. These principles weren't just about getting a better output; they were about creating a more effective and predictable collaborative process with the AI.

1. Define the "Pairing Contract" Upfront

Before generating any content, we established a clear "contract" that would govern our entire interaction. This wasn't a formal document, but a set of initial instructions that aligned the AI with my expectations. The key clauses of this contract were:

• A Step-by-Step Workflow: We explicitly agreed to work in small, approved increments. The AI would propose a plan for a section or a draft for a slide, and I would approve or critique it before we moved on. This prevented the AI from getting too far ahead on a wrong path.

• A Dual-Output Structure: For every slide, I specified two distinct deliverables: minimalist on-slide text for readability and a more detailed accompanying speech for the narrative. This separation of concerns is critical for creating effective presentations.

• A Pre-Defined Tone: We established that the voice should be "professional and neutral," not "promotional." This simple directive guided the tone of every piece of generated text.

This upfront alignment ensured the AI's "creative freedom" was always channeled within the bounds of my strategic goals for the project.

2. A Lot of Tiny Steps

Borrowing a key principle from effective software development, I resisted the urge to ask the AI to solve large problems in one go. Instead, we broke down the task of creating the presentation into a hierarchy of tiny, manageable steps:

• First, we debated and finalized the high-level outline of the entire presentation.

• Next, we planned the narrative flow for one section at a time.

• Then, we drafted the content for only one slide at a time.

• Finally, once the core content was set, we refined the smallest details, like the wording of a single bullet point or the line breaks in a sentence for better visual balance.

This micro-iterative approach kept the AI's output focused and reviewable. It allowed for constant course correction and ensured that every component, from the overall structure down to the final polish, met my expectations before we considered it complete.

3. An Unexpected Discovery: The Power of Separated Concerns

In any deep-dive process, some of the most valuable insights are the ones you don't anticipate. While I expected the step-by-step workflow to be effective, I underestimated the impact of one particular clause from our initial "Pairing Contract": the strict separation of On-Slide Text and Accompanying Speech.

Initially, this seemed like a simple, practical rule for creating a presentation. However, it quickly revealed itself to be a powerful disciplinary tool that forced a higher level of clarity throughout the entire process. Here's how:

• It Forced Conciseness. The most common failure mode of presentations is a slide cluttered with text. By having a dedicated place for the detailed narrative (the speech), we were forced to be ruthless with the on-slide text. The question was no longer "What should this slide say?" but "What is the absolute minimum text needed on this slide while I am speaking?" This led to cleaner, more impactful visuals.

• It Clarified the Narrative. The dual-output structure forced us to constantly distinguish between the visual aid (the slide) and the story (the speech). At every step, we had to decide what the audience should see to anchor them, and what they should hear to understand the deeper context. This clarified the purpose of every single element we created.

• It Improved the AI's Output. Giving the AI two smaller, distinct tasks consistently produced better results than one larger, ambiguous task. A prompt like "Write three concise bullet points for this slide" yielded more useful output than "Create content for a slide about Topic X."

What began as a simple formatting rule for a presentation revealed itself to be a core principle for effective AI collaboration in general. It is a powerful strategy for ensuring clarity and quality in any complex, multi-layered project. Ultimately, the AI didn't reduce my cognitive load; it shifted it. It took on the heavy lifting of drafting text, which freed me up—and required me—to focus entirely on the higher-level strategic thinking involved in shaping the narrative, structure, and tone.

Conclusion: Thinking Differently

This journey of creating a presentation with an AI partner confirmed a critical insight: the promise of these tools is not to reduce the need for human thought, but to change its nature. The most effective approach I've found combines the speed and pattern-recognition of the AI with the architectural thinking and quality standards that an experienced professional brings to the table.

Our success didn't come from a single, brilliant prompt. It came from a disciplined process: establishing a "pairing contract," taking a lot of tiny, deliberate steps, and enforcing a clear separation of concerns.

Ultimately, these tools are powerful amplifiers of our own capabilities, not replacements for our judgment. They excel at generating drafts, suggesting patterns, and handling the tactical work of filling in the details. However, they require a human director to provide thoughtful integration, strategic thinking, and a clear vision for the final product.

This isn't about thinking less—it's about learning to think more architecturally about the creative process itself. In my experience, the key to success is learning to direct these powerful tools effectively. As with any powerful tool, the final quality of the work lies not in the tool itself, but in the wisdom and discipline of its user.

The promise of AI-powered development tools is seductive: write natural language descriptions, get working code, move fast, ship features. Tools like GitHub Copilot and Cursor have become staples in many developers' workflows, mine included. I use VSCode with Copilot as my primary environment, with Cursor as my secondary platform for cross-checking and refining solutions.

But after several weeks of experimenting with different approaches to AI-assisted development, I've come to a counterintuitive conclusion: we cannot think less with AI

My initial approach was what I'd call "lazy prompting"—throwing poorly constructed, vague requests at AI tools and expecting magic. Here are examples of the kind of prompts I was using:

1. "The resources created in the rds.tf file could be placed in their own module. How would you go about it? Which variables and outputs are necessary for the module to deliver the functionality?"

2. "Expose the ECS module output for ecr_url in root outputs.tf as well."

These prompts, while technically clear, were asking AI to make too many architectural decisions at once without proper context. Despite having established foundation rules for AI development, I wasn't applying them consistently.

The results were consistently disappointing:

• Information overload: AI would generate vast amounts of code that technically worked but was difficult to comprehend

• Constant rollbacks: Every 20 minutes, I found myself undoing changes and starting over

• Non-iterative code: The output was functional but rigid, making incremental improvements nearly impossible

• Structural mess: While the code fulfilled requirements, it lacked coherent architecture

The code worked, but it wasn't good code. More importantly, it wasn't code I could build upon.

Two Principles That Work

I had been using these principles in my earlier AI development work, but my recent experiment with "lazy prompting" confirmed just how essential they are for effective AI assistance:

1. Small Steps

Rather than asking AI to solve large, complex problems in one go, I've learned to break work into smaller, focused increments. This aligns with the principle of taking a lot of tiny steps in software development. This approach:

• Keeps the AI's output manageable and reviewable

• Allows for course corrections before investing too much time

• Maintains code quality by preventing architectural drift

• Enables better understanding of each component

2. Pair Programming with AI

The most significant shift in my thinking came from treating AI as a pair programming partner rather than a code generator. This builds on the established benefits of pair programming while adapting them for AI collaboration. This means:

• Active engagement: Continuously reviewing and questioning the AI's suggestions

• Collaborative iteration: Building solutions together rather than accepting wholesale output

• Maintained agency: Staying in control of architectural decisions and code quality

• Continuous learning: Understanding what the AI produces rather than blindly accepting it

This approach mirrors the benefits of traditional pair programming—better code quality, knowledge sharing, and reduced bugs—while leveraging AI's strengths in pattern recognition and rapid prototyping.

The Pomodoro Connection

An unexpected discovery was how well the Pomodoro Technique complements AI-assisted development. In traditional pair programming, natural breaks occur when your partner steps away for coffee or other needs. These interruptions, while sometimes frustrating, provide valuable thinking time.

When pairing with AI, these natural breaks disappear. The AI never gets tired, never needs coffee, and never suggests taking a step back. This can lead to tunnel vision and mental fatigue. The Pomodoro Technique artificially introduces these crucial breaks, providing time to:

• Reflect on the direction of the work

• Assess code quality objectively

• Consider alternative approaches

• Prevent the cognitive overload that comes from continuous AI interaction

For VSCode users, extensions like "Pomodoro Timer" can help integrate these breaks directly into your development workflow.

The Thinking Paradox

The central paradox of AI-assisted development is this: tools that promise to reduce cognitive load actually require more disciplined thinking to use effectively. Success with AI development tools depends on:

• Clear problem articulation: Better prompts lead to better solutions

• Architectural awareness: Understanding how generated code fits into the larger system

• Quality assessment: Evaluating AI output against engineering standards

• Strategic thinking: Knowing when to accept, modify, or reject AI suggestions

Moving Forward

AI tools for software development are powerful amplifiers of human capability, not replacements for human judgment. They excel at generating boilerplate, suggesting patterns, and rapid prototyping. However, they require thoughtful integration into development workflows.

The most effective approach I've found combines the speed and pattern recognition of AI with the architectural thinking and quality standards that experienced developers bring. This isn't about thinking less—it's about thinking differently and more strategically.

The future of AI-assisted development isn't about replacing developer intelligence but augmenting it. The developers who thrive will be those who learn to think clearly about how to direct these powerful tools toward creating maintainable, understandable, and robust software.

As with any powerful tool, the key lies not in the tool itself but in the wisdom and discipline of its user.