Georgios Theodorakopoulos, Software Engineer
George’s journey into backend development started at the age of 11, when he first encountered the MySQL dolphin while trying to launch his very first modded Minecraft server. After many failed setups, …

When I started at Epignosis, I folded Cursor into how I actually work, not as a novelty, but as something I reached for when the codebase outpaced my notes. It was the first time I relied on an AI editor for more than autocomplete in a real, high-complexity environment. What changed was not my typing speed; it was how I budget time between discovery and implementation.

The Context

Every codebase has a personality. History baked into it. Mine arrived as a large LMS: many modules, wires between them, and legacy paths you do not refactor for sport. Onboarding here is not “read the README and ship.” It is learning where the same word means different things depending on which folder you are in.

First Impressions

Cursor felt less like an autocomplete box and more like a second pair of eyes that could keep several files in view at once. The part that mattered for this post is not the suggestions themselves. It is that I could ask in plain language instead of chaining grep, IDE search, and hallway questions, and still know I had to verify everything myself. The rest of this article is about that balance.

My First Task: An Event in an Event-Driven Flow

My first assignment was to implement a new EDA (event-driven architecture) event: a message the system emits when something important happens, with consumers in other services or layers.

The questions piled up fast:

• Where do handlers for similar events live?
• How does the legacy stack publish or consume events compared to the newer REST API?
• What breaks if the payload shape is wrong?

Here is where I stopped treating all search tools as interchangeable.

grep / ripgrep is unbeatable when you already know the string: a class name, a queue name, a constant. You get a list of hits, you open files, you stitch the story together yourself. It is honest work. It breaks down when the codebase uses five phrases for the same idea, or when the important word is buried in a string builder three calls deep.

IDE search (scoped to a folder, or “find usages” on a symbol) widens the net. It is still fundamentally text and symbols. You can filter by path and file type, which helps in a monorepo, but you are still guessing which symbol to anchor on. If you pick the wrong entry point, you spend an afternoon in the wrong neighborhood.

Cursor with a narrow mission was different in kind, not only in degree. I could ask for “where events like this are published and consumed,” across legacy and newer layers, and get a proposed map: files grouped by role, sometimes synonyms I would not have thought to search. That map was often wrong in the details. It was still a faster wrong than a slow blind search because I could correct it with the debugger and a close read, instead of discovering I had been searching the wrong word at hour three.

None of that replaces grep. I still use it every day. The point is to match the tool to the uncertainty: exact string → ripgrep; symbol you trust → IDE; fuzzy concept spanning stacks → assistant first, then verify.

A pattern I was looking for in existing handlers looked conceptually like this (dummy names and schema; only the shape matters):

{
  "event": "domain.course.created",
  "version": 1,
  "occurred_at": "2026-03-30T12:00:00Z",
  "tenant_id": "acme",
  "payload": {
    "course_id": "crs_01jqxyz",
    "actor_user_id": "usr_01abc"
  }
}

<?php
// Illustrative only, not production code

final class CourseCreatedPublisher
{
    public function publish(CourseCreated $event, EventBus $bus): void
    {
        $envelope = $this->envelopeFactory->fromDomainEvent($event);
        $bus->dispatch('domain.course.created', $envelope);
    }
}

Technically, what I cared about next was not “emit an event” in the happy path. It was contract compatibility: version in the envelope, whether consumers are at-least-once and therefore need idempotency keys, and what happens when one subscriber upgrades before another. I will say it plainly: event schemas are public APIs. Treat them as an afterthought and you will ship a breaking change that only shows up under load or in a downstream queue. Cursor helped me find where similar envelopes were assembled and validated; it did not write the idempotency strategy for me.

There was no single obvious entry point. I spent half a day in internal docs and file trees, useful but fragmented. That is when I switched from “read everything” to “tell the assistant what success looks like, then tear the answer apart,” with the same verification I would use after any senior’s sketch on a whiteboard.

From Vague Prompts to Missions

I started with a broad prompt:

Hi, what can you tell me about this project?

The answer was a reasonable map: major areas, how pieces relate. Fine for day one. It also showed me a rule I still use: vague questions get survey answers. They do not replace a goal.

So I reframed. Instead of “tell me about X,” I gave a mission with boundaries, stacks, folders, what “done” looks like. The next prompt looked like this:

Find every place user impersonation is implemented or checked. Include legacy PHP modules and the newer REST API code. List files and how they connect.

That shift, from open chat to scoped reconnaissance, is what made the tool feel earned instead of magical.

Case Study 1: Impersonation Across Legacy and REST

I kept the mission concrete: both legacy and REST API folders, and the interaction points between them, not a single happy path.

What came back was not a wall of prose. It read more like a reconnaissance brief: a short list of areas, then files grouped by role. In my own notes I distilled it into something like the structure below (names and paths are illustrative, not a copy-paste from our repo):

legacy/
  └── User/
      └── Impersonation*.php          # session / context switch
rest-api/
  └── src/
      └── Identity/
          └── ImpersonationGuard.php  # token + permission gate

Alongside that, it pointed to middleware or filters that attach identity to the request, the same layers I would have had to discover by stepping through with a debugger.

On the REST side, a simplified version of what I expected to find (and later verified line-by-line) looked like:

<?php
// Illustrative middleware, real code has more guards

namespace App\Http\Middleware;

final class AttachImpersonationContext
{
    public function handle(Request $request, Closure $next): Response
    {
        $token = $request->attributes->get('session_token');
        if ($token?->isImpersonating()) {
            $request->attributes->set('effective_user_id', $token->subjectId());
        }
        return $next($request);
    }
}

And a fragment of legacy-style session switching might resemble:

<?php
// Illustrative legacy helper

function tlms_begin_impersonation(int $adminId, int $targetUserId): void
{
    $_SESSION['impersonation'] = [
        'admin_id' => $adminId,
        'target_id' => $targetUserId,
        'started_at' => time(),
    ];
}

Seeing both shapes in the same exploration session made it obvious where parity checks belong.

How I verified it

Cursor gave me a hypothesis graph. I still:

1. Opened each suggested file and read the real control flow.
2. Set a breakpoint on the REST path and walked the same route in XDebug.
3. Compared: does legacy enforce the same invariants as the new API, or only some of them?

In one case the overview was slightly over-merged: two similarly named helpers were described as one flow when they served different entry points. That is not a reason to abandon the tool; it is a reason to treat its map as R&D output, not a spec.

Roughly, that first targeted round took on the order of minutes to produce a navigable list; doing the same with search keywords alone would have been hours of false positives and missed synonyms (“impersonate” vs “act as” vs “switch user”).

From a security angle, impersonation is where I am least willing to trust generated code. I want explicit invariants: who initiated the switch, whether it is time-bounded, whether audit logs record both identities, and whether APIs reject confused-deputy patterns. My view is that an assistant is fine for locating those invariants across stacks; it is not the authority on whether your threat model is complete. If the map says “middleware X,” I still read X and ask whether that is sufficient for every transport (browser session, API token, background job). That skepticism is not cynicism about the tool; it is how I sleep at night.

Case Study 2: When “Permissions” Means Five Different Things

While tracing features, I kept hitting the word Permissions. In a smaller codebase that might be one module. Here it could mean:

After company onboarding (product and engineering orientation, not a public certification name), I could name concrete actions “create user,” “update user,” “view user” but I still did not know where those checks were enforced relative to “create course,” which spans UI, legacy API, and newer flows.

So I asked:

Where is permission enforced so a user cannot create a course? Distinguish UI-only checks from API enforcement, and legacy vs newer paths.

What made this answer useful

The valuable part was not “here is a file.” It was layering: legacy UI affordances, legacy API handlers, and REST handlers, with an explicit call-out where behavior could diverge, for example UI hiding a button while an API still allows the operation if called directly. That is the class of bug you hunt when you care about consistency, not just about compiling.

Dummy examples of what “three layers” can look like in practice:

// Client may hide UI without enforcing server-side (illustrative)

const canCreateCourse = usePermission('courses.create');
return canCreateCourse ? <CreateCourseButton /> : null;

<?php
// Legacy API handler illustrative

public function postCreateCourse(CreateCourseRequest $req): JsonResponse
{
    if (!$this->acl->userMay($req->user(), 'courses.create')) {
        return response()->json(['error' => 'forbidden'], 403);
    }
    // ...
}

<?php
// REST policy illustrative

final class CreateCoursePolicy
{
    public function create(User $actor, Tenant $tenant): bool
    {
        return $this->capabilities->granted($actor, $tenant, 'courses.create');
    }
}

The point of the exercise was not to memorize snippets like these. It was to know which of them actually runs for the client I cared about.

I am opinionated about defense in depth: the UI should reflect policy, but the server must enforce it. If those two disagree, I consider it a defect unless there is a documented, intentional reason (for example, progressive enhancement with a degraded mode, which still needs a story for direct API access). In a brownfield LMS, “permission” often leaks into feature flags and product experiments too. I do not think those should be conflated with RBAC in code, even when marketing uses one word for all of them. Naming and module boundaries matter because the next engineer will grep for permission and land in the wrong layer.

Trade-Offs: Cursor vs Other Tools

None of these replace the others; they have different failure modes:

The workflow that worked for me: Cursor for a structured first pass, then the debugger and raw reading for proof. Cursor’s own documentation stresses context and rules; pairing that with repo-specific rules files (when your team maintains them) improves consistency.

Opinions I am willing to defend

• Navigation beats codegen for onboarding. The highest leverage use of an AI editor in a large repo, for me, has been finding and relating code, not letting it draft whole features on day three. I would rather own fewer lines I understand than ship many I do not.
• Context windows are a budget, not a miracle. Long chats drift. I restart threads when the task changes, and I pin concrete paths or symbols when I know them. Treating the assistant like a stateless search plus narrative layer keeps quality higher than pretending it remembers last week’s decision.
• When grep wins: exact symbol renames, generated migrations, or a single known string across the repo. When Cursor wins: “this concept has five names and three frameworks.”
• Telemetry still beats prose. If logs or traces show which component handled a request, that evidence outranks a confident paragraph from any model. I use AI to suggest where to add a log or breakpoint, not to replace runtime truth.

One technical detail: request identity

On the REST side, identity often flows through attributes populated by middleware (see the dummy AttachImpersonationContext earlier). That matters because authorization policies usually read the same effective user the domain services see. If those two disagree, you get bugs that look like “permissions are random.” When I explore, I explicitly ask how Request attributes, session state, and policy classes align. A boring question, but it prevents spectacular production incidents.

When I want a reproducible check after an exploratory chat, I sometimes leave a scratch assertion in a test or script (nothing that ships), just a guardrail for my own understanding:

<?php
// Spike / scratch: throw away after you trust the real integration

public function test_create_course_requires_capability(): void
{
    $this->actingAsUserWithout('courses.create');
    $response = $this->postJson('/api/v2/courses', ['title' => 'T']);
    $response->assertStatus(403);
}

A Small Playbook You Can Reuse Tomorrow

If you take one thing from this post, make it operational:

1. Name the subsystem (e.g. “impersonation,” “course creation permissions”).
2. Bound the search (legacy vs new, UI vs API).
3. Ask for layers and divergence points, not just file paths.
4. Verify with reads and, when it matters, a debugger.
5. Log wrong merges when the model conflates two flows. Those notes train your next prompt.

Closing

The hard part of a large system is rarely typing the implementation. It is knowing which layer owns a rule, whether two stacks agree, and what breaks downstream. Cursor did not hand me that understanding. It narrowed where to look and sharpened the questions I asked in code review and in my own head.

I use it as a reconnaissance tool: point, verify, then own the change. That shortened the distance between “new on the team” and “comfortable changing this.” That is the bar I care about for the next task too.

If one belief ties this post together: in a brownfield codebase, competence shows up as impact awareness, not as commit velocity. Tools that pull impact into view earlier are worth learning. The rest is packaging.

Alexander Antoniades, Frontend Chapter Lead
Alexander Antoniades is the Frontend Chapter Lead at TalentLMS. He spends his days obsessing over web performance and front-end architecture — the kind of work where shaving off 50 milliseconds feels …

I want you to picture something. It’s a Tuesday. You’re at your desk. Coffee’s still warm. You open your terminal, bump a version number, hit install, and watch your entire project catch fire.

That’s a React upgrade.

It always sounds straightforward — a quick version bump, npm install, maybe mute a few warnings. But if you’ve actually done it, you know the truth. The version number is the easy part. Everything that comes after is the part nobody warns you about.

A few months back, our Frontend chapter pulled off a full upgrade from React 17 to React 18 during a hackathon at our headquarters in Athens. The whole team, working toward a common goal. It was challenging, messy, and — I’ll admit — actually fun.

React 18 was working fine after that. Life was good. But the ecosystem, it never sits still, does it? Libraries started hinting that React 19 was the “expected” baseline. TypeScript types were drifting in that direction. Deprecation warnings started showing up like passive-aggressive Post-it notes on your monitor.

Nobody wants to be the team still running the old version when the next wave hits. That’s how you end up three versions behind, staring down a rewrite.

So this time, I decided to do it solo. Just me, a codebase, and what I assumed would be a quiet afternoon.

I was wrong.

The Challenges

Dependency Conflicts

Here’s the thing about upgrading React. You’re not upgrading React. You’re upgrading everything that ever touched React.

The moment I bumped to React 19, the whole project started screaming. React Router needed a version bump. Nearly all unit tests failed. Testing libraries demanded newer React DOM APIs. ESLint plugins lost their minds. I thought this would be easier than the 17-to-18 jump. Instead, I was playing whack-a-mole with a cascade of small fires, each one revealing two more underneath.

I thought about quitting. Just reverting the branch, closing the laptop, going for a walk. Pretending none of it happened.

I didn’t. But I thought about it.

The Bugs That Were Always There

Here’s a dirty secret about React upgrades: half the bugs you “discover” aren’t new. They were always there. You just never had a reason to look.

