Irrational Exuberance

Facilitating AI adoption at Imprint

Sun, 07 Dec 2025 08:00:00 -0700

I’ve been working on internal “AI” adoption, which is really LLM-tooling and agent adoption, for the past 18 months or so. This is a problem that I think is, at minimum, a side-quest for every engineering leader in the current era. Given the sheer number of folks working on this problem within their own company, I wanted to write up my “working notes” of what I’ve learned.

This isn’t a recommendation about what you should do, merely a recap of how I’ve approached the problem thus far, and what I’ve learned through ongoing iteration. I hope the thinking here will be useful to you, or at least validates some of what you’re experiencing in your rollout. The further you read, the more specific this will get, ending with cheap-turpentine-esque topics like getting agents to reliably translate human-readable text representations of Slack entities into mrkdwn formatting of the correct underlying entity.

I am hiring: If you’re interested in working together with me on internal agent and AI adoption at Imprint, we are hiring our founding Senior Software Engineer, AI. The ideal candidate is a product engineer who’s spent some time experimenting with agents, and wants to spend the next year or two digging into this space.

Prework: building my intuition

As technologists, I think one of the basics we owe our teams is spending time working directly with new tools to develop an intuition for how they do, and don’t work. AI adoption is no different.

Towards that end, I started with a bit of reading, especially Chip Huyen’s AI Engineering, and then dove in a handful of bounded projects: building my rudimentary own agent platform using Claude code for implementation, creating a trivial MCP for searching my blog posts, and an agent to comment on Notion documents.

Each of these projects was two to ten hours, and extremely clarifying. Tool use is, in particular, something that seemed like magic until I implemented a simple tool-using agent, at which point it become something extremely non-magical that I could reason about and understand.

Our AI adoption strategy

Imprint’s general approach to refining AI adoption is strategy testing: identify a few goals, pick an initial approach, and then iterate rapidly in the details until the approach genuinely works. In an era of crushing optics, senior leaders immersing themselves in the details is one of our few defenses.

Shortly after joining, I partnered with the executive team to draft the above strategy for AI adoption. After a modest amount of debate, the pillars we landed on were:

Pave the path to adoption by removing obstacles to adoption, especially things like having to explicitly request access to tooling. There’s significant internal and industry excitemetn for AI adoption, and we should believe in our teams. If they aren’t adopting tooling, we predominantly focus on making it easier rather than spending time being skeptical or dismissive of their efforts towards adoption.
Opportunity for adoption is everywhere, rather than being isolated to engineering, customer service, or what not. To become a company that widely benefits from AI, we need to be solving the problem of adoption across all teams. It’s not that I believe we should take the same approach everywhere, but we need some applicable approach for each team.
Senior leadership leads from the front to ensure what we’re doing is genuinely useful, rather than getting caught up in what we’re measuring.

As you see from those principles, and my earlier comment, my biggest fear for AI adoption is that they can focus on creating the impression of adopting AI, rather than focusing on creating additional productivity. Optics are a core part of any work, but almost all interesting work occurs where optics and reality intersect, which these pillars aimed to support.

As an aside, in terms of the components of strategy in Crafting Engineering Strategy, this is really just the strategy’s policy. In addition, we used strategy testing to refine our approach, defined a concrete set of initial actions to operationalize it (they’re a bit too specific to share externally), and did some brief exploration to make sure I wasn’t overfitting on my prior work at Carta.

Documenting tips & tricks

My first step towards adoption was collecting as many internal examples of tips and tricks as possible into a single Notion database. I took a very broad view on what qualified, with the belief that showing many different examples of using tools–especially across different functions–is both useful and inspiring.

I’ve continued extending this, with contributions from across the company, and it’s become a useful resource for both humans and bots alike to provide suggestions on approaching problems with AI tooling.

Centralizing our prompts

One of my core beliefs in our approach is that making prompts discoverable within the company is extremely valuable. Discoverability solves four distinct problems:

Creating visibility into what prompt’s can do (so others can be inspired to use them in similar scenarios). For example, that you can use our agents to comment on a Notion doc when it’s created, respond in Slack channels effectively, triage Jira tickets, etc
Showing what a good prompt looks like (so others can improve their prompts). For example, you can start moving complex configuration into tables and out of lists which are harder to read and accurately modify
Serving as a repository of copy-able sections to reuse across prompts. For example, you can copy one of our existing “Jira-issue triaging prompts” to start triaging a new Jira project
Prompts are joint property of a team or function, not the immutable construct of one person. For example, anyone on our Helpdesk team can improve the prompt responding to Helpdesk requests, not just one person with access to the prompt, and it’s not locked behind being comfortable with Git or Github (although I do imagine we’ll end up with more restrictions around editing our most important internal agents over time)
Identifying repeating prompt sub-components that imply missing or hard to use tools. For example, earlier versions of our prompts had a lot of confusion around how to specify Slack users and channels, which I got comfortable working around, but others did not

My core approach is that every agent’s prompt is stored in a single Notion database which is readable by everyone in the company. Most prompts are editable by everyone, but some have editing restrictions.

Here’s an example of a prompt we use for routing incoming Jira issues from Customer Support to the correct engineering team.

Here’s a second example, this time of responding to requests in our Infrastructure Engineering team’s request channel.

Pretty much all prompts end with an instruction to include a link to the prompt in the generated message. This ensures it’s easy to go from a mediocre response to the prompt-driving the response, so that you can fix it.

Adopting standard platform

In addition to collecting tips and prompts, the next obvious step for AI adoption is identifying a standard AI platform to be used within the company, e.g. ChatGPT, Claude, Gemini or what not.

We’ve gone with OpenAI for everyone. In addition to standardizing on a platform, we made sure account provisioning was automatic and in place on day one. To the surprise of no one who’s worked in or adjacent to IT, a lot of revolutionary general AI adoption is… really just account provisioning and access controls. These are the little details that can so easily derail the broader plan if you don’t dive into them.

Within Engineering, we also provide both Cursor and Claude. That said, the vast majority of our Claude usage is done via AWS Bedrock, which we use to power Claude Code… and we use Claude Code quite a bit.

Other AI tooling

While there’s a general industry push towards adopting more AI tooling, I find that a significant majority of “AI tools” are just SaaS vendors that talk about AI in their marketing pitches. We have continued to adopt vendors, but have worked internally to help teams evaluate which “AI tools” are meaningful.

We’ve spent a fair amount of time going deep on integrating with AI tooling for chat and IVR tooling, but that’s a different post entirely.

Metrics

Measuring AI adoption is, like all measurement topics, fraught. Altogether, I’ve found measuring tool adoption very useful for identifying the right questions to ask. Why haven’t you used Cursor? Or Claude Code? Or whatever? These are fascinating questions to dig into. I try to look at usage data at least once a month, with a particular focus on two questions:

For power adopters, what are they actually doing? Why do they find it useful?
For low or non-adopters, why aren’t they using the tooling? How could we help solve that for them?

At the core, I believe folks who aren’t adopting tools are rational non-adopters, and spending some time understanding the (appearance of) resistance goes further than top-down mandate. I think it’s often an education gap that is bridged easily enough. Conceivably, at some point I’ll discover a point of diminishing returns, where the lack of progress is stymied on folks who are rejecting AI tooling–or because the AI tooling isn’t genuinely useful–but I haven’t found that point yet.

Building internal agents

The next few sections are about building internal agents. The core implementation is a single stateless lambda which handles a wide variety of HTTP requests, similar-ish to Zapier. This is currently implemented in Python, and is roughly 3,000 lines of code, much of it dedicated to oddities like formatting Slack messages, etc.

For the record, I did originally attempt to do this within Zapier, but I found that Zapier simply doesn’t facilitate the precision I believe is necessary to do this effectively. I also think that Zapier isn’t particularly approachable for a non-engineering audience.

What has fueled adoption (especially for agents)

As someone who spent a long time working in platform engineering, I still want to believe that you can build a platform, and users will come. Indeed, I think it’s true that a small number of early adopters will come, if the problem is sufficiently painful for them, as was the case for Uber’s service migration (2014).

However, what we’ve found effective for driving adoption is basically the opposite of that. What’s really worked is the intersection of platform engineering and old-fashioned product engineering:

(product eng) find a workflow with a lot of challenges or potential impact
(product eng) work closely with domain experts to get the first version working
(platform eng) ensure that working solution is extensible by the team using it
(both) monitor adoption as indicator of problem-solution fit, or lack thereof

Some examples of the projects where we’ve gotten traction internally:

Writing software with effective AGENTS.md files guiding use of tests, typechecking and linting
Powering initial customer questions through chat and IVR
Routing chat bots to steer questions to solve the problem, provide the the answer, or notify the correct responder
Issue triaging for incoming tickets: tagging them, and assigning them to the appropriate teams
Providing real-time initial feedback on routine compliance and legal questions (e.g. questions which occur frequently and with little deviation)
Writing weekly priorities updates after pulling a wide range of resources (Git commits, Slack messages, etc)

For all of these projects that have worked, the formula has been the opposite of “build a platform and they will come.” Instead it’s required deep partnership from folks with experience building AI agents and using AI tooling to make progress. The learning curve for effective AI adoption in important or production-like workflows remains meaningfully high.

Configuring agents

Agents that use powerful tools represent a complex configuration problem. First, exposing too many tools–especially tools that the prompt author doesn’t effectively understand–makes it very difficult to create reliable workflows. For example, we have an exit_early command that allows terminating the agent early: this is very effective in many cases, but is also easy to break your bot. Similarly, we have a slack_chat command that allows posting across channels, which can support a variety of useful workflows (e.g. warm-handoffs of a question in one channel into a more appropriate alternative), but can also spam folks. Second, as tools get more powerful, they can introduce complex security scenarios.

To address both of these, we currently store configuration in a code-reviewed Git repository. Here’s an example of a JIRA project.

Here’s another for specifying a Slack responder bot.

Compared to a JSON file, we can statically type the configuration, and it’s easy to extend over time. For example, we might want to extend slack_chat to restrict which channels a given bot is allowed to publish into, which would be easy enough. For most agents today, the one thing not under Git-version control is the prompts themselves, which are versioned by Notion. However, we can easily require specific agents to use prompts within the Git-managed repository for sensitive scenarios.

After passing tests, linting and typechecking, the configurations are automatically deployed.

Resolving foreign keys

It’s sort of funny to mention, but one thing that has in practice really interfered with easily writing effective prompts is making it easy to write things like @Will Larson which is then translated into <@U12345> or whatever the appropriate Slack identifier is for a given user, channel, or user group. The same problem exists for Jira groups, Notion pages and databases, and so on.

This is a good example of where centralizing prompts is useful. I got comfortable pulling the unique identifiers myself, but it became evident that most others were not. This eventually ended with three tools for Slack resolution: slack_lookup which takes a list of references to lookup, slack_lookup_prefix which finds all Slack entities that start with a given prefix (useful to pull all channels or groups starting with @oncall-, for example, rather than having to hard-code the list in your prompt), and slack_search_name which uses string-distance to find potential matches (again, useful for dealing with typos).

If this sounds bewildering, it’s largely the result of Slack not exposing relevant APIs for this sort of lookup. Slack’s APIs want to use IDs to retrieve users, groups and channels, so you have to maintain your own cache of these items to perform a lookup. Performing the lookups, especially for users, is itself messy. Slack users have a minimum of three ways they might be referenced: user.profile.display_name, user.name, and user.real_name, only a subset of which are set for any given user. The correct logic here is, as best I can tell, to find a match against user.profile.display_name, then use that if it exists. Then do the same for user.name and finally user.real_name. If you take the first user that matches one of those three, you’ll use the wrong user in some scenarios.

In addition to providing tools to LLMs for resolving names, I also have a final mandatory check for each response to ensure the returned references refer to real items. If not, I inject which ones are invalid into the context window and perform an additional agent loop with only entity-resolution tools available. This feels absurd, but it was only at this point that things really started working consistently.

As an aside, I was embarassed by these screenshots, and earlier today I made the same changes for Notion pages and databases as I had previously for Slack.

Formatting

Similarly to foreign entity resolution, there’s a similar problem with Slack’s mrkdwn variant of Markdown and JIRA’s Atlassian Document Format: they’re both strict.

The tools that call into those APIs now have strict instructions on formatting. These had been contained in individual prompts, but they started showing up in every prompt, so I knew I needed to bring them into the agent framework itself rather than forcing every prompt-author to understand the problem.

My guess is that I need to add a validation step similar to the one I added for entity-resolution, and that until I do so, I’ll continue to have a small number of very infrequent but annoying rendering issues, To be honest, I personally don’t mind the rendering issues, but that creates a lot of uncertainty for others using agents, so I think solving them is a requirement.

Logging and debugging

Today, all logs, especially tool usage, are fed into two places. First, it goes into Datadog for full logging visibility. Second, and perhaps more usefully for non-engineers, they feed into a Slack channel, #ai-logs which create visibility into which tools are used and with which (potentially truncated) parameters.

Longer term, I imagine this will be exposed via a dedicated internal web UX, but generally speaking I’ve found that the subset of folks who are actively developing agents are pretty willing to deal with a bit of cruft. Similarly the folks who aren’t developing agents directly don’t really care, they want it to work perfectly every time, and aren’t spending time looking at logs.

Biggest remaining gap: universal platform for accessing user-scope MCP servers

The biggest internal opportunity that I see today is figuring out how to get non-engineers an experience equivalent to running Claude Code locally with all their favorite MCP servers plugged in. I’ve wanted ChatGPT or Claude.ai to provide this, but they don’t really quite get there, Claude Desktop is close, but is somewhat messy to configure as we think about finding a tool that we can easily allow everyone internally to customize and use on a daily basis.

I’m still looking for what the right tool is here. If anyone has any great suggestions that we can be somewhat confident will still exist in two years, and don’t require sending a bunch of internal data to a very early stage company, then I’m curious to hear!

What’s next?

You’re supposed to start a good conclusion with some sort of punchy anecdote that illuminates your overall thesis in a new way. I’m not sure if I can quite meet that bar, but the four most important ideas for me are:

We are still very early on AI adoption, so focusing on rate of learning is more valuable than anything else
If you want to lead an internal AI initiative, you simply must be using the tools, and not just ChatGPT, but building your own tool-using agent using only an LLM API
My experience is that real AI adoption on real problems is a complex blend of: domain context on the problem, domain experience with AI tooling, and old-fashioned IT issues. I’m deeply skeptical of any initiative for internal AI adoption that doesn’t anchor on all three of those. This is an advantage of earlier stage companies, because you can often find aspects of all three of those in a single person, or at least across two people. In larger companies, you need three different organizations doing this work together, this is just objectively hard
I think model selection matters a lot, but there are only 2-3 models you need at any given moment in time, and someone can just tell you what those 2-3 models are at any given moment. For example, GPT-4.1 is just exceptionally good at following rules quickly. It’s a great model for most latency-sensitive agents

I’m curious what other folks are finding!

Coding at work (after a decade away).

Wed, 19 Nov 2025 08:00:00 -0700

Since joining Imprint a bit over six months ago as the CTO of a ~50 engineer team, I’ve merged 104 pull requests, which is slightly over four per week. Many of them are very minimal configuration and documentation tweaks, and none were the hardest or even most time-sensitive task available at any given time; I’m much more of a pull request scavenger finding opportunities that don’t disrupt the operating teams’ rhythms.

That said, a decent chunk represent meaningful software development tasks, and these 104 pull requests are more pull requests than I’ve completed combined in my prior decade of work, where Uber was the last time I was substantially submitting pull requests (well, whatever Phabricator called its pull request equvialent). Since then, I’ve been predominantly managing managers, and not writing software with my own hands at work.

This has been a fascinating shift, and I wanted to write dome some thoughts on whether this is good for software, good for me, whether it’s fun, and how I’ve personally worked to adapt to the current era.

Unrelatedly, I did enjoy Peter Seibel’s Coders at Work (2009).

Dubious return-on-effort of manager coding

I was a computer science major, and worked as a software engineer prior to becoming an engineering manager. I continued to write software when I was a line manager, and continued to write small projects in my free time after becoming a manager. The idea of writing software at work has always appealing to me.

However, when I became a manager of managers, I stopped writing software at work. I wanted to write software, but it simply felt like a lower return on time than doing something else. For example, if I focusd my time hiring another engineer onto the team, they would undoubtedly do more than I would. Similarly, if I spent time improving our plans, that would have a higher impact than me writing a piece of software. Ultimately, I got stuck in the trap that it was always clear that writing software would be valuable, but it would always be less valuable than another endeavor. Each hour I spent writing software was bad for the business overall, and a sign of questionable judgment.

The same wasn’t true when it came to understanding the codebase, and I’ve tried–to various degrees of success–to build a workable degree of awareness of the codebases I’ve managed. That being said, since I left line management roles, I’ve never been truly successful at doing this beyond the superficial level. My experience is that only writing software can build a truly effective understanding of unreasonable software, and that most startup software is unreasonable due to its origin of being iteratively designed by a shifting cast of characters with an evolving understanding of the domain they are modeling.

You can get very far with a minimal understanding of a codebase and surrounding yourself with strong engineers who you can ask useful questions to and get honest answers. For the big things, this is generally sufficient, but it means you can’t really engage with the small questions without spending engineers’ time on it or making low-judgment decisions.

