Corey Duffy

Basketball-Driven Development

Mon, 12 Oct 2026 00:00:00 GMT

One of the perks of being a fully-grown adult, is that you can waste your own time and money however you want. A few months ago, I made full use of this perk. I saw a basketball net on sale as I was walking past a toy shop. Needless to say, I am now the proud owner of my own basketball net.

I’m no Michael Jordan, but I enjoy it. After a few months of practice, I’d say most of my shots are now finding the net. At least I don’t have to sheepishly ask the neighbours for my ball back as often.

I’m extremely lucky to be able to work remotely for my role. I’ve taken advantage of this set-up by heading out to the garden to shoot some hoops a few times during the working day. Not really when I’m stuck on a bug, funnily enough, but when my head just feels full. Usually after a long stretch of working with AI assistants, or in the middle of a big architecture planning or design session.

Death by a Thousand Decisions

Back in ye olde days, when I wrote most of my code by hand, a lot of the day was spent making things. I’d pick up a problem, get my head down, and work through it. It took a while, but it had a nice rhythm to it, and the decisions I had to make were a bit more spaced out. As I physically typed out the code, my brain could work away in the background on whatever else I needed to figure out.

Working with AI assistants has changed that. The assistant does a lot of the actual coding, and my job shifts towards planning, reviewing, and judging what it’s written. The decisions I have to make each day come at me thick and fast. Is this plan right? Are there any edge cases that I’ve missed? Should I really be adding that dependency? Why do these useless comments keep creeping in?

None of these decisions are particularly taxing on their own. But there are far more of them in a single day than there used to be, and they come at the speed of AI, not the pace I think. By mid-afternoon, I can feel the difference. I’m not necessarily tired from doing a lot, I’m tired from deciding a lot.

The Human in the Loop Is Tired

A popular concept when dealing with AI and LLMs is that of keeping a “human in the loop”. Maybe I’m just a bit of a control freak, but it’s something that I think is hugely important. I’ve written before about how critical it is to actually read and understand the changes your AI assistant makes. Personally, I want to ensure that I’m not committing to anything I can’t explain myself.

However, this only matters if the human in the loop is actually paying attention. When I’m tired, I’m not. After reading through an endless swathe of code for hours, I know how easy it can be to just give the next change a quick skim. It’s really easy to think “ah it’s probably fine”. I can find myself starting to trust the assistant’s summary of a change instead of actually inspecting the change itself. I can easily just accept things I’d have pushed back on at 10am, mostly because pushing back would mean yet another decision, and another loop.

That worries me. A tired reviewer ultimately just becomes a rubber stamp, the actual review becomes a checkbox exercise.

Get Your Head Out of the Game… to Get Your Head in the Game

When I find myself slipping into that funk, I head out to the garden and to my basketball net. Three to five minutes of missing free throws does two things for me.

The first is that it acts as a reset. For a few minutes there are no decisions to make, and I can clear my head. Then, when I come back in, I’m actually reading the changes again, rather than just skimming them.

The second is less obvious, but I think fairly well understood. I’ve found that my “best” thinking on a problem usually happens when I’m not actively thinking about it. For example, I’ll normally go out halfway through an architecture design session, not trying to solve anything in particular. After a few minutes of letting things simmer in the background, I come back with an answer to something I’d been going round in circles on.

Salvador Dalí used to nap in a chair holding a heavy key. As he dozed off, the key would drop and wake him, and he’d get back to work with whatever ideas had surfaced. Thomas Edison reportedly did something similar with steel balls. Obviously, I’m not a world-class artist or inventor, but if it worked for them, then hopefully it can work for me too.

There are a few studies that back this up. A 2021 study found that people who reached an early stage of sleep were far more likely to crack a hidden pattern in a maths problem. A Stanford study also found that people came up with about 60% more creative ideas while walking than sitting, and that boost lasted for a while after they sat back down.

Call a Timeout

As engineers, our way of working has changed. There are trade-offs, but when I use them properly, I’ve found that AI assistants do make my work better. However, our attention spans are finite, and we need to plan around this in the same way that we’d plan around any other limited resource.