Take this example. On React 18, this effect worked without complaints — reset was replacing the entire form state with just { event: { type } }:

useEffect(() => {
  const preservedEventType = formValuesWatch.event?.type;
  reset({ event: { type: preservedEventType } });
}, [eventTypeWatch]);

It worked. It shipped. Nobody questioned it. But it was broken the whole time. Every time this effect ran, it was throwing away the rest of your form values and replacing everything with a minimal object. React 18’s StrictMode was already double-firing effects in development — which meant this bug was being triggered twice per render cycle. But TypeScript didn’t complain about the shape mismatch, and the form seemed to work, so nobody noticed. Or maybe we just looked the other way.

Then we upgraded to React 19 and updated @types/react. The stricter types lit up like a Christmas tree. Suddenly TypeScript cared about what we were passing to reset(). And once we started looking at the flagged code, the real bug became obvious — this effect had been silently corrupting form state all along. The upgrade didn’t break it. It just ripped off the bandage.

The fix was to stop being lazy about it:

useEffect(() => {
  const preservedEventType = formValuesWatch.event?.type;
  const currentValues = getValues();
  reset({
    ...currentValues,
    event: { ...currentValues.event, type: preservedEventType },
  });
}, [eventTypeWatch]);

Grab the current values. Spread them. Override only what you need. Don’t blow away things you didn’t mean to touch. Simple, once you see it. But you have to see it first — and sometimes it takes an upgrade to force you to look.

TypeScript Got Stricter As Well

This is the part where it gets fun. And by fun, I mean the kind of fun where you open your IDE and every single file has red squiggles. Everywhere. Like your codebase developed a rash overnight.

React 19 shipped with completely overhauled TypeScript types, and the changes were not cosmetic. ReactChild, ReactText, a handful of other utility types you probably used without thinking — gone. Just removed. If your codebase referenced them, even indirectly through a shared component library, you got a wall of errors the moment you updated @types/react.

Then there was the ref situation. React 19 finally lets you pass ref as a regular prop. No more forwardRef wrapping. That’s the good news. The bad news is that on the TypeScript side, ref callback return types got stricter. If you had ref callbacks with implicit returns — an arrow function that accidentally returned something — TypeScript now rejected them. Across a large codebase, these “small” changes multiplied into hundreds of type errors.

useRef got pickier too. Call it without an argument? TypeScript error. You need to explicitly pass null or undefined now. RefObject no longer includes null by default, so any code that assumed ref.current could be null needed touching.

The React team published a codemod (types-react-codemod) that handled some of this. The keyword being some. The more custom your type patterns, the more you were on your own.

The forwardRef Farewell

This one deserves its own section because it touched everything.

With React 19 treating ref as a regular prop, forwardRef becomes unnecessary. In theory, that’s a beautiful simplification. In practice, we had dozens of components wrapped in forwardRef, each with its own generic type signatures, its own quirks, its own reasons for existing.

Removing forwardRef meant restructuring every single one. Pull ref into the props interface. Update the type signatures. Make sure the parent components that pass refs still compile. It was mechanical, repetitive, mind-numbing work — the kind where you get sloppy on component number 47 because your eyes have gone glassy and everything looks the same.

The kind of work that breaks you if you let it.

Enter Claude Code

A few hours in. Buried in type errors. Tests failing everywhere. That quiet voice in your head saying this solo upgrade was a terrible idea.

That’s when I decided to throw Claude Code at it.

I’d used it before for smaller things — generating boilerplate, explaining someone else’s code, the usual. But I’d never thrown it at a full-scale migration. A real mess. The kind of mess where you don’t even know where to start.

Turns out, that’s exactly where it comes alive.

Bulk Code Migrations

The forwardRef removal was the first real test. Dozens of components. All needing the same structural surgery: unwrap forwardRef, move ref into the props type, clean up the generics. By hand, this is the kind of task that takes hours and introduces bugs at a steady, reliable rate.

With Claude Code, I described the pattern once. It understood the structure. And then it just… did it. Across the codebase.

What got me was how it adapted. It didn’t do a dumb find-and-replace. Components with complex generic types got different treatment than simple ones. It caught cases where ref was being used in non-standard ways and flagged them for manual review instead of blindly transforming them. It was thinking about the code, not just processing it.

Same approach worked for the deprecated type references. Every instance of ReactChild that needed to become React.ReactElement | number | string? Handled. File by file. Respecting existing imports. Not introducing noise.

Debugging Type Errors

This is where Claude Code really earned its place. After the bulk migrations, I still had a backlog of type errors that weren’t mechanical. Nuanced things — useReducer inference changes, ref callback return types, third-party library type mismatches.

Normally, each of these is a 20-minute rabbit hole. Google the error. Find a GitHub issue from eight months ago. Read through 40 comments to find the one that actually has the answer. Try three different approaches. Repeat.

Instead, I could feed Claude Code the error and the surrounding code and get back a clear explanation of why it broke and how to fix it. Not just “change this line.” It understood the difference between “this broke because React 19 changed the type definition” and “this was always wrong, React 18 just let you get away with it.”

One that sticks out: we had a custom hook that returned a ref callback. After the upgrade, TypeScript hated the return type. Claude Code immediately identified the issue — React 19 introduced ref cleanup functions, so you can now return a cleanup function from a ref callback, similar to useEffect. The implicit return in our arrow function was being interpreted as a cleanup function. The fix was a one-liner. Add explicit curly braces. Done.

Understanding why that was the fix? That would have cost me half an hour on my own. Maybe more.

Fixing Broken Tests

Nearly all our unit tests were failing. This was probably the most daunting part, because test failures are a special kind of demoralizing — you can’t tell at a glance whether it’s a real problem or just noise from the upgrade.

The failures fell into categories. Testing library API changes. StrictMode behavior affecting test output. Genuine regressions from our refactoring. The tricky part is figuring out which is which.

Claude Code helped me triage at speed. Feed it a failing test with its error output. It would tell me: this is a testing library compatibility issue (update @testing-library/react, adjust the assertions), this is a StrictMode double-render thing (your test was relying on render count), this is an actual bug you introduced (fix it).

For the testing library issues, it helped me batch-update patterns across the entire test suite. Replacing deprecated query methods. Updating async utilities. Adjusting mock setups that assumed React 18 rendering behavior. The boring, necessary work that eats your day if you do it by hand.

What I Learned

A few things I’m taking away from this:

Upgrade to 18.3 first. If you haven’t already, install react@18.3 before you even think about 19. It’s identical to 18.2 but adds deprecation warnings for everything that will break. Think of it as a damage report before the actual damage.

Don’t underestimate the type changes. The runtime breaking changes in React 19? Manageable. The TypeScript type changes? That’s where the real volume lives, especially in a large codebase. Run the official types-react-codemod early — it won’t catch everything, but it’ll clear the surface-level wreckage. And if you’re on a large project and can’t afford to fix every type error in one go, look into Betterer. It lets you snapshot your current type errors and enforce that things only get better over time — no new errors allowed, but existing ones can be chipped away incrementally across PRs. Merge the upgrade, unblock your team, and clean up at your own pace. No shame in that.

The upgrade didn’t break your code. It exposed what was already broken. Half the bugs we found during the migration existed in React 18 too — we just never had a reason to look. Stricter types forced us to revisit code we hadn’t touched in months, and that’s where the real issues were hiding. Don’t blame the upgrade. Thank it.

AI tooling has crossed a line for migrations. I’ll be honest — I was skeptical. Migrations aren’t about writing new code. They’re about understanding why existing code breaks under new rules and applying the right fix without creating new problems. That felt too nuanced for an AI tool. I was wrong. Claude Code didn’t replace my judgment, but it cut the mechanical work and research time dramatically. The ratio shifted from “90% investigation, 10% fixing” to something much more sane.

Final Thoughts

Would I do the solo upgrade again? Yes. But only because Claude Code made it possible. Without it, this would have been days of documentation, GitHub issues, and Stack Overflow threads. The kind of work that makes you question your career choices.

Instead, it was one intense session where I could focus on the decisions that actually mattered and hand off the repetitive, soul-crushing investigation work to something that didn’t mind doing it.

The React ecosystem keeps moving. These upgrades aren’t optional forever. You put them off, they compound. The gap gets wider. The next upgrade gets worse.

The good news? The tooling for managing migrations — from the React team’s codemods and incremental releases, to AI assistants that actually understand what they’re looking at — is getting better, fast.

If you’ve been sitting on the React 19 upgrade, my advice is simple: stop waiting. It’s not going to get easier on its own. Grab the best tools you have and start pulling the thread.

Your future self will thank you. Or at least stop resenting you.

Yannis Rizos, Chief Software Architect
Yannis discovered programming at age 7. Soon after, he encountered Larry Wall's three virtues of laziness, impatience, and hubris, principles that have guided his approach to software development ever …

The deceptively simple question came at Open Conf last November, when a curious young engineer approached me at the conference’s mentorship corner. We were going to get a fresh cup of coffee when she asked: What is architecture?

It should have been easy terrain for someone who has spent years inside the problem, but what came out was a few sentences that gestured at decisions and trade-offs without ever landing anywhere. She nodded in the way people nod when they are being polite to someone who has just disappointed them. Almost four months later, I am still turning the question over, which is either embarrassing or instructive.

I have decided to treat it as the latter and write up what I owe her.

The Short Answer Problem

The resistance to a clean answer shows up immediately when you go looking for a definition. The closest thing to a satisfying formulation belongs to Ralph Johnson, one of the four authors of Design Patterns, the book that shaped how the industry thinks about software structure. After all that engagement with the problem, Johnson arrived at something that sounds almost flippant:

Architecture is about the important stuff, whatever that is.

Martin Fowler, who often returns to this line, treats the deliberate vagueness as a feature rather than a bug. The longer I’ve spent on architectural problems, the more I think he is right.

Whenever I’ve tried to give a more precise version of that formulation, something slips. “Architecture is about structure” works until you notice that a pile of undifferentiated code has structure too, and most of it isn’t architectural. “Architecture is about decisions,” works until you ask which ones count, and where you draw that line depends entirely on context. “Architecture is the decisions that are hard to reverse” is closer, but reversibility is partly a function of how the rest of the system is built, which puts you in a loop before you’ve arrived anywhere.

I’m not alone in this struggle. The Software Engineering Institute maintains a compiled catalogue of definitions across modern, classic, and bibliographic sources, and the fact that such a catalogue exists and keeps growing is itself data. That is not a gap in the literature waiting to be filled. It is signal about the nature of the thing.

What Architecture Is Not

The space left by every failed definition does not stay empty for long. A few specific misconceptions keep filling it, and each one was invited by some shorter version that came before it.

The first, my favorite, is that architecture is the diagrams. UML, C4 models, whiteboard sessions and ADRs are representations of architecture, and useful ones, but they are not the thing itself. A decision shapes what is possible, what is difficult, and what is effectively ruled out, regardless of whether anyone drew it on a whiteboard or wrote it down. You can tear up the whiteboard. The structural commitment has already been made.

The second misconception is that architecture is a phase. You do the architecture work, hand it off, and then engineering builds the thing. That model comes from construction, where you can hand off a completed design and step back, but software never reaches a completion state. It keeps changing; the structure that shapes it needs to keep being shaped, and a system left without active tending decays. Entropy is not a metaphor for codebases. It is the normal trajectory of any system that nobody is attending to.

The third misconception is that architecture lives in a role. One person or a small group owns the structural decisions, and everyone else builds inside them without needing to understand or influence them. This is the most consequential of the three because it concentrates exactly the wrong thing in exactly the wrong place. An architect who owns all the decisions has also insulated themselves from the feedback that would improve those decisions. The engineers closest to implementation are the ones who will live with the consequences, and cutting them out of the process means cutting out the most important signal in the room.

Deciding Which Tension to Accept

Clearing those misconceptions away is useful, but it still leaves the original question open. What I’ve found myself reaching for, when people push past the misconceptions and ask what architecture actually is, is this:

The practice of deciding which tensions to accept and which to release.

Every structural decision trades something: consistency against availability, deployability against performance, team autonomy against system coherence, and there is no configuration that resolves all of these simultaneously.

If you think you’ve found something without a trade-off, you just haven’t found it yet. Nobody opts out.

The right trade-off is always context-specific. The skill is not knowing the right tension to accept in the abstract but recognizing which tensions a specific context can absorb, which ones will compound painfully over time, and being deliberate about the choice rather than stumbling into it.

That relocation is the point. As the old adage goes, complexity cannot be destroyed, only relocated. The architect’s job is to decide where it lives and why that location is better than the alternatives, and no short answer can carry that much context without losing most of what matters.

The Organization Is the Architecture

One of the things it loses almost every time is the organizational dimension, and that loss is not trivial. Any definition of architecture that stops at the technical is incomplete. In 1968, Melvin Conway made an observation that reads almost like a complaint about a frustrating project: any organization that designs a system will produce a design whose structure is a copy of the organization’s communication structure.

This may be hard to believe today, but Harvard Business Review actually rejected the paper (for lack of evidence). Decades later, a Harvard Business School study confirmed exactly what Conway described, and subsequent research at MIT, the University of Maryland, and Tampere University of Technology validated it independently.

Conway illustrated the dynamic with a story from a compiler project he assigned to eight engineers, five to COBOL and three to ALGOL. Nobody decided how many phases each compiler would have, yet the COBOL compiler ended up with five phases and the ALGOL compiler with three. The structure of the output matched the structure of the team that built it, as an unintended emergent outcome, without anyone planning it.

If you’ve spent time inside a large engineering organization and wondered why the system looks the way it does, that story will feel less surprising than it should. The uncomfortable version of the observation is that the relationship runs in both directions. The organization shapes the system, and then the system shapes the organization. Teams form around modules, and modules persist because teams formed around them. Technical and organizational concerns co-evolve in ways that make it impossible to cleanly separate them, which is another reason any short definition falls apart. It leaves out half of what is actually happening.