Whether manager coding is valuable comes down to whether you believe making large decisions more quickly with fewer interrupts for context pulling–and the ability to make numerous small decisions that are otherwise too expensive to make effectively–builds into meaningfully more impactful management. This isn’t a proclimation for others, but for me, I’ve really enjoyed getting back to writing software at work, in large part because the time commitment to do so has dropped significantly over the past couple years.

Finding small pockets of time to write software

The biggest specific challenge for me when it came to writing software as a manager was finding blocks of thinking time to either understand a problem, or to implement the solution. Even simple fixes require an effective mental model of the codebase being worked on.

This becomes inescapably true when you’re focused on long-term impact of your work. For example, adding a bunch of tests might be useful, but it’s often the case that poorly designed tests get throw away over time because they overlap with other existing tests, are flaky, or are slow in aggregate. I think traditionally, a lot of manager coding has fallen into this bucket of optically useful with somewhat dubious long-term value. Doing high quality work simply requires too complete a mental model for folks jumping in and out of writing software.

The new wave of AI tooling like Claude Code or OpenAI Codex are extremely susceptive to creating low-quality commits, but my experience is that used effectively they also provide several opportunities for creating useful code contributions are well. They are effective at:

answering questions into a codebase, e.g. “what are our most common patterns for working with authn and authz? what are good examples of each?”
writing code that fits the existing codebase’s patterns and structure, particularly with a well-written AGENTS.md’s guidance
taking general feedback to revise the approach, e.g. “look for existing utilities that solve date math within our codebase and reuse those”

Most importantly, you can do each of those in a few minutes at a time. Between meetings at work, I generally pop back into one of several Claude Code sessions to see where it got to on a given task, review the code, and suggest next steps.

It’s worth acknowledging that there’s a significant learning curve to doing this well. I’ve spent a meaningful amount of time in the last year learning to write software this way, and each month there are new caveats that I’ve had to understand. Slowly but surely, I’ve built a mental model of both how writing software with AI works, and how Imprint’s codebases work.

As I’ve gotten more knowledgable at both, I’ve refound my ability to write software at work because I can make progress in the small chunks of time between other projects, combined with an hour or two over the week to think more deeply about my approach to more complex issues.

Judgment / problem selection

While new AI tools make it easier than ever for managers to write useful software at work, they also make it easier than ever to write unhelpful software at work. Particularly in senior roles, it’s very easy to write software that makes you feel helpful, but is genuinely unhelpful to the team, and leaves them busier than they were before.

The handful of rules that I’ve found useful for myself here are:

Never contribute to something that is truly time sensitive unless it’s a very constrained thing that I can solve end-to-end today. When that isn’t the case, I’m usually going to slow things down despite trying to help.
Prioritize projects that are hard for teams to get to, but are obviously valuable over time. For example, technical debt clean up, small user-requested features, or missing instrumentation.

Infrequently take on a strategic company project which doesn’t have an owner, and which I am able to complete myself. A real example of this has been writing our first pass of a new Interactive Voice Response built on an AI agent, which was clearly valuable but difficult to prioritize over the team’s existing work.
Hold myself to a higher bar than I would hold others in terms of fully releasing my software, monitoring its release, and solving bugs it creates. If I don’t have time to do those things, then I am stealing time from the team rather than helping them.
Err towards implementing feedback in pull requests, even if I consider it generally neutral. The cost of giving feedback to me is so high for folks, that I’m responsible for going out of my way to incorporate it when it is given.

These rules have meant that I didn’t work on some projects that I wanted to, but I think they’ve done a fairly good job of allowing me to build my judgment about how our software works without getting in the way of the teams who are doing the vast majority of the heavy lifting. I’m sure there are better versions of these rules, but in general I’d guess that managers ignoring them are close to the border of being unhelpful.

Should you be coding at work?

I’m pretty sure that “Should managers be coding at work?” isn’t nearly as interesting a question as folks want it to be, and a meaningful answer depends on each situation’s details. However, what’s been clearly true for me is that the overhead of writing software at work is substantially lower than it was a few years ago. If you weren’t writing software at work because it simply took too much time away from managing the team directly: the constraints have shifted in a profound way after you learn the new wave of tooling.

The learning loop for writing software with agents is definitely not zero, but it’s something you can learn for a few dollars of tokens and a couple dozen hours spent writing personal projects that are safe to throw away afterwards. That feels like a worthwhile investment to remain effective in one’s chosen profession.

"Good engineering management" is a fad

Sun, 26 Oct 2025 04:00:00 -0700

As I get older, I increasingly think about whether I’m spending my time the right way to advance my career and my life. This is also a question that your company asks about you every performance cycle: is this engineering manager spending their time effectively to advance the company or their organization?

Confusingly, in my experience, answering these nominally similar questions has surprisingly little in common. This piece spends some time exploring both questions in the particularly odd moment we live in today, where managers are being told they’ve spent the last decade doing the wrong things, and need to engage with a new model of engineering management in order to be valued by the latest iteration of the industry.

If you’d be more interested in a video version of this, here is the recording of a practice run I gave for a talk centered on these same ideas (slides from talk).

Good leadership is a fad

When I started my software career at Yahoo in the late 2000s, I had two 1:1s with my manager over the course of two years. The first one came a few months after I started, and he mostly asked me about a colleague’s work quality. The second came when I gave notice that I was leaving to join Digg. A modern evaluation of this manager would be scathing, but his management style closely resembled that of the team leader in The Soul of A New Machine: identifying an important opportunity for the team, and navigating the broader organization that might impede progress towards that goal. He was, in the context we were working in, an effective manager.

Compare that leadership style to the expectations of the 2010s, where attracting, retaining, and motivating engineers was emphasized as the most important leadership criteria in many organizations. This made sense in the era of hypergrowth, where budgets were uncapped and many companies viewed hiring strong engineers as their constraint on growth. This was an era where managers were explicitly told to stop writing software as the first step of their transition into management, and it was good advice! Looking back we can argue it was bad guidance by today’s standards, but it aligned the managers with the leadership expectations of the moment.

Then think about our current era, that started in late 2022, where higher interest rates killed zero-interest-rate-policy (ZIRP) and productized large language models are positioned as killing deep Engineering organizations. We’ve flattened Engineering organizations where many roles that previously focused on coordination are now expected to be hands-on keyboard, working deep in the details. Once again, the best managers of the prior era–who did exactly what the industry asked them to do–are now reframed as bureaucrats rather than integral leaders.

In each of these transitions, the business environment shifted, leading to a new formulation of ideal leadership. That makes a lot of sense: of course we want leaders to fit the necessary patterns of today. Where things get weird is that in each case a morality tale was subsequently superimposed on top of the transition:

In the 2010s, the morality tale was that it was all about empowering engineers as a fundamental good. Sure, I can get excited for that, but I don’t really believe that narrative: it happened because hiring was competitive.
In the 2020s, the morality tale is that bureaucratic middle management have made organizations stale and inefficient. The lack of experts has crippled organizational efficiency. Once again, I can get behind that–there’s truth here–but the much larger drivers aren’t about morality, it’s about ZIRP-ending and optimism about productivity gains from AI tooling.

The conclusion here is clear: the industry will want different things from you as it evolves, and it will tell you that each of those shifts is because of some complex moral change, but it’s pretty much always about business realities changing. If you take any current morality tale as true, then you’re setting yourself up to be severely out of position when the industry shifts again in a few years, because “good leadership” is just a fad.

Earlier this summer, I also gave a presentation at the YCombinator CTO summit on this specific topic of the evolution of engineering management. You can watch a recorded practice run of that talk on YouTube as well, and see the slides.

Self-development across leadership fads

If you accept the argument that the specifically desired leadership skills of today are the result of fads that frequently shift, then it leads to an important followup question: what are the right skills to develop in to be effective today and to be impactful across fads?

Having been and worked with engineering managers for some time, I think there are eight foundational engineering management skills, which I want to personally group into two clusters: core skills that are essential to operate in all roles (including entry-level management roles), and growth skills whose presence–or absence–determines how far you can go in your career.

The core skills are:

Execution: lead team to deliver expected tangible and intangible work. Fundamentally, management is about getting things done, and you’ll neither get an opportunity to begin managing, nor stay long as a manager, if your teams don’t execute.

Examples: ship projects, manage on-call rotation, sprint planning, manage incidents
Team: shape the team and the environment such that they succeed. This is not working for the team, nor is it working for your leadership, it is finding the balance between the two that works for both.

Examples: hiring, coaching, performance management, advocate with your management
Ownership: navigate reality to make consistent progress, even when reality is difficult Finding a way to get things done, rather than finding a way that it not getting done is someone else’s fault.