For me, that means noticing when I’ve started skimming and taking that as the signal to step away, rather than push through. I’m learning not to start a big review or an important decision when I’m already running on empty. Part of that process involves not feeling guilty about spending a few minutes outside, because approving a bad change due to fatigue will ultimately cost far more than that.

It doesn’t have to be basketball. You can take a walk, go for a run, or play with the dog. Ultimately, I just think it’s important to have something that gets you away from the screen and gives your brain some respite from all of the decisions.

AI doesn’t get tired, but we do. Keeping a human in the loop only works if that human is fit to be there, so it’s important to look after yourself.

Now if you’ll excuse me, I have to go fish my basketball out of the neighbour’s hedge.

Pulling Out Weeds

Wed, 30 Sep 2026 00:00:00 GMT

I have an uncanny ability to kill any plant I come into contact with. This doesn’t bode well for the many house plants I’m trying (and likely failing) to maintain at home. However, sometimes this flaw can become a source of good.

I recently spent a weekend tearing up weeds in my garden. I’d been meaning to get round to it for a while (ever since we first moved), and by the time I did, they’d made themselves at home. They’d been there much, much longer than I had, and they put up one hell of a fight.

The thing about weeds is that they never announce themselves. Nobody plants them. They just creep in a little at a time while you’re busy with everything else. Then, one day, you look out the window and wonder how it got this bad.

Our codebases are no different. A while back, I inherited a codebase for an existing project. At some point over that project’s lifespan, the contractor who developed the application migrated it from one cloud provider to a completely different platform. The migration itself seemed to have went well. The application was running fine, pipelines were green, and everyone had moved on to the next thing.

In this new era of AI-assisted development, I have no doubts that the previous team faced pressure to get more and more features delivered quickly. Thus, nobody went back to remove the old code and infrastructure from the previous provider. What would be the point when they have 50 other features they need to get done this week? As a newcomer to the project though, I justifiably assumed that this dead code was still doing something. It took a lot of digging (and swearing) to eventually realise that it wasn’t.

Nothing to See Here

Semgrep, SonarQube and a lot of other static analysis tools don’t know or care whether code is actually running. They scan what’s in the repo, that’s their job. In this case, the static scanners kept raising vulnerabilities in the old code.

Every one of those findings has to be picked up by someone (in this case, me), traced back to code we’d stopped using, and then either fixed or suppressed. Obviously, fixing code that never runs is wasted effort. Suppressing it is arguably worse, because once a team gets used to waving findings through, it gets easier to wave through one that matters.

Thankfully, I was able to realise early on that the best way to get rid of these findings, and make the codebase more secure, was to start ripping it out. I could’ve just as easily wasted hours fixing security vulnerabilities in unreachable code “just in case”.

These static code scanners are just the most obvious example. Dependency alerts, search results and anyone new to the codebase all have the same problem. So do AI coding assistants, which will read old, unused code just as happily as the useful parts of your codebase, burning up a tonne of tokens and potentially polluting their context window in the process.

You might know the code is dead, but until it’s deleted, your tools don’t, and your readers don’t.

”For Now” Is a Lie We Tell Ourselves

I don’t think anyone left it there on purpose. The goal of the migration was to get the new platform live, and once it was, the migration felt finished. On to the next thing. No time to breathe.

There’s also a bit of nervousness about deleting code that used to run production infrastructure. What if something still depends on it? It’s easier to leave it for now, and remove it when we’re absolutely 100% certain that it’ll never ever be needed again. The trouble is that “for now” tends to last until somebody trips over it.

Too Big to Own

Dead code and tech debt have been around for as long as there have been codebases. Most projects that I’ve worked on have had a dark corner somewhere where the bodies were buried that nobody wanted to touch.

What has changed though, is how fast projects grow now. AI assistants make writing code almost free, and in the rush to be more and more productive, it’s easy to accept more than we can really keep track of. Each change may be small and look fine on its own, but it adds up. Before long, a lot of the codebase is code nobody has read closely enough to know whether it still matters. (I wrote more about this in How I avoid becoming a stranger in my own codebase.)

When code grows faster than we can look after it, we slowly stop owning it.

Finish the Job