Separating Decision from Construction

That missing half also reshapes how we need to think about the architect’s role. The broken metaphor at the center of how the field thinks about the architectural role is the building architect: design first, hand off to construction, step back.

The word itself comes from the Greek arkitekton, meaning chief builder, and the original was not a separate designer standing apart from construction. The chief builder was the most skilled person on the site, someone who understood the full problem from the inside. The software industry borrowed the building architecture metaphor wholesale and quietly erased that origin, replacing it with a designer insulated from consequence.

Erik Dörnenburg identified this as a structural information problem, not a cultural one. When the decision-maker is systematically insulated from the feedback loop that would otherwise correct bad choices, the design drifts from the reality it is supposed to serve. The distinction Dörnenburg draws is between being aware of consequences and having to live with them, and that gap is where architectural decisions quietly degrade. The moment you separate design from construction, you are separating decision from consequence.

This leads to a formulation that still surprises people when they hear it:

An architect’s value is inversely proportional to the number of decisions they make.

The goal of architectural leadership is to build the capacity for good structural decisions to happen across the teams doing the work, not to own those decisions permanently. This often gets misread as architecture without accountability, which couldn’t be further from the truth. It requires far more architectural maturity, not less, because teams need to maintain decision records, argue trade-offs honestly, and hold themselves to a standard.

The concept only works where that maturity exists, and building that maturity is itself one of the architect’s main jobs.

The Elevator and the Engine Room

What that job looks like across an entire organization is something Gregor Hohpe captures in a metaphor I’ve returned to more than almost anything else in this field. Large organizations are tall buildings. The IT engine room is in the basement: the systems, the infrastructure, the code. The executive penthouse is at the top: the strategy, the resourcing decisions, the market bets. Between them are floors of management, and each floor is a translation layer where information degrades as it moves in either direction, telephone game dynamics at the organizational scale. The architect’s job is to ride the elevator, carrying meaning intact in both directions across those translation layers.

I run an Architecture Modernization Enabling Team (AMET) at Epignosis, and this is what the work actually looks like in practice. The problems that determine whether a modernization succeeds are not purely technical. They are questions about which teams have capacity for which changes, how organizational constraints shape what sequences of work are even possible, and where leadership understanding needs to deepen before a technical choice can be made safely.

Architecture that stays in the engine room is working with half its inputs. Hohpe puts it plainly:

Excessive complexity is nature’s punishment for organizations that are unable to make decisions.

Architecture is also about options, the right to defer a decision while locking in key parameters. In volatile conditions option value increases, and a system locked by deep coupling has had its options foreclosed. Modernization, in this framing, is not paying off the past. It is rebuilding the capacity to choose.

That framing also redefines what an enabling team is for. An enabling team exists to build capability in the teams doing the product work, not to own the work permanently.

The AMET model applies this logic specifically to modernization, as a bell curve of involvement that increases as capability is built and decreases as teams internalize it, until the enabling team eventually dissolves. That lifecycle is not the failure mode. The failure mode is an enabling team that never dissolves because it keeps doing the work instead of transferring the capacity.

There is a second failure mode that gets less attention, which is the team that dissolves before the capability transfer is genuine. The downslope of the bell curve only resolves correctly when the skills and confidence are actually there, and premature dissolution looks like success until the teams are on their own and discover what they did not actually internalize.

Both these failure modes point at the same thing from different directions: architecture done well is partly an exercise in making itself unnecessary. That is not something you can fit into two sentences without losing everything that makes it true.

The Foundation and What It Enables

What it makes possible is the part of the argument that gets framed backwards almost every time I hear it.

The common version treats modernization as competing with innovation, time spent on the foundation is time not spent building new things, and every sprint on the former feels like something stolen from the latter.

What this misses is that a system that has not been modernized does not just move slowly. It actively constrains which questions engineers are allowed to ask, and when every change requires deep knowledge of how the system currently holds together, the mental load shifts from “what should we build?” to “what can we build without breaking everything?” That is not a resource problem. It is a cognitive constraint that narrows the product imagination of the entire organization.

What modernization actually enables is optionality: the capacity to change direction without foreclosing the future, to experiment in one slice of the system without risking another, to run multiple hypotheses simultaneously because the boundaries are clean enough to hold them.

The features you could not build on the old foundation leave no trace, and nobody wrote them on a roadmap. The innovation that never happened is invisible, which is precisely why modernization is chronically undervalued: its benefits are counterfactual, and counterfactuals do not appear in sprint reports.

The Question Persists

The same invisible cost applies to the question itself. An engineer without language for what architecture is will still make structural decisions, and that gap accumulates silently, below the threshold of any report, in exactly the same way as the features that never got built.

Which brings me to the part where I go against everything in this article and add to the pile:

Architecture is the practice of maintaining the conditions under which better decisions remain possible.

You can probably drill more holes in it than in most short definitions. But it happens to be the one I like the most, and the one I wish I had at the ready four months ago. It would not have been a satisfactory answer, of course.

But it might, just might, have saved me from that polite nod.

Christina Koleri, Software Engineer
Christina started as a mechanical engineer before computers won her over. Annoyingly curious by nature, she believes the best solutions are usually the simplest ones — they're just harder to find. …

I have generated six different AI-powered learning roadmaps for Go in the past year. Each one was well-structured, personalized, and genuinely good. None of them survived past day three.

This isn’t a post about AI being bad for learning. It’s about a specific trap I kept falling into.

Everything Is Faster Now

Everything in tech moves faster than it used to. That’s not controversial. We write code faster. We ship faster. We find answers faster. The tools are better, AI is accelerating everything, and the industry moves at a pace that would have been unrecognizable five years ago.

And we’ve adapted. We genuinely pick things up faster than developers did a decade ago. That’s real.

But speed has a cost. When everything around you accelerates, you feel the pressure to accelerate too. New framework drops and you haven’t tried it yet. A colleague mentions a tool you’ve never heard of and suddenly you feel behind. The industry moves and you need to move with it, or at least that’s what it feels like. There’s this quiet anxiety humming in the background. Whether you’re learning the right thing (whatever “right” even means), whether you’re fast enough, whether you’ll become irrelevant if you stop moving.

And in that rush to keep up, something gets lost. We reach for tools and frameworks and concepts without fully understanding them. We get surface-level familiarity with twelve things instead of real understanding of one. We consume explanations that make perfect sense in the moment and evaporate by the next morning. I was no exception. I was moving fast. But I’m not sure I was actually getting anywhere.

This is especially painful if your brain is wired the way mine is. I studied mechanical engineering before I got into software. I didn’t end up working as one, but the training left a permanent mark. When I encounter something new, I can’t just use it. I need to understand how it works. Not the API. The mechanism. Why it was designed that way. What’s happening underneath. That need for depth is constantly at war with the pressure to go wide and fast. The result is a person who starts a lot of things and finishes approximately none of them.

The Loop

I’ve been writing PHP for about four years. A LOT of PHP. But I’ve had this itch to learn Go because I want to understand how the infrastructure tools I use every day actually work under the hood. The CLI tools, the CI/CD pipelines, the container orchestration, the devops stuff. Look at the cloud-native ecosystem and it’s Go everywhere: Docker, Kubernetes, Terraform, Prometheus, Helm. It’s the language that most of this world is built in.

Here’s how it always went. I’d get excited. I’d open Claude or ChatGPT and say “create me a roadmap to learn Go.” I’d tweak it a bit, make it mine. Plan ready. Time to learn.

Day one: I’m in the docs, writing little programs, feeling great.

Day two: setting up my editor, installing tools, taking notes.

Day three: I stumble on something completely unrelated. Maybe someone posts their Raspberry Pi homelab setup and I think “I should build one of those.” Maybe I read about Rust and think “wait, should I learn Rust instead?” Maybe a new DevOps tool shows up on Hacker News. And suddenly I’m down THAT rabbit hole, generating THAT roadmap, and Go is sitting in a forgotten terminal tab.

A month later, I’d circle back. “OK, for real this time.” New roadmap. New plan. Same result.

Six times.

And AI made the cycle frictionless. Thirty seconds and I have a beautiful, comprehensive plan for literally anything I’m curious about. The barrier to starting something new is zero. Which means the barrier to abandoning the previous thing is also zero.

Each time, I’d understand a little bit. Enough to feel like I was making progress. But it was Kahneman’s System 1 thinking: fast, intuitive, and shallow. It felt like learning. It wasn’t sticking.

Fred Brooks wrote in The Mythical Man-Month that nine women can’t make a baby in one month. Some things have an irreducible timeline. Understanding is one of them. You can speed up access to information, but you cannot speed up the moment where your brain actually wrestles with a concept and comes out the other side getting it. That moment takes however long it takes, and I kept trying to rush past it.

How It Started (The Zed Post)

Then at some point, Zed’s “Let’s Git Together” blog post came my way. Their team had paired with community contributors for eight weeks and shipped 66 Git improvements. They had a curated project board, weekly pairing sessions, biweekly demo days. People showing up consistently, working on the same thing, keeping each other moving.

Something clicked. Not about the program itself, but about the structure. The regularity. The showing up. Maybe I could find someone to learn with like that.

I found a colleague who was also interested in learning Go. We agreed to jump on a call a few times a week, a couple of hours each time. Loose plan: learn together, maybe eventually contribute to some open source.

First session. No roadmap. No chapter one. We opened a small Go project on GitHub (genuinely not great code, which honestly made it more fun) and just started reading it together. Line by line.

“OK so this is the main function I think.”
“What does that := thing do?”
“I think it’s like… shorthand for declaring a variable? Let me check.”
“Why is THIS function capitalized but that one isn’t?”
“OH. Oh wait. Is that the public/private thing?”

When we got stuck we asked Copilot. Got the answer, talked about it until we both understood it, and kept reading. Two people squinting at code and talking out loud.

It was SLOW. Way slower than reading an AI explanation. We spent twenty minutes on things an AI could have explained in twenty seconds. We went on tangents. We got things wrong and had to backtrack.

In a few hours I understood more about Go than in all my fast solo attempts combined. Because when I had to explain something out loud, my brain couldn’t coast. I had to organize the thought well enough to say it. And when I got it wrong, my colleague would go “hmm, that doesn’t sound right” and we’d dig into it together. That friction, the getting-it-wrong part, is where the understanding actually happened.

But beyond that, something I didn’t expect: I was enthusiastic. The feeling of pulling someone forward and being pulled forward at the same time. I couldn’t wait for the next session. That had never happened with any roadmap. And when someone is expecting me on Thursday, I can’t quietly wander off to research Rust or build a homelab. The commitment acts as a filter on my curiosity. It doesn’t kill it (nothing could), but it channels it.

How It’s Going

I still use AI every day. I used it today. I’ll use it tomorrow. I literally used AI to help me edit this article.

What I changed is small: I added a regular call with another person learning the same thing. That’s it.

We read open source Go projects together. We argue about what the code is doing. Sometimes we spend way too long on something. It’s not efficient at all.

Three weeks in, I haven’t abandoned Go. I haven’t jumped to some new shiny thing. I actually want to show up to the next call. For someone with my track record, that’s remarkable.

Maybe the problem was never discipline. Maybe it’s that everything around me was telling me to go faster, and I’d been listening. Some things can’t be rushed. Nine women, one month, no baby.

I didn’t need another roadmap. I just needed someone to be confused with, and be slow together.

Vassilis Poursalidis, TalentLMS Engineering Director
Vassilis has nearly 20 years of experience working in diverse projects in the technology industry, with a strong record of leadership and technical expertise. He is currently an Engineering Director …

Almost everyone has experienced it: the relentless stream of LinkedIn connection requests, the “just following up” emails, the messages that start with “Hey Vassilis!” as if you’re old friends. Some are merely persistent. Others cross into territory that feels manipulative, even offensive.

For years, I sat on the receiving end of these approaches, treating them as little more than background noise. My strategy was simple: ignore and move on. I viewed these messages as a byproduct of having an online presence; annoying, but harmless. However, lately, the tactics have shifted. I began seeing patterns that moved beyond mere persistence and into calculated manipulation. The uncomfortable truth? They work. And they work often enough to justify their continued use.

This crossing of the threshold (from annoying, to deceptive) is what finally prompted me to speak up. It is one thing to be sold to; it is another to be engineered. Let’s dissect the mechanics of these modern B2B playbooks, why they persist despite the friction they cause, and what this evolution reveals about the current and future state of sales.

The Standard Playbooks

The Multi-Touch Sequence

This is sales 101: contact a prospect across multiple channels over 2-3 weeks. The pattern is based on the widely-cited statistic that it takes 7-8 “touches” to get a response from a cold prospect. The persistence isn’t personal, it’s systematic.

The Value-First Approach

Rather than leading with a pitch, they offer something first: a relevant article, an invitation to a webinar, a whitepaper, or benchmark report. By “providing value” upfront, they create a subtle obligation and establish themselves as a helpful resource rather than just another vendor. The ask comes later, after you’ve presumably been warmed up by their generosity.

The Problem-Aware Template

These messages reference specific pain points supposedly common to software engineering departments at companies like yours:

I noticed companies like [company name] often struggle with scaling engineering teams / managing technical debt / attracting senior talent…

Here’s the thing: they’re using industry generalizations rather than researching your actual situation.

The Social Proof Play

We work with [competitor or similar product], and they’ve seen a 40% improvement in deployment velocity.

This simultaneously creates legitimacy (if our competitors use them, maybe we should) and Fear Of Missing Out - FOMO (are we falling behind?). Sometimes the social proof is genuine. But most of the time they’re cherry-picked, exaggerated, or strategically vague.

The Trigger Event Approach

