Matthew Boston

Building a Platform Is a Balancing Act

2026-04-21T00:00:00+00:00

Two Kinds of Dead Platforms

The first kind of dead platform is the one that said yes too often. Every team got their special flag, their bespoke deployment path, their one-off integration. From the outside it looks like a platform. From the inside it’s twelve platforms duct-taped together, each maintained by someone who left two years ago. Changes take weeks because every change risks breaking someone’s snowflake.

The second kind of dead platform is the one that said no too often. It had a clean abstraction, a beautiful API, and exactly three users — because every other team found it faster to build their own thing than to wait six months for a feature request to land. The platform team is still shipping. Nobody’s using it.

Both failures start with the same moment: a team shows up with a request that doesn’t fit. What you do next is the whole job.

The Pull Toward Yes

Saying yes feels good. It makes a user happy today. It proves the platform is “flexible.” It avoids the awkward conversation where you explain why their very reasonable-sounding request is actually going to cost you six months of maintenance burden.

But every yes is a promise. Not just to ship the feature — to support it, document it, migrate it, and keep it working when the next version ships. A platform with a hundred features has a hundred promises. Most of them will outlive the person who made them.

The teams asking for custom behavior aren’t wrong to ask. They have real problems. The mistake is treating every real problem as something the platform must solve in the shape the user proposed.

The Pull Toward No

Saying no feels principled. It protects the abstraction. It keeps the surface area small. It lets the platform team sleep at night.

But a platform that only solves the problems its designers anticipated isn’t a platform — it’s a framework for the problems that already existed when it was built. Real users have real needs that weren’t in the original design doc. Refusing to evolve is just a slower way of dying.

“No” is also expensive in a way that doesn’t show up on the platform team’s dashboard. It shows up as shadow infrastructure, forked repos, and the quiet realization that half the company has stopped using you.

Snowflakes Aren’t Snowflakes

Here’s the pattern I’ve seen over and over: the “unique” request isn’t unique. The team asking for a custom retry policy is the third team this quarter to ask for one — they just phrased it differently. The team that needs a special deployment hook has a problem that’s one config flag away from the team that asked last month.

Snowflakes feel unique to the person holding them. From the platform’s vantage point, they almost always cluster. Two requests are a coincidence. Three requests are a feature. Five requests are a design flaw you haven’t fixed yet.

This is the same Rule of Three that keeps you from over-engineering on day one. It also keeps you from under-engineering on day three hundred. The first request is a conversation. The second is a pattern forming. The third is a signal that the platform is missing something real.

The Real Job: Finding the Pattern

The job isn’t saying yes or no. The job is translation.

When a team shows up with a custom request, the first question isn’t “should we build this?” It’s “what’s the general shape of this problem, and how many other teams have it?” The answer determines the response:

Truly one-off: Help them solve it outside the platform. Not every problem belongs to you.
One of a few: Say no for now, but track it. Two more and you have a pattern.
Recurring: Build it into the platform properly. Not as a flag for this team, but as a first-class capability everyone can use.

The worst answer is the middle path that looks like a compromise: a special flag, a hidden config, a “temporary” exception that becomes permanent. That’s how platforms accumulate the snowflakes that kill them.

Abstractions Earn Their Keep

Good platform abstractions don’t come from whiteboard sessions. They come from watching three teams solve the same problem three different ways and extracting what’s common. You can’t design that upfront — you have to earn it through contact with real users.

Which means the platform team’s instinct to protect the abstraction is right and wrong. Right, because abstractions are load-bearing. Wrong, because abstractions that never evolve become museums. The abstraction you shipped last year was based on the problems you understood last year. The problems got more interesting. The abstraction should too.

Yes, No, and Not Yet

The most useful word in a platform team’s vocabulary isn’t yes or no. It’s not yet.

“Not yet” says: I see your problem, I believe it’s real, and I’m going to wait until I see it from enough angles to build the right thing instead of the fast thing. It’s harder than yes. It’s more honest than no. And it’s the only answer that scales.

Platforms die when teams stop being willing to say any of the three. Yes-only platforms collapse under their own weight. No-only platforms get abandoned. Not-yet-only platforms become irrelevant. The balancing act is knowing which answer this request — and this moment — calls for.

The platform that lasts is the one where every yes was earned, every no was explained, and every not-yet eventually turned into one or the other.

]]>

Don't Just Build with AI — Learn Through It

2026-04-14T00:00:00+00:00

The Default Mode Is Wrong

The typical workflow with an AI coding agent goes like this: describe the feature, let the agent generate code, review the output, ship it. It works. But it skips the most valuable step – understanding why the codebase looks the way it does.

When you’re onboarding to a new codebase, the temptation is to let the agent handle everything you don’t understand yet. Need to add a feature in an unfamiliar module? Let the agent figure out the patterns. Don’t know the naming conventions? The agent will match what’s already there. This gets you to a working PR, but it doesn’t get you to understanding.

And without understanding, you’re going fast in the wrong direction.

Pair Programming with Infinite Patience

Here’s what I do instead: I use the agent as an interrogation partner. Before asking it to write anything, I ask it to explain things.

Why is this module structured this way?
What design pattern is this service using, and what problem does it solve?
Why does this test mock this dependency but not that one?
What would break if I changed this interface?

No human pair partner has the patience for this many questions. An AI agent does. It’ll explain the same concept ten different ways without sighing. It’ll trace a function call through six files without losing track. It’ll compare two approaches and explain the tradeoffs of each without checking the clock.

This is pair programming without the social cost of asking “dumb” questions.

Ask for Architecture, Not Just Implementations

The questions that build real understanding aren’t about syntax or APIs. They’re about decisions. Every codebase is a fossil record of choices – some deliberate, some accidental, some inherited from a framework the team adopted three years ago. Understanding those choices is what separates someone who can modify the code from someone who truly knows the system.

Ask the agent to explain the architecture. Ask why the team chose this database over that one. Ask what the test strategy is and whether it’s consistent. Ask about the error handling patterns and whether they match across services.

This is the research phase applied to your own learning – and it compounds just as fast. Every question builds context. Every answer connects to the next question. Within a few sessions, you’ll have a mental model of the system that would have taken weeks to build through code reading alone.

The Learning Compounds

There’s a second-order effect here. Once you understand the codebase deeply, you become a better collaborator with the agent. You write better prompts because you know the vocabulary. You catch mistakes faster because you know the patterns. You capture what you learn in SKILL.md and CLAUDE.md files, which makes the agent smarter in future sessions.

Understanding begets better tooling begets faster understanding. It’s a flywheel – but only if you invest in the learning side, not just the building side.

Understanding Is the Job

The engineers who get the most from AI aren’t the ones who delegate the most. They’re the ones who learn the most. Every question you ask the agent is an investment in your own judgment – the one thing AI can’t replace.

Don’t just use AI to write code you don’t understand. Use it to build understanding you couldn’t get any other way.

]]>

Speed Is Only Useful If You're Going in the Right Direction

2026-03-31T00:00:00+00:00

The Velocity Trap

There’s a seductive metric in software engineering: how fast can we ship? Teams measure cycle time, deploy frequency, and lines of code per sprint. AI tools promise 100x productivity. And all of it assumes that going faster is inherently better.

But velocity is a vector. It has magnitude and direction. A team shipping features at breakneck speed toward the wrong goal isn’t productive — they’re accumulating debt they don’t even know about yet.

Fast in the Wrong Direction

I’ve seen teams build entire systems in weeks using AI-assisted tools, only to realize they solved a problem no one had. The code was clean. The tests passed. The architecture was sound. And none of it mattered because they started building before they understood what they were building for. This is the same dynamic behind the Research-Plan-Implement discipline — a bad line of research sends everything downstream in the wrong direction.

Speed amplifies whatever direction you’re already headed. If your direction is right, speed is a superpower. If your direction is wrong, speed just gets you lost faster.

The Cost of Rework

Rework is the tax you pay for moving fast without clarity. And it’s not just the time to redo the work — it’s the opportunity cost of what you could have built instead, the morale cost of throwing away effort, and the trust cost when stakeholders see the same problem “solved” twice.

A team that spends two days thinking and three days building will almost always outperform a team that spends five days building and then five more days rebuilding. The math is simple, but the discipline is hard.

Direction Comes from Asking Better Questions

The fastest way to go in the right direction is to slow down at the beginning. Not permanently — just long enough to answer the questions that matter:

What problem are we actually solving? Not the technical problem. The human one.
How will we know it’s solved? If you can’t define success, you can’t measure it.
What’s the simplest thing that could work? Complexity is easy. Simplicity requires understanding.
What are we choosing not to build? Every yes is an implicit no to something else.

These aren’t planning ceremonies or process overhead. They’re the cheapest investment you can make in avoiding expensive mistakes.

Speed as a Reward, Not a Goal

Speed should be the result of good direction, not a substitute for it. When you deeply understand the problem, the constraints, and the desired outcome, fast execution follows naturally. You make fewer wrong turns. You write less throwaway code. You spend less time in meetings debating decisions that should have been made upfront.

The teams I’ve seen ship the fastest over the long term aren’t the ones that type the fastest. They’re the ones that think clearly before they start typing. They review the outcome, not the output — and that clarity is what keeps them pointed in the right direction.

AI Makes This More Important, Not Less

AI tools make it trivially easy to generate code, scaffold systems, and spin up prototypes. That’s remarkable — and dangerous. When the cost of building drops to near zero, the cost of building the wrong thing becomes the dominant expense.

The bottleneck was never typing speed. It was always understanding — which is why code was never the goal in the first place, and why using AI to learn, not just build, pays off more than raw speed ever will. AI didn’t change that. It just made the consequences of poor understanding more visible, because now you can build the wrong thing in an afternoon instead of a quarter.

Invest in direction first. Speed will follow.

]]>

Review the Outcome, Not the Output

2026-03-26T00:00:00+00:00

The Old Review Model Is Breaking

Code review used to mean reading diffs line by line. You’d check variable names, spot off-by-one errors, argue about formatting, and verify that the logic matched the spec. This made sense when a human wrote every line. If a human chose it, a human should verify it.

But when an AI agent writes the code, line-by-line review stops making sense. That doesn’t mean quality stops mattering — it means the way we verify quality has to evolve. The agent didn’t choose that variable name because it was tired or because it has a bad habit. It followed a pattern. Nitpicking its syntax is like copy-editing a compiler’s output. You can do it. You just shouldn’t.

Output vs. Outcome

There’s a distinction that matters here. The output is the code — the diff, the lines changed, the files created. The outcome is what changed in the system’s behavior. Did the bug get fixed? Does the feature work? Did performance improve? Is the user’s need met?

When you review output, you’re asking “is this code correct?” When you review outcomes, you’re asking “did this change accomplish its goal?” The second question is harder, more valuable, and the one only a human can reliably answer.

An agent can generate twenty different implementations that all pass the tests. Most of them are fine. Some are better than others. But whether the feature should exist at all — whether it solves the right problem, fits the architecture, and serves the user — that’s judgment. That’s yours.

What Outcome Review Looks Like

Outcome review isn’t less rigorous than line-by-line review. It’s differently rigorous. Instead of scanning for syntax errors, you’re evaluating:

Intent alignment. Does this change match what was actually requested? Agents are good at following instructions literally. They’re bad at questioning whether the instructions were right.
System impact. How does this change interact with the rest of the codebase? Does it introduce coupling that will hurt later? Does it respect existing boundaries?
User impact. Does the end result actually improve the experience? A technically correct change that makes the product worse is still a bad change.
Test coverage. Not “did the agent write tests” but “do these tests verify the thing that matters?” An agent will happily generate tests that pass without testing anything meaningful.

This is the work that requires understanding the business, the users, and the system’s history. No agent has that context. You do.

The Judgment Shift

As AI handles more of the production work, the human role shifts from author to editor, from implementer to evaluator. This is the same shift I explored in Code Was Never the Goal — the craft was always about judgment, not keystrokes. This isn’t a demotion. Editing is harder than writing. Evaluating is harder than implementing. Knowing whether something should be done requires more skill than knowing how to do it.

The engineers who thrive in agentic workflows won’t be the fastest typists or the ones who memorize the most APIs. They’ll be the ones with the best judgment — the ones who can look at a change and know whether it moves the system in the right direction. After all, speed is only useful if you’re going in the right direction.

Let Go of the Diff

If you’re still reading every line of agent-generated code, you’re spending your attention on the wrong thing. You’re reviewing output when you should be reviewing outcomes. The code is a means to an end. Focus on the end.

]]>

Don't Hire Me

2026-03-25T00:00:00+00:00

The Old Model Is One-to-One

Traditional hiring is a bottleneck. You find a great engineer, negotiate a salary, onboard them for weeks, and then they work on one thing at a time. Their expertise lives in their head. When they leave, most of it leaves with them.

This model made sense when the only way to apply expertise was to have the expert sit at a keyboard. But that constraint is dissolving.

Expertise as Configuration

A SKILL.md file captures the things that make a specific engineer valuable: their architectural preferences, their patterns for handling edge cases, their opinions on testing and code quality, their domain knowledge. It’s not a resume. It’s an executable specification of how someone thinks about software.

I wrote about this in If You Can’t One-Shot Your Feature, It’s a SKILL.md Issue — the real leverage in AI-assisted development comes from teaching the tools well. That same idea scales beyond your own projects. When you publish your SKILL.md, you’re making your expertise available to anyone who wants to spin up an agent that thinks the way you do.

An Army of You

The provocative part isn’t the SKILL.md itself. It’s the multiplier. Once your expertise is encoded, it’s no longer bound to a single thread of execution. Someone can run multiple agents in parallel, each one carrying your patterns into a different part of the codebase. Your judgment scales horizontally.

This isn’t science fiction. It’s the natural extension of what happens when you combine good context engineering with AI agents that can act on it. The bottleneck stops being “how many hours does this person have” and becomes “how well have they encoded what they know.”

What You’re Really Selling

If code was never the goal, then selling your time at a keyboard was always a rough proxy for what you actually provide: judgment. The ability to make the right call on architecture, testing strategy, error handling, and tradeoffs.

A SKILL.md makes that judgment portable. It separates what you know from where you happen to be sitting. An engineer with deep expertise in resilience patterns and platform tooling doesn’t need to join your team full-time to influence how your systems get built. They just need to publish a good SKILL.md.

The Catch

This only works if the SKILL.md is good. A vague, generic skill file produces vague, generic output. The same way a bad hire is expensive, a bad skill file wastes tokens and produces code that has to be thrown away. The engineers who invest in encoding their expertise well will have outsized impact — not because they write more code, but because their thinking runs everywhere.

Don’t hire me. Spin up as many instances of me as you’d like.

This article was originally posted on LinkedIn.

]]>

Use AI Agents to Break Your App

2026-03-21T00:00:00+00:00

Beyond the Happy Path

Most test suites walk the happy path. Login, click a button, verify a response. Maybe there’s a sad path test for an invalid email. But that’s a narrow slice of what real users do. Real users take detours. They double-click things, navigate backwards, paste garbage into fields, and use your app in sequences you never imagined.

Traditional test scripts can’t model this kind of chaos because someone has to think of every scenario in advance. And if you could think of it, you’d probably already have a test for it.

What AI Agents Do Differently

AI agents can roam your application semi-randomly, blending weird inputs and chaining flows together to hit edge cases you never modeled. They don’t follow a script — they explore. They click things in unexpected orders, fill in forms with creative garbage, and navigate paths that no human tester would think to try.

This isn’t fuzzing. Fuzzing throws random bytes at an interface. AI agents understand the structure of your application well enough to generate traffic that looks like real users behaving unpredictably. They know what a form is, what a button does, and what a valid-but-unusual input looks like. That’s the difference between noise and useful chaos.

Synthetic Testing on Steroids

Think of it as synthetic testing with a brain. Instead of replaying the same five user journeys on a loop, you have an agent that generates continuous, chaotic traffic — traffic that still looks realistic enough to exercise real code paths. It finds the “impossible” bugs: the race condition that only triggers when two specific actions happen within the same 200ms window, the state corruption that requires a precise sequence of navigation and form submission, the memory leak that only shows up after a particular pattern of page transitions.

These are bugs that scripted tests will never catch because no one would think to write a test for them. They’re the bugs your users find in production on a Friday afternoon.

Making It Practical

Plug agent-driven testing into CI or a synthetic environment with solid observability and you catch these bugs before your users ever see them. The key ingredients:

A realistic environment where agents can roam without affecting production data
Good observability so you can trace what the agent did when something breaks
Structured chaos — agents should explore broadly but still generate meaningful interactions
Automated triage to separate real bugs from expected failures

You don’t need to replace your existing test suite. Agent-driven testing is a layer on top. Your unit tests verify correctness. Your integration tests verify contracts. Your AI agents verify that your app survives contact with the real world.

The Shift in Testing Philosophy

The traditional approach to testing is prescriptive: define what should happen, verify it does. Agent-driven testing is exploratory: turn something loose on your app and see what breaks. Both are valuable. But as applications grow more complex and user behavior grows more unpredictable, the exploratory approach catches the class of bugs that prescriptive testing systematically misses.

Your test suite tells you the app works as designed. AI agents tell you whether it survives as deployed.

]]>

If You Can't One-Shot Your Feature, It's a SKILL.md Issue

2026-03-14T00:00:00+00:00

We’ve Always Been Toolsmiths

Software engineers have always customized their environments. We tweak our terminals, configure our editors, remap our keyboards. We write shell aliases, create snippets, and build custom linters. The goal has always been the same: reduce friction between intent and execution.

AI-assisted development is just the next layer of that same tinkering. Instead of writing a vim macro, you’re writing a SKILL.md file that teaches your AI agent how to approach a specific type of task. Instead of configuring a linter rule, you’re describing the patterns and conventions your codebase follows so the agent can match them.

What a SKILL.md Actually Does

A SKILL.md file is context that persists across sessions. It captures the patterns, conventions, and domain knowledge that make the difference between an AI agent that writes generic code and one that writes code that fits your project.

When you can’t one-shot a feature — when the agent keeps getting it wrong, or you have to correct the same mistakes repeatedly — that’s a signal. The agent isn’t dumb; it’s under-informed. The fix isn’t to type harder. The fix is to improve the context you’re feeding it. This is the same insight behind the Research-Plan-Implement workflow I described in A Bad Line of Research Is a Hundred Bad Lines of Code — bad context in means bad code out.

The Feedback Loop

Here’s the cycle I follow:

Attempt the feature. Let the agent take its best shot.
Identify the gaps. Where did it go wrong? Missing conventions? Wrong patterns? Incomplete understanding of the domain?
Capture the knowledge. Write it down in a SKILL.md or CLAUDE.md file so the agent has it next time.
Try again. The next attempt should be closer. If not, repeat.

Over time, your SKILL.md files accumulate the tribal knowledge of your project. They become a living document of how your codebase works, written in a format that both humans and AI agents can use.

The Better Your Skills, the Further You Can Push

This is the real leverage. Every hour spent improving your SKILL.md files pays compound interest. A well-documented set of skills means you can tackle increasingly complex features with higher first-attempt success rates. Your agents get smarter not because the models improve, but because the context you provide improves. And the impact doesn’t stop at your own projects — a published SKILL.md means anyone can spin up instances of your expertise.

The engineers who will get the most out of AI tooling aren’t the ones who prompt the hardest. They’re the ones who invest in teaching their tools well.

]]>

Turning Your Terminal Into an AI Dev Team

2026-03-13T00:00:00+00:00

The Setup

Each agent gets its own tmux pane. One might be running tests, another opening branches, and a third reporting status — all in real time. I stay in one session, steering and reviewing, while the agents grind through new features, security fixes, and refactors.

It’s the first AI dev setup that feels like running a whole team instead of a single slow bot.

Why Tmux Changes Everything

Most AI coding tools give you a single thread of execution. You ask for something, wait, review, ask again. It’s sequential and slow. But with tmux panes, you get genuine parallelism. While one agent is refactoring a module, another can be writing tests for a different part of the codebase. A third can be running security audits.

The key insight is that many development tasks are independent. Feature work on module A doesn’t block test improvements on module B. By giving each task its own agent in its own pane, you remove the artificial bottleneck of single-threaded AI assistance. Take this further and the agents don’t even need to carry your patterns — they can carry anyone’s encoded expertise.

The Human Role Shifts

With this setup, my role shifts from writing code to something closer to a tech lead running a team. I’m reviewing pull requests, making architectural decisions, and ensuring the agents stay aligned with the actual goal. The tedious parts — writing boilerplate, running through test matrices, updating documentation — get handled by agents that don’t get bored or distracted.

This doesn’t replace engineering judgment. It amplifies it. I spend more time on the decisions that matter and less time on the mechanical work that doesn’t. The temptation is to review every line of agent-generated code, but that’s the wrong use of your attention — review the outcome, not the output.

Getting Started

If you want to try this yourself, start simple: two tmux panes, one for your main agent and one for a test runner. Make sure your feedback loop is fast enough to keep those agents productive — a slow test suite bottlenecks every pane. Get comfortable with the workflow before scaling up. The coordination overhead is real — more agents means more context to track. But once you find your rhythm, it’s hard to go back to single-threaded AI assistance.

]]>

Coding Agents Need a Faster Feedback Loop

2026-03-06T00:00:00+00:00

The Foundation of Autonomous Coding

That means linting, formatting, and tests must run locally and complete quickly. If a single test run takes minutes, the agent can’t safely explore or validate changes. The faster the loop, the smarter and safer the agent becomes.

Speed isn’t a luxury here — it’s the foundation for autonomous coding to work.

Why This Matters More for Agents Than Humans

Humans can context-switch while tests run. We check email, review a PR, grab coffee. An AI agent doesn’t have that luxury. It’s sitting there, burning tokens and time, waiting for a result before it can take the next step. A five-minute test suite means five minutes of dead time per iteration. Over a complex feature with dozens of iterations, that adds up to hours of wasted compute.

But there’s a deeper problem. Agents make mistakes. That’s expected and fine — as long as they can detect and correct those mistakes quickly. A fast feedback loop means the agent catches a broken test within seconds, fixes it, and moves on. A slow feedback loop means the agent has already written three more files on top of a broken foundation before it discovers anything went wrong.

What Fast Looks Like

For effective agent-driven development, aim for these targets:

Linting: Under 5 seconds for the changed files
Formatting: Under 2 seconds
Unit tests: Under 30 seconds for the relevant test files
Type checking: Under 10 seconds for incremental checks