The clean-up itself thankfully wasn’t difficult. However, in an ideal world, this pruning should be treated as part of the migration from day one, rather than a tidy-up for later.

The rate of delivery can feel relentless these days. However, these are the kinds of tasks that need dedicated time set aside, not squeezed in whenever there’s a spare moment.

If we just keep churning out more and more code, without refining what we actually need, it will come back to bite us eventually.

In this case, deletion belongs in the migration plan itself, not left as a tidy-up for later. Carrying out any removal in its own pull request (PR) helps too. Ideally, this deletion should be kept well away from feature work, since a PR that only deletes things is much easier to review, test and revert if needed.

In my mind, nothing really needs to be kept around “just in case,” either. Git remembers everything, so the code isn’t lost, just out of the way. You can always get it back if you’re using source control properly.

Now I Am Become Death, the Destroyer of Nettles

After a weekend of ripping weeds out of my garden with an underpowered hedge-trimmer, I had to confront what I’d always known deep-down to be true. The longer I’d put this off, the harder it became when I eventually did get around to tackling it.

AI is going to keep making our codebases grow faster. And that’s fine, as long as someone is still doing the weeding. Regularly.

Eternal Sunshine of the Spotless Model

Sun, 16 Aug 2026 00:00:00 GMT

There are some things we just know.

They’re ingrained in our memories, and whether we like it or not, we just can’t scoop them out of our brains. For example, if anyone’s seen the movie Hereditary, there are multiple scenes (I won’t spoil which if you haven’t seen it) that will stay with me until I die, no matter how much I would very much like to forget them.

This also holds true for LLMs, which can be problematic when you’re working in regulated industries, when you need to fulfil someone’s right to be forgotten, or if it’s somehow learned some deeply embarrassing personal secrets about you.

Don’t You (Forget About Me)

An AI agent broadly retrieves and recalls data in the following ways…

The first is via external memory; a database, blob storage, a text file, anything that an AI agent has to query and pull information from. For us human-folk, an example of this type of memory or storage would be an address book, or a list of contacts on our phone. It’s information that we can look up whenever we need it, but it’s not necessarily something we can just easily recall. An agent doesn’t actually know any of this information, it looks it up. In the same way I don’t know my partner’s phone number, or our anniversary, or… actually, let me stop there. This type of memory is where an agent keeps anything personal or likely to change.

Then there is cache memory. It’s essentially our short-term memory, like when we need to memorise a phone number for a short while before we find a pen and paper to write it down. This memory normally clears after a certain period of time, or when we end a chat session for example. After a while, the memory/data just disappears, like how I’ll forget someone’s name approximately 5 seconds after they tell me for the first time.

Finally there is in-weight memory, this refers to all of the data baked into the model itself during training. Nothing gets looked up here, it’s all been learned. This data has been scattered across billions of tiny numbers and layers within the model until it’s part of how the model itself “thinks”. For example, if I asked you to complete the phrase “Practice makes …” your brain might automatically complete the phrase “Practice makes perfect” without you having to do any real deep thinking.

This is essentially your own “in-weight memory”. It’s what you know that you don’t need to look up, and it’s what’s very very very hard to forget.

Let’s play this out; let’s consider Logan. Logan is extremely privacy-savvy, and he’s asked us to delete everything we hold on him from our agentic system. From the interactive demo below, try deleting his data from our external store. Then, we’ll fine-tune a model on his details and try the exact same thing again.

◆ try it

Looks like this interactive demo didn’t load, please try enabling JavaScript. It would have walked you through this:

We're asked to delete Logan's data from a database, and the deletion just works. The record is gone, and asking our model for information about Logan turns up nothing.

However, when we try to delete the same data once it's been trained into the model's weights, nothing happens: there's no record to remove, and the model will still answer questions about them. From here, there are two options: cheap machine unlearning, which is fast but leaves the weights leaking traces of what it just erased, or a full retrain from scratch, which works but costs a huge amount of time and resources.

Delete, Done, Dusted

Luckily, that first delete just worked. Logan’s data was a single row you could point at, you removed it, and now the agent draws a blank when you ask. It’s like ripping a page out of a notebook and shredding it; once it’s gone, it’s gone. This means that deleting Logan’s personal data in this case is straightforward.