These reps are monitoring your company for signals: funding announcements, job postings for senior engineers, product launches, conference appearances. They time their outreach for moments when you might actually need their solution. You may think this is actually one of the more legitimate approaches (at least they’re doing their homework!), but it still means your company’s activities and your own personal activities are being fed into sales automation systems across dozens of vendors.

Other Common Approaches

Beyond these core playbooks, you’ll encounter several other variations:

• The “Breakup” Email: After no response, they send a final message - “I’ll assume this isn’t a priority and remove you from my list” - designed to trigger guilt.
• The “Quick Question” Hook: Messages with sentences suggesting a brief ask when it’s actually a full sales pitch waiting on the other side.
• The Survey/Research Request: “We’re conducting research on engineering leadership”, but the research mysteriously reveals you need their offering.
• The Comparison/Audit Offer: “Free assessment” of your current infrastructure, that’s really just sales qualification disguised as service.
• The Latest Hype Integration Play: “Your customers are demanding AI features”, the latest hype cycle where every vendor suddenly has an AI solution that will help you add intelligence to your product.

And of course countless other baiting techniques are waiting for you out there.

When Playbooks Turn Manipulative

The tactics above are standard, perhaps even acceptable. But there’s a darker set of approaches that cross ethical lines.

The Escalation Ladder: From Polite to Aggressive

Watch as the tone shifts across this sequence:

• Touches 1-2: Friendly, helpful tone. “I’d love to show you how we’re helping companies like yours…”
• Touches 3-4: Mild pressure. “Just circling back on my previous message…”
• Touches 5-6: Guilt or challenge. “I haven’t heard back - is this not a priority for you right now?”
• Touches 7+: Aggressive ultimatum. “Should I assume you’re not the right person?” or “Can I close your file?”

The psychology is deliberate: create urgency or trigger a response through discomfort. Some Sales Development Reps (SDRs) are explicitly taught that a “no” is better than silence, because it’s a response they can log and report to their manager.

The Gatekeeper Bypass

You respond to a cold outreach stating that you are not the right person, or perhaps you choose not to respond at all. Instead of accepting this boundary, they counter: “I understand - who should I speak with instead?” or “Would you mind introducing me to the person who handles this?”

Think about the audacity here. You have clearly indicated a lack of interest or relevance, yet their response is to dismiss your boundary and deputize you into their sales force. By asking for a direct introduction or a colleague’s contact details, they are asking you to compromise your internal network for their commercial gain.

In any other context, providing internal contact paths to an unverified external actor would be flagged as a security risk. In sales, it’s framed as “helpfulness.” You should not, under any circumstances, provide the details of your colleagues to a cold caller. If you genuinely believe an offering has merit, you may choose to discuss this internally with your company and then decide how to proceed.

Manufactured Intimacy

Messages that open with “Hey [First Name]!” and casual language as if you’re already acquainted. Or worse: “We’re delighted to have met you at [conference name]!” when you’ve never communicated at all.

They’re trained to write as if they’re continuing an existing relationship rather than initiating a cold contact. It’s deliberately deceptive, designed to bypass your mental filters for unsolicited sales approaches.

Identity-Based Manipulation: Where It Gets Personal

This is where sales tactics cross from annoying into genuinely offensive territory.

You receive a message that opens with:

• “As a fellow Greek…” (or even worse, written in Greek)
• “I noticed we’re both from [your hometown]…”
• “My family is also from [your region of origin]…”
• Comments about your name’s etymology or ancestral background

This isn’t accidental. This is weaponizing your identity and heritage as a sales tool.

Why is this particularly egregious: It exploits cultural norms around helping “one of your own.” It creates artificial obligation based on shared background. It takes something deeply personal (your heritage, your roots, your identity) and commodifies it for commercial gain.

Some sales trainers actually teach this as “finding common ground” or “building rapport.” But there’s nothing genuine about it. It’s manufacturing false kinship for the explicit purpose of making a sale.

For those of us from smaller ethnic communities or regions, this manipulation is especially invasive. The bonds within these communities are real and meaningful. Using them as a sales tactic is a calculated exploitation of something that is morally wrong.

The Uncomfortable Economics

Here’s the part that’s hard to accept: these tactics work.

Not on you, perhaps. You may be immune or have developed pattern recognition to understand and avoid these approaches. But they work often enough across the broader target audience to justify their continued use.

Those few opportunities can generate enough potential revenue to make the entire campaign “successful.” The remaining 99+% who were spammed or offended simply don’t matter in this calculation, because as it turns out the ends justify the means. Let that sink in for a bit.

Who Responds to These Tactics?

They’re effective with:

• Less experienced engineers who haven’t yet developed pattern recognition for sales approaches
• People-pleasers who feel guilty not responding or uncomfortable refusing to help
• Those from cultures with strong in-group obligations (the ethnicity/ancestry play specifically targets this)
• Those who think that responding will just make it stop (personally, if I have not subscribed to a newsletter, I will not even hit unsubscribe as this is a signal for them that someone is listening)
• People who haven’t learned to set firm boundaries with cold outreach

The Race to the Bottom

The companies that use manipulative tactics have optimized for conversion rate, not reputation. They’ve calculated that:

• Burning bridges with 99% of prospects is acceptable collateral damage
• Offending people doesn’t hurt them (those people weren’t going to buy anyway, goes the logic)
• The people who respond don’t seem to care about the tactics used

It’s the same economic model as spam email or robocalls. A tiny success rate justifies a massive negative impression on everyone else.

And here’s the meta problem: this creates a race to the bottom. Companies see competitors using aggressive tactics and getting results, so they adopt them too. Sales leaders promote SDRs who hit quota using these methods, reinforcing them as “best practices.” The system perpetuates itself.

The Opportunity Cost: What You’re Not Getting

Here’s something that makes these tactics even more frustrating: in theory, sales conversations could be valuable learning opportunities. A good salesperson understands their market deeply. They talk to dozens of engineers every week. They see patterns across companies, industries, and use cases. They could offer genuine insights about what your peers are struggling with, what solutions are actually working, and what emerging challenges you should be thinking about.

But that’s not what happens with these playbook-driven approaches. The conversation is extractive, not collaborative. They’re mining you for information (budget size, decision timeline, pain points they can exploit) while offering nothing substantive in return. The entire interaction is optimized for moving you through their sales funnel, not for mutual value exchange. Also be vigilant with what information you are allowed to share about your company.

This is the real tragedy of modern sales playbooks: they’ve eliminated the possibility of unexpected learning. You might engage with a cold outreach hoping to discover something new about your market, a technology, or an approach you hadn’t considered. Almost universally, you come away with nothing but time wasted.

Now imagine an interaction where someone reaches out with genuine domain expertise and offers real insights before asking for anything. Not vague numbers, but the actual facts of what the value proposition is. Would you remember them years later?

What This Means for You

First, recognize that you’re the target of an industrial process. Sales development is now heavily automated, data-driven, and optimized. The personalization you see is often manufactured at scale. The commonalities they mention are frequently mined from your LinkedIn profile by automation tools.

Second, understand that your response (or lack thereof) is a data point in their system. They’re iterating on what works. Every A/B test, every message variation, every new manipulation tactic exists because somewhere, at some point, it outperformed the alternative.

Third, accept that the vast majority of these interactions will offer you nothing of value. You’re not missing out by ignoring them. The chance that you’ll learn something genuinely useful is vanishingly small; not because the products are necessarily bad, but because the sales process is designed for extraction, not education.

Fourth, and most importantly: you owe these cold outreach attempts nothing. No response, no explanation, no referral to a colleague. The manufactured intimacy is not real. The shared heritage angle is exploitation, not community. The aggressive follow-ups after you’ve said no are not deserving of guilt.

Your attention and your network are valuable. Protect them accordingly and follow up only if you are genuinely interested in their offering.

A Better Way Forward?

For sales professionals reading this: I understand you have quotas. I understand the pressure you’re under. But consider what you’re optimizing for. Your help is needed to fix this broken system.

The manipulative tactics I’ve described may generate short-term results, but they’re burning long-term trust not just to your company but for all B2B outreach. They’re training an entire generation of software engineers to automatically dismiss and block sales outreach. They’re making it harder for every company out there to get through the noise.

There is a better approach: do real research, reach out with genuine specificity, respect boundaries when set, and build actual relationships rather than manufactured ones. It’s slower. It doesn’t scale as well. But it works with the prospects who matter most, the true potential buyers with real budgets and real problems.

For engineering fellows: share your experiences. When a vendor uses manipulative tactics, tell your network. When someone reaches out with genuine value and respect for your time, remember them and speak about their company. We can collectively shape what “best practices” look like by rewarding the behavior we want to see. And remember, those tactics are mostly executed by companies with products and services that do not speak for themselves.

The current system works because we allow it to. We can choose differently.

Christina Koleri, Software Engineer
Christina started as a mechanical engineer before computers won her over. Annoyingly curious by nature, she believes the best solutions are usually the simplest ones — they're just harder to find. …

How I built a simple setup to stop losing context in brownfield projects

I came back from the holidays and spent almost a full day trying to remember what I was doing.

I’m not talking about forgetting how to code. I’m talking about the hundreds of small discoveries (quirks, edge cases, “oh that’s why it does that” or “this is how it is supposed to work, it’s a feature not a bug”) that led me toward certain solutions and away from others. I use Claude Code as my pair programming partner. It does the heavy lifting of searching and figuring things out, while I challenge its proposals, find problems, and work through trade-offs together. But all that accumulated knowledge? Gone.

I’m a software engineer working on unifying multiple projects that were never designed to talk to each other. Identity brokering, data synchronization, event-driven communication between systems that evolved independently for years.

Here’s the fun part: I’m touching five different GitHub repositories. One is deep legacy, the ancient beast. One is middle-aged legacy, newer but full of quirks. One I don’t even build myself; I guide external developers and hope my documentation is clear enough.

🥲

And I’d been using Claude Code to help me navigate this mess. It was going great, until it wasn’t.

The Documentation Death Spiral

AI tools make documentation trivially easy. I can generate a README, a design doc, an architecture overview in minutes. And with so much unfamiliar code to cover, I needed that detail: both to understand how these projects work and to capture why we made certain decisions. You know the pattern when such detail doesn’t exist: two months from now you’re wondering why we did X and not Y, you try the “obvious” approach, hit a wall halfway through, and suddenly remember “oh right, that’s why we did it the other way.”

But keeping documentation accurate is hard. With such a large surface area (five repos, identity flows, event systems), the details change constantly during a conversation. You start with an approach, hit a limitation, tweak it, hit another, tweak again. By the end, you have a detailed document that’s accurate about the outcome but wrong about half the specifics.

Okay, so document at the end of the process instead? But by then, several compactions have happened, and I’ve already lost information. I end up repeating myself, re-explaining architecture, re-discovering edge cases. After a while, this became my main bottleneck.

I tried adding instructions to CLAUDE.md telling Claude to update documentation as it worked. I tried using hooks to automatically save state before clearing or compacting. I tried splitting knowledge across multiple markdown files, one per area. I tried consolidating into a single large file. None of it worked.

Even when I got the documentation right in the moment, it doesn’t stay right. Two weeks later, someone mentions a constraint I’d completely missed, and now that document needs updating. Good luck remembering (you or Claude) that this thing was even documented in the first place.

Long story short, I’ve restarted the documentation process from scratch three times now, each with a different approach.

Understanding the Actual Problem

I started reading documentation (the irony) to understand what was happening.

Context compaction is lossy by design. When conversations get long, Claude Code automatically summarizes older parts to make room. The summary captures the gist, but not the nuance: why you rejected an approach, which edge cases you already handled, what specific constraints led to a decision. After a few compactions, Claude might suggest the exact same tweak you rejected an hour ago. The details that led you to reject it are gone.

Auto-compact can’t be customized. It triggers automatically at ~95% context. You can disable it via /config in the CLI, but then you just hit a hard failure when context fills up. Pick your poison.

Hooks don’t help here, at least not yet. PreCompact hooks only support shell commands, not prompts. You can run a script, but you can’t ask Claude to do anything. There’s no PreClear hook at all. And built-in slash commands like /clear and /compact bypass UserPromptSubmit, so you can’t intercept those either.

CLAUDE.md instructions aren’t always followed. I had instructions telling Claude to update documentation as it worked. Sometimes it did. Often it didn’t. Claude tends to treat instructions as suggestions rather than requirements. This is a known issue — one user put it bluntly: “Does that mean that with each prompt I need to tell you to follow the instructions? …Yes, unfortunately.”

Multiple documentation files don’t scale. New information often needs to update more than one file, and that doesn’t always happen. Then Claude references outdated information from the wrong file, and you’re back to square one.

A single large documentation file bloats context. The more detail you add, the more context it eats. And Claude’s accuracy degrades as context fills up.

The workflows assume greenfield. Every tutorial I found follows almost the same pattern: “describe your idea and let Claude build it.” When you’re starting fresh, you can plan everything upfront. No legacy constraints, no mid-stream discoveries that force you to pivot. Nobody’s writing about maintaining five existing repos where you’re constantly discovering how things actually work, then trying to remember those discoveries next week.

So I stopped looking for the clever solution and started looking for the dumbest thing that might actually work.

What Actually Worked

Instead of relying on CLAUDE.md to automatically update docs (which it often ignores), I took explicit control.

One command: /save

That’s it. When I want to preserve state, I run /save. It tells Claude to update the status file with current progress, decisions, blockers, and anything we discovered about how the code works. Then I run /clear for a fresh start.

No automation that sometimes works. No hoping Claude remembers. Just a manual habit, and for now, a reliable habit beats unreliable automation. Before any transition (break, end of day, context getting full), run /save, then /clear.

The Actual Setup

Here’s what the structure looks like. I’ll walk through the important parts.