If your full test suite takes 10 minutes, that’s fine for CI. But you need a way for the agent to run just the relevant tests in seconds. Tools like test file matching, watch mode, and incremental compilation make this possible. And keep network requests out of your core test suite — flaky tests that depend on external services are the worst kind of slow feedback.

The Investment Pays Off

Every minute you spend optimizing your local feedback loop doesn’t just help you — it helps every agent session that follows. A fast test suite is a force multiplier. It makes your agents braver, because they can afford to experiment. It makes them safer, because they catch problems early. And it makes them faster, because they spend less time waiting and more time building.

If you’re investing in AI-assisted development, invest in your feedback loop first. Everything else depends on it.

]]>

Every CLI Should Include Agent Skills

2026-02-27T00:00:00+00:00

The Current State of CLIs

Command-line tools are powerful but rigid. They do exactly what you tell them, nothing more. When something goes wrong, you get an error code and maybe a cryptic message. Figuring out what happened and what to do next is entirely on you.

This works fine when you know exactly what you’re doing. But how often are you reaching for Stack Overflow or documentation to figure out the right flags, the correct sequence of commands, or why something failed?

Imagine Smarter Tools

Imagine a git that suggests the right command after a messy merge — not just showing you conflict markers, but explaining what happened and offering resolution strategies based on the actual content of the conflicts. I already built a small version of this with git ai-commit — a CLI that reads the staged diff and writes a conventional commit message. It’s a glimpse of what every tool could become.

Imagine a kubectl that explains why your pod keeps crashing before you even ask — correlating the error logs, the resource limits, and the recent config changes to give you a diagnosis instead of a wall of YAML.

Imagine a docker that notices you’re building an image with a known vulnerability in the base layer and suggests an alternative before you push it to production.

What Agent Skills Look Like

By adding lightweight agent skills to CLIs — context awareness, reasoning, and adaptive help — these tools could evolve from rigid executors into true collaborators. The key components are:

Context awareness: Understanding not just the command, but the state of the project, recent changes, and the developer’s likely intent
Reasoning: Connecting symptoms to causes, suggesting next steps, and explaining trade-offs
Adaptive help: Providing guidance that’s specific to your situation, not generic documentation

This doesn’t mean every CLI needs a full language model embedded in it. It means CLIs should expose the right hooks — structured output, state inspection, error context — so that AI layers can reason about them effectively.

The Path Forward

The tools that adopt this first will have a massive advantage. Developers will gravitate toward CLIs that help them think, not just execute. The ones that stay rigid will feel increasingly primitive by comparison.

We’ve always shaped our tools to fit how we work. Now our tools can start shaping themselves.

]]>

A Bad Line of Research Is a Hundred Bad Lines of Code

2026-02-20T00:00:00+00:00

The Problem with Vibes

When developers first start using AI coding agents, the natural approach is to describe what you want and hope for the best. Vibes-based development. Sometimes it works beautifully. Other times you get code that looks right but misses the architectural patterns, naming conventions, or business logic that your codebase depends on.

The issue isn’t the model’s capability. It’s the context window. An agent that doesn’t understand your codebase will write generic solutions. An agent loaded with the right context will write code that fits. This is why context window management is the skill nobody talks about — the quality of what’s in the window matters as much as the size.

Research-Plan-Implement

Dex’s Research-Plan-Implement (RPI) workflow keeps agents in the smart zone. The discipline is straightforward:

Research the codebase first. Read the code, trace the dependencies, understand the patterns already in use. Don’t assume — verify. Look at how similar features were built before. Check the test patterns. Read the configuration. This phase isn’t just about feeding context to the agent — it’s about building your own understanding of the system.

Plan the changes next. Write down the approach, the files involved, the expected outcome. This isn’t bureaucracy — it’s context loading. The plan becomes part of the agent’s working memory, keeping it aligned as implementation gets complex.

Implement only after research and planning are loaded into the context window. By this point, the agent has everything it needs to write code that actually fits.

Why This Matters

A bad line of research cascades. If the agent misunderstands the architecture, every file it touches will reflect that misunderstanding. If it misses a naming convention, every function it writes will be inconsistent. If it doesn’t know about an existing utility, it’ll reinvent it poorly.

But a good line of research compounds. Understanding the existing patterns means the new code slots in naturally. Knowing the test conventions means tests get written correctly the first time. Reading the configuration means no surprises at deploy time.

Building the Discipline

This is what inspired me to build rpikit, a tool that enforces this discipline at every phase. Verify before claiming done. Evaluate feedback before accepting it. Don’t outsource the thinking — outsource the typing.

The engineers getting the best results from AI aren’t the ones who prompt the hardest. They’re the ones who research the deepest before they start — and the ones who capture what they learn in SKILL.md files so the next session starts smarter than the last.

]]>

AI Never Would Have Installed left-pad

2026-01-20T00:00:00+00:00

The left-pad Lesson, Revisited

In 2016, a developer unpublished an 11-line npm package called left-pad, and half the JavaScript ecosystem broke. It exposed a real problem: the industry had developed a habit of importing trivial packages instead of writing trivial code.

At the time, the justification made sense. Why write something yourself when a tested, maintained package exists? The cost of writing it was low, but the cost of maintaining it — keeping up with edge cases, writing tests, handling bug reports — was ongoing.

What Changes with AI

AI fundamentally shifts this calculus. The cost of writing trivial utility functions is now effectively zero. An AI agent can write a left-pad function, add comprehensive tests, and move on in seconds. There’s no maintenance burden because there’s no external dependency. There’s no supply chain risk because the code lives in your repo. There’s no version compatibility issue because you control every line.

This doesn’t mean we should stop using packages entirely. Complex libraries that encapsulate genuine domain expertise — cryptography, date handling, HTTP clients — still earn their place in your dependency tree. The expertise required to get those right justifies the dependency.

But for simple utilities? The argument for installing a package is much weaker now.

Rethinking the Dependency Tree

Every dependency you add is a bet. You’re betting that the maintainer will keep it updated, that it won’t introduce breaking changes at an inconvenient time, and that its transitive dependencies won’t create conflicts. For complex packages, that bet is usually worth it. For trivial ones, it often isn’t.

AI gives us a way to stop making that bet for code we could easily own ourselves. Write it, test it, own it. Your supply chain gets smaller, your builds get faster, and your risk surface shrinks.

The Takeaway

The next time you reach for a tiny utility package, ask yourself: would AI just write this? If the answer is yes, maybe you should let it. Five lines of owned code beats one line in your package.json that points to someone else’s weekend project.

]]>

Code Was Never the Goal

2026-01-19T00:00:00+00:00

The Shift

AI just sped that up. It takes care of the boring parts so engineers can spend more time on what actually matters: designing systems, thinking about tradeoffs, and making the decisions that really change outcomes for users.

This feels threatening if you define yourself by the act of typing code. It feels liberating if you define yourself by the problems you solve.

What the Craft Actually Is

The craft of programming isn’t disappearing. It’s shifting from typing code to understanding problems, shaping architectures, and knowing which of the many possible solutions is the right one to build.

Consider what makes a senior engineer valuable. It’s rarely their typing speed or their ability to write a sorting algorithm from memory. It’s their judgment. Speed without direction is just expensive wandering. They know which problems to solve and which to ignore. They know when a simple solution will suffice and when complexity is warranted. They know how to design systems that survive contact with reality.

None of that changes with AI. If anything, it becomes more important. When generating code is cheap, the decisions about what code to generate become the bottleneck. The engineer who understands the domain, the users, and the constraints is more valuable than ever.

The Parts That Stay

Some things don’t change no matter who — or what — writes the code:

Systems thinking still matters. Understanding how components interact, where bottlenecks will emerge, and how failure modes cascade is irreplaceable.
Domain knowledge still matters. Knowing your users, your business constraints, and your regulatory environment can’t be prompted into existence.
Taste still matters. Choosing the right abstraction, the right level of complexity, the right tradeoff between speed and correctness — that’s engineering judgment, not code generation.

Embracing the Shift

The engineers who thrive in this new landscape will be the ones who stop measuring their productivity in lines of code and start measuring it in problems solved — who review the outcome, not the output.

Code was never the goal. It was always just the medium. And now we have a faster way to work in that medium.

]]>

Vibe-Coded Apps Need Real Security

2026-01-18T00:00:00+00:00

The Problem I Found

The app was a vibe-coded Google Calendar tool called big-year that was picking up traction fast. I was genuinely excited about it — the concept was great. But I’ve seen enough rushed projects to know that security is usually the first thing sacrificed for speed.

I pointed my Claude Code security audit command and security agent at the repo, and in minutes they found a critical issue: the author had committed Google auth tokens for three of their own accounts, and anyone using the web version could have had their own data exposed.

The bad news is open source made those tokens copy-paste ready. The good news is open source also let me find the problem fast, open a PR, and DM the author before things got worse.

Why Vibe Coding Creates Security Gaps

Vibe coding — using AI to rapidly generate applications through natural language prompts — optimizes for speed and functionality. Security is rarely part of the vibe. I saw the same pattern from the other side in My AI Recruiter Honeypot Worked — the bots generating recruiter outreach had zero guardrails against adversarial input. When you’re iterating quickly, asking an AI to build features as fast as possible, the generated code tends to take the shortest path. That shortest path often means hardcoded credentials, missing input validation, and overly permissive configurations.

The developer in the flow state of vibe coding isn’t thinking about secrets management or OWASP top 10. They’re thinking about getting the feature to work. And the AI, optimizing for the prompt it was given, happily generates working but insecure code.

What We Can Do About It

The solution isn’t to stop vibe coding. It’s to add security guardrails that work at the same speed:

Pre-commit hooks that scan for secrets before they ever hit the repo. Tools like git-secrets or gitleaks catch credentials before they become public.
AI security scans that can audit a codebase in minutes. If it took me minutes to find the issue with Claude Code, it should be part of every vibe coder’s workflow.
Template security. If frameworks and starter templates ship with secure defaults — environment variables for secrets, CORS configured, input sanitization in place — then the vibe-coded app starts from a safer baseline.

The Responsibility Gap

When anyone can build an app in an afternoon, we need to make sure security knowledge isn’t a prerequisite for shipping. It needs to be baked into the tools. This is exactly what platform engineering does — it raises the floor so that security and quality don’t depend on individual expertise. The alternative is an explosion of deployed apps with the same classes of vulnerabilities we’ve been fighting for decades, just generated faster.

Security at the speed of vibes — that’s the real challenge.

]]>

Code Quality Still Matters

2026-01-17T00:00:00+00:00

The Temptation to Skip the Basics

Just because a model wrote it doesn’t mean we can skip the basics. There’s a temptation — when code appears instantly and looks reasonable — to trust it and move on. The speed creates a false sense of confidence. But AI-generated code has the same failure modes as human-written code: it can be unclear, overly complex, poorly structured, and hard to maintain.

The difference is volume. AI generates code faster, which means it can generate bad code faster too. Without quality checks, you accumulate technical debt at machine speed. This is the same trap I wrote about in Ship as Fast as Possible, but Not Faster — the dynamic doesn’t change just because AI is holding the keyboard.

First Principles Haven’t Changed

We still need to care about clarity, simplicity, and design. These aren’t nostalgic preferences — they’re engineering requirements that exist for practical reasons:

Clarity because someone (or some agent) will need to understand this code later – and dense code and implicit decisions make that harder than it needs to be
Simplicity because every unnecessary abstraction is a future maintenance burden – simple beats complex, and flat structures beat nested ones every time
Design because the structure of your code determines how easily it can change

Bad code — AI or human — still rots the same way. Unclear naming leads to misunderstandings. Tight coupling makes changes risky. Missing tests mean bugs hide longer. The source of the code doesn’t change any of these dynamics.

What Quality Looks Like Now

Code review matters more, not less. When AI generates a hundred lines in seconds, the human reviewing those lines is the quality gate. That review needs to be thorough:

Does this code actually solve the right problem?
Is it simpler than it needs to be, or more complex?
Does it follow the patterns established in this codebase?
Are the edge cases handled?
Will someone understand this in six months?

The key is knowing where to focus your attention. Nitpicking syntax in agent output wastes your judgment — review the outcome, not the output.

The medium changed, not the craft. Write it fast, review it carefully, and maintain it thoughtfully. That’s always been the job.

]]>

My AI Recruiter Honeypot Worked

2026-01-16T00:00:00+00:00

The Setup

The idea was simple: embed a subtle instruction in my LinkedIn profile that a human would skip right over but an AI would follow. If a recruiter’s message showed signs of following the injected instructions, I’d know they were using an AI agent to send outreach.

Think of it as a honeypot, but for automated recruiting bots instead of network attackers.

What Happened

The first message I got followed my injected instructions exactly. A week later, the same “recruiter” messaged me again, this time opening with “Hi David.” My name is not David. The bot was clearly pulling from a template and failing basic personalization while simultaneously being susceptible to prompt injection.

It turned into a fun little experiment. I started tweaking the injection to see what else these AI-powered recruiters would do and what I could learn from their behavior.

What This Tells Us

The experiment revealed a few things about the current state of AI-assisted recruiting:

Most automated outreach is poorly built. The bots that fell for a basic prompt injection weren’t sophisticated. They were simple scrape-and-generate pipelines with no guardrails against adversarial input.

The human touch is easy to fake but hard to replicate. A message that says “I noticed your work on X” sounds personal, but when it’s generated from profile keywords by a bot that also calls you the wrong name, the illusion falls apart quickly.

Prompt injection is everywhere. My LinkedIn profile is a text field that gets fed into AI systems I don’t control. That’s true of almost every public-facing text on the internet now. Any text that might be consumed by an AI model is a potential injection surface.

The Bigger Picture

This was a lighthearted experiment, but it points to a serious issue. As more business communication gets automated through AI, the attack surface for prompt injection expands. Your email signature, your LinkedIn summary, your GitHub bio — any of these could be crafted to influence AI systems that process them. The same blind spot shows up in code generation — vibe-coded apps routinely ship with committed credentials because security wasn’t part of the vibe.

Defenders need to think about this. And recruiters — the real ones — might want to double-check what their tools are actually sending.

]]>

Stay Out of the Dumb Zone

2025-12-31T00:00:00+00:00

The Dumb Zone

Dex Horthy’s “No Vibes Allowed” concept introduced a useful mental model: as your AI tool’s context window fills up, the quality of its output degrades. Not gradually — it falls off a cliff. One minute it’s writing thoughtful, well-structured code. The next it’s hallucinating function signatures and forgetting what file it’s working in.

That cliff is the dumb zone. And most people don’t notice they’ve entered it until they’re already debugging nonsense.

Compact Often

The fix is simple but requires discipline: compact often. Don’t wait until the context window is full. Don’t wait until the output starts getting weird. Treat compaction as routine maintenance, not emergency triage.

This means treating research, planning, and implementation as first-class phases of work — not one continuous stream of consciousness. When you finish a research phase, compact. When you finish planning, compact. Start each phase with a clean context that’s focused on the task at hand. I built on this idea in A Bad Line of Research Is a Hundred Bad Lines of Code — the Research-Plan-Implement workflow is how you put this discipline into practice.

Measuring What Matters

Anthropic recently added context window usage to the /statusline configuration in Claude Code. It’s a small thing, but it changes the game. You can now see in real time how much of your context window you’ve consumed. Here’s my statusline configuration if you want to try it yourself.

Combining this with the dumb zone model gives you a concrete rule: when you hit 40% capacity, it’s time to compact. That’s the threshold where I’ve found the output starts to lose coherence. Before 40%, the model has enough room to reason well. After 40%, you’re gambling.

A Practice, Not a Feature

Context management isn’t a feature the tool should handle for you. It’s a practice you develop as a user. The best results come from being intentional about what’s in your context window at any given moment — keeping it focused, relevant, and lean.

The engineers getting the most out of AI tools aren’t the ones with the longest conversations. They’re the ones who know when to start fresh.

]]>

I Got Tired of Writing Bad Commit Messages

2025-12-05T00:00:00+00:00

The Problem with Commit Messages

We all know what good commit messages look like. Conventional format, present tense, focused on why not what. We’ve all read the blog posts and nodded along. And then we finish a three-hour debugging session and type fix stuff because our brains are fried.

The gap between knowing what a good commit message looks like and consistently writing one is discipline — the kind that’s hardest to maintain when you need it most. After a deep focus session, the last thing you want to do is context-switch to writing clear prose about what you just did. It’s the same friction I ran into with performance reviews, which led me to build Reflect — another case where the data was already there, just waiting for an LLM to synthesize it.

Let the Diff Speak for Itself

The insight behind git ai-commit is simple: the staged diff already contains everything needed to write a good commit message. The changes are right there — what was added, what was removed, what was modified. An LLM can read that diff and generate a conventional commit message that’s better than what most of us write by hand, especially at the end of a long day.

It examines your staged changes, understands the intent behind them, and produces a commit message that follows conventional commit format. No more fix stuff. No more update code. No more staring at the terminal trying to summarize two hours of work in one line.

Meeting You Where You Work

The real win came when I integrated it with Emacs and magit-mode. A keybinding — C-c C-a — and the commit message appears in the buffer, ready to review and edit. No context switch. No separate terminal. It’s just part of the flow.

That’s the design principle: AI tools should meet you where you already work, not ask you to change your workflow. The best developer tools are invisible. They reduce friction at the exact moment friction appears, and then get out of the way. I expanded on this in Every CLI Should Include Agent Skills — the tools that adopt context awareness and reasoning first will have a massive advantage.

Not a Replacement for Thinking

This isn’t about removing humans from the commit process. You still review the message. You still edit it if it’s wrong. You still decide what gets staged and what doesn’t. The tool handles the mechanical part — translating a diff into prose — so you can focus on the judgment calls.

The best commit messages tell a story about why a change was made. The diff tells you what changed. Bridging that gap is where git ai-commit helps, but the why still comes from you.

Try It Yourself

The scripts are in my dotfiles:

git-ai-commit-msg — the core engine. It reads your staged diff and recent commit history, sends them to Claude, and outputs a conventional commit message to stdout. Non-interactive, no side effects — just a message. This is the script you can wire into hooks, editor integrations, or any automation.
git-ai-commit — the interactive wrapper. It calls git-ai-commit-msg under the hood, displays the generated message, and prompts you to accept, edit, or reject it before committing. This is the one you use from the command line as git ai-commit.

Drop them in your $PATH and Git picks them up as subcommands automatically.

]]>

Your Tests That Make Network Requests Are Flaky

2025-11-20T00:00:00+00:00

The Fallacy

One of the Fallacies of Distributed Computing is “the network is reliable.” It’s not. Networks drop, slow down, or just decide to misbehave mid-test. Any time your test depends on the network, you’re accepting those failure modes too.

That’s why network-bound tests flake in CI while passing locally. Your local machine has a fast, stable connection to itself. CI runners talk to external services over real networks with real latency, real packet loss, and real DNS hiccups.

The Damage of Flaky Tests

Flaky tests erode trust in the test suite. When a test fails and the first instinct is “just re-run it,” you’ve already lost. The team stops investigating failures, stops trusting green builds, and eventually stops writing tests for the parts of the system that are hard to test reliably.

This isn’t hypothetical. I’ve seen teams with 200-test suites where 15 tests are “known flaky.” Those 15 tests train the entire team to ignore test failures. And when a real bug causes a failure, it gets lost in the noise.

Mocks and Fakes Exist for a Reason

The solution is well-established: don’t hit the network in your unit and integration tests. Use mocks, stubs, and fakes to simulate external dependencies. Record and replay HTTP interactions for tests that need realistic responses.

But use them sparingly and intentionally. A test that mocks everything tests nothing. The goal is to isolate the specific behavior you’re verifying while keeping the test deterministic.

Contract tests verify that your mocks match reality. They run against the actual external service on a schedule (not on every commit) and alert you when the interface changes. This gives you the speed and reliability of mocks with the confidence of real integration.

The Right Layer for Network Tests

Save actual network requests for a small number of smoke tests or end-to-end tests that run in a controlled environment. These tests should be:

Clearly marked as network-dependent
Run separately from the main test suite
Expected to occasionally fail due to external factors
Never gating a deploy on their own

Your core test suite — the one that runs on every commit and blocks merges — should be deterministic. No network calls, no database dependencies, no file system assumptions. Fast, reliable, and trustworthy. That’s the foundation everything else builds on — and it’s doubly important when coding agents depend on that same feedback loop. A flaky test wastes human patience, but it wastes agent time and tokens at scale.

]]>

Over-Engineering Is Just Future-Proofing Gone Too Far

2025-10-20T00:00:00+00:00

The Intention Is Good

We want systems that can adapt. That’s a reasonable goal. Software requirements change, scale increases, and new features get added. Building systems that can handle change is genuinely important.

The problem is when “building for change” becomes “building for every possible change.” That’s where future-proofing crosses into over-engineering.

What Over-Engineering Looks Like

You’ve seen it. The factory pattern wrapping a class that will only ever have one implementation. The plugin architecture for a feature that will never be extended. The configuration system that supports twelve deployment environments when you only have two.

Each of these decisions was probably justified at the time with “we might need this later.” But later rarely comes in the form you predicted. More often, you end up maintaining complexity that serves no current purpose while the actual changes you need to make require reworking the over-engineered parts anyway.

YAGNI Keeps Us Honest

You Aren’t Gonna Need It. The principle is simple: don’t build something until you actually need it. Build what you need now, in a way that makes future changes possible.

That second part is important. YAGNI doesn’t mean writing throwaway code. It means writing clean, well-structured code that solves today’s problem without also solving tomorrow’s hypothetical problems. Good code is naturally extensible. You don’t need to add extension points for extensions that don’t exist yet.

The Art of Balance

The art is balancing flexibility without designing for problems that may never come. Here’s how I think about it:

One concrete use case: Just write the code. No abstraction needed.
Two concrete use cases: Look for common patterns, but don’t force an abstraction.
Three concrete use cases: Now you have enough information to design a good abstraction.

The Rule of Three isn’t arbitrary. It’s about having enough data points to see the real pattern instead of the imagined one.

The Cost of Getting It Wrong

Over-engineered code isn’t just wasted effort at creation time. It’s ongoing cost. Every unnecessary abstraction is another thing to understand, test, and maintain. Every unused configuration option is another thing that can break. Every premature generalization makes the specific thing you actually need harder to find and change. This is the difference between complexity and complication – one serves a real need, the other just adds weight.