Can’t Touch This

But the second you fine-tuned the model on Logan, that same delete isn’t really possible. There’s no row left to remove. His details aren’t in a specific location that you can just get rid of, they’re scattered across millions of parameters, tangled up with everything else the model has ever learned.

“Deleting” this data now means inherently changing the model itself.

Just like we can’t consciously “delete” memories that are ingrained in our brains, we can’t force an LLM to outright forget what it knows. The information is part of it’s very fabric.

What we can do, is retrain the model from scratch, or try some machine unlearning. However, retraining is slow and expensive, and unlearning hasn’t yet been shown to be reliably effective.

Only full retraining actually guarantees that the data is gone; the cheaper methods estimate a data point’s influence and subtract it, which is an approximation that can leave traces behind. So if you ask where Logan lives in a slightly different way, or particularly nicely, the model might just tell you. For example, researchers recovered over half of supposedly forgotten content from a model by simply by padding the prompt with filler text (Jang et al.). Much of what passes for unlearning teaches the model to decline the question, not necessarily to forget the answer.

Not only that, but the unlearning process itself can ultimatlely provide an attack surface. Given a model’s parameters before and after machine unlearning, researchers were able to recover the features and labels of the very data that was supposed to have been “forgotten” (Hu et al.).

Total recall

When building an agentic system, we have to be deliberate and considerate about how data enters our model(s), because that choice determines whether or not the data can ever really leave again. When we question “should we fine-tune a model?”, we should also ask “what kind of data would we be training it on, and do we need it to be forgotten at some point?”.

Making the wrong choice here can lead to permanent regret, which is ultimately why I’ve still never gotten a tattoo, despite threatening to for years. It’ll be any day now. Maybe a dragon, or a tiger, or my dog, we’ll see.

Suggestions welcome.

A Commentary on Code Comments

Fri, 14 Aug 2026 00:00:00 GMT

If there’s one thing LLMs seem to love, it’s padding out code with unnecessary comments and docstrings.

This post may come across as an old-man-yells-at-cloud-style rant but it’s a trend I’ve noticed, and in my eyes, it’s actively making codebases harder to read and maintain. Here’s why.

War and Peace

To me, code that’s easy to read and maintain is code that is self-documenting. By that, I mean it’s well-structured, doesn’t try to do too much at once, and uses clear, descriptive names throughout (easier said than done, I know).

If your code is already well written and structured, adding comments that re-state what it’s doing, or docstrings that just restate parameters and return types, is just noise. It’s unnecessary fluff that someone needs to scroll through to get to the line of code that they’re looking for.

If you feel you need comments to explain what your code is doing, that may be the first sign that it’s too convoluted or complex.

The Simpsons Movie (2007)

Liar Liar

The only constant in software engineering is change (truly, I am a glorious “thought leader”). As you find bugs or add new features your actual code will change, because it has to.

Comments however, can easily be missed because they don’t do anything. It’s harder to spot when a comment should be updated because there’s no measurable impact. There’s generally no test suite that fails, and no screaming product manager if it isn’t updated in time.

This means that your comments and your code can often get out of sync. Your comments can end up lying to the reader about how your code actually behaves. Life as a software engineer is already hard, let’s not make it any harder than it has to be by lying to each other.

Taking Up Tokens

More comments also mean more text for an LLM to read through when it’s trying to understand your codebase. If you’re using a coding agent to help navigate existing code, then every comment it processes are tokens spent decyphering noise rather than signal.

Ironically enough, the same tool that will happily spit out fifty lines of docstrings is now also having to wade through those same fifty lines every time you ask it to make a change. If any of those comments are out of date, you’re only wasting tokens and feeding your model misinformation.

The Vibe(Code) Check

There’s something about an abundance of comments through code that just makes me trust it a bit less. This could be completely unwarranted, but when I see a pull request that’s riddled with what are clearly AI-generated comments, I’m immediately a bit more sceptical of it.