workspace/
├── PROJECT_STATUS.md           # What's done, in progress, blocked, decisions
├── PRD_REQUIREMENTS.md         # Current requirements (synced from Confluence)
├── CLAUDE.md                   # Instructions for Claude
├── docs/understanding/         # What I've learned about each codebase
│   ├── project-alpha.md
│   ├── project-beta.md
│   └── ...
├── project-alpha/              # Cloned repo
├── project-beta/               # Cloned repo
└── .claude/
    ├── settings.local.json     # Hooks configuration
    ├── commands/
    │   ├── save.md             # /save command
    │   └── refresh-prds.md     # /refresh-prds command
    └── hooks/
        └── session-start.sh    # Loads context on startup

The Files

PROJECT_STATUS.md — Not a plan, a snapshot of reality that gets updated as reality changes. Current focus, decisions made (with rejected alternatives), blockers. I also keep a sequence of small, testable tasks: the kind of instructions I’d give a junior engineer, or how I’d approach the work if I were writing the code myself. Not “build the whole feature,” but “create the route, add a controller that returns hello world, hit the endpoint to verify it works, then add the actual logic.” One problem at a time. Small checkpoints where I can test and review each piece before moving on, rather than ending up with ten new files and feeling overwhelmed. Gets loaded into context on every session start via the SessionStart hook.

PRD_REQUIREMENTS.md — Current requirements from Confluence, cached locally. Also loaded on session start, so Claude always knows what we’re building toward.

docs/understanding/ — How each codebase actually works. The authentication quirks, the unusual database choices, the non-obvious patterns you only discover by reading the code.

CLAUDE.md — Instructions for Claude. I still have them, but they help just not reliably. Things like “update PROJECT_STATUS.md as you work” and “suggest /save when context is getting long.” Nice to have, not critical path.

The Hooks

SessionStart — When Claude Code starts (including after /clear), this hook loads PROJECT_STATUS.md and PRD_REQUIREMENTS.md into context automatically.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume|clear|compact",
      "hooks": [{
        "type": "command",
        "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\"",
        "timeout": 10
      }]
    }]
  }
}

The script just outputs the files to stdout, which goes into Claude’s context:

#!/bin/bash
echo "=== PROJECT STATUS ==="
cat "$CLAUDE_PROJECT_DIR/PROJECT_STATUS.md"
echo ""
echo "=== REQUIREMENTS ==="
cat "$CLAUDE_PROJECT_DIR/PRD_REQUIREMENTS.md"

Every session starts with context. No re-explaining.

The Commands