Examples: doing hard things, showing up when it’s uncomfortable, being accountable despite systemic issues
Alignment: build shared understanding across leadership, stakeholders, your team, and the problem space. Finding a realistic plan that meets the moment, without surprising or being surprised by those around you.

Examples: document and share top problems, and updates during crises

The growth skills are:

Taste: exercise discerning judgment about what “good” looks like—technically, in business terms, and in process/strategy. Taste is a broadchurch, and my experience is that broad taste is an somewhat universal criteria for truly senior roles. In some ways, taste is a prerequisite to Amazon’s Are Right, A Lot.

Examples: refine proposed product concept, avoid high-risk rewrite, find usability issues in team’s work
Clarity: your team, stakeholders, and leadership know what you’re doing and why, and agree that it makes sense. In particular, they understand how you are overcoming your biggest problems. So clarity is not, “Struggling with scalability issues” but instead “Sharding the user logins database in a new cluster to reduce load.”

Examples: identify levers to progress, create plan to exit a crisis, show progress on implementing that plan
Navigating ambiguity: work from complex problem to opinionated, viable approach. If you’re given an extremely messy, open-ended problem, can you still find a way to make progress? (I’ve written previously about this topic.)

Examples: launching a new business line, improving developer experience, going from 1 to N cloud regions
Working across timescales: ensure your areas of responsibility make progress across both the short and long term. There are many ways to appear successful by cutting corners today, that end in disaster tomorrow. Success requires understanding, and being accountable for, how different timescales interact.

Examples: have an explicit destination, ensure short-term work steers towards it, be long-term rigid and short-term flexible

Having spent a fair amount of time pressure testing these, I’m pretty sure most effective managers, and manager archetypes, can be fit into these boxes.

Self-assessing on these skills

There’s no perfect way to measure anything complex, but here are some thinking questions for you to spend time with as you assess where you stand on each of these skills:

Execution
- When did your team last have friction delivering work? Is that a recurring issue?
- What’s something hard you shipped that went really, really well?
- When were you last pulled onto solving a time-sensitive, executive-visible project?
Team
- Who was the last strong performer you hired?
- Have you retained your strongest performers?
- What strong performers want to join your team?
- Which peers consider your team highly effective?
- When did an executive describe your team as exceptional?
Ownership
- When did you or your team overcome the odds to deliver something important? (Would your stakeholders agree?)
- What’s the last difficult problem you solved that stayed solved (rather than reoccurring)?
- When did you last solve the problem first before addressing cross-team gaps?
Alignment
- When was the last time you were surprised by a stakeholder? What could you do to prevent that reoccuring?
- How does a new stakeholder understand your prioritization tradeoffs (incl rationale)?
- When did you last disappoint a stakeholder without damaging your relationship?
- What stakeholders would join your company because they trust you?
Taste
- What’s a recent decision that is meaningfully better because you were present?
- If your product counterpart left, what decisions would you struggle to make?
- Where’s a subtle clarification that significantly changed a design or launch?
- How have you inflected team’s outcomes by seeing around corners?
Clarity
- What’s a difficult trade-off you recently helped your team make?
- How could you enable them to make that same trade-off without your direct participation?
- What’s a recent decision you made that was undone? How?
Navigating ambiguity
- What problem have you worked on that was stuck before assisted, and unstuck afterwards?
- How did you unstick it?
- Do senior leaders bring ambiguous problems to you? Why?
Working across timescales
- What’s a recent trade off you made between short and long-term priorities?
- How do you inform these tradeoffs across timescales?
- What long-term goals are you protecting at significant short-term cost?

Most of these questions stand on their own, but it’s worth briefly explaining the “Have you ever been pulled into a SpecificSortOfProject by an executive?” questions. My experience is that in most companies, executives will try to poach you onto their most important problems that correspond to your strengths. So if they’re never attempting to pull you in then either you’re not considered as particularly strong on that dimensions, or you’re already very saturated with other work such that it doesn’t seem possible to pull you in.

Are “core skills” the same over time?

While those groupings of “core” and “growth” skills are obvious groupings to me, what I came to appreciate while writing this is that some skills swap between core to growth as the fads evolve. Where execution is a foundational skill today, it was less of a core skill in the hypergrowth era, and even less in the investor era.

This is the fundamentally tricky part of succeeding as an engineering manager across fads: you need a sufficiently broad base across each of these skills to be successful, otherwise you’re very likely to be viewed as a weak manager when the eras unpredictably end.

Stay energized to stay engaged

The “Manage your priorities and energy” chapter in The Engineering Executive’s Primer captures an important reality that took me too long to understand: the perfect allocation of work is not the mathematically ideal allocation that maximizes impact. Instead, it’s the balance between that mathematical ideal and doing things that energize you enough to stay motivated over the long haul. If you’re someone who loves writing software, that might involve writing a bit more than helpful to your team. If you’re someone who loves streamlining an organization, it might be improving a friction-filled process that is a personal affront, even if it’s not causing that much overall inefficiency.

Forty-year career

Similarly to the question of prioritizing activities to stay energized, there’s also understanding where you are in your career, an idea I explored in A forty-year career.

For each role, you have the chance to prioritize across different dimensions like pace, people, prestige, profit, or learning. There’s no “right decision,” and there are always tradeoffs. The decisions you make early in your career will compound over the following forty years. You also have to operate within the constraints of your life today and your possible lives tomorrow. Early in my career, I had few responsibilities to others, and had the opportunity to work extremely hard at places like Uber. Today, with more family responsibilities, I am unwilling to make the tradeoffs to consistently work that way, which has real implications on how I think about which roles to prioritize over time.

Recognizing these tradeoffs, and making them deliberately, is one of the highest value things you can do to shape your career. Most importantly, it’s extremely hard to have a career at all if you don’t think about these dimensions and have a healthy amount of self-awareness to understand the tradeoffs that will allow you to stay engaged over half a lifetime.

Crafting Engineering Strategy!

Sat, 25 Oct 2025 04:00:00 -0700

On November 3rd, 2023, I posted Thoughts on writing and publishing Primer to celebrate the completion of my work on my prior book, The Engineering Executive’s Primer. Three weeks later, I posted Engineering strategy notes on November 21st, 2023, as I started to pull together thoughts to write my upcoming book, Crafting Engineering Strategy.

Those initial thoughts turned into my first chapter draft, How should you adopt LLMs? on May 14th, 2024. Writing continued all the way through the Stripe API deprecation strategy, which was my final draft, completed the afternoon of April 5th, 2025. In between there were another 35 chapters: two of which were Wardley maps, four of which are systems models, and two of which are short section introductions.

This post is a collection of notes on writing Crafting Engineering Strategy, how I decided to publish it, ways that I did and did not use foundational models in writing it, and so on.

Buy on Amazon. Read online on craftingengstrategy.com.

Why write this book?

One of my decade goals for the 2020s, last updated in my 2024 year in review, is to write three books on some aspect of engineering. I published An Elegant Puzzle in 2019, so that one doesn’t count, but have two other books published in the 2020s: Staff Engineer in 2021, and The Engineering Executive’s Primer in 2024. So I knew I needed one more to complete this decade goal. At one point, I was planning on finishing Infrastructure Engineering as my fourth book, but honestly I’ve lost traction on that topic a bit over the past few years.

Instead, the thing I’d been thinking about a lot instead was engineering strategy. I’ve written chapters on this topic in my last two books, and each of those chapter was tortured by the sheer volume of things I wanted to write. By the end of 2024, I’d done enough strategy work myself that I was pretty confident I could take the best ideas from Staff Engineer–anchoring the essays in amazing stories–and the topic I’d spent so much time on over the past there years, and turn it into a pretty good book.

It’s also a topic that, like Staff Engineer in 2020 when I started writing it, was missing an anchor book pulling the ideas together for discussion. There are so many great books about strategy out there. There are some great books on engineering strategy, but few of them are widely read. My aspiration in writing this book was to potentially write that anchor book. It’ll take a decade or two to determine whether or not I’ve succeeded. At the minimum I think this book will either become that anchor or annoy someone enough that they write a better anchor instead. Either way, I’ll mark it as a win for advancing the industry’s discussion a bit.

LLM-optimized edition

Buy the AI Companion to Crafting Engineering Strategy on Amazon.

While I was writing this book, I was also increasingly using foundational models at work. Then I was using them to write tools for managing this book. Over time, I became increasingly fascinated with the idea of having a version of this book optimized for usage with large language models.

For this book in particular, the idea that you could collaborate with it on creating your own engineering strategy was a very appealing idea. I’m excited that this ultimately translated into an LLM-optimized edition that you can also purchase on Amazon, or you can read the AI companion’s text on craftingengineeringstrategy.com, although you’ll have to buy the actual book to get the foundational model optimized file itself (e.g. a markdown version of the book that plays well with foundational models).