I think I feel a bit uneasy because it indicates that the author may not actually have read a lot of the code themselves. It gives off a sense of “ah, that’ll do”, a sense that someone hasn’t dotted all the i’s and crossed all the t’s.

Again, that may be completely unfair, but it’s something I can’t quite shake.

Why, Not What

There’s always exceptions, I’m not an out and out anti-comment zealot.

Comments are genuinely useful when they’re used to describe why a decision was made. This isn’t necessarily something that can be understood by reading the code alone.

When comments are used to explain a non-obvious reason behind an implementation, or some business logic then they do actually provide value, both to humans and to the AI agents who need to get an understanding of the code.

For example, something like this could justify its place in a codebase:

# We deliberately don't retry on 429 here, the upstream rate limit resets
# monthly and retrying would just queue up failures for 30 days.
if response.status_code == 429:
    raise HardFailure()

Same Old Story

Of course, none of this is new or revolutionary territory. The argument against over-commenting has been made countless times before. What has changed is that LLMs have made it dramatically easier to generate noise at scale, and I think more and more people are starting to mistake that noise for thoroughness.

How I avoid becoming a stranger in my own codebase

Mon, 22 Jun 2026 00:00:00 GMT

I’ve been leaning on AI coding assistants pretty heavily for a while now. Tools like Claude Code and the like can churn out a huge amount of code in an alarmingly short amount of time. This is obviously great in a lot of ways, and the magic of LLMs makes my life infinitely easier day-to-day, if I look past the existential dread of just how capable AI is at a formerly large part of my job.

But it isn’t all great. With great power comes great responsibility, and with great AI adoption comes an overwhelming amount of output to digest, code to review, and (at times) mind-numbing documentation to read. With the accelerated pace of AI-assisted development and the push towards greater and greater “productivity” gains (Gotta love the “My multi-agent setup made me a 100000X developer. Here’s How.” threads), it can be so easy to get swept along in the rush and find yourself in unfamiliar territory.

It’s never been easier to become a stranger in your own codebase, not quite sure how you got here or what this OrchestrationInterfaceFactoryImplementerService is for, but it’s way too late to turn back now.

And therein lies the problem. These tools have made writing code almost free. The trouble is that they’ve also moved the cost somewhere else, onto reviewing, understanding, and being responsible for its outputs. If I’m not careful, the work now lands faster than my brain can naturally absorb it, and I can end up lost at sea.

So this is how I try to keep the robots in check, or really, how I try to keep my own cognitive load in check while letting them do their thing. This is entirely my own approach to wrangling AI assistants, I’m definitely not claiming it’s the best way to do things, but it’s what’s working for me at the minute. I’d love to hear more about your workflow or approach too.

Measure Twice, Cut Once

As I learned the hard way when I set about building some fencing for my house and accidentally bought enough wood to fence off the entire estate, the cheapest place to prevent a mess is before the actual work begins.

Check the Spec

Previously, I had been a big proponent of Claude Code’s plan mode for any kind of complex task. More recently, I’ve adopted a more thorough spec-driven development approach. I use OpenSpec in particular.

Rather than handing over a vague one-liner and hoping for the best, I start by getting an assistant to lay out a plan or a spec first, get it to question my decisions and find missing details, agree on what we’re building and how, and only then let it start getting to work. This works for me for a number of reasons:

It forces me to actually think about what I really want to produce in detail, without rushing in and making a mess.
It keeps a record of my decision-making process. It documents why I’ve made the decisions I have, what the considered alternatives were and why things have been done in a certain way. This makes it easier for me to get back into the headspace of the project when I’ve taken a break for a while.
It gives me something concrete to review the output against. Reviewing a diff against an agreed plan is a world away from reviewing it against a vague feeling of whether it looks about right.

That’s the way uh-huh, uh-huh I like it

Beyond planning each task, I also encode my standards, coding style and preferences once rather than re-explaining them every five minutes. Most of these tools let you drop in a file of persistent instructions (e.g. Claude Code uses a CLAUDE.md at several levels), where you can spell out your conventions, your preferred libraries, the things you never want it to touch, etc. It means the assistant starts inside the guardrails instead of me having to herd it back behind them on every single task.