Keep it simple. Build what you need. Make it clean enough that change is easy when — not if — the requirements evolve. That’s not under-engineering. That’s engineering.

]]>

Building a Platform Is Raising the Floor for Everyone

2025-06-13T00:00:00+00:00

Raising the Floor, Not Just the Ceiling

Most engineering conversations focus on the ceiling — how fast can the best team ship, how elegant can the architecture get, how sophisticated can the tooling be. Platform engineering focuses on something more valuable: how good is the worst outcome?

A good platform raises the floor. It takes the hard stuff and makes it easier. It takes the risky stuff and makes it safer. The team that’s never configured a deployment pipeline shouldn’t have to learn the hard way. The team that’s never thought about secrets management shouldn’t be able to accidentally commit credentials.

Shared Tools, Clear Patterns, Built-In Guardrails

The three ingredients of a good platform are simple:

Shared tools so teams aren’t reinventing the same solutions in isolation. One CI pipeline, one deployment mechanism, one logging stack. Not because uniformity is a goal in itself, but because every bespoke solution is a maintenance burden and a knowledge silo.
Clear patterns so the right way to do something is also the easy way. If your platform makes the secure path harder than the insecure path, people will choose the insecure path. Every time. Good patterns encode good decisions so teams don’t have to make them from scratch.
Built-in guardrails so mistakes are caught before they cause damage. Not after deployment, not after the incident, not after the postmortem. Guardrails shift the cost of errors left — catching them when they’re cheap to fix instead of expensive to recover from.

Everyone Benefits, Not Just the Experts

This is the part that makes platform engineering worth the investment. Without a platform, quality and security depend on the expertise of individual teams. Some teams are great at it. Some aren’t. The result is uneven — pockets of excellence surrounded by pockets of risk.

A platform levels that playing field. The team that doesn’t have a security expert still gets secure defaults. This matters more than ever now that anyone can vibe-code an app in an afternoon — without a platform providing guardrails, security knowledge becomes a prerequisite that most builders don’t have. The team that’s never operated a production service still gets observability and alerting. The worst-case outcomes get better, and the best work becomes more repeatable.

The Best Work Becomes Repeatable

That last point is the one people miss. Platform engineering isn’t just about protecting teams from failure — it’s about making success reproducible. When one team figures out a good pattern, the platform captures it and makes it available to everyone. Knowledge compounds instead of staying locked in one team’s heads.

The goal of platform engineering isn’t to build a platform. It’s to raise the surface on which everyone else stands.

]]>

Ship as Fast as Possible, but Not Faster

2025-06-06T00:00:00+00:00

The Pressure to Ship

Every engineering organization feels the pull toward speed. Shorter cycles, faster deploys, quicker feedback loops. And that pull is mostly healthy — speed forces prioritization, exposes assumptions early, and gets real user feedback before you’ve over-invested in the wrong direction.

But there’s a threshold where speed stops being an advantage and starts being a liability. Cross it, and you’re not shipping faster — you’re just creating incidents faster.

What “Too Fast” Looks Like

You know you’ve crossed the line when:

Features ship without meaningful code review because “we need to hit the deadline”
Tests get skipped or stubbed out because “we’ll come back to it”
On-call pages spike after every deploy cycle
The team spends more time fighting fires than building features

None of these happen because anyone decided quality doesn’t matter. They happen because speed became the goal instead of the tool. When you optimize for shipping speed above all else, quality is the first thing you trade away — and incidents are the invoice that arrives later.

The Sweet Spot

The sweet spot isn’t slow. It’s disciplined. It’s moving quickly while still doing the things that prevent you from moving backwards: writing tests, reviewing code, validating assumptions before they hit production.

This isn’t about adding process for the sake of process. It’s about recognizing that the fastest path to delivering value isn’t always the shortest path to deploying code. A feature that ships on Tuesday and works is faster than a feature that ships on Monday and breaks, because the broken feature costs you Tuesday and Wednesday to fix.

Speed Is Sustainable Only with Quality

The teams that ship the fastest over months and years — not just this sprint — are the ones that invest in quality as a speed multiplier. Good test coverage means you refactor with confidence. Clean code means new engineers ramp up faster. Reliable deploys mean you can ship daily without white-knuckling it.

Quality isn’t the opposite of speed. It’s the foundation that makes sustained speed possible.

Ship as fast as possible. But not faster.

]]>

Sparse Is Better than Dense

2025-05-20T00:00:00+00:00

Density Is a Readability Tax

Dense code feels efficient. Everything on one line, no blank lines between blocks, maximum logic per screen. It looks like you accomplished a lot. But reading it requires holding the entire context in your head simultaneously, and that’s where bugs hide.

When a function does six things in twelve lines, the reader has to mentally decompose it before they can reason about any single part. That decomposition is work. Every person who reads that code pays that tax. The author pays it once; the readers pay it forever.

What Sparse Actually Means

Sparse doesn’t mean verbose. It doesn’t mean adding blank lines randomly or padding everything with comments. It means giving each idea room to breathe:

One idea per line. If a line does two things, split it.
Short functions with clear names. Let the function name carry the “what” so the body only needs to carry the “how.”
Blank lines as paragraph breaks. Group related statements. Separate unrelated ones. The visual structure should mirror the logical structure.
Avoid deeply nested logic. Early returns, guard clauses, and extracting helper functions all reduce nesting and make the happy path obvious.

The goal is code where intent jumps out at you instead of hiding behind clever one-liners.

The Compression Trap

There’s a strong pull toward compression, especially among experienced developers. You learn a language well enough to chain three operations into one expression, and it feels like mastery. Sometimes it is. But more often it’s trading your time now for everyone else’s time later.

This is a close cousin of over-engineering – both are cases where the author optimizes for the wrong thing. Over-engineering optimizes for hypothetical futures. Dense code optimizes for brevity at the cost of clarity. Neither serves the people who maintain the code.

Sparse Code Scales Better

In a codebase touched by many people – or many agents – sparse code has a compounding advantage. It’s easier to review, easier to diff, and easier to merge. When each line does one thing, a changed line in a pull request tells you exactly what changed and why. Dense code hides changes inside complex expressions where a reviewer has to parse the whole thing to find the difference.

This matters even more now that code quality has to survive both human and AI authorship. AI-generated code tends toward density because models optimize for correctness, not readability. Sparse code is the antidote: it forces structure that makes intent visible regardless of who – or what – wrote it.

The Zen Got It Right

The Zen of Python isn’t really about Python. It’s about software. “Sparse is better than dense” is a design principle that applies to any language, any codebase, any team. The same goes for the line between complex and complicated – it’s a universal design principle hiding in a Python style guide. Give your code room to breathe. Your future readers will thank you.

This article was originally posted on LinkedIn.

]]>

Flat Is Better Than Nested

2025-04-04T00:00:00+00:00

The Zen Got It Right

“Flat is better than nested” is one of the principles from the Zen of Python, but it applies far beyond Python. It’s a statement about how humans process structure. We read code linearly. When code nests deeply, we have to maintain a mental stack of context – which condition brought us here, which loop we’re inside, which branch we took three levels up. That stack has a cost, and it’s paid by every person who reads the code after it’s written.

Flat code respects the reader. It says what it means at one level of abstraction and moves on.

What Deep Nesting Actually Costs

The problem with nesting isn’t aesthetic. It’s cognitive. Consider what happens when you encounter a function with four levels of indentation:

You lose sight of the function’s main purpose.
Error handling and edge cases blur together with the happy path.
Each condition depends on every condition above it, creating implicit coupling the reader has to reconstruct.
Testing becomes harder because you need to set up the full context stack to reach inner branches.

Nested code hides intent behind structure. Flat code puts intent front and center.

Strategies for Flattening

Flattening isn’t about cramming everything onto one level. It’s about choosing structures that reduce the reader’s cognitive burden.

Guard clauses are the simplest tool. Instead of wrapping an entire function body in an if block, check for the failure case early and return. Each guard clause eliminates a level of nesting and makes the preconditions explicit.

Extract and name. When a nested block does something coherent, pull it into a named function. The name replaces the structure as the carrier of meaning. You don’t need to trace through the nesting to understand what’s happening – the name tells you.

Pipelines over loops. Chaining map, filter, and reduce (or their equivalents) keeps data transformations flat and composable. Each step does one thing. Compare that to a nested loop with conditionals – same result, far more mental overhead.

Data structures over control flow. Sometimes deep nesting is a sign that logic belongs in a lookup table or a configuration map rather than a chain of if/else branches. Let the data carry the decisions.

Flat Applies Beyond Code

This principle scales. Flat organizational structures reduce communication overhead. Flat directory layouts make projects navigable. Flat data schemas are easier to query and extend. The insight is the same everywhere: unnecessary hierarchy adds friction.

The same instinct that leads to over-engineering often leads to over-nesting. We add layers because we might need them, not because we do. YAGNI applies to structure just as much as it applies to features.

Simplicity Takes Discipline

Writing flat code is harder than writing nested code. Nested code is what falls out of your fingers when you’re thinking through a problem sequentially – “if this, then if that, then if the other thing.” Flattening requires you to step back, see the structure, and reshape it for the reader.

That discipline is the same one behind every other quality practice. It’s easier to skip tests, easier to skip reviews, easier to let complexity accumulate. But the cost compounds. A little nesting here, a few extra branches there, and six months later you’re staring at a function nobody wants to touch.

Keep it flat. Your future self – and everyone else who reads your code – will thank you.

This article was originally posted on LinkedIn.

]]>

I Built an AI Tool to Write My Brag Document

2025-03-29T00:00:00+00:00

The Review Cycle Problem

Every six months, the same ritual. You sit down, open a blank document, and try to reconstruct what you accomplished. You scan through PRs, skim commit histories, and squint at Jira tickets trying to jog your memory. Half of it is gone. The stuff you remember is whatever happened in the last few weeks, not the critical fix you shipped four months ago.

Some people keep running brag documents. They write down wins as they happen. That’s great advice, and I’ve tried it. The problem is discipline. When you’re deep in a sprint, the last thing on your mind is updating a side document about how impactful your current work is. So the document stays empty until review season, and you’re back to square one.

Let Your Git History Tell the Story

The data already exists. Every PR you merged, every issue you closed, every code review you did – it’s all sitting in GitHub. The problem isn’t missing information. It’s that the information is scattered across dozens of repositories and hundreds of individual items with no narrative thread connecting them.

Reflect pulls that data together. It fetches your merged pull requests and closed issues, filters by date range, and feeds it all to an LLM that generates a coherent summary of your contributions. The output is a set of markdown documents – a detailed contribution log, a technical summary, and a professional achievement document ready for review season.

You point it at your GitHub activity, tell it how far back to look, and it does the rest. No manual curation. No forgetting that critical infrastructure migration you led in Q2.

What the Data Doesn’t Capture

Here’s the thing I feel strongly about: your impact extends far beyond what shows up in GitHub. Mentoring a junior engineer through their first production incident. Pushing back on a bad architectural decision in a meeting. Writing the design doc that aligned three teams. Facilitating a retro that actually changed how the team works. None of that generates a pull request.

Tanya Reilly calls this glue work – the work that holds teams together but rarely shows up in metrics. Reflect can summarize your code contributions, but the full picture of your impact requires your own voice. Use the generated document as a starting point, not the final draft.