This is the culmination of my thinking about the advantage of authors in the age of LLMs, where I see a path to book turning into things that are both read and also collaborated with.

Regarding the foundational model optimized-version, at its core, this is just running repomix against the repository of Markdown files, but there are a number of interesting optimizations for a better product. For example, it’s adding absolute paths to every referenced file and link, including adding a link to each chapter at its beginning to help models detect to them as references.

It’s also translating images into text descriptions. For example, here’s an image from one of the chapters.

Then here is the representation after I wrote a script to pull out every image and replace it with a description.

My guess is that many books are going to move in the direction of having an LLM-optimized edition, and I’m quite excited to see where this goes. I’ll likely work on an LLM-optimized edition of Staff Engineer at some point in the near-ish future as well.

Role of LLMs

When non-authors talk about LLMs making it easier to write books, they often think about LLMs literally writing books. As a fairly experienced author, I have absolutely no interest in an LLM writing any part of my book. If I don’t bring something unique to the book, the sort of thing that an LLM would not bring, then generally either it isn’t a book worth writing or I am the wrong author to write it. As a result, I wrote every word in this book. I didn’t use LLMs to expand bullets into paragraphs. I didn’t use LLMs to outline or assemble topics. I didn’t use LLMs to find examples to substantiate my approach. Again, this is what I know how to do fairly well at this point.

However, there are many things that I’m not that good at, where I relied heavily on an LLM. In particular, I used LLMs to copy-edit for typos, grammatical errors and hard-to-read sentences. I also used LLMs to write several scripts that I used in writing this book:

grammar.py which sent one or more chapters to an LLM for grammatical and spelling correction, returning the identified errors as regular expressions that I could individually accept or reject
import.py which translated from my blog post version of the posts into the craftingengstrategy.com optimized version
links.py which I used for standardizing format of chapter references, and balancing the frequency that strategies were referenced

Generated craftingengstrategy.com’s FAQ by attaching full LLM-optimized version to Anthropic Claude 3.7 thinking and running this prompt:

 I want to make a frequently asked questions featuring topics from this book. What are twenty good question and answer pairs based on this book, formatted as markdown (questions should be H2, and answers in paragraphs). Answers should include links to relevant chapters at the end of each answer.
Some example questions that I think would be helpful are:
1. Is engineering strategy a real thing?
2. How is engineering strategy different from strategy in general?
3. What are examples of engineering strategy?
4. What template should I use to create an engineering strategy?
5. Can engineers do engineering strategy? Is engineering strategy only for executives?
6. How to get better at engineering strategy?
7. Are there jobs in engineering strategy?
8. What are other engineering strategy resources?
Please directly answer those 8 questions, and then include another 10-15 question/answer pairs as well.

This worked quite well, in my opinion. Generating a better FAQ than the one I created for Staff Engineer’s FAQ in a very small amount of time. SEO seems well and truly “cooked” based on this experience.

Just like I don’t see software engineers being replaced by LLMs, I don’t see authors being replaced either.

craftingengstrategy.com

For Staff Engineer, I put up staffeng.com. For The Engineering Executive’s Primer I just posted things on this blog, without making a dedicated, standalone site. For Crafting Engineering Strategy, I decided to put together a dedicated site again, which maybe deserves an explanation.

My writing over the past few years is anchored in my goal of advancing the industry, and I think that having a well-structured, referencable version of the book online is a valuable part of that. If people want to recommend someone read Staff Engineer, they can simply point them to staffeng.com, and they can read the whole book. They might also buy it, which is great, but it’s fine if they don’t. The Engineering Executive’s Primer is just much less referencable online, so someone ultimately has to decide to buy it before testing the content, which undermines its ability to advance the industry.

For the record, that wasn’t an O’Reilly limitation, just poor planning on my part. An Elegant Puzzle didn’t require a standalone site, so I thought that Primer wouldn’t either, but I think that’s more a reflection of An Elegant Puzzle being a collection of this blog’s writing in the 2010s rather than the best way to support the typical book.

At this point, my experience is that most books benefit from having a dedicated site, and that it doesn’t detract from sales numbers. Rather, if properly done with clear calls to action on the site, it supports sales very effectively.

Decision to publish vs self-publish

I worked with O’Reilly to publish this book, same as I did for my previous book, The Engineering Executive’s Primer. My continued experience is that it’s harder to create a book with a publisher, the financial outcomes are significantly muted, but the book itself is almost always a much better book than you would have created on your own.

For me, that was the right tradeoff for this book.

My last book of 2020s

I’m not at all sure this is the last book that I’ll ever write, but I’ve completed my decade writing goal for the 2020s, and I’m committed to this being my last book of the 2020s. For the past seven years I have been continually writing, editing or promoting a book, and I am exhausted with that process. I’ve loved getting to do it, and am grateful for having had the chance to do this four times. But, I’m still exhausted with it!

I could imagine eventually having another book to write, and that is definitely not now. Instead I want to spend more time with my family, my son, personally writing software professionally (rather than exclusively leading teams doing the writing), and other projects that are anything but writing another book.

Commenting on Notion docs via OpenAI and Zapier.

Sun, 20 Jul 2025 04:00:00 -0700

One of my side quests at work is to get a simple feedback loop going where we can create knowledge bases that comment on Notion documents. I was curious if I could hook this together following these requirements:

No custom code hosting
Prompt is editable within Notion rather than requiring understanding of Zapier
Should be be fairly quickly

Ultimately, I was able to get it working. So a quick summary of how it works, some comments on why I don’t particularly like this approach, then some more detailed comments on getting it working.

General approach

Create a Notion database of prompts.

Create a specific prompt for providing feedback on RFCs.

Create a Notion database for all RFCs.

Add an automation into this database that calls a Zapier webhook.

The Zapier webhook does a variety of things that culminate in using the RFC prompt to provide feedback on the specific RFC as a top-level comment in the RFC.

Altogether this works fairly well.

The challenges with this approach

The best thing about this approach is that it actually works, and it works fairly well. However, as we dig into the implementation details, you’ll also see that a series of things are unnaturally difficult with Zapier:

Managing rich text in Notion because it requires navigating the blocks datastructure
Allowing looping API constructs such as making it straightforward to leave multiple comments on specific blocks rather than a single top-level comment
Notion only allows up to 2,000 characters per block, but chunking into multiple blocks is moderately unnatural. In a true Python environment, it would be trivial to translate to and from Markdown using something like md2notion

Ultimately, I could only recommend this approach as an initial validation. It’s definitely not the right long-term resting place for this kind of approach.

Zapier implementation

I already covered the Notion side of the integration, so let’s dig into the Zapier pieces a bit. Overall it had eight steps.

I’ve skipped the first step, which was just a default webhook receiver. The second step was retrieving a statically defined Notion page containing the prompt. (In later steps I just use the Notion API directly, which I would do here if I was redoing this, but this worked too. The advantage of the API is that it returns a real JSON object, this doesn’t, probably because I didn’t specify the content-type header or some such.)

This is the configuration page of step 2, where I specify the prompt’s page explicitly.

)

Probably because I didn’t set content-type, I think I was getting post formatted data here, so I just regular expressed the data out. It’s a bit sloppy, but hey it worked, so there’s that.

)

Here is using the Notion API request tool to retrieve the updated RFC (as opposed to the prompt which we already retrieved).

)

The API request returns a JSON object that you can navigate without writing regular expressions, so that’s nice.

)

Then we send both the prompt as system instructions and the RFC as the user message to Open AI.

)

Then pass the response from OpenAI to json.dumps to encode it for being included in an API call. This is mostly solving for newlines being \n rather than literal newlines.

)

Then format the response into an API request to add a comment to the document.

Anyway, this wasn’t beautiful, and I think you could do a much better job by just doing all of this in Python, but it’s a workable proof of concept.

An agent to use Notion docs as prompts to comment on Notion docs.

Sun, 20 Jul 2025 04:00:00 -0700

Last weekend, I wrote a bit about using Zapier to load Notion pages as prompts to comment on other Notion pages. That worked well enough, but not that well. This weekend I spent some time getting the next level of this working, creating an agent that runs as an AWS Lambda. This, among other things, allowed me to rely on agent tool usage to support both page and block-level comments, and altogether I think the idea works extremely well.

This was mostly implemented by Claude Code, and I think the code is actually fairly bad as a result, but you can see the full working implementation at lethain:basic_notion-agent on Github. Installation and configuration options are there as well.

Watch a quick walkthrough of the project I recorded on YouTube.

Screenshots