It’s a bit of effort up front to save myself repeating the same frustrated corrections and disappointed sighs later on. Whether or not these coding assistants are great at sticking to these guardrails is a separate matter, but I at least try to keep them in line.

Keep things small

When I write code, I do my utmost to keep any pull-requests I make small and self-contained, mostly so my team won’t shout at me. These conventional development best-practices apply to AI-assisted development too.

It’s tempting to ask for the whole feature in one go, but a 600-line diff is a diff that’s much easier to just rubber-stamp, because reviewing it properly is exhausting and the robot knows I’m tired. With a 40-line change, I can actually read and understand it quickly. Keeping each task narrow keeps the cost of checking it low, and keeps the blast radius small when it inevitably does something daft.

Stay in the race

Now that my plan/spec is generated it can be so tempting to just let the genie out of the lamp and come back when it’s magicked up my code. Personally, I’m just not ready to hand over the reins entirely yet. There’s a number of reasons for this, maybe I’m just a control-freak, but mostly I feel like if I stay engaged in the process then the final outcome is just better. I can explain things easier, the code makes more sense to me, and I just understand more. So this is how I keep engaged while my coding assistant does the heavy lifting.

Learn to read

First, and I cannot stress this enough (to myself more than anyone), actually read the plan. If you’ve gone to the trouble of getting the assistant to write a spec, it’s a special kind of self-sabotage to then wave it through without reading it thoroughly. The plan is your one chance to catch a bad idea before it becomes a thousand lines of confidently bad code.

Then, I read the diff. Every time. The plan tells you what the assistant meant to do, but the diff tells you what it actually did, and those two things drift apart far more often than you’d like. This gap between intent and execution is where a lot of gremlins live. An assistant will happily tell you it’s made a small, surgical change and then quietly refactor three files you didn’t ask it to touch. Personally, I don’t even let Claude add or commit files for me. I like having the chance to manually inspect what files it’s made changes to before anything gets committed to a branch, it keeps me engaged throughout the process and gives one more touch-point where I can catch anything going off the rails and course-correct.

Take responsibility

I try to keep a human, me, in the loop on the decisions that actually matter. The assistant is great at the how, but I don’t outsource the what or the why. Architecture, trade-offs, anything I’m going to have to live with for the next two years, those are mine. Letting a tool make decisions you’ll be maintaining long after the session ends is a quick route to a codebase nobody understands. This obviously applies at the planning stage, but it can also apply throughout the actual implementation stage too. If I see that Claude is about to bolt a whole new library onto the project to save itself five lines, or restructure something that was working fine, that’s a decision, not an implementation detail, and it’s one I want to make myself. It’s probably a cliché at this point to say that AI is a tool, just like any other, but that is how I approach it. I’ll entrust it with some of the execution, but I won’t hand over the decision-making.

And the rule that ties all of this together: don’t commit to what you can’t explain. I may use AI assistants to generate code, but at the end of the day, it’s still my code. I have to stand-over it, and I have to be able to traverse it and fix it if something goes wrong. Generally, you’ll catch the code that doesn’t work out of the box. The hidden danger lies in the code that does work but that you don’t actually understand, quietly accumulating until the codebase stops feeling like yours. This is essentially cognitive debt, and it’s every bit as nasty as the technical kind.

Who watches the watchmen?

At the end of the day, I am only human, after all. There will always be the chance that I miss something or get something wrong (likely a very high chance in my case). This is a problem that pre-dates AI assistants. So wherever I can, I get other machines to do the watching for me.

Tried and true

I love old-fashioned deterministic checks. Tests, linters, type checkers, formatters, pre-commit hooks. None of this is new or exciting, but that’s kind of the point. Traditional best practices still apply to this new AI-enabled world. If they’re set up correctly, these checks fail loudly and consistently, every single time, without me having to remember to be vigilant. An AI assistant might write a plausible-looking function that quietly breaks an existing test or key feature, and I’d far rather a red CI run tell me that than my users. Good test coverage and a strict linter act as a second line of defence against AI slop. Unlike me, they will never get tired, they will never get overwhelmed with a huge sea of changes and they will never get talked into “accept all” by a smooth-talking AI assistant.