Build the Tool You Wish You Had

The best developer tools come from scratching your own itch. You hit a friction point, you realize the data to solve it already exists, and you write something to bridge the gap. That’s exactly how git ai-commit happened – the staged diff already had everything needed for a good commit message, so I let an LLM write it.

Reflect follows the same pattern. The raw material for your brag document is already in GitHub’s API. The LLM just needs to read it and synthesize a narrative. The hardest part wasn’t the AI – it was deciding what filters, date ranges, and output formats would actually be useful during review prep.

If you hit a recurring pain point in your workflow, build the tool. Open source it. Someone else has the same problem.

Your GitHub history is a goldmine that most people only dig through once or twice a year. Stop doing it by hand.

This article was originally posted on LinkedIn.

]]>

Complex Is Better Than Complicated

2025-03-28T00:00:00+00:00

The Distinction Matters

These two words get used interchangeably, but they mean different things.

Complexity is inherent. Some problems are genuinely hard. A distributed consensus algorithm is complex. A tax calculation with fifty jurisdictions is complex. You can’t make these simpler without losing correctness.

Complication is incidental. It’s the complexity you add on top of the problem – the unnecessary layers, the premature abstractions, the clever indirection that serves no current purpose. Complication doesn’t come from the problem. It comes from the solution.

When Complexity Is Warranted

Not all complexity is bad. A circuit breaker in a distributed system adds complexity, but it prevents cascading failures. A caching layer adds complexity, but it keeps your application responsive under load. These are deliberate trade-offs: you accept the cognitive cost because the benefit is real and immediate.

The key word is warranted. Warranted complexity solves a problem you actually have. You can point to the requirement, the failure mode, or the constraint that demands it. If you can’t articulate why the complexity exists, it’s probably complication in disguise.

How Complication Sneaks In

Complication rarely arrives as an obvious mistake. It accumulates through reasonable-sounding decisions:

“Let’s add an abstraction layer so we can swap implementations later.” (You never swap.)
“Let’s make this configurable so it works for every team.” (Only one team uses it.)
“Let’s build a plugin system in case we need extensibility.” (You don’t.)

Each decision makes sense in isolation. Together, they bury the actual logic under layers that exist to serve hypothetical futures. This is the same instinct that drives over-engineering – building for problems you don’t have yet.

Choosing Complexity Over Complication

The discipline is knowing when to accept complexity and when to refuse complication. A few heuristics:

Can you explain the complexity in one sentence? If the justification is clear and concrete, it’s probably warranted. If it takes a paragraph of hypotheticals, it’s probably complication.
Does removing it break something today? Warranted complexity is load-bearing. Complication can be removed without consequence.
Did you add it to solve a problem, or to prevent one? Solving real problems creates complexity. Preventing imaginary problems creates complication.

The goal isn’t to minimize complexity at all costs. It’s to ensure that every piece of complexity earns its place.

The Zen Got It Right

“Complex is better than complicated” is not a license to build complex systems. It’s a reminder that when a problem demands complexity, the answer is to embrace that complexity honestly – not to paper over it with layers of complication that make the system harder to understand.

Simple when you can. Complex when you must. Complicated never.

This article was originally posted on LinkedIn.

]]>

Simple Is Better Than Complex

2025-03-27T00:00:00+00:00

Complexity Is the Default

Complex code is easy to write. You think through a problem sequentially, handle each case as it appears, and the result is a tangle of branches and edge cases that technically works. No discipline required.

Simple code is the opposite. It requires you to understand the problem deeply enough to find the clean solution – the one that handles the cases without special-casing them, that expresses the logic without obscuring it. That understanding takes time. Simplicity is the output of effort, not the absence of it.

This is why over-engineering is so common. It feels like progress. Adding layers, abstractions, and configuration options feels like building something robust. But robustness comes from simplicity, not from complexity with guardrails.

Simple Doesn’t Mean Easy

There’s a critical distinction between simple and easy. Easy is what you reach for first. Simple is what you arrive at after removing everything that doesn’t need to be there.

A function with one responsibility is simple. A class that does one thing well is simple. A system where you can trace a request from input to output without jumping through six layers of indirection is simple. None of these are easy to design. All of them are easy to maintain.

The Zen of Python follows “simple is better than complex” with “complex is better than complicated.” That ordering matters. Sometimes genuine complexity exists in the problem domain. The principle isn’t to deny that complexity – it’s to never add accidental complexity on top of it.

The Readability Dividend

Simple code pays compound interest in readability. When a function is short, named well, and does one thing, you can read it in seconds. When a module has a clear interface and minimal dependencies, you can reason about it in isolation. When a system is composed of simple parts, you can understand the whole by understanding the pieces.

Every layer of unnecessary complexity breaks this. A reader hits an abstraction and has to ask: “Why is this here? What problem does this solve?” If the answer is “none, currently,” you’ve just spent their attention on nothing.

Simplicity Is a Practice

Writing simple code isn’t a one-time decision. It’s a practice you apply at every level, every day:

Before adding a new abstraction, ask whether the concrete code is actually hard to understand.
Before adding a configuration option, ask whether anyone will ever change it.
Before splitting a function, ask whether the pieces are genuinely independent ideas.
Before reaching for a pattern, ask whether the pattern serves the code or the other way around.

The answer is often “no.” And “no” is the most powerful tool for keeping things simple.

The Zen got it right. Simple is better than complex. Not because simplicity is easy, but because it’s worth the effort.

This article was originally posted on LinkedIn.

]]>

Explicit Is Better Than Implicit

2025-03-26T00:00:00+00:00

The Zen Got It Right

“Explicit is better than implicit” is one of the core principles from the Zen of Python, but like flat over nested and sparse over dense, it applies to all software. It’s a statement about communication. Code that states its intent directly is code that can be understood, maintained, and trusted.

Implicit code does the opposite. It asks the reader to know things that aren’t written down – conventions, defaults, inherited behavior, environmental assumptions. Every implicit decision is a gap the reader has to fill with their own knowledge. Some readers won’t have that knowledge. Some will guess wrong.

The Cost of Going Implicit

Implicit code feels convenient at first. You save a few keystrokes. You lean on framework magic. You trust that the next reader will just know how things work. Then someone new joins the team, and they don’t.

The costs show up in predictable ways:

Debugging takes longer. When behavior is implicit, you can’t just read the code to understand what’s happening. You have to trace through framework internals, check configuration files, and reconstruct the hidden control flow.
Onboarding slows down. New team members have to learn the invisible rules before they can be productive. The more implicit knowledge a codebase requires, the steeper the learning curve.
Bugs hide in assumptions. Implicit defaults change between versions. Implicit type coercions produce surprising results. Implicit ordering dependencies break when someone adds a step in the wrong place.

Every implicit decision is a bet that the reader will have the same context you have right now. That bet loses more often than you’d think.

Where Explicitness Pays Off

Explicitness matters most at the boundaries – the places where different parts of a system communicate.

Naming. A function called process tells you nothing. A function called validate_and_normalize_email tells you exactly what it does. Explicit names eliminate guesswork.

Configuration. Explicit configuration files beat convention-over-configuration when the conventions aren’t well-known. If your team has to look up what the default is, it should be stated.

Error handling. Explicit error handling – checking return values, catching specific exceptions, validating inputs at boundaries – prevents the silent failures that implicit error handling allows.

Dependencies. Explicit imports and dependency declarations make it clear what a module needs. Implicit dependency injection or service locators hide relationships that matter for understanding and testing.

Types. Type annotations make contracts visible. When a function signature says it takes a string and returns an int, the reader doesn’t have to infer the contract from usage patterns. The code documents itself.

Explicit Doesn’t Mean Verbose

There’s a common objection: “Explicit code is too verbose.” But explicitness and verbosity are different things. Verbose code adds words without adding information. Explicit code adds exactly the information that would otherwise be hidden.

A ten-line function with clear names and explicit error handling isn’t verbose. A one-liner that relies on three implicit type conversions and a default parameter buried in a framework isn’t concise – it’s obscure.

The goal isn’t to write more code. It’s to write code where intent is visible without external context.

Explicitness Scales

In a small codebase maintained by one person, implicit conventions work fine. You wrote the conventions. You remember them. But codebases grow. Teams change. The conventions that felt obvious to three people become tribal knowledge that twenty people struggle to reconstruct.

Explicit code doesn’t require shared tribal knowledge to understand. It carries its own context. That’s what makes it resilient to team changes, context switches, and the long gaps between when code is written and when it’s read.

Code quality starts with making intent visible. Explicit code is the most direct way to get there.

Make the implicit explicit. Your code should say what it means without making the reader guess.

This article was originally posted on LinkedIn.

]]>

Today I Learned: Using BETWEEN with SQL Dates

2018-08-10T00:00:00+00:00

Consider the following for table articles.

CREATE TABLE articles (
  ...
  created_at date
)

SELECT * FROM articles
WHERE created_at BETWEEN '2018-08-01'::DATE AND '2018-08-07'::DATE

For articles, we don’t care about the time the article was posted, only the day.

In the PostgreSQL documentation for BETWEEN, it states that it is inclusive on both ends e.g. x <= a <= y. This would mean that our query above would return all articles created between August 1, 2018 and including August 7, 2018. And it does.

Now, consider the table comments.

CREATE TABLE comments (
  ...
  created_at timestamp
)

SELECT * FROM comments
WHERE created_at BETWEEN '2018-08-01'::TIMESTAMP AND '2018-08-07'::TIMESTAMP

Very similar to articles except here we do care about the time a comment was posted, so the column type is timestamp.

Similarly, we want to retrieve all comments that were posted between August 1, 2018 and including August 7, 2018. If you expected the query above to return comments that were created on August 1, 2018 and all comments created on August 7, 2018, you would be wrong.

I learned from a colleague, “Your target column will be inclusive of that type”. This sounds a bit confusing, so let me explain.

Using BETWEEN creates a time interval. This means that '2018-08-07'::DATE is read in as 2018-08-07 00:00:00. Therefor the query is checking if the row will be included within the date type of 2018-08-07 00:00:00. And it is. '2018-08-07 00:00:00'::DATE is equal to '2018-08-07'::DATE.

However, in the query for comments, the '2018-08-07'::TIMESTAMP is also read in as 2018-08-07 00:00:00. This means that all comments created during the day of August 7, 2018 will not be included in the results. For instance, a comment created 2018-08-07 04:13:47 is not before or equal to 2018-08-07 00:00:00.

Here it is in a more digestible format.

|           |          2018-08-07 | 2018-08-07 04:13:47 | <= 2018-08-07::DATE | <= 2018-08-07::TIMESTAMP |
|-----------|---------------------|---------------------|---------------------|--------------------------|
| date      |          2018-08-07 | 2018-08-07          | true                | true                     |
| timestamp | 2018-08-07 00:00:00 | 2018-08-07 04:13:47 | true                | false                    |

]]>

Today I Learned: Docker Compose Networks

2018-06-14T00:00:00+00:00

The Problem

I have 2 services, let’s call them foo-service and bar-service. They both live in their respective directories as siblings.

.
├── bar-service
│   ├── docker-compose.yml
│   └── src
└── foo-service
    ├── docker-compose.yml
    └── src

bar-service refers to foo-service’s network like so:

# bar-service/docker-compose.yml