To give a sense of what the end experience is, here are some screenshots. You start by creating a prompt in a Notion document.

Then it will provide inline comments on blocks within your document.

It will also provide a summary comment on the document overall (although this is configurable if you only want in-line comments).

A feature I particularly like is that the agent is aware of existing comments on the document, and who made them, and will reply to those comments.

Altogether, it’s a fun little project and works surprisingly well, as almost all agents do with enough prompt tuning.

Moving from an orchestration-heavy to leadership-heavy management role.

Sat, 19 Jul 2025 04:00:00 -0700

For managers who have spent a long time reporting to a specific leader or working in an organization with well‑understood goals, it’s easy to develop skill gaps without realizing it. Usually this happens because those skills were not particularly important in the environment you grew up in. You may become extremely confident in your existing skills, enter a new organization that requires a different mix of competencies, and promptly fall on your face.

There are a few common varieties of this, but the one I want to discuss here is when managers grow up in an organization that operates from top‑down plans (“orchestration‑heavy roles”) and then find themselves in a sufficiently senior role, or in a bottom‑up organization, that expects them to lead rather than orchestrate (“leadership‑heavy roles”).

Orchestration versus leadership

You can break the components of solving a problem down in a number of ways, and I’m not saying this is the perfect way to do it, but here are six important components of directing a team’s work:

Problem discovery: Identifying which problems to work on
Problem selection: Aligning with your stakeholders on the problems you’ve identified
Solution discovery: Identifying potential solutions to the selected problem
Solution selection: Aligning with your stakeholders on the approach you’ve chosen
Execution: Implementing the selected solution
Ongoing revision: Keeping your team and stakeholders aligned as you evolve the plan

In an orchestration‑heavy management role, you might focus only on the second half of these steps. In a leadership‑heavy management role, you work on all six steps. Folks who’ve only worked in orchestration-heavy roles often have no idea that they are expected to perform all of these. So, yes, there’s a skill gap in performing the work, but more importantly there’s an awareness gap that the work actually exists to be done.

Here are a few ways you can identify an orchestration‑heavy manager that doesn’t quite understand their current, leadership‑heavy circumstances:

Focuses on prioritization as “solution of first resort.” When you’re not allowed to change the problem or the approach, prioritization becomes one of the best tools you have.
Accepts problems and solutions as presented. If a stakeholder asks for something, questions are around priority rather than whether the project makes sense to do at all, or suggestions of alternative approaches. There’s no habit of questioning whether the request makes sense—that’s left to the stakeholder or to more senior functional leadership.
Focuses on sprint planning and process. With the problem and approach fixed, protecting your team from interruption and disruption is one of your most valuable tools. Operating strictly to a sprint cadence (changing plans only at the start of each sprint) is a powerful technique.

All of these things are still valuable in a leadership‑heavy role, but they just aren’t necessarily the most valuable things you could be doing.

Operating in a leadership-heavy role

There is a steep learning curve for managers who find themselves in a leadership‑heavy role, because it’s a much more expansive role. However, it’s important to realize that there are no senior engineering leadership roles focused solely on orchestration. You either learn this leadership style or you get stuck in mid‑level roles (even in organizations that lean orchestration-heavy).

Further, the technology industry generally believes it overinvested in orchestration‑heavy roles in the 2010s. Consequently, companies are eliminating many of those roles and preventing similar roles from being created in the next generation of firms. There’s a pervasive narrative attributing this shift to the increased productivity brought by LLMs, but I’m skeptical of that relationship—this change was already underway before LLMs became prominent.

My advice for folks working through the leadership‑heavy role learning curve is:

Think of your job’s core loop as four steps:
1. Identify the problems your team should be working on
2. Decide on a destination that solves those problems
3. Explain to your team, stakeholders, and executives the path the team will follow to reach that destination
4. Communicate both data and narratives that provide evidence you’re walking that path successfully
If you are not doing these four things, you are not performing your full role, even if people say you do some parts well. Similarly, if you want to get promoted or secure more headcount, those four steps are the path to doing so (I previously discussed this in How to get more headcount).
Ask your team for priorities and problems to solve. Mining for bottom‑up projects is a critical part of your role. If you wait only for top‑down and lateral priorities, you aren’t performing the first step of the core loop.

It’s easy to miss this expectation—it’s invisible to you but obvious to everyone else, so they don’t realize it needs to be said. If you’re not sure, ask.
If your leadership chain is running the core loop for your team, it’s because they lack evidence that you can run it yourself. That’s a bad sign. What’s “business as usual” in an orchestration‑heavy role actually signals a struggling manager in a leadership‑heavy role.
Get your projects prioritized by following the core loop. If you have a major problem on your team and wonder why it isn’t getting solved, that’s on you. Leadership‑heavy roles won’t have someone else telling you how to frame your team’s work—unless they think you’re doing a bad job.
Picking the right problems and solutions is your highest‑leverage work. No, this is not only your product manager’s job or your tech lead’s—it is your job. It’s also theirs, but leadership overlaps because getting it right is so valuable.

Generalizing a bit, your focus now is effectiveness of your team’s work, not efficiency in implementing it. Moving quickly on the wrong problem has no value.
Understand your domain and technology in detail. You don’t have to write all the software—but you should have written some simple pull requests to verify you can reason about the codebase. You don’t have to author every product requirement or architecture proposal, but you should write one occasionally to prove you understand the work.

If you don’t feel capable of that, that’s okay. But you need to urgently write down steps you’ll take to close that gap and share that plan with your team and manager. They currently see you as not meeting expectations and want to know how you’ll start meeting them.

If you think that gap cannot be closed or that it’s unreasonable to expect you to close it, you misunderstand your role. Some organizations will allow you to misunderstand your role for a long time, provided you perform parts of it well, but they rarely promote you under those circumstances—and most won’t tolerate it for senior leaders.
Align with your team and cross‑functional stakeholders as much as you align with your executive. If your executive is wrong and you follow them, it is your fault that your team and stakeholders are upset: part of your job is changing your executive’s mind.

Yes, it can feel unfair if you’re the type to blame everything on your executive. But it’s still true: expecting your executive to get everything right is a sure way to feel superior without accomplishing much.

Now that I’ve shared my perspective, I admit I’m being a bit extreme on purpose—people who don’t pick up on this tend to dispute its validity strongly unless there is no room to debate. There is room for nuance, but if you think my entire point is invalid, I encourage you to have a direct conversation with your manager and team about their expectations and how they feel you’re meeting them.

Advancing the industry, part two.

Fri, 18 Jul 2025 04:00:00 -0700

I’m turning forty in a few weeks, and there’s a listicle archetype along the lines of “Things I’ve learned in the first half of my career as I turn forty and have now worked roughly twenty years in the technology industry.” How do you write that and make it good? Don’t ask me. I don’t know!

As I considered what I would write to summarize my career learnings so far, I kept thinking about updating my post Advancing the industry from a few years ago, where I described using that concept as a north star for my major career decisions. So I wrote about that instead.

Recapping the concept

Adopting advancing the industry as my framework for career decisions came down to three things:

The opportunity to be more intentional: After ~15 years in the industry, I entered a “third stage” of my career where neither financial considerations (1st stage) nor controlling pace to support an infant/toddler (2nd stage) were my highest priorities. Although I might not be working wholly by choice, I had enough flexibility that I could no longer hide behind “maximizing financial return” to guide, or excuse, my decision making.
My decade goals kept going stale. Since 2020, I’ve tracked against my decade goals for the 2020s, and annual tracking has been extremely valuable. Part of that value was realizing that I’d made enough progress on several initial goals that they weren’t meaningful to continue measuring.

For example, I had written and published three professional books. Publishing another book was not a goal for me. That’s not to say I wouldn’t write another—in fact, I have—but it would serve another goal, not be a goal in itself. As a second example, I set a goal to get twenty people I’ve managed or mentored into VPE/CTO roles running engineering organizations of 50+ people or $100M+ valuation. By the end of last year, ten people met that criteria after four years. Based on that, it seems quite likely I’ll reach twenty within the next six years, and I’d already increased that goal from ten to twenty a few years ago, so I’m not interested in raising it again.
“Advancing the industry” offered a solution to both, giving me a broader goal to work toward and reframe my decade and annual goals.

That mission still resonates with me: it’s large, broad, and ambiguous enough to support many avenues of progress while feeling achievable within two decades. Though the goal resonates, my thinking about the best mechanism to make progress toward it has shifted over the past few years.

Writing from primary to secondary mechanism

Roughly a decade ago, I discovered the most effective mechanism I’ve found to advance the industry: learn at work, write blog posts about those learnings, and then aggregate the posts into a book.