Stop hitting yourself

It can also be fun to turn your AI coding assistant against itself. At key points throughout the decision-making and implementation process I will prompt my assistant to review its own code or suggestion. But the secret sauce is that I ask it to review its own work as a panel of grizzled senior engineers who absolutely HATE the current approach. This forces your assistant to be critical, sometimes too critical, of its own work and offers a fresh perspective. Again, I don’t just blindly trust the outcome of this hostile review, but it does often give me some new approaches or changes to consider. This can even be wrapped into its own skill or command to make things that much quicker.

Sidenote on speed

Just as an aside, the faster these checks run, the less I have to carry in my head between one step and the next. Slow tests and a sluggish pipeline don’t just waste time, they force me to hold more state in my own brain while I wait, which is the very thing I’m trying to offload.

Know when to get your hands dirty

I think another thing to remember is that not everything needs AI. Sometimes the change is small or fiddly enough that it’s genuinely faster to just write it myself than to explain it, review it, and correct it. Making that call, rather than reflexively reaching for an assistant, keeps me close to my own codebase. It keeps me tuned in to the effort involved in any change, and the current lay of the land.

Keeping the robots honest

All this being said, I love AI coding assistants, and they’ve genuinely changed how I work. But loving them and letting them run the place unsupervised are two very different things. For example, I love my dog, Millie, but I’m not going to leave her unsupervised with my dinner on the table (again).

The whole game is making sure that you remain the person in charge of your own codebase, rather than becoming a stranger to the very code you’re shipping. And so, these habits are just how I personally try to stay in the loop, instead of buried underneath a mountain of changes. It’s my way of keeping the robots honest, and hopefully, keeping myself honest too.

What to do when your knowledge agent doesn't seem so knowledgeable

Sun, 14 Jun 2026 00:00:00 GMT

I’ve worked on a number of knowledge agent projects now. At some point during the development process, when users finally get their hands on their shiny new AI tool to test it, I might hear some variation of the following:

“Oh… uhh… it should know that.”

“That’s not right, why is it saying that?”

“It should know that, it’s on our website.”

“That doesn’t sound right…”

Much like with humans, sometimes it’s hard to know why a knowledge agent does what it does, or what it knows and doesn’t know.

In this context, by knowledge agent, I’m referring to an LLM-backed system with agency to make decisions on how to answer user queries. This might involve retrieving knowledge from a knowledge base via Retrieval-Augmented Generation (RAG), making tool calls to obtain useful information from an external system or environment, or some combination of all of the above.

When a knowledge agent I’ve been working on suddenly doesn’t seem so knowledgeable, this is generally how I go about troubleshooting.

Is the answer actually available?

Step one in the process for me normally involves figuring out if the information to answer a user’s question actually exists somewhere, and if the knowledge agent has access to it. This information could be buried in a knowledge base, or returned from some external tool call, but it must exist somewhere. Not just in a customer’s head.

It’s a bit like asking me when a family member’s birthday is - if I can’t open my Calendar app and check, then I have no idea (sorry Mum, I know it’s sometime in July).

If the answer doesn’t exist somewhere that the agent can pull from, then it’s going to either decline to answer, or worse, make something up.

To fix this, we update the information available to the agent and retest.

If, however, the answer does exist somewhere that the agent should be able to read from, then we move on to step two.

Why isn’t it getting the right context?

So we know that the answer is out there somewhere, lurking in the depths, and the agent has access to it in principle. However, our agent still just can’t seem to give the right answer. There are a few usual suspects that could cause this:

Firstly, knowledge bases are usually broken into chunks before they’re indexed. If a piece of information is split across two chunks, e.g. half of the required information in one chunk and the other half in another, then retrieving either one on its own gives the agent half a picture. Choosing the correct chunking strategy for your use case is a whole article in itself that I’ll not go into here, but adjusting your chunking approach to use larger or overlapping chunks, chunking semantically or pulling in surrounding context once a match is found, can help stitch the full picture back together and lead to better answers.