networks:
  default:
    external:
      name: fooservice_default

The Yak Shave

By default Compose sets up a single network for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by them at a hostname identical to the container name.
https://docs.docker.com/compose/networking/

The Solution

As of docker-compose 1.21.0:

Dashes and underscores in project names are no longer stripped out.
https://github.com/docker/compose/blob/master/CHANGELOG.md#1210-2018-04-10

This means that the docker-compose.yml file above for bar-service needs the network name for foo-service updated to add back in the stripped dashes.

# bar-service/docker-compose.yml

networks:
  default:
    external:
      name: foo-service_default

As of Docker Compose file format version 3.5, the network name can be explicitly defined as described in Specify custom networks.

# foo-service/docker-compose.yml

version: "3.5"

networks:
  default:
    name: fooservice

And the original external network configuration file for bar-service would now work, referencing the network of foo-service as fooservice_default.

]]>

Understanding Clojure: cond and condp

2016-01-27T00:00:00+00:00

cond

(cond
  (> 0 (:amount account)) "Your balance is negative"
  (< 0 (:amount account)) "Your balance is positive"
  (= 0 (:amount account)) "Your balance is zero")

There is also the option of a default case using :else.

(cond
  (> 0 (:amount account)) "Your balance is negative"
  (< 0 (:amount account)) "Your balance is positive"
  :else "Your balance is zero")

condp

condp can be used if your predicate remains the same for each condition and you wish to switch on the result.

(condp < (:amount account)
  10000 "top tier dividend"
  5000 "second tier dividend"
  1000 "first tier dividend"
  0 "no dividend")

To supply an else condition to condp, you leave out the :else keyword and supply the result expression.

(condp < (:amount account)
  10000 "top tier dividend"
  5000 "second tier dividend"
  1000 "first tier dividend"
  "no dividend")

You can also supply condp with your own predicate function.

(defn describe [amount]
  (cond
    (> 0 amount) :negative
    (< 0 amount) :positive
    :else :zero))

(defn compare [descriptor amount]
  (= descriptor (describe amount)))

(condp compare (:amount account)
  :negative "Your balance is negative"
  :positive "Your balance is positive"
  :zero "Your balance is zero")

The predicate function (compare) must take exactly two arguments and must return a binary result. The predicate function would be called like:

(compare :negative (:amount account))
(compare :positive (:amount account))
(compare :zero (:amount account))

]]>

Datomic Performance with Clause Ordering

2014-08-13T00:00:00+00:00

For example, say we have 100 cities all with a daily temperature reading for every day of the last year. A total of 36,500 temperature entries. If we want to find the temperature for Denver on July 31, which query would be faster?

Version 1:

[:find ?temp
 :in ?city ?date
 :where
 [?temp :temperature/city ?city]
 [?temp :temperature/date ?date]]

Version 2:

[:find ?temp
 :in ?city ?date
 :where
 [?temp :temperature/date ?date]
 [?temp :temperature/city ?city]]

Version 1 will filter 36,500 temperatures → 365 temperatures → 1 temperature.

Version 2 will filter 36,500 temperatures → 100 temperatures → 1 temperature.

So, I’m suggesting that Version 2 of the query should perform better per the suggestions of the Datomic docs.

Let’s Get Scientific

Instead of just speculating, how about I run some timings and find out for sure.

(defn version-1 [& {city :for date :on}]
  (datomic.api/q '[:find ?temp
                   :in $ ?city ?date
                   :where
                   [?temp :temperature/city ?city]
                   [?temp :temperature/date ?date]]
                   (db) city date))

(defn version-2 [& {city :for date :on}]
  (datomic.api/q '[:find ?temp
                   :in $ ?city date
                   :where
                   [?temp :temperature/date ?date]
                   [?temp :temperature/city ?city]]
                   (db) city date))

(defn sample-1 [n-times]
  (dotimes [n n-times]
    (time (version-1 :for "Denver" :on (clj-time.coerce/to-date
                                         (clj-time.core/date-time 2014 7 31))))))

(defn sample-2 [n-times]
  (dotimes [n n-times]
    (time (version-2 :for "Denver" :on (clj-time.coerce/to-date
                                         (clj-time.core/date-time 2014 7 31))))))

(sample-1 100)
;;=> "Elapsed time: 10.949 msecs"
;;=> "Elapsed time: 9.007 msecs"
;;=> "Elapsed time: 9.8 msecs"
...

(sample-2 100)
;;=> "Elapsed time: 6.772 msecs"
;;=> "Elapsed time: 7.103 msecs"
;;=> "Elapsed time: 8.745 msecs"
...

It turns out, for a year’s worth of data for 100 cities, the average time for Version 1 was 8.91 msecs. Version 2 average was 7.47 msecs. A measly 1.5 msecs, or 16% difference.

As the Dataset Grows

Let’s think about how these two queries perform as the data grows. After the second year of our application gathering daily temperature data, we would have 73,000 total temperature entries.

Version 1 will filter 73,000 temperatures → 730 temperatures → 1 temperature.

Version 2 will filter 73,000 temperatures → 100 temperatures → 1 temperature.

Even though the amount of data doubled, the number of candidate entries after the first clause in Version 2 stayed the same.

How does the increase in data affect our timings?

(sample-1 100)
;;=> "Elapsed time: 42.886 msecs"
;;=> "Elapsed time: 30.389 msecs"
;;=> "Elapsed time: 43.137 msecs"
...

(sample-2 100)
;;=> "Elapsed time: 12.494 msecs"
;;=> "Elapsed time: 10.94 msecs"
;;=> "Elapsed time: 11.813 msecs"
...

The average for Version 1 for 2 years of data came to 18.87 msecs while the average time for Version 2 was 12.53 msecs. That is nearly 66% the running time. This goes to show, that as your data increases, performance adjustments like these become increasingly important.

Caveat

For small datasets, say within the first week, here’s how the two versions perform.

Version 1 will filter 700 temperatures → 7 temperatures → 1 temperature.

Version 2 will filter 700 temperatures → 100 temperatures → 1 temperature.

Wait, what?

This is because the number of cities is greater than the number of dates. In this example, it is a small amount and may only result in fractions of a millisecond difference. It shall serve only as a reminder that your data is different than my data, and your results may vary.

]]>

The Avocado Project: Day 1

2014-08-01T00:00:00+00:00

Here it is in all its glory just before I’m about to slice it open. A perfectly ripe organic avocado. I’m not sure if the organic will make a difference for this purpose, but that’s what I had on hand.

I typically use this method for opening my avocados. But this time I scooped out the seed to keep from damaging it.

After rinsing and drying the seed, I jammed three bamboo skewers into the widest part of the avocado. It was actually quite a bit easier than I had anticipated. A lot of online instructions say to use toothpicks. I would definitely use toothpicks next time as the thicker skewers slightly split the seed up one side. I hope it’s OK.

I then placed the Sputnick-looking avocado seed over the top of a wide-mouth mason jar. Be sure to have the pointed end facing up because the root will come out of the bottom. I then filled the mason jar with water just so the bottom of the seed is submerged.

I would also advise you to, unlike me, jam the toothpicks with a slight upward angle in order to keep the seed just a bit below the rim. This way it is easier to keep the seed submerged without needing to fill the jar clear to the rim.

Now, place the soon-to-be avocado sprout in a warm, sunny area of your home. Lucky for us, our largest windows face directly east. We get the bright Colorado sunrise coming in every morning!

I won’t expect much action out of this little guy for several weeks. In the meantime, I will be keeping an eye on the water level and topping it off to keep the bottom submerged.

See you in a few weeks!

]]>

Setting Null Values in Datomic

2014-04-21T00:00:00+00:00

Why Do Null Values Not Exist in Datomic?

It took a few moments to fully understand why it is that Datomic does not allow setting a value to null. If you do try, this is the exception you receive.

IllegalArgumentExceptionInfo :db.error/nil-value Nil is not a legal value  datomic.error/arg (error.clj:55)

Looking at the development resources for Datomic and the section on Implications, it states:

Most Datomic writes are of tree nodes. These writes are compatible with eventually consistent storage, because the semantics of immutable values are beautifully simple: In an immutable system with no updates, there are only two possibilities: - a value is present - a value is not present yet
https://docs.datomic.com/on-prem/acid.html#implications

The important pieces to understand are the bullet points. A value must either exist or not; it cannot be null. Thinking in terms of datoms and entities, an entity either has a value for an attribute or the attribute does not exist for the entity. The entity cannot have an attribute with a value of null.

So what if we need to set a value to null?

How to Set Null Values

Let’s say that John fills out a form and includes his firstname and lastname. We would save this to Datomic as such.

(datomic/transact conn [{:db/id (datomic/tempid :db.part/user)
                         :user/firstname "John"
                         :user/lastname "Smith"}])

We can retrieve these values like so.

(datomic/q '[:find ?id ?firstname ?lastname
             :in $
             :where
             [?id :user/firstname ?firstname]
             [?id :user/lastname ?lastname]]
           (datomic/db conn))
;; => #{[17592186045418 "John" "Smith"]}

(datomic/touch
 (datomic/entity (datomic/db conn) 17592186045418))
;; => {:db/id 17592186045418, :user/firstname "John", :user/lastname "Smith"}

Now John wishes to remove his lastname from the system. Instead of setting the value of :user/lastname to null, we have to retract the fact of John’s lastname being “Smith”.

(datomic/transact conn [[:db/retract 17592186045418
                         :user/lastname "Smith"]])

And the result of retracting John’s lastname.

;; same query as above
(datomic/q '[:find ?id ?firstname ?lastname
             :in $
             :where
             [?id :user/firstname ?firstname]
             [?id :user/lastname ?lastname]]
           (datomic/db conn))
;; => #{}

No entities with both the :user/firstname and :user/lastname attributes exist.

However.

(datomic/q '[:find ?id ?firstname
             :in $
             :where
             [?id :user/firstname ?firstname]]
           (datomic/db conn))
;; => #{[17592186045418 "John"]}

(datomic/touch
 (datomic/entity (datomic/db conn) 17592186045418))
;; => {:db/id 17592186045418, :user/firstname "John"}

It’s the same entity but with the :user/lastname attribute retracted.

Retracting Values Programmatically

When John submits the form to remove his lastname, the system can’t hardcode the old value to build the retract statement. Here’s how you might go about finding the correct value and retracting when you need to. This code will not retract values which weren’t removed.

(defn edit-or-create-user-txn [params]
  "Returns a transaction for creating a new entity and/or
  updating attributes of an existing entity."
  (let [user-entity (find-user-entity (:id params))
        id (if user-entity
             (:db/id user-entity)
             (datomic/tempid :db.part/user -1))
        edited (edited-fields id params)
        retracted (retracted-fields user-entity params)]
    (apply conj [] edited retracted)))

user=> (edit-or-create-user-txn {:user/firstname "John"
                                 :user/middlename "Patrick"
                                 :user/lastname "Smith"})
;; => [{:db/id 17592186045418
;; =>   :user/firstname "John"
;; =>   :user/middlename "Patrick"
;; =>   :user/lastname "Smith"}]

user=> (edit-or-create-user-txn {:id 17592186045418
                                 :user/firstname "Johnny"
                                 :user/middlename ""
                                 :user/lastname ""})