An Elegant Puzzle was the literal output of that loop. Staff Engineer was a more intentional effort but still the figurative output. My last two books have been more designed than aggregated, but still generally followed this pattern. That said, as I finish up Crafting Engineering Strategy, I think the loop remains valid, but it’s run its course for me personally. There are several reasons:

First, what was energizing four books ago feels like a slog today. Making a book is a lot of work, and much of it isn’t fun, so you need to be really excited about the fun parts to balance it out. I used to check my Amazon sales standing every day, thrilled to see it move up and down the charts. Each royalty payment felt magical: something I created that people paid real money for. It’s still cool, but the excitement has tempered over six years.

Second, most of my original thinking is already captured in my books or fits shorter-form content like blog posts. I won’t get much incremental leverage from another book. I do continue to get leverage from shorter-form writing and will keep doing it.

Finally, as I wrote in Writers who operate, professional writing quality often suffers when writing becomes the “first thing” rather than the “second thing.” Chasing distribution subtly damages quality. I’ve tried hard to keep writing as a second thing, but over the past few years my topic choices have been overly pulled toward filling book chapters instead of what’s most relevant to my day-to-day work.

If writing is second, what is first?

My current thinking on how to best advance the industry rests on four pillars:

Industry leadership and management practices are generally poor.
We can improve these by making better practices more accessible (my primary focus in years past but where I’ve seen diminishing returns).
We can improve practices by growing the next generation of industry leaders (the rationale behind my decade goal to mentor/manage people into senior roles, but I can’t scale it much through executive roles alone)
We can improve practices by modeling them authentically in a very successful company and engineering organization.

The fourth pillar is my current focus and likely will remain so for the upcoming decade, though who knows—your focus can change a lot over ten years.

Why now? Six years ago, I wouldn’t have believed I could influence my company enough to make this impact, but the head of engineering roles I’ve pursued are exactly those that can. With access to such roles at companies with significant upward trajectories, I have the best laboratory to validate and evolve ways to advance the industry: leading engineering in great companies. Cargo-culting often spreads the most influential ideas—20% time at Google, AI adoption patterns at Spotify, memo culture at Amazon, writing culture at Stripe, etc. Hopefully, developing and documenting ideas with integrity will hopefully be even more effective than publicity-driven cargo-culting. That said, I’d be glad to accept the “mere” success of ideas like 20% time.

Returning to the details

Most importantly for me personally, focusing on modeling ideas in my own organization aligns “advancing the industry” with something I’ve been craving for a long time now: spending more time in the details of the work. Writing for broad audiences is a process of generalizing, but day-to-day execution succeeds or fails on particulars. I’ve spent much of the past decade translating between the general and the particular, and I’m relieved to return fully to the particulars.

Joining Imprint six weeks ago gave me a chance to practice this: I’ve written/merged/deployed six pull requests at work, tweaked our incident tooling to eliminate gaps in handoff with Zapier integrations, written an RFC, debugged a production incident, and generally been two or three layers deeper than at Carta. Part of that is that Imprint’s engineering team is currently much smaller— 40 rather than 350—and another part is that industry expectations in the post-ZIRP reentrenchment and LLM boom pull leaders towards the details. But mostly, it’s just where my energy is pulling me lately.

What can agents actually do?

Sun, 06 Jul 2025 04:00:00 -0700

There’s a lot of excitement about what AI (specifically the latest wave of LLM-anchored AI) can do, and how AI-first companies are different from the prior generations of companies. There are a lot of important and real opportunities at hand, but I find that many of these conversations occur at such an abstract altitude that they border on meaningless. Sort of like saying that your company could be much better if you merely adopted more software. That’s certainly true, but it’s not a particularly helpful claim.

This post is an attempt to concisely summarize how AI agents work, apply that summary to a handful of real-world use cases for AI, and to generally make the case that agents are a multiplier on the quality of your software and system design. If your software or systems are poorly designed, agents will only cause harm. If there’s any meaningful definition of an AI-first company, it must be companies where their software and systems are designed with an immaculate attention to detail.

By the end of this writeup, my hope is that you’ll be well-armed to have a concrete discussion about how LLMs and agents could change the shape of your company, and to avoid getting caught up in the needlessly abstract discussions that are often taking place today.

How do agents work?

At its core, using an LLM is an API call that includes a prompt. For example, you might call Anthropic’s /v1/message with a prompt: How should I adopt LLMs in my company? That prompt is used to fill the LLM’s context window, which conditions the model to generate certain kinds of responses.

This is the first important thing that agents can do: use an LLM to evaluate a context window and get a result.

Prompt engineering, or context engineering as it’s being called now, is deciding what to put into the context window to best generate the responses you’re looking for. For example, In-Context Learning (ICL) is one form of context engineering, where you supply a bunch of similar examples before asking a question. If I want to determine if a transaction is fraudulent, then I might supply a bunch of prior transactions and whether they were, or were not, fraudulent as ICL examples. Those examples make generating the correct answer more likely.

However, composing the perfect context window is very time intensive, benefiting from techniques like metaprompting to improve your context. Indeed, the human (or automation) creating the initial context might not know enough to do a good job of providing relevant context. For example, if you prompt, Who is going to become the next mayor of New York City?, then you are unsuited to include the answer to that question in your prompt. To do that, you would need to already know the answer, which is why you’re asking the question to begin with!

This is where we see model chat experiences from OpenAI and Anthropic use web search to pull in context that you likely don’t have. If you ask a question about the new mayor of New York, they use a tool to retrieve web search results, then add the content of those searches to your context window.

This is the second important thing that agents can do: use an LLM to suggest tools relevant to the context window, then enrich the context window with the tool’s response.

However, it’s important to clarify how “tool usage” actually works. An LLM does not actually call a tool. (You can skim OpenAI’s function calling documentation if you want to see a specific real-world example of this.) Instead there is a five-step process to calling tools that can be a bit counter-intuitive:

The program designer that calls the LLM API must also define a set of tools that the LLM is allowed to suggest using.
Every API call to the LLM includes that defined set of tools as options that the LLM is allowed to recommend
The response from the API call with defined functions is either:
1. Generated text as any other call to an LLM might provide
2. A recommendation to call a specific tool with a specific set of parameters, e.g. an LLM that knows about a get_weather tool, when prompted about the weather in Paris, might return this response:
```
 [{
"type": "function_call",
"name": "get_weather",
"arguments": "{\"location\":\"Paris, France\"}"
}]
```
The program that calls the LLM API then decides whether and how to honor that requested tool use. The program might decide to reject the requested tool because it’s been used too frequently recently (e.g. rate limiting), it might check if the associated user has permission to use the tool (e.g. maybe it’s a premium only tool), it might check if the parameters match the user’s role-based permissions as well (e.g. the user can check weather, but only admin users are allowed to check weather in France).
If the program does decide to call the tool, it invokes the tool, then calls the LLM API with the output of the tool appended to the prior call’s context window.

The important thing about this loop is that the LLM itself can still only do one interesting thing: taking a context window and returning generated text. It is the broader program, which we can start to call an agent at this point, that calls tools and sends the tools’ output to the LLM to generate more context.

What’s magical is that LLMs plus tools start to really improve how you can generate context windows. Instead of having to have a very well-defined initial context window, you can use tools to inject relevant context to improve the initial context.

This brings us to the third important thing that agents can do: they manage flow control for tool usage. Let’s think about three different scenarios:

Flow control via rules has concrete rules about how tools can be used. Some examples:
1. it might only allow a given tool to be used once in a given workflow (or a usage limit of a tool for each user, etc)
2. it might require that a human-in-the-loop approves parameters over a certain value (e.g. refunds more than $100 require human approval)
3. it might run a generated Python program and return the output to analyze a dataset (or provide error messages if it fails)
4. apply a permission system to tool use, restricting who can use which tools and which parameters a given user is able to use (e.g. you can only retrieve your own personal data)
5. a tool to escalate to a human representative can only be called after five back and forths with the LLM agent
Flow control via statistics can use statistics to identify and act on abnormal behavior:
1. if the size of a refund is higher than 99% of other refunds for the order size, you might want to escalate to a human
2. if a user has used a tool more than 99% of other users, then you might want to reject usage for the rest of the day
3. it might escalate to a human representative if tool parameters are more similar to prior parameters that required escalation to a human agent

LLMs themselves absolutely cannot be trusted. Anytime you rely on an LLM to enforce something important, you will fail. Using agents to manage flow control is the mechanism that makes it possible to build safe, reliable systems with LLMs. Whenever you find yourself dealing with an unreliable LLM-based system, you can always find a way to shift the complexity to a tool to avoid that issue. As an example, if you want to do algebra with an LLM, the solution is not asking the LLM to directly perform algebra, but instead providing a tool capable of algebra to the LLM, and then relying on the LLM to call that tool with the proper parameters.