Secondly, even when the right chunk exists, retrieval might simply miss it, like me trying to find my keys anytime I’m late and trying to get out the door. With RAG, an agent searches the knowledge base using some representation of the user’s query, and pulls back the chunks it thinks are most relevant. But “most relevant” can be hard to determine. If a user phrases their question differently to how the source material is written, the right chunk simply may not rank highly enough to make the cut. Fixing this usually means giving retrieval a better shot at the match, maybe by revisiting your embedding model, adding a reranking step, or rewriting the user’s query before you search so it lines up more closely with how the source is actually worded.

Thirdly, maybe the agent just didn’t go looking in the first place. With tool-calling agents, retrieval isn’t necessarily automatic, the agent has to decide to make a call and to where. If the agent doesn’t recognise that the question needs an external lookup, it’ll happily answer from whatever it already has in context, and you’ll get a confident, but more than likely wrong answer. The issue here normally lives in your tool definitions/descriptions and your prompts. Making it clearer when and why a tool should be used, and giving the agent permission to admit when it doesn’t know, tends to nudge it towards looking things up rather than guessing.

Finally, maybe the right tool was called, but with the wrong arguments. Even when the agent does reach for a tool, it might query it badly. It could use the wrong filter, wrong date range, or wrong customer ID. This will likely lead to an external system returning nothing, or returning something completely irrelevant. Tightening up your tool’s schema, being more strict about what each argument expects, and giving the agent a few examples of correct usage all go a long way here.

When trying to untangle any of these causes, the key is traceability. When developing agents, I always ensure that I can follow as much of its thinking as possible - what did it retrieve? Did it make any tool calls? What arguments did it use? Normally, if I can lay this out in front of me, I’ll be able to figure out roughly where things went sideways.

If the right context did make it into the agent’s hands, and it still got the answer wrong, then we’re onto step three.

Why isn’t it using the context properly?

This is the fun part, because it looks like everything upstream worked. The answer existed, retrieval found it, everything is queued up for success, and like Gabriel in the 2026 Champions League final, our agent just can’t finish the job (sorry gooners).

A handful of things may be going on here:

There’s too much context, and our agent can’t see the forest for the trees. It’s tempting to think more context is always better, but agents can and do lose track of relevant details buried in a wall of retrieved text. If you stuff twenty chunks into the prompt to be safe, the one that actually mattered can get drowned out by the nineteen that didn’t. Likewise, if you’ve had a long conversation with a knowledge agent, and that history/context hasn’t been condensed adequately, the knowledge agent’s brain may simply be too fried to think straight. The fix is usually to be more selective rather than generous here. Retrieve fewer, higher-quality chunks, and summarise or trim the conversation history so the signal isn’t drowned out by noise.

Another cause may be that the context contradicts itself. If the knowledge base contains two versions of the truth, say an outdated policy and the current one, the agent has no reliable way of knowing which to trust. It might pick the wrong one, or awkwardly try to reconcile both. This is less an agent problem and more a knowledge hygiene problem, but our poor knowledge agent will get the blame. Here we may need to look at the source. We can likely improve our knowledge agent’s answers by pruning stale documents, deduplicating, and making sure there’s a single, clear version of the truth for the agent to find.

The instructions and the context could also be fighting. Sometimes the system prompt tells an agent to behave one way and the retrieved content pulls it another. The agent is left trying to serve two masters and does neither well. Untangling this usually means being explicit in the prompt about what wins when they clash, for example, telling the agent to always defer to the retrieved source material over its own assumptions.

Maybe it’s also just a hard reasoning step. Occasionally the information is all there for an agent, but answering correctly requires it to combine several facts, do a bit of arithmetic, or make an inference. Some questions are just harder than others, and a model that nails simple lookups can still trip over multi-step reasoning. Giving the agent some room to think can help here. This may involve encouraging some step-by-step reasoning, breaking the task into smaller pieces, or reaching for a more capable model when the question genuinely warrants it.

Turns out it should know that

I suppose the takeaway here is that as an engineer, we aren’t entirely at the mercy of the mysterious AI box whenever we don’t get the answers that we’re looking for from our agents. Like most problems with software, there’s a logical set of steps we can walk through to try and make our knowledge agents sound a bit smarter. Almost smarterer than me.