/save — The core of the whole setup. When I run /save, Claude updates PROJECT_STATUS.md with current progress, decisions, blockers, and next steps. If we discovered how something works internally, it updates the relevant docs/understanding/*.md file too. Then I run /clear for a fresh start.

/refresh-prds — We use Confluence for PRDs. Querying it every session is slow, so this command fetches relevant PRD pages via the Atlassian MCP server and saves them to PRD_REQUIREMENTS.md locally.

The Decision Log

One of the most valuable parts of PROJECT_STATUS.md is the Decision Log with rejected alternatives:

This prevents Claude from suggesting approaches we already tried and rejected. The “Rejected” column is critical. Without it, you’re one compaction away from re-discovering the same dead ends.

What Still Sucks

I’m not going to pretend this is perfect:

It’s manual. I sometimes forget. The habit helps, but it’s still on me to remember.

Auto-compact can still surprise you. If context fills up mid-task, it compacts before you can save. I’ve learned to run /save proactively rather than waiting until I’m about to leave.

It uses context. Loading PROJECT_STATUS.md and PRD_REQUIREMENTS.md on every session takes up space. The tradeoff is worth it; the alternative is spending even more context and time re-explaining the same things. But it means keeping these files concise: a snapshot of current state, not a detailed history.

SessionStart has bugs. Output sometimes (rarely but it happens) doesn’t inject after compact.

The Results

After a few weeks, this has worked unexpectedly well:

• New sessions start with context. No more re-explaining the architecture or the end goal.
• Decisions and rationale are preserved. Including what we rejected and why.
• Failed approaches are documented. No re-trying things that didn’t work.
• Implementation knowledge accumulates. The understanding docs grow over time.
• Coming back after time off works. The status file is a reliable snapshot.
• PRDs stay current. One command to sync from Confluence.

The Bigger Lesson

With something really simple, I solved 80% of my problem.

A SessionStart hook that loads a couple of markdown files. Two commands that are just instructions for what to update. That’s it. No clever automation, no complex tooling, just files and habits.

But this simple foundation gives me something to build on. I’m already working on a tool to share with my team: something configurable where each developer can define their own files, their own instructions, their own context to keep up to date. What started as a personal workaround is turning into team tooling. And building it has taught me a ton about how AI tools actually work under the hood.

Interestingly, Claude Code itself started this way — as a simple internal tool that Anthropic engineers built for themselves. It spread through the company because it solved a real problem, and they debated whether to release it publicly or keep it as their “secret sauce.”

Most AI workflows assume you’re building something new. Most of us aren’t. We’re maintaining, integrating, extending, debugging (often messy) codebases that evolved over years.

If the tools don’t exist for your situation, build the simplest thing that works. You might be surprised where it leads.

If you’re dealing with similar problems (legacy codebases, context loss, documentation that can’t keep up), I’d love to hear how you’re handling it.

Christos Xanthos, Lead Software Engineer
Christos has more than 15 years of experience developing internet services and over a decade shaping e-learning trends. Watching young people grow and shine brings a smile to his face - whether …

“Are code reviews even worth it?”
“A fast, reliable CI suite would make them obsolete”
“Code reviews should be automated, not manual”

Relax - this is not that article.

We’ve already made our choice: we do code reviews. Human code reviews. Full stop.

Instead, here’s the real question we want to explore: If code reviews are already part of your workflow, how can you make them better?

It turns out the answer has less to do with the code and more to do with the people writing it. How a small shift in how we review code leads to faster decisions, fewer misunderstandings, and better collaboration.

The Reality of Our Code: Legacy, Quirks, and a Little Mystery

Every codebase has a personality. History baked into it.
Ours? Let’s say we support diversity. Some parts are elegant. Others… well, they feel like someone left cryptic clues for future generations. Archaeological findings from a civilization that didn’t believe in documentation.

If any of this sounds familiar, congratulations: you also work with legacy code.

When code has this much backstory, reviewing changes stops being a matter of scanning the lines. It becomes a search for context - hidden, implied, or half-forgotten.

And this is where collaboration, real collaboration, starts to shine.

Where Pair Programming Fits In

For developers still building their seniority, pairing is one of the fastest ways to learn. It’s an immersive way to learn the codebase, the domain, the quirks, the conventions, and the “why does this function behave like that?” questions no onboarding handbook can truly capture.

And speaking of onboarding:

Onboarding Reality
One of our onboarding exercises involves opening a seemingly innocent controller file.
By line 30, new developers usually ask, “Wait, why is that happening here? Isn’t this a controller?”
And that’s when onboarding really begins.

But we don’t pair only for mentoring juniors or onboarding. We do use it to guide new hires through our legacy codebase and navigate risky code that catches people off guard, but also for complex features and critical architectural decisions that are too risky to tackle alone.

But Pair Programming Isn’t Always an Option

Even when pairing makes sense technically, life gets in the way. Calendars clash. Deep focus is needed. The change is small. Or, honestly, we’re just not in the mood to narrate every mental step - no judgment.

Pair programming isn’t a default; it’s a tool.
And tools work best when used intentionally.

So when pairing isn’t feasible but collaboration still matters, we rely on the next best thing.

Enter Pair Code Reviews: Collaboration Without the Calendar Gymnastics

Pair code reviews take the essence of pairing (discussion, alignment, shared understanding) and apply it to the review stage.

The process is simple:

1. Screen shared.
2. Questions asked and answered instantly.
3. Reviewer and author discuss decisions, alternatives, trade-offs, and risks.
4. They refine the code together.

Here’s the difference in velocity:

Async review timeline:

• Monday: PR created
• Tuesday: Reviewer asks questions
• Wednesday: More questions, more answers
• Thursday: Changes pushed
• Friday: Approval
• Monday: Merge

Pair review timeline:

• Thursday 14:00 → call
• 14:20 → updates made
• 14:25 → merged

The collaboration loop:

Author explains → Reviewer questions → Discuss → Improve → Approve → Merge

Why Pair Reviews Outperform Classic Async Reviews

Clarity over comment threads.
A short conversation beats days of typed misunderstandings.

The Comment Novel
Most of us have seen a PR where the review thread was longer than the actual code.
By the end, no one remembered what they were discussing.
A 15-minute pair review would’ve saved a week.

Shared context leads to better decisions.
Reviewers understand not just the code, but the thinking behind the code.

Higher quality feedback.
Design issues, subtle risks, and legacy pitfalls surface more naturally through discussion.

Fewer iterations.
Async reviews can feel like pen-pal correspondence. Pair reviews compress the whole thing into one iteration.

Built-in mentorship.
Everyone leaves the room smarter than they entered.

Less friction, more humanity.
Tone doesn’t get misread. Nuance isn’t lost.
Communication feels… normal.

The Trade-offs

Pair code reviews aren’t a silver bullet. They require synchronous time - both people need to be available at the same moment. That’s not always possible, and it can become a bottleneck if every PR demands a live session.

They work best in teams with a safe culture where junior developers feel comfortable asking questions and senior developers don’t dominate the conversation. Without that foundation, the risk of one person steering the entire discussion is real.

And honestly? For tiny, low-risk changes, the overhead isn’t worth it. A one-line typo fix doesn’t need a 15-minute call.

Pros and Cons of Pair Code Reviews

Choosing Between Pair Programming, Pair Reviews, and Async Reviews

Our practical decision guide:

• Use Pair Programming
  For complex features, architectural decisions, or exploring legacy areas.
• Use Pair Code Reviews
  When collaboration is needed but pairing wasn’t possible during implementation.
• Use Async Reviews
  For small, low-risk changes that don’t require deep discussion.

Each tool fits a different situation.
The magic comes from choosing intentionally.

Conclusion: The Goal Isn’t Perfection. It’s Better Collaboration.

The Aha! Moment
“I thought this code did X… then we paired, talked it through, and realized it actually did Y.”
That collective Aha! is where the real value lives.

Code reviews aren’t just checkpoints - they are opportunities to share knowledge and improve systems together.

Pair code reviews strike a healthy balance: structured enough to keep things moving, collaborative enough to avoid misunderstandings, and flexible enough to fit into real workflows.

Perfect code doesn’t exist.
But better collaboration does - and pair reviews help us get there.

Evangelos Kalosynakis, Software Engineer
Vaggelis is a back-end software engineer, coming from a full stack background with experience in multiple technologies. Currently working in TalentLMS and is passionate about trying new technologies …

There are plenty of resources explaining what Spec-Driven Development (SDD) is and why it was created, but rarely do they cover how to actually use it and what problems it solves in practice.

For reference, here’s a solid definition from GitHub’s blog:

Instead of coding first and writing docs later, in spec-driven development, you start with a (you guessed it) spec. This is a contract for how your code should behave and becomes the source of truth your tools and AI agents use to generate, test, and validate code. The result is less guesswork, fewer surprises, and higher-quality code.

But what does this mean for your daily AI usage? What can SDD do that you can’t achieve with AI on your own?

The answer: it can do what you already do, but in a far more organized and predictable way.

Getting Started with OpenSpec

The key lies in the specification and supporting documentation. We chose OpenSpec because it’s as simple as it gets — it helps you get acquainted with the process without mental overload.

After installing the tool, run openspec init to create the necessary files. The only thing you need to provide is context for your project in /openspec/project.md, which you can do by using the AI Agent. OpenSpec, after installation, also gives you the prompt to do this: "Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions".

This file serves as the main entry point for your AI agent, giving it full context without declaring it on every prompt. It also acts as guardrails, keeping the agent within your project’s scope.

The Four-Prompt Workflow

Once set up, SDD boils down to four prompts:

1. “Please create the change proposal for [FEATURE]”
2. “Let’s update the change proposal with [CHANGE]”
3. “I’m happy with the change proposal. Let’s proceed with the implementation”
4. “I’m happy with the implementation, let’s archive the proposal”

That’s the essence of working with SDD. Since all documentation is provided upfront, you don’t need to repeat references. Just describe your feature in as much detail as possible, review the generated proposal, refine it if needed, then approve and implement. If the result isn’t satisfactory, you can always point the agent back to the proposal for guidance. When you’re happy, archive it and move on.

Why This Beats Blind Prompting

1. No fighting the AI — Guidelines are baked in, so you don’t need to repeat them on every prompt
2. No guessing — You know exactly what the AI will implement before reviewing code
3. Catch issues early — Reading the proposal surfaces problems before they become code
4. Iterate with confidence — Strictly defined guidelines make refinement predictable
5. Full control over implementation order — Want TDD? Tests first? Documentation updates? You decide
6. No repeated context — Everything is centrally located
7. Always current — Keeping documentation updated means the AI always has the latest guidelines

Does It Work?

Yes, it does. Case in point is this very project you’re reading. This is an entirely different stack compared to what we use daily, yet we managed to add this article and some features in less than 20 minutes from when we started working on the project — without any prior experience with the implementation stack.

Great documentation already existed, so the AI agent had an easy time filling our project.md file with all the relevant info, which in turn made this a breeze.

How Can You Make It Work?

One great initiative we had was to share SDD in a workshop with the intention of implementing it in more projects. The workshop included colleagues unfamiliar with our projects to make it interactive and test its effectiveness. We then asked them to implement a feature in a project they weren’t fully familiar with.

This has many benefits for everyone:

• Developers, even when inexperienced, can feel valuable within the company — even when they aren’t confident in their knowledge of the project or product
• They get a high-level overview of what’s needed when implementing something, which reduces cognitive overload since they don’t have to get lost in a codebase
• They can be more productive even with limited knowledge
• They can follow guidelines without the need for external supervision or course correction
• Projects can be maintained by more people instead of relying on a select few with experience

Isidoros Lemonidis, Frontend Software Engineer
Isidoros is an ever-loving enthusiast of technology, gaming and PC related stuff in general from a young age. Having joined the company in May, 2023, his main focus is on the client-side of the …

There’s a special kind of technical debt that doesn’t look like debt at all. The app works. The screens load. Nobody’s yelling. So we tell ourselves the classic lie:

“It’s fine. We’ll upgrade later.”

But “later” is where upgrades go to become migrations.

Staying behind on library versions is rarely painful day-to-day. The pain shows up slowly and quietly: docs stop matching what you have, examples on the internet don’t apply, new teammates assume a newer API, and tiny workarounds pile up because “that’s how this old version needs it.” And then one day you’re not upgrading a library, you’re upgrading a whole era of decisions.

That’s where we were: our client repo was still on TanStack Query v3, while the world had moved on to v5.

The Spark: Amsterdam, June 2025

This upgrade didn’t start as a roadmap initiative or a “mandatory improvement.” It started in June 2025, at React Summit Amsterdam.

I watched Tanner Linsley (the creator of TanStack Query) talk about where the library is going, and why. I also joined a hands-on workshop led by TkDodo (Dominik Dorfmeister), one of the main contributors.

And that combination did something dangerous to my brain: it made the future feel close. Suddenly, staying behind didn’t feel “safe” anymore, it felt like we were choosing to be stuck.

I came back with the kind of motivation that only conferences provide: equal parts inspiration and “I can totally do this in a week.”

Spoiler Alert: It didn’t take a week

Why We Migrated (Without the Marketing Fluff)

Even if you’ve never heard of TanStack Query (or even React) this part is relatable: some upgrades are worth doing because they make the system safer, clearer, and easier to change.

For us, v5 had a few big reasons to move:

• Our client is TypeScript-first, and v5 improves the overall type-safety story (fewer “trust me” moments).
• It aligns better with modern React patterns (including improved suspense/error support in the ecosystem around it).
• It encourages a more intuitive flow for keeping data in sync, especially around invalidations and organizing query keys.
• It comes with new structure, improved consistency, and generally a more “current” mental model.

And yes: no one wants to be left behind, especially on a library that sits at the core of how data flows through the app.

That’s the practical version. The emotional version is simpler:

If this thing is part of our app’s foundation, it shouldn’t be fossilized.

What Actually Changes in an Upgrade Like This (The Vibe, Not the Details)

Here’s the trick with explaining upgrades: people don’t care about the exact API changes and they shouldn’t. What matters is the shape of the pain.

The v3 → v5 jump had a theme: more consistency, fewer “choose your own adventure” patterns.

In plain language, we moved from “there are multiple ways to call this and they all kinda work” to “there’s one clear way to do it.” In practice, that meant a lot of the code had to be rewritten into a more unified structure.

Some of the internal vocabulary changed too (for example, what used to be described as “loading” moved toward “pending”). Not exciting!? Sure, until you realize how many places in a mature product use those states for spinners, skeleton loaders, button disabling, and empty states.

So even small changes ripple into real UI behavior.

The Elephant in the Room: “Wait… Where Did My Callbacks Go?”

This was the moment I knew the migration was going to turn into a story.

If you’ve ever used a “data fetching” tool, you’ve probably used callbacks like:

• “when it succeeds, do this”
• “when it fails, do that”
• “when it finishes, clean up”

In v5, query callbacks were deprecated. TanStack’s reasoning (paraphrased) is basically:

They can create confusing side-effects; prefer using useEffect or dependent queries instead.

Now, that’s a fair philosophy. But in a large existing codebase, it also means:

• You can’t just upgrade the package.
• You have to decide what your new “standard way” is.
• And you have to apply it everywhere fairly consistently.

So we did what we’ve learned (and, frankly, what big codebases often need and should do!):

We created facades

Instead of rewriting the whole app to adopt the new callback philosophy directly in every file, we introduced our own wrappers (facades) for useQuery and useInfiniteQuery.

Under the hood, they follow the recommended approach (via useEffect and status/data checks), but from the developer’s point of view, they act as the familiar “house style” of our repo:

• Import our own hook, not directly from the library.
• Keep behavior consistent.
• Make future changes easier because we control the interface.

It’s the same spirit as other abstractions we already have (like how we’ve wrapped other libs to add our own conventions).

This ended up being one of the most important parts of the migration, not because it’s “clever,” but because it reduces confusion and keeps the codebase cohesive.

How the Migration Took Life (aka: The Montage)

I won’t pretend this was a calm, linear process. It was more like a series of increasingly honest conversations with reality.

Step 1: Cursor was a big part of it

I fed the agent documentation, asked it to handle the “mechanical” stuff (renames, repetitive edits, the new unified syntax), and it did help, especially early on.

And then we hit the classic wall: large codebase + many patterns + many edge cases = AI starts hallucinating and confidently breaks things.

So the vibe shifted from “AI will do this for me” to “AI will do the tedious parts while I supervise like a tired detective.”

Step 2: Linting as a compass

At some point it became pure grind in the best sense: npm run lint, click errors one by one, guide the tool, fix things manually when needed, repeat.

Not glamorous, but effective. Like cleaning a kitchen by starting from the most visible mess.

After these first steps, and while I was working on this, in between my “planned tasks” and some of it on my free time, two weeks flew by.

The reality hit me then. It’s gonna take a year if I move like this. So I did the only thing that can help me finish this. I escalated the issue and I bought myself some time off my “regular work”, in order to see this through.

Step 3: The facade fix

Once the obvious deprecations were handled, we solved the “callbacks” problem properly by introducing the wrappers. That was a turning point: suddenly the rest of the migration felt possible.

At this point, I was nearly a month in but I could actually see the light at the end of the tunnel.

Step 4: Running the client

There’s a moment in every migration where you finally get to:

build,

load the app,

click around…

…and you think, “We did it.”

That moment is a liar.

Step 5: Bring in QA (and humility)

This is where the real work started. Compilers can’t catch logic misunderstandings. QA can!

I asked QA to run the full product suite and help expose anything that “felt off” after the changes.

Step 6: Fix → Test → Repeat

You fix what QA finds, QA tests again, you fix again… until the upgrade stops being “technically correct” and starts being “actually correct.”

After almost a week of doing this, I actually got the green light from everyone involved.

One and a half months after all these started and finally dropping down to my normal BPM, the cherry on top was a big presentation I made to everyone in the front end chapter and shared with the whole company, about the changed stuff and all the new, cool things we can build.

This was my first time diving so deep into a professional repository and I will never forget the experience.

The Takeaway: Cleanliness Is a Decision We Make Repeatedly

Doing this alone was a struggle, but it taught me a ton about the library, about our codebase, and about migration strategy. And it also made something obvious:

If we keep upgrades small and regular, they stay boring.
If we postpone them long enough, they become heroic.

Keeping the client modern is an ongoing struggle—but it’s also one of the most important forms of care we can give the product. Not because “new is shiny,” but because clean foundations make everything else easier.

So here’s my small, slightly dramatic plea:

Let’s not let garbage become architecture.
Let’s keep things up to date, consistently, incrementally, and without fear.

Yannis Rizos, Chief Software Architect
Yannis discovered programming at age 7. Soon after, he encountered Larry Wall's three virtues of laziness, impatience, and hubris, principles that have guided his approach to software development ever …

DDD Europe 2020, Amsterdam. For a COVID-era hire like me, this was the first time meeting several colleagues in person whom I had been working with daily for months. I kept noticing how familiar everyone sounded and how unfamiliar they looked. An odd sense of delayed recognition. We had paired on code over Google Meet, argued about bounded contexts in Slack, but never shared the same room. The talks, the workshops, the hallway conversations with practitioners who had been doing this for years. We absorbed everything we could.

This was not a one-off. Over the next five-plus years, Epignosis doubled down on more conferences, internal training programs, external consultants, workshops, books, the works. The investment was significant. The business case was clear. Align our code with our business. Make the codebase maintainable as we scale. Enable domain experts and developers to speak the same language.

What we did not anticipate five years ago, in that Amsterdam conference hall, was that we were also preparing our codebase for a future where AI would help us write it.

What We Built

The first fruits came when we built the new TalentLMS API. This is where Domain-Driven Design stopped being conference theory and became operational practice. We established Ubiquitous Language with domain experts. I remember the shift when conversations with product became faster because we had finally stopped translating ideas back and forth. No more translation layer between what product teams said and what engineers built.

We introduced Value Objects to replace primitives. A CourseStatus is a CourseStatus with its own validation and behavior. Some engineers hesitated at first because what we were now calling primitive obsession had been the norm for years. That hesitation faded once the constraints started catching real issues. No more passing around strings and hoping they were the right kind of string.

The Anti-Corruption Layer became the cornerstone of our refactoring strategy. We were building new code alongside what was, at the time, a 12-year-old system. We could not afford to let old assumptions bleed into the new model. I could feel the team relax once they realized the new model would stay protected from old assumptions. The ACL created a boundary, a translation layer that let us move forward without being dragged backward by legacy constraints.

Legacy systems demand clarity at every layer. When domain experts and engineers speak different languages, features get built wrong. When boundaries blur, technical debt compounds. At our scale, DDD was not optional. It was operational necessity.

After the API project, we restructured the codebase around domain concepts. We moved from a technical organization to a domain one. Now you do not just know where the models, the views, and the controllers are. You know where the Learning Paths are. Where Talent Library lives. Where to look for Reports.

How AI Reads It

Today, when I ask AI to add a feature to Notifications, it enters the module as if it already understands the territory. It reads the surrounding files, forms a picture of the local concepts, and uses those patterns to shape its first draft. The result is not perfect, but the model moves through the module with a level of confidence that only appeared once the structure became consistent.

AI tools work with limited context. Your current file plus nearby files. This turns domain-based organization from nice to have into critical. When AI is working in the Notifications module, the files it can see are notification concepts, not random controllers. Proximity becomes a semantic relationship instead of accidental collocation.

AI consumes our DDD structure through multiple channels. File and directory names reflect domain concepts. When AI scans the Notifications module, it sees how we handle trigger conditions, execution schedules, and result tracking. Architectural Decision Records document why certain boundaries exist and what alternatives we considered.

Value Object type signatures make constraints explicit in method signatures. When AI sees a function that takes NotificationsTitle instead of a string, it recognizes a constraint. The Ubiquitous Language we established means the model encounters terms that carry domain meaning, not generic technical jargon.

The Anti-Corruption Layer shows AI where boundaries are. It will not couple new feature code directly to legacy database schemas. The ACL is a boundary, a wall you cannot walk through without noticing.

The first time AI added code that matched the existing module structure, it felt like the model had finally learned the shape of our system. That was the moment when the link between our boundaries and the model’s output stopped being theoretical and became visible in daily work.

Was It Worth It?

DDD is not free. Introducing Value Objects means wrapping primitives. Defining aggregates means thinking hard about consistency boundaries. Building an Anti-Corruption Layer means accepting the overhead of translation between old and new.

In a greenfield project, you can build with DDD from day one. In a legacy codebase, you are retrofitting. You are making incremental changes while keeping the system running. Every change needs careful migration. Every boundary you introduce might break something. Restructuring a codebase around domains when you have more than a decade of technical organization is months of work.

Maximalists argue we should wait for better models. Models are improving fast. By the time you have spent six months on DDD, maybe AI will not need that structure anymore. Maybe it will figure things out. These are not unreasonable positions.

But TalentLMS is not a prototype; it is not something you build at a 3-day hackathon. It serves more than 20 million users. That means edge cases accumulated over more than a decade that are not in any training data. Business logic that reflects real-world complexity, not textbook examples. Performance optimizations that look odd but exist because a specific query pattern was crushing the database back in 2014. Regulatory requirements across different countries. Integrations with dozens of third-party tools, each with its own quirks. Data migrations that took months to plan and execute.

AI cannot hold this in its context window. Even the largest models. You cannot fit years of accumulated decisions, trade-offs, and reasons for odd behavior into a prompt. Seeing AI miss a detail that every senior engineer at TalentLMS knew by heart reminded me how much of our system lives outside documentation. Kent Beck frames it clearly in Programming Deflation:

In a world of abundant cheap code, what becomes scarce? Understanding. Judgment. The ability to see how pieces fit together. The wisdom to know what not to build.

What We Are Seeing

Features that would have taken days now take hours. AI-generated code fits our architecture more consistently. I cannot tell whether the improvement comes from our structure, better prompts, or rapid model progress. I only know the change is visible in daily work.

Structure that helps humans navigate complexity seems to help machines navigate it too. Whether that is causal or correlation, we will know in the near future. For now, we are paying close attention.

But the shift is real. When AI writes the boilerplate, what remains are the decisions that matter. Where boundaries go. What invariants hold the system together. How capabilities compose. Which trade-offs we are willing to accept and why.

In the good old days, we spent mental energy on low-level questions. How to implement a validation. How to write a specific query. With AI, that energy can be reserved for higher-level reasoning. What invariants an aggregate must protect. Where a capability belongs in the architecture. Same mental load, different altitude. More time on structure. Less on mechanics.

At 100 million requests per hour, architectural decisions compound. A poor boundary creates operational problems. A missing invariant risks data integrity. AI can help you move faster, but only if your architecture can guide it. Without that, AI only helps you make mistakes faster.

Five Years Later

Standing in that Amsterdam conference hall, we were learning DDD to build better software. The investment was about aligning code with business language, about creating boundaries that made sense, about sustainable complexity management.

Today, that same investment pays dividends we never anticipated. Our domain modules. Our explicit boundaries. Our Ubiquitous Language. The Anti-Corruption Layer that keeps old assumptions from bleeding into new code. None of it was built with AI in mind, yet all of it matters for AI effectiveness.

I look back at that conference trip now with a sense of quiet irony because none of us imagined what those early choices would enable. Those workshops and late-night debates about aggregate boundaries were not only about maintainability. They were shaping the maps that modern development tools now rely on.

Not a bad return on investment for a conference trip.

Konstantinos Chatzinikolakis, TalentLMS Enterprise Engineering Director
Kostas joined Epignosis back in 2019 and somehow ended up managing around 30 engineers across the company's e-learning platforms. He's fascinated by the human side of building software and believes …

The Evolution Never Stops: Three-Plus Years of Hiring Adventures in Engineering

It is not the strongest of the species that survives, nor the most intelligent, but the one most responsive to change.

Charles Darwin

Darwin probably wasn’t thinking about tech hiring when he wrote this, though I first encountered this quote in Kent Beck’s “Extreme Programming Explained.” But here we are. Over the past three-plus years, our engineering hiring process has been on a wild ride of transformations. Not because some consultant told us to, not because we read it in a blog post, but because… well, things kept changing and we kept trying stuff. This is that story.

Where We Started: The Traditional Days

Three-plus years ago, when I took over hiring responsibilities, I inherited what seemed like a solid, time-tested process. Private portal, comprehensive assignments, PHP specs, EER diagrams: the works. This had been the way things were done for years (I’d gone through it myself when I was hired back in 2019). Candidates would disappear for 3-5 days and emerge with their solutions.

It mostly worked. We could spot who understood patterns, who thought about security, and who could document their thinking. But my favorite discovery? README files became this unexpected window into people’s minds. The way someone explains how to set up their project, how they anticipate confusion, how they communicate with a future stranger - pure gold.

The Time We Tried to Be Nice: Live Coding Adventures

At some point, we had this collective moment of “Wait, are we asking too much?” Five days of someone’s life for maybe getting a job? That felt… heavy.

So we pivoted. Live coding! Respectful of time! Only 1-2 hours! What could go wrong?

For backend folks, we cooked up these Slim framework challenges. 30-40 minutes, boom, done. People seemed to appreciate it, and we could watch them think in real-time. Pretty cool.

Frontend was… a different story. For an entire year (I kid you not, a YEAR) we couldn’t find Vue.js developers who could handle basic tasks. “Fetch data from an API and put it in a table.” That was it. And yet, when we did find people who breezed through? They became absolute rockstars on our team.

The Pendulum Swings Back: Take-Home Redux

Then my direct reports wanted to take ownership of the hiring process. Fresh eyes, fresh ideas. Their theory? Maybe live coding was too stressful. Maybe we were losing gems to performance anxiety.

Back to take-home we went. For the frontend, we switched to Vue 3 projects with public APIs. Backend reverted to our original portal assignments. And wow, suddenly everyone was passing! Success rates through the roof! We were geniuses!

…Until these same stellar assignment-completers joined the team and proved less capable than those who’d excelled in our live coding sessions.

This got us thinking. The people who breezed through live coding consistently outperformed those who aced take-home assignments but struggled with real-time collaboration. Maybe we were onto something with that live format after all.

Then AI Showed Up and Flipped the Table

Just when we thought we had it figured out (narrator: they didn’t), ChatGPT and friends crashed the party. Our carefully crafted assignments? Obsolete overnight. What took juniors days now took anyone with decent prompting skills about 20 minutes.

The generational shift was fascinating to watch. Early on, candidates would get this deer-in-headlights look when we mentioned they’d clearly used AI. Like kids caught with their hand in the cookie jar. Fast forward a few months, and NOT using AI was the weird choice. It became as natural as breathing.

Suddenly, we’re asking different questions. If AI can write the code, what’s left? Turns out - everything that makes us human. How you think, how you communicate, how you collaborate, whether you can navigate the beautiful mess of ambiguity that is real-world software development.

Where We Landed (For Now)

After all this experimentation, we’ve learned some things. Or at least, we think we have:

The best code isn’t always the cleverest code - it’s the code your teammate can understand at 3 AM during an incident.

Seniority used to mean “can implement any spec flawlessly.” Now it means “can figure out what we should build when nobody’s quite sure, and help the team get there together.”

AI changed the game, but it didn’t replace the players. The engineers thriving now are the ones who see AI as another tool in the toolbox, not a magic wand.

We’ve gotten great feedback about our process from candidates, which makes us feel pretty good. Then we go through other companies’ interview processes and… yikes. Humbling. If we had it all figured out, we wouldn’t still be changing things.

The Never-Ending Story

Will we change our approach again? Actually, we already are. Vassilis Poursalidis, our Engineering Director, is spearheading a new unified approach that goes live-by-default for everyone—frontend, backend, QA, the whole crew. Because here’s the thing about working in tech: the moment you think you’ve got it figured out, the ground shifts. The process that works today might be laughable tomorrow. And that’s actually… kind of exciting?

We’re not adapting because we have to survive. We’re adapting because it’s interesting, because we’re curious, because every failure teaches us something new. Even when those failures are spectacular.

Our hiring journey has been messy, nonlinear, sometimes frustrating, often surprising. But it’s been ours. Every weird experiment, every “what if we tried…”, every pendulum swing - it’s all been part of figuring out how to find people we want to work with.

In technology, evolution isn’t optional; it’s the path to excellence.

At TalentLMS, we’re always trying new things and learning as we go. If that sounds like your kind of environment, come join the experiment.

Ioannis Psaronikolakis, Lead QA Engineer
Ioannis is a Lead QA Engineer with nearly a decade of experience in software quality assurance. He is deeply passionate about quality engineering and continuous improvement.

The introduction of AI into software testing raised a common concern among QA professionals. Not that AI will replace testers, but that it might reduce the traits that give the role its value: curiosity, critical thinking, and attention to detail.

If AI can write tests, analyze logs, and generate large amounts of data quickly, what happens to the craft behind quality assurance?

Relying on AI without review risks weakening the skills that define strong QA work.

In a world where a prompt can create a test case faster than we can read it, the concern felt valid.

But as AI becomes part of daily workflows, another point becomes clearer:

The risk isn’t AI.

The risk is overlooking our core QA values.

The Fear: “AI Will Make Us Less Critical”

This concern appears in simple ways.

AI produces a set of tests, and the review becomes faster, sometimes too fast.

Outputs that would normally raise questions may pass unnoticed because they look structured or complete.

Speed can create the impression of quality even when depth is missing.

These situations show a pattern:

AI can give a sense of productivity while lowering the level of scrutiny – if allowed to.

The Shift: AI Is a High-Delivering Partner

Here’s the shift that changed the narrative:

AI can act like an architect.

It can propose designs, suggest flows, and structure ideas faster than any of us can type.

It can even behave like a quality engineer – pointing out risks, generating scenarios, evaluating consistency.

But AI still lacks something fundamental to QA work:

• It cannot interpret experience
• It cannot sense friction in a user journey
• It cannot experience frustration, confusion, or surprise
• It cannot detect when something is technically correct but still wrong for the user

That human layer of perception – the intuition built from experience – is irreplaceable.

So while AI can behave like a highly productive partner, it still needs our:

• guidance
• direction
• prioritization
• correction
• and, above all, assessment

AI can generate a hundred tests in a minute.

But it cannot tell when something feels wrong.

The Thin Line: When Tests Lose Meaning

Quantity is not value – and in QA, this distinction is everything.

Without proper review, AI can produce:

• verbose test suites with no business impact
• redundant cases that inflate execution time
• noise disguised as coverage
• flakiness hidden behind sophistication
• blind spots in core flows that genuinely matter

It is common to see AI generate many versions of a small validation and overlook a major product path.

This is the thin line we walk:

AI can accelerate useful coverage or accelerate unnecessary complexity.

The deciding factor is our critical thinking.

The Realization: AI Gives Space to Quality

When the expectation that AI will replace thinking is removed, its benefit becomes clearer:

With AI handling the repetitive, mechanical tasks – the boilerplate test structures, the obvious edge cases, the initial draft work – we finally gain more time to think deeply: to explore behaviors, question assumptions, dig into risk, business context, user reality, and quality architecture.

AI doesn’t reduce quality thinking.

It creates more space for it.

The New QA Era: From Test Writer to Quality Architect

This shift becomes clearer when looking at how the role has evolved:

• AI writes faster – we need to think deeper
• AI produces more – we need to evaluate better
• AI expands quantity – we protect quality

The role shifts towards:

• deciding what is worth testing
• defining the quality bar
• shaping automation strategy
• ensuring business alignment
• analyzing patterns and risks
• preventing meaningless test bloat
• maintaining clarity, purpose, and intent

These are not tasks AI can replace.

They rely on experience, reasoning, and context.

AI increases execution capacity, but it does not define meaning.

Only QA engineers can determine which scenarios matter, how coverage aligns with user behavior, and where testing supports real product outcomes.

This is the modern QA identity:

moving from executor to quality architect,

from generating tests to designing purpose,

from checking output to governing meaning.

AI strengthens this identity by giving us more space to focus on it.

So, Does AI Mitigate QA Curiosity?

No.

AI introduces a decision point:

Either accept its output blindly and let critical skills fade – or use it intentionally and expand the scope of quality thinking.

Curiosity becomes more important, not less.

Critical thinking becomes mandatory, not optional.

An eye for detail becomes even more essential.

These traits have always defined the QA.

Now we need an extra eye – one that examines AI’s work, protects meaning, and keeps quality aligned with real business value.

In the end, AI does not change what makes QA valuable.

It highlights why those qualities continue to matter.

Aggelos Bellos, Senior Software Engineer
Aggelos decided to become a software engineer at a young age. At 12, he started experimenting with web technologies through a Blogspot. He is currently working in the Architecture Team on TalentLMS, …

Managing APIs is hard. An application usually supports a single version of itself. It can be refactored, restructured, and redesigned with relative freedom. On the other hand, an API has to maintain stability for all its versions that are being consumed.

As requirements change, more and more time is spent on how to avoid breaking changes instead of actually delivering value.

Frozen in Time

An API is a contract between the provider and the consumer. This means that once a version is released, it should remain frozen in time. This is not only true for the contract of the API but also for its implementation. However, this is not a “should” but what happens in practice.

When an API is released, we don’t care about its internal implementation anymore. Yes, there will be bugs and yes, there are multiple shared components. But other than these, we do not make changes. If it works, don’t change it. Right?

Theoretically, we could develop a completely new application for each new version. This would allow us to build something and just make sure we keep it alive. Practically, the cost of maintaining such an approach is prohibitive. Furthermore, this is not how software is built in practice.

Software is built in small incremental batches. So why don’t we optimize our APIs for small incremental changes?

Problem

Code frozen in time sounds good, but what about code that reflects data? Data is also evolving with each new requirement. Take this for example:

 if ($course->active) {
    // do something
 } else {
    // do something else
 }

If we delete the active field in favor of a new status field, then we will have code that depends on a field that does not exist anymore. Even a new application wouldn’t help us here as there is still the dependency on the data.

There are ways to mitigate this problem. The easiest one is to check the version of the API and adapt the code accordingly.

 if ($apiVersion >= 2) {
     if ($course->status === 'active') {
         // do something
     } else {
         // do something else
     }
 } else {
     if ($course->active) {
         // do something
     } else {
         // do something else
     }
 }

As you can see, this approach quickly becomes unmanageable. Each new version adds more complexity to the code.

A more common approach is to use feature flags or to split each version in a different folder / class:

  - api
      - v1
          - CourseController.php
      - v2
          - CourseController.php

While this can work, it does not scale well with small incremental changes. Furthermore, you tend to lose what is the latest state of the application.

APIs as Infrastructure

To solve these problems, we decided to treat APIs as infrastructure. An approach first introduced by Stripe back in 2017.

The idea is simple. Your code always reflects the latest version of your API. Each time you need to introduce a change, you update your code to reflect the new requirements. Then, you add a VersionChange that lets you go back in time.

Instead of branching the system into multiple versions, we move the system forward and let transformations pull older versions backward. This keeps change concentrated in one place instead of fragmented across versions.

Let us build on our previous example. We have a CourseEntity that had an active field in V1 and in V2 introduced a status field. We would update our code to reflect the latest version, which means that our code would use only the status field.

To make sure we won’t break the previous versions we add a VersionChange that restores the active field from the status field.

 class ConvertCourseStatusToActiveChange {
    private string $description = 'The active field was replaced by the status field for ...';
 
    public function apply(CourseEntity $course): CourseEntity {
        $course->active = $course->status === 'active';
        return $course;
    }
 }

When a request comes in, we check the requested version and apply all the necessary changes to bring the data to the requested version.

Here’s why we like this approach:

• The code always reflects the latest version of the API.
• Small incremental changes are easy to implement.
• Each version change has a mandatory description that explains why the change was necessary.
• We can freeze old versions without duplicating code.

Treating APIs as infrastructure lets us evolve safely, incrementally, and without fear of breaking the past.

Keeping Versions Aligned With Reality

Most API versioning schemes assume that products evolve through major releases. Versions like example.com/api/v1/courses and example.com/api/v2/courses work well when changes arrive in large batches.

The problem is that major releases require coordination across departments and strict lifecycle planning. More importantly, they contradict everything we have said so far: $small_incremental_changes !== $major_release.

Small, steady changes are easier for consumers to adopt. Ideally, the versioning scheme should reflect that and communicate something meaningful to them.

Date-based versioning ( YYYY-MM-DD ) does exactly that. Each version corresponds to a real point in time, making the incremental nature of our changes visible and predictable. It aligns the version history with how the API actually evolves, instead of forcing artificial release boundaries.

Design First, Change Maybe

Code will always remain a technical debt. Having a framework that supports change does not mean that we can avoid thinking about design. Some changes will always ripple through the system. We try to balance between over-engineering and pragmatism.

What matters is creating an environment where change is expected, guided, and safe. A structure that lets us introduce new behavior incrementally, without rewriting the past. An approach where old versions can be frozen with confidence, and new versions can evolve without fear.

By treating APIs as long-lived infrastructure rather than short-lived features, we make this balance possible. We keep the codebase aligned with the current truth of the system, we document why each version exists, and we ensure that past behavior stays accessible without forcing duplication or hacks.

Bonus

While we were experimenting with this approach, we found an open-source project that implements in FastAPI what Stripe describes in their blog post. Having a concrete implementation really helped us to implement this approach in PHP.

You can check it out here: cadwyn.

Yannis Rizos, Chief Software Architect
Yannis discovered programming at age 7. Soon after, he encountered Larry Wall's three virtues of laziness, impatience, and hubris, principles that have guided his approach to software development ever …

In May 2023, I sent an email to a handful of engineers inviting them to discuss a “super secret project that probably won’t happen.” Yes, that was the actual meeting title. I figured if I was asking people to bet time on something uncertain, I should at least be honest about the odds.

25 mentorship pairs later, that meeting turned into the most unexpectedly durable thing I’ve built at Epignosis. I’m still not entirely sure why it worked.

The Gap

At the time, Junior engineers at Epignosis only knew their immediate squad. Maybe 5 to 7 people in a 200-person company. After the pandemic, teams had drifted into their own orbits and remained there. The casual spillover that used to happen in offices was just gone. These engineers had no idea how other teams worked, what they were building, or who to even ask when they hit something outside their area. The problem wasn’t that they lacked skill. They lacked context.

Four Skeptics and a Plan

I pitched something simple in that first call. Pair junior engineers across products and functions. TalentLMS padawan with an eFront mentor, and vice versa. An engineer interested in backend work with someone from DevOps. Not technical coaching about their specific codebase, but something harder to name. Engineering socialization, maybe. The stuff that happens when people occupy the same physical space but vanish in distributed work.

Someone spoke up immediately. I don’t remember who anymore, but I remember this: they were enthusiastic about the idea and skeptical I’d actually pull it off. Penelope, Thrasos, Christos, and Dimitris all volunteered to be the first mentors. Their skepticism wasn’t about the concept. It was about execution. They were feeling the siloing problem too, and they thought breaking it down would take massive effort.

Without them stepping into something uncertain before it was proven, the program would have stayed a document in a folder somewhere. Pushed down the priority list when something urgent arrived, one more thing that seemed reasonable at the time but never quite happened.

Six Sessions, Three Months

We launched in June 2023 with a new cohort of interns. The format was simple on purpose. An hour every 2 weeks for 3 months, 6 sessions total. I matched the duration to the internship window partly because research says the first 90 days determine whether someone succeeds, but mostly because I didn’t want an open-ended commitment. Open-ended things drift. Boundaries create focus.

I insisted on one thing: document your meetings. Not for oversight, but to help pairs track their own conversations. In time, some pairs shared sanitized versions of their notes. Those became the best onboarding material new mentors could ask for. Actual conversations, actual topics, actual problems that came up. No scorecards, no frameworks, no evaluation rubrics. Just enough structure to prevent drift without turning the whole thing into theater.

The Conversations

One mentee showed up to their second session worried they were underperforming. Not on any specific task. Just a general anxiety about not being good enough, not learning fast enough, not contributing enough. The mentor shared their own story about imposter syndrome. They kept coming back to that thread over the next few sessions while also covering technical stuff. How do you tell the difference between actually underperforming and just feeling like you are?

By session 5, they’d covered the structured agenda and used the final meeting to just talk. They met in person that time. Career paths came up, and what actually matters long-term, and work-life balance. I’m curious how that conversation resolved, but I’m not part of these sessions. I only see what pairs choose to document.

Another pair spent an entire session mapping the org chart. Not the official one, the real one. Who actually makes architecture decisions? Who do you talk to when you need infrastructure help? Who knows why certain systems exist the way they do? This stuff doesn’t live in any documentation. It shifts every time someone changes roles or teams are reorganized.

A third pair had a 20-minute detour in their second session about falsehoods programmers believe about names. Edge cases, international character sets, all the assumptions we make that blow up in production. By session 4, they were talking about how to give code review feedback that actually helps without making someone feel terrible. The mentee walked away with a plan to raise task ambiguity in their team’s next retrospective.

The documentation turned out to serve a double purpose I didn’t fully anticipate. It helps pairs track their own evolution, sure. But it also creates institutional memory without needing someone to formalize it. New mentors read notes from previous pairs and see what’s actually possible. One pair investigated architecture testing tools and decided none of them fit. That documented failure is now a useful context for anyone else hitting the same question.

Twenty-Five Pairs Later

We’ve run 25 mentorship pairs at this point. Some of the past mentees are now mentors themselves. I never imagined the program would endure long enough for that to happen. We’ve expanded beyond interns to include all junior hires. The cross-product and cross-functional pairing continues. Those first 90 days still feel like the window that matters most.

The program has been valuable for the mentors, too. They practice one-on-one skills in a low-stakes environment, an early step in their leadership path. Explaining complex systems simply is harder than it looks. They get better at it. They remember what it’s like to be new, which helps them improve their own team’s onboarding. Mentee questions expose them to parts of the codebase they don’t usually touch. Gaps in documentation that experienced people don’t notice anymore suddenly become obvious.

Cross-product pairing creates what I later found out researchers call weak ties. An intern who spends 6 hours over 3 months talking to a mentor from another product builds a bridge that wouldn’t exist otherwise. Later, when they need help with an integration problem or want to understand how another team handles something, they have an actual person to ask. Conway’s Law always in motion.

Deliberately Incomplete

Every choice here involved trade-offs I couldn’t fully resolve. The 3-month window fits the critical adjustment period, but also just matches how long interns stay. Cross-product pairing builds bridges but sacrifices domain-specific technical mentorship. Light structure keeps people engaged but risks inconsistent execution. I chose these parameters deliberately, but I wouldn’t claim they’re universally right. They work for our specific context.

From Super Secret Project to Standard Practice

From “probably won’t happen” to standard practice took a few months, far less time than I thought it would. Low expectations helped. I didn’t promise transformation or measurable outcomes. The engineers who volunteered as first mentors turned that uncertain beginning into something that stuck.

Now it’s just how we work. New hires get matched. Past mentees become mentors. The first mentors were skeptical I’d pull it off, and I understand why. Programs like this usually collapse under their own complexity or drift when they ask too much. But they were wrong about one thing. Breaking down silos didn’t take massive effort. It took a meeting with a ridiculous title, a handful of people ready to try something uncertain, and the discipline to keep it simple.

Sometimes that’s enough.

Vassilis Poursalidis, TalentLMS Engineering Director
Vassilis has nearly 20 years of experience working in diverse projects in the technology industry, with a strong record of leadership and technical expertise. He is currently an Engineering Director …

Long gone are the days when a developer will walk across the entire stack. For years, software development has been moving toward specialization. We’ve carved ourselves into distinct tribes: infrastructure engineers who live in YAML and Terraform, architects who sketch systems in boxes and make decisions in ADRs, backend developers who speak in APIs and databases, frontend developers who breathe JavaScript and CSS, and QA engineers who guard the gates of production.

This specialization brought expertise. But it also brought something else: gaps.

The Gaps Between the Silos

These gaps are where projects slow down. They’re in the handoffs, the assumptions, the translation layers between team members and teams. They’re in the backend developer who builds an API without considering how the frontend will consume it. The infrastructure engineer who provisions resources without understanding the application’s actual needs. The QA engineer who writes tests disconnected from how the code actually behaves.

Each handoff is a game of broken telephone. Each specialized role is a potential bottleneck.

Enter Agentic Coding

This is where agentic coding becomes transformative, not as a way to create the mythical 10x developer, but as a way to bridge these gaps. AI-assisted development tools enable a different kind of developer: the full-stack generalist who can move fluidly across the entire stack.

Not because they’re superhuman, but because they have assistance.

The Bridge Builder, Not the Specialist

With agentic coding tools, a single developer can:

• Provision the infrastructure layer: spinning up containers, configuring cloud resources, setting up CI/CD pipelines; not as an infrastructure specialist, but as someone who understands enough to make informed decisions with AI assistance filling the knowledge gaps.
• Design coherent architecture: mapping out system boundaries, considering scalability and maintainability, with AI helping validate approaches and spot potential issues.
• Build backend services: implementing business logic, designing database schemas, creating APIs; with AI suggesting patterns, catching edge cases, and writing boilerplate.
• Craft frontend experiences: building interfaces that actually work with the backend they just created, because there’s no translation layer, no assumptions, just continuity.
• Think like QA: writing tests at every layer, shifting testing left (earlier in the development cycle) as much as possible, because they understand the full context of what could break and why.

Importantly, these bridge builders don’t vibe code and don’t work in isolation. They carefully review what AI suggests and always improve how they use those tools. They’re also supported by a network of evangelists, senior staff members, and domain experts who provide guidance, review architectural decisions, and help navigate complex technical challenges. The difference is that with AI assistance, these senior voices can focus on high-level guidance and strategic direction rather than being pulled into every implementation detail. The generalist can execute across the stack with AI handling the tactical work, while leaning on experienced colleagues for wisdom about patterns, pitfalls, and best practices that only years of experience can provide.

The Power of Context

The real advantage isn’t speed, it’s context. When the same person (with AI assistance) works across the stack, knowledge doesn’t get lost in translation. The API is designed with the frontend in mind because the same person is considering both. The infrastructure is provisioned based on actual application needs, not assumptions. Tests are written by someone who intimately knows the failure modes and has incorporated the appropriate logic in the development process.

Agentic coding tools make this possible by:

• Keeping you in focus: Instead of spending hours researching unfamiliar territory or waiting for a specialist to become available, developers can move forward immediately with AI assistance that understands the context of what they’re building.
• Providing on-demand expertise: need to write a complex SQL query with proper indexing strategies? Configure a load balancer with health checks and failover logic? Set up CORS policies that balance security and functionality? The developer doesn’t need years of specialization in databases, infrastructure, or security protocols. They need to understand the problem well enough to evaluate the solution, and AI bridges the gap between understanding and implementation.
• Maintaining consistency: when infrastructure configuration, backend logic, frontend implementation, and test suites all flow from the same contextual understanding, the result is a more coherent approach.

What makes this even more powerful is that AI can leverage context from across the entire development process. When building the frontend, the AI can reference the backend implementation you just created (understanding the exact shape of API responses, the error states that might occur, and the validation rules already in place). When writing tests, it knows the actual business logic from the backend and the user interactions from the frontend. When configuring infrastructure, it understands the actual resource needs based on the application code. This contextual awareness means each layer informs and improves the rest, creating solutions that are more coherent and robust than what emerges from siloed development.

Greenfield and Legacy: Two Sides of the Same Coin

For greenfield projects, agentic coding is remarkably effective. AI tools come equipped with knowledge of current best practices across the entire stack: modern framework patterns, security considerations, scalability approaches, testing strategies, and more. Starting from scratch, a developer with AI assistance can bootstrap a properly structured project in hours: infrastructure as code following current standards, a backend with sensible architecture, a frontend using modern patterns, and comprehensive test coverage. The AI doesn’t just generate code; it applies the collective wisdom of thousands of well-architected projects.

But here’s what makes agentic coding truly powerful: it works just as well with existing codebases. AI tools can analyze and understand the patterns, conventions, and architectural decisions already present in a project. They can be tuned to mimic the existing codebase style: the naming conventions, the error handling patterns, the testing approaches, and the architectural boundaries. When you’re adding a new feature to a five-year-old application, the AI doesn’t impose some idealized pattern from its training. It stays aligned with your project’s conventions, making contributions that feel native to the codebase.

This adaptability means the full-stack generalist can be effective whether they’re building something new or extending something that’s been running in production for years.

Not Replacing Specialists

As mentioned earlier, experts who provide guidance remain important. Deep expertise still matters. But it’s about recognizing that many projects don’t need ten specialists (they need many well-rounded developers who can bridge the gaps with AI assistance).

For startups, small teams, and rapid prototyping, this is transformative. For larger organizations, it’s about creating developers who can work across team boundaries, who can understand and contribute to multiple layers, who can see the whole system rather than just their piece.

Don’t get me wrong, I do not advocate that we need less specialists or less developers. On the contrary, I advocate to allow specialists to do more meaningful work and to give developers new powers.

The Skills That Matter

The full-stack generalist in the age of agentic coding needs different skills than before:

• Breadth over depth: understanding enough about each layer to ask the right questions, validate AI suggestions, and knowing when to call in specialists.
• Systems thinking: seeing how pieces fit together, understanding trade-offs across the stack.
• Critical evaluation: knowing when AI suggestions make sense and when they don’t.
• Communication: being able to speak the language of different domains, even if not fluent.

In a sense, the most important skills are problem-solving and the ability to communicate with fellow engineers.

The Future Is Bridge Builders

Software development is at an inflection point. Agentic coding tools aren’t creating 10x developers who work faster. They’re creating bridge builders who eliminate the gaps between specialized domains.

This new breed of developers won’t replace specialists. But they’ll change how teams are structured, how quickly products can be built, and how much overhead is lost to handoffs and translation.

The future isn’t about being the best backend developer or the best frontend developer. It’s about being effective across the entire stack; not through years of specialization in each domain, but through intelligent use of AI assistance that makes generalist competence not just possible, but powerful.

The gaps are closing. The bridges are being built. And the developers building them might just change how we think about software development itself.

When you combine all of the above (the elimination of silos, the contextual awareness across layers, the ability to work on both greenfield and legacy projects, the support from senior expertise), with the significant speedup that agentic coding offers, you get compound results.

It’s not just about doing more things; it’s about doing them faster, with better integration, and with higher quality. This convergence is giving rise to what we might call v2.0 of the Full-Stack Developer: someone who leverages AI to move seamlessly across the entire development lifecycle, producing cohesive solutions at a pace that would have seemed impossible just a few years ago. These developers aren’t superhuman, but they are transformative, and they represent the future of how software gets built.