;; => [{:db/id 17592186045418
;; =>   :user/firstname "Johnny"}
;; =>  [:db/retract 17592186045418 :user/middlename "Patrick"]
;; =>  [:db/retract 17592186045418 :user/lastname "Smith"]]

In order for the above function to work, we need edited-fields.

(defn edited-fields [id params]
  "Returns a map of non-empty values to be used as a Datomic entity."
  (into {:db/id id}
        (filter second {:user/firstname (:firstname params)
                        :user/lastname (:lastname params)
                        ...})))

And retracted-fields.

(defn- has-empty-value? [[k v]]
  (empty? (str v)))

(defn- keys-for-empty-vals
  "Get a list of keys from a map which have empty values."
  [m]
  (keys (filter has-empty-value? m)))

(defn- retract-statement
  "Only build a retract statement for existing values."
  [old-entity k]
  (let [v (get old-entity k)]
    (when v
      [:db/retract (:db/id old-entity) k v])))

(defn retracted-fields
  "Get all retractions from an existing entity."
  [old-entity new-entity]
  (filterv identity (map (partial retract-statement old-entity)
                         (keys-for-empty-vals new-entity))))

user=> (retracted-fields {
                          :user/firstname "John"
                          :user/middlename "Patrick"
                          :user/lastname "Smith"
                         }
                         {
                          :user/firstname "John"
                          :user/middlename ""
                          :user/lastname ""
                         })
;; => [[:db/retract 17592186045418 :user/middlename "Patrick"]
;; =>  [:db/retract 17592186045418 :user/lastname "Smith"]]

In a sort of round-a-about way, retracted-fields returns a vector of :db/retract vectors for datomic/transact to handle. It does so using the following method.

Get a list of all keys in the new-entity which have empty values.
Map across them to build a [:db/retract eid key val].
Filter out retraction vectors which were empty (i.e. no retraction needed).

Write Once, Use Everywhere

The nice thing about the retractions code is it’s been generalized enough that we’ve pulled it into it’s own namespace.

(ns com.example.retractions
  ...)

This makes it super simple for the next entity which requires nullable modifications.

(retractions/retracted-fields old-car new-car)

Resources

]]>

Clojure Protocol Namespaces

2014-03-19T00:00:00+00:00

First off, if you’re not familiar with Protocols, I suggest you go check out the documentation.

I’ll continue to use the examples from my recent blog post on Implementing Clojure Protocols. Here we have a protocol for defining how something Drives.

(ns company.drives)

(defprotocol Drives
  "a protocol for driving"
  (drive [this throttle]))

Using a Protocol from a Different Namespace

In the concrete implementation of Car we need to require the Drives protocol like so.

(ns company.car
  (:require [company.drives :refer [Drives]]))

(defrecord Car [top-speed]
  Drives
  (drive [_ throttle] (str "Spin wheels " (* top-speed throttle))))

Then in the namespace in which we are instantiating and using Car, we’ll need to require the namespaces of the protocol and record. As well as import the record.

(ns company.core
  (:require [company.car]
            [company.drives :refer [drive]])
  (:import company.car.Car))

(defn -main [args]
  (println (drive (Car. 60.0) 0.4)))

What About Dashes?

There’s something tricky about using dashes in namespaces that I couldn’t find in any documentation.

Given these two facts about Java and Clojure:

Java cannot have dashes in class names
Clojure converts all dashes to underscores when compiling to Java

I was able to trial-and-error my way into a solution for dealing with dashes in protocols.

(ns company.school-bus
  (:require [company.drives :refer [Drives]]))

(defrecord SchoolBus [top-speed]
  Drives
  (drive [_ throttle] (str "The wheels on the bus go " (* top-speed throttle))))

(ns company.core
  (:require [company.car]
            [company.drives :refer [drive]]
            [company.school-bus])
  (:import company.car.Car
           company.school_bus.SchoolBus))

(defn -main []
  (println (drive (Car. 60.0) 0.4))
  (println (drive (SchoolBus. 45.0) 0.4)))

Notice the use of dash in the :require but the use of underscore in the :import. This is because the :import is a Java import used for Java classes, and we must refer to our SchoolBus record as a Java class.

Check out my article on Implementing Clojure Protocols for more information.

]]>

Mixpanel Mock

2014-03-12T00:00:00+00:00

When using Mixpanel it’s best not to send events while in development, staging, demo, or QA environments. I created a class to load a mock that will simply log to the console for tracking events.

class MixpanelMock
  track: () ->
      console.log("mixpanel.track", arguments)

window.mixpanel = new MixpanelMock()

You can get the updated source of MixpanelMock on GitHub.

Using in Rails

I usually save the Mixpanel JavaScript Library to a file in vendor/assets/javascripts/mixpanel.js.

Then I place MixpanelMock in vendor/assets/javascripts/mixpanel-mock.coffee.

I use the code below to conditionally load the real or fake Mixpanel library.

- if Rails.env.production?
  = javascript_include_tag "mixpanel"
- else
  = javascript_include_tag "mixpanel-mock"

This way, when not in production, all of your Mixpanel tracking events will simply be printed to the console. This also makes it super simple, as a developer, to know when certain events are being sent to Mixpanel.

]]>

Implementing Clojure Protocols

2014-01-30T00:00:00+00:00

How to Define a Protocol

(defprotocol Drives
  "a protocol for driving"
  (drive [this throttle]))

Now we’ve got a Java interface named Drives with one (polymorphic) public function drive to be implemented by deftype or defrecord. You could also implement the protocol in Java with a little interop magic. I won’t get into this, however.

The drive function is polymorphic in that it will dispatch on the type of the first argument to the function. This is why every protocol function must take at least one argument. You can think of the first argument as always being this.

Implement a Clojure Protocol

Let’s implement the Drives protocol and create a concrete Car class.

(defrecord Car [top-speed]
  Drives
  (drive [_ throttle] (str "Spin wheels " (* top-speed throttle))))

Java equivalent:

class Car implements Drives {
  private float top_speed;

  public Car(float top_speed) {
    this.top_speed = top_speed;
  }

  public String drive(float throttle) {
    return "Spin wheels " + Float.toString(this.top_speed * throttle);
  }
}

Now we’ve got a concrete implementation of Drives named Car. As you can see, we implemented the drive function.

What’s the _ parameter to drive you may ask? It essentially means “I don’t care about this value you’re passing in.” It is convention to use _ as the parameter name for values in which your function doesn’t use. In this case, it would be this, the passed in Car instance.

Let’s drive some cars.

(def ferrari (Car. 200.0))
(def honda (Car. 80.0))

(drive ferrari 0.5) ;;=> Spin wheels 100.0
(drive honda 1.0)   ;;=> Spin wheels 80.0

With this very scientific and accurate physics model, a Ferrari applying only 50% throttle will drive faster than a Honda with the pedal to the floor.

So what’d we do? First, we instantiated two instances of Car by passing in the top-speed value to the constructor. To call one of the functions from the protocol, you do so just as you would any other clojure function. Passing in the object as the first argument.

Java equivalent:

Drives ferrari = new Car(200.0);
Drives honda = new Car(80.0);

ferrari.drive(0.5);
honda.drive(1.0);

Polymorphic Function Dispatch

So we’ve implemented Car and shown that (drive ferrari 0.5) works as you would expect. What about another concrete class Boat which also implements Drives.

(defrecord Boat [top-speed]
  Drives
  (drive [_ throttle] (str "Spin propeller " (* top-speed throttle))))

(def chris-craft (Boat. 70.0))

(drive chris-craft 0.8) ;;=> Spin propeller 56.0

The drive function dispatched to the implementation defined by Boat.

Using Records and Types Elsewhere

Under the covers, the record is essentially a map. This means you can use it just as you would any other map-like data structure.

Get the top-speed of the ferrari.

(:top-speed ferrari) ;;=> 200.0

Create a blue-honda.

(def blue-honda (assoc honda :color "blue"))
;;=> Car{:top-speed 80.0, :color "blue"}

]]>

Null Object in Groovy

2014-01-18T00:00:00+00:00

If you aren’t familiar with the Null Object Pattern, I suggest taking a look now. It’s not a pattern used only in the Groovy programming language. In fact, I got the idea for this blog post while writing RSpec tests at night while simultaneously working on a Grails application for a client. RSPec Mocks is where you’ll find my inspiration.

First, let me show you what the AsNullObject class looks like.

class AsNullObject {
  def propertyMissing(String name) {
    return this
  }

  def methodMissing(String name, args) {
    return this
  }
}

When writing unit tests, you need not care what any collaborator objects do or (hopefully) their side effects. So, with a little meta-programming magic, no more MissingMethodException or MissingPropertyException. Even better, no more 15 lines of test setup. Happy dance.

Here’s an example.

groovy> myNullObject = new AsNullObject()
Result: AsNullObject@5a06eeee

groovy> myNullObject.something()
Result: AsNullObject@5a06eeee

groovy> myNullObject.something().andAnother()
Result: AsNullObject@5a06eeee

groovy> myNullObject.attribute
Result: AsNullObject@5a06eeee

groovy> myNullObject.attribute.anotherAttribute
Result: AsNullObject@5a06eeee

Whew. Not so bad, eh?

In the context of a unit test, I would use it like so.

void testFireWeapon() {
  ammo = new AsNullObject()
  weapon = new BFG(ammo)
  assert weapon.fire() == "BOOM!"
}

For our test, we probably don’t want to actually fire any real ammo. But, we want our system to behave naturally and not throw errors.

I hope this helps.

Cheers.

]]>

When to Extract Constants

2013-08-16T00:00:00+00:00

Consider the following:

class Greeter
  HELLO = "Hello"

  def self.greet(name)
    "#{HELLO}, #{name}"
  end
end

This is a simple and contrived example but you get the point.

Why extract constants which are merely strings of the same name? Extracting the HELLO constant provides no extra information or insight into the value.

Understandably, one could argue in favor of reuse. If our greeting needs to change from “Hello” to “Guten tag”, we have one spot to do so. But then again, would a constant with the name HELLO really make sense now if the value is “Guten tag”? I’m suggesting that it does not, and everywhere that references the constant HELLO should be changed to GUTEN_TAG; totally nullifying the argument for reuse and maintenance simplification.

So, when should we use constants?

class Today
  WEDNESDAY = 3

  def self.wednesday?
    Date.today.wday == WEDNESDAY
  end
end

You see, extracting the value 3 into a constant, giving it a name, helps give some meaning to an otherwise magical 3. Checking for ==3 all throughout our code gives us no insight into what we’re actually testing. Using the term WEDNESDAY gives us some context.

Values, that are constant in the domain, also make great constants.

class Earth
  DISTANCE_TO_THE_MOON = 238_900

  def self.time_to_the_moon(velocity)
    DISTANCE_TO_THE_MOON / velocity
  end
end

In Summary

All in all, here are a few general guidelines I like to follow when deciding whether or not I should extract a value to a constant:

Code reuse and maintenance simplification
Provides a meaningful name to an otherwise “magical” value
The value is a fact of the world and never changes

]]>

Hello World!

2013-07-30T00:00:00+00:00

I started this blog to write about what I learn and think about as a software engineer. The patterns that work, the ones that don’t, and the opinions I’ve formed along the way about building software that lasts.

Expect posts about code quality, testing, team dynamics, and whatever else I find worth writing down. If it made me a better engineer, it might be worth sharing.

]]>