At this point, there is one final important thing that agents do: they are software programs. This means they can do anything software can do to build better context windows to pass on to LLMs for generation. This is an infinite category of tasks, but generally these include:

Building general context to add to context window, sometimes thought of as maintaining memory
Initiating a workflow based on an incoming ticket in a ticket tracker, customer support system, etc
Periodically initiating workflows at a certain time, such as hourly review of incoming tickets

Alright, we’ve now summarized what AI agents can do down to four general capabilities. Recapping a bit, those capabilities are:

Use an LLM to evaluate a context window and get a result
Use an LLM to suggest tools relevant to the context window, then enrich the context window with the tool’s response
Manage flow control for tool usage via rules or statistical analysis
Agents are software programs, and can do anything other software programs do

Armed with these four capabilities, we’ll be able to think about the ways we can, and cannot, apply AI agents to a number of opportunities.

Use Case 1: Customer Support Agent

One of the first scenarios that people often talk about deploying AI agents is customer support, so let’s start there. A typical customer support process will have multiple tiers of agents who handle increasingly complex customer problems. So let’s set a goal of taking over the easiest tier first, with the goal of moving up tiers over time as we show impact.

Our approach might be:

Allow tickets (or support chats) to flow into an AI agent
Provide a variety of tools to the agent to support:
1. Retrieving information about the user: recent customer support tickets, account history, account state, and so on
2. Escalating to next tier of customer support
3. Refund a purchase (almost certainly implemented as “refund purchase” referencing a specific purchase by the user, rather than “refund amount” to prevent scenarios where the agent can be fooled into refunding too much)
4. Closing the user account on request
Include customer support guidelines in the context window, describe customer problems, map those problems to specific tools that should be used to solve the problems
Flow control rules that ensure all calls escalate to a human if not resolved within a certain time period, number of back-and-forth exchanges, if they run into an error in the agent, and so on. These rules should be both rules-based and statistics-based, ensuring that gaps in your rules are neither exploitable nor create a terrible customer experience
Review agent-customer interactions for quality control, making improvements to the support guidelines provided to AI agents. Initially you would want to review every interaction, then move to interactions that lead to unusual outcomes (e.g. escalations to human) and some degree of random sampling
Review hourly, then daily, and then weekly metrics of agent performance
Based on your learnings from the metric reviews, you should set baselines for alerts which require more immediate response. For example, if a new topic comes up frequently, it probably means a serious regression in your product or process, and it requires immediate review rather than periodical review.

Note that even when you’ve moved “Customer Support to AI agents”, you still have:

a tier of human agents dealing with the most complex calls
humans reviewing the periodic performance statistics
humans performing quality control on AI agent-customer interactions

You absolutely can replace each of those downstream steps (reviewing performance statistics, etc) with its own AI agent, but doing that requires going through the development of an AI product for each of those flows. There is a recursive process here, where over time you can eliminate many human components of your business, in exchange for increased fragility as you have more tiers of complexity. The most interesting part of complex systems isn’t how they work, it’s how they fail, and agent-driven systems will fail occasionally, as all systems do, very much including human-driven ones.

Applied with care, the above series of actions will work successfully. However, it’s important to recognize that this is building an entire software pipeline, and then learning to operate that software pipeline in production. These are both very doable things, but they are meaningful work, turning customer support leadership into product managers and requiring an engineering team building and operating the customer support agent.

Use Case 2: Triaging incoming bug reports

When an incident is raised within your company, or when you receive a bug report, the first problem of the day is determining how severe the issue might be. If it’s potentially quite severe, then you want on-call engineers immediately investigating; if it’s certainly not severe, then you want to triage it in a less urgent process of some sort. It’s interesting to think about how an AI agent might support this triaging workflow.

The process might work as follows:

Pipe all created incidents and all created tickets to this agent for review.
Expose these tools to the agent:
1. Open an incident
2. Retrieve current incidents
3. Retrieve recently created tickets
4. Retrieve production metrics
5. Retrieve deployment logs
6. Retrieve feature flag change logs
7. Toggle known-safe feature flags
8. Propose merging an incident with another for human approval
9. Propose merging a ticket with another ticket for human approval
Redundant LLM providers for critical workflows. If the LLM provider’s API is unavailable, retry three times over ten seconds, then resort to using a second model provider (e.g. Anthropic first, if unavailable try OpenAI), and then finally create an incident that the triaging mechanism is unavailable. For critical workflows, we can’t simply assume the APIs will be available, because in practice all major providers seem to have monthly availability issues.
Merge duplicates. When a ticket comes in, first check ongoing incidents and recently created tickets for potential duplicates. If there is a probable duplicate, suggest merging the ticket or incident with the existing issue and exit the workflow.
Assess impact. If production statistics are severely impacted, or if there is a new kind of error in production, then this is likely an issue that merits quick human review. If it’s high priority, open an incident. If it’s low priority, create a ticket.
Propose cause. Now that the incident has been sized, switch to analyzing the potential causes of the incident. Look at the code commits in recent deploys and suggest potential issues that might have caused the current error. In some cases this will be obvious (e.g. spiking errors with a traceback of a line of code that changed recently), and in other cases it will only be proximity in time.
Apply known-safe feature flags. Establish an allow list of known safe feature flags that the system is allowed to activate itself. For example, if there are expensive features that are safe to disable, it could be allowed to disable them, e.g. restricting paginating through deeper search results when under load might be a reasonable tradeoff between stability and user experience.
Defer to humans. At this point, rely on humans to drive incident, or ticket, remediation to completion.
Draft initial incident report. If an incident was opened, the agent should draft an initial incident report including the timeline, related changes, and the human activities taken over the course of the incident. This report should then be finalized by the human involved in the incident.
Run incident review. Your existing incident review process should take the incident review and determine how to modify your systems, including the triaging agent, to increase reliability over time.
Safeguard to reenable feature flags. Since we now have an agent disabling feature flags, we also need to add a periodic check (agent-driven or otherwise) to reenable the “known safe” feature flags if there isn’t an ongoing incident to avoid accidentally disabling them for long periods of time.

This is another AI agent that will absolutely work as long as you treat it as a software product. In this case, engineering is likely the product owner, but it will still require thoughtful iteration to improve its behavior over time. Some of the ongoing validation to make this flow work includes:

The role of humans in incident response and review will remain significant, merely aided by this agent. This is especially true in the review process, where an agent cannot solve the review process because it’s about actively learning what to change based on the incident.

You can make a reasonable argument that an agent could decide what to change and then hand that specification off to another agent to implement it. Even today, you can easily imagine low risk changes (e.g. a copy change) being automatically added to a ticket for human approval.

Doing this for more complex, or riskier changes, is possible but requires an extraordinary degree of care and nuance: it is the polar opposite of the idea of “just add agents and things get easy.” Instead, enabling that sort of automation will require immense care in constraining changes to systems that cannot expose unsafe behavior. For example, one startup I know has represented their domain logic in a domain-specific language (DSL) that can be safely generated by an LLM, and are able to represent many customer-specific features solely through that DSL.
Expanding the list of known-safe feature flags to make incidents remediable. To do this widely will require enforcing very specific requirements for how software is developed. Even doing this narrowly will require changes to ensure the known-safe feature flags remain safe as software is developed.
Periodically reviewing incident statistics over time to ensure mean-time-to-resolution (MTTR) is decreasing. If the agent is truly working, this should decrease. If the agent isn’t driving a reduction in MTTR, then something is rotten in the details of the implementation.

Even a very effective agent doesn’t relieve the responsibility of careful system design. Rather, agents are a multiplier on the quality of your system design: done well, agents can make you significantly more effective. Done poorly, they’ll only amplify your problems even more widely.

Do AI Agents Represent Entirety of this Generation of AI?

If you accept my definition that AI agents are any combination of LLMs and software, then I think it’s true that there’s not much this generation of AI can express that doesn’t fit this definition. I’d readily accept the argument that LLM is too narrow a term, and that perhaps foundational model would be a better term. My sense is that this is a place where frontier definitions and colloquial usage have deviated a bit.

Closing thoughts

LLMs and agents are powerful mechanisms. I think they will truly change how products are designed and how products work. An entire generation of software makers, and company executives, are in the midst of learning how these tools work.

For everything that AI agents can do, there are equally important things they cannot. They cannot make restoring a database faster than the network bandwidth supports. Access to text-based judgment does create missing tools. Nor does text-based judgment solve access controls, immediately make absent document exist, or otherwise solve the many real systems problems that exist in your business today. It is only the combination of agents, great system design, and great software design that will make agents truly shine.

As it’s always been, software isn’t magic. Software is very logical. However, what software can accomplish is magical, if we use it effectively.