Notes
Most of my shorter writing happens on X. These are selected notes I want to keep easier to find. I have lightly edited them so they make sense outside the original thread. They are dated because the tools change quickly, and so does my thinking.
A five-minute fix for a stuck liftgate
The liftgate on my Jeep Cherokee was stuck. I could press the release, but nothing happened. I asked ChatGPT what to do, and it asked me a few questions.
It told me which panel to open and mentioned a Reddit thread where someone had found a loose washer or nut blocking the mechanical latch. I looked, and sure enough, there was one stuck there. I removed it and the liftgate worked.
A minor thing, but it took about five minutes to fix.
Sometimes the agent can use the API directly
In the past year, I've built agent workflows directly on top of raw data APIs. In the past, I would have built a scheduled ingestion job to pull that data into a warehouse first.
Good tools and clear tool definitions let the agent figure out how to get the data it needs. For some use cases, that's enough to avoid building a more complex pipeline. Some data can stay less structured than it would have before.
Data engineering still matters. You still need data modeling, transforms, validation, and pipelines. Companies that have already done that work have a useful foundation for agents.
A fresh review still needs judgment
If you ask an agent to find something wrong, it will find something wrong. That doesn't mean the problem is real.
I still find adversarial review with a fresh context window useful. Asking the same agent to keep checking its work can reinforce the assumptions already in its context. A separate review gives it another starting point.
You still need enough understanding of the work to judge what comes back.
When the harness changes and I don't know why
I used to run /add-dir in Claude Code when I wanted a session to access a folder outside its project. Now it sometimes finds related project folders and works in them on its own. I don't know why that changed.
Was it a new version of Claude Code? A memory it generated? A change one of my skills made to the project context? I could ask it why, but I also wonder whether that conversation would change its memory and affect the behavior again.
This is one reason I find smaller, open harnesses like Pi refreshing. They take more work to set up, but it's easier to inspect what they're doing. I like that the larger tools adapt to me; I also want to understand how.
Enjoying the old job doesn't mean enjoying the new one
I've been building software professionally for 23 years. I love refactoring, making things simpler, and solving hard bugs. Sometimes I'd wake up in the middle of the night with an idea for a problem that had been nagging me all week.
In two years, I've gone from being the most stringent person on code reviews to scanning the code and letting agents do much of the reviewing. It's been disorienting and energizing. I still get into a flow state, but through work that takes a different kind of focus.
Some of the best engineers I've worked with don't want to work this way. I wish I could convince them to try it, but I understand. The job has changed, and some people who were good at the old job also enjoy the new one. Some don't.
Finding the things I saved and never read
I built a CLI to pull down my Twitter data and create searchable embeddings. Claude Code can use the CLI, so I can ask questions about the archive from inside the project.
I like a lot of longer AI posts and then never circle back to read them. I talked into MacWhisper and asked Claude Code to look over the last three months and find the twenty things it thought were most worth reading.
The instruction was mostly me rambling about what I wanted. It put together a reading list from material I'd already saved.
Experienced engineers still matter
I'm an old-school software engineer: design patterns, domain-driven design, TDD, all the things. I took a class from Ralph Johnson during my CS master's at UIUC. I loved the craft for a long time and still do. I miss writing code, and I also understand that the role has completely changed.
All of that still matters, but in a different way. You don't need to read every line of code now, but you need to find a way to bring your experience and preferences into the work. There's no single way to do this.
I still believe the people who benefit most from AI coding tools are the people with experience and battle scars. They also seem to be among the hardest to convince that this is real.
Write the important context yourself
It's easy to ask a model to write a skill for you. But if you're building something you plan to use over and over, do you want it filling in the blanks with a generic set of instructions?
I like to open a text editor and write the instructions myself. I pretend I'm explaining the work to a new employee. I don't have to specify every step, just the context, constraints, and end goal.
Use deterministic tools for deterministic work
Break what you are trying to do into smaller steps. If code can handle a step reliably, write that code and give it to the agent as a tool. Do not ask a model to imitate a process that ordinary software can do reliably.
Look for problems you can test
I think there are probably lots of narrow fields where you can verify an outcome, or at least verify it well enough to be useful. My suspicion is that very few people have tried building that verification into an agent yet.
Being able to try something, check the result, and try again seems useful in many more places than we've applied it so far.
Domain expertise still matters
If you're an expert in your field and can write down what you know, you can get a lot from language models. Whatever you learned in your field is probably more complex than learning to use these tools.
Start using them, or find someone who knows a bit more and can help you get going.
Write the content before building the presentation
One of my favorite things to do now is focus entirely on the content in text. I open a text editor and work through the exact message, organization, and flow I want.
Then I ask Claude to turn it into an interactive website.
Retrieval tools still have a place
Giving an agent filesystem tools works well, but it isn't the full story. In many of the domains I work in, I've had good results building custom tools for vector search or TF-IDF and letting the harness decide how to use them.
During development, it helps to have the model look at its traces: what did it do, and where did it fail to use the retrieval tools well? That gives you something specific to improve.
Match the retrieval tools and rules to the problem, and have a systematic way to evaluate whether the results are useful.
Build a small baseline, then distill your preferences
When I start a project with coding agents, I build in small pieces. For a Flask app, the first instruction might be to set up a uv environment and a hello-world endpoint. I read the code carefully and ask the agent to adjust the structure and style until they fit what I want. I repeat that for several small additions, maybe ten.
Once there's a useful baseline, I ask the agent to review the code and session traces, then write an AGENTS.md and supporting context that capture my preferences. I read those files carefully too. Then I store them in the repo and start giving the agent bigger pieces of work, with less detailed review of every change.
This has worked better for me than starting with a generic set of instructions. I think my preferences are more dependent on the project than I sometimes realize. Having the agent derive them from actual work gives it a better starting point. It's one approach that's worked for me, not a rule for every project.
Production agents need more visibility
I use Claude Code or Codex for almost all of my interactive coding, and Claude Code in non-interactive mode for a lot of background jobs. But the model is already nondeterministic. Putting another layer on top that I can't inspect makes it harder to understand what's happening.
I've begun experimenting with custom Pi-based harnesses around my knowledge wiki and specific code projects. Moving the context from a more mature project into Pi has started to show signs of value. For agents inside products, I've gravitated toward LangChain DeepAgents because I like its lighter base harness and the way it handles skills and tools.
It might still be too early for companies to invest a lot of time in this. I don't know where it all goes, but I'd bet that cost, control, and the ability to change models will push more teams toward purpose-built harnesses.
The right level of instruction has changed
I've been feeling a shift in my work. A year ago, context often meant specific steps, guardrails, and long lists of what to do and what not to do. Now I'm finding that too many rules can get in the way.
Some of my best recent sessions started with instructions I typed myself: what I want, what information is available, and what success looks like. Writing that down forces me to think through the work before I ask the agent to do it.
There's still a pull to involve the agent immediately and watch things start changing. But I've found it useful to be more deliberate about that, depending on the work.
Build systems that keep improving the work
For some codebases I'm working in, I have a weekly GitHub Action that runs Claude Code in non-interactive mode with -p. A few custom skills inspect the repos and recent changes, then write an architecture overview, a changes summary, and a map of how the repos or services fit together.
Those markdown files go into a repo with a Claude Code plugin so future agents can use the context directly. Another step turns them into a self-contained HTML site. It's been useful for understanding how a part of the system fits together and sharing that view with the team.
It takes tuning. I have to decide what the skills should inspect, what belongs in the docs, and what the site should look like. But once it's wired into GitHub Actions, it runs without me having to remember to ask for it.
Companies need people to implement AI
Even if the tools stopped improving today, it would take companies a long time to use what's already possible. You still need people who know how to use them and understand the work well enough to figure out where they fit.
In my work with teams, everyone is busy with their actual job. That job usually doesn't include figuring out how AI changes their role, how it relates to other roles, or how to use the tools across functions.
There's work here that someone needs to own. I don't think the shape of that role is fully defined yet, but the need for it is pretty clear.
Adopting AI means changing how work gets done
These tools make you reconsider how work gets done, how it moves through a company, which roles do what, who works with whom, and which systems need to exist.
You cannot simply add AI to the current process and expect it to work. You have to step back and decide how the process itself should change.
Give the model a filesystem, not a blank chat
A lot of people open a blank chat, paste in context, ask a question, and start over next time. I still do this all the time, but it forces the model to rebuild context from scratch.
Tools with filesystem access can list directories, read files, search across them, and follow links. That works outside code too. Give the model a folder of well-organized information and it can explore it like a map.
For me, the starting point is usually small markdown files with project context, constraints, preferences, examples, and links to other files. There's some art to deciding what goes in them and how they stay current. I don't think there's one perfect way to do it.
Leaders need to learn by doing
Leaders cannot delegate all of this. Find the people inside the company who already understand the tools, watch how they work, and then use the tools yourself. You will learn more from doing that than from a presentation.
People also need time and permission to learn. Most employees already have a job, and that job does not include rethinking it with AI. Telling people to learn is not enough. Leaders need to give them space to experiment on real work.
Practical habits for coding with agents
Save useful session history in markdown. Keep AGENTS.md up to date and link to more detailed files from it. Run a review within the session and others with fresh context, then bring the findings together. Use CI to run recurring checks and refresh architecture docs.
Do not skip planning. You still need to describe clearly what you want to build. That thinking matters more than pressing the button quickly.
Connect the harness to the work
I'm in favor of teams using an existing harness, connecting their data sources, and building a skills library around the work. It takes time to get the skills right, but you can get a lot done that way.
For an internal database or a service with an API but no connector, my approach has been FastMCP Python wrappers around API calls, deployed on Modal, with Auth0 for authentication. The context in the tool definitions matters, and I don't want to build authentication myself.
The first version can become the specification
For some projects, the first version of the software is a way to discover the requirements. Build it quickly, try multiple approaches, and see whether it creates value. At that stage, the lessons matter more than the shape of the code.
When the idea is ready to ship, distill what you built and what you learned into a specification another agent can use. Rebuilding from that clearer specification can be better than preserving and gradually refactoring the exploratory version.
Make skills work together
Turn something into a skill when you have done it repeatedly and it has real steps. A useful skill reads the relevant context before it asks a question, shows proposed changes before writing, and cites the information it used.
The output of one skill should become useful context for the next. Over time, the skills and files form a map the agent can follow without making you explain the project again. That is when a collection of commands becomes a workflow.
Skills drift as the collection grows. Audit them for inconsistent conventions, overlapping responsibilities, and missing steps. Not every task should become a skill. Keep them for work you want done consistently.
Build for change, not stability
The right way to build an AI-enabled product can change in a few months. Sometimes rebuilding makes more sense than adapting a system built around assumptions that no longer hold. The same tools causing the change also make rebuilding easier.
You can't wait for everything to stabilize. For me, the best answer right now is to keep domain knowledge in markdown that I can adapt as the tools change. I don't have a more settled answer than that.
Agentic engineering is not vibe coding
Agentic engineering requires systems thinking, architectural knowledge, testing discipline, and the ability to describe in technical detail what you want. You also need to recognize what good work looks like.
The work includes choosing an incremental approach, deciding what the agent should build first, defining the right unit of work, and creating feedback loops that make the process more reliable over time.
A voice memo is enough to get started
Open Voice Memo and talk through everything you want to accomplish. When you think you're done, keep talking. Aim for at least ten minutes. Transcribe it with MacWhisper and give the transcript to Claude Code.
Ask it to read what you said and keep asking questions until it understands what you're trying to do. You can tell it you've never used it before and need help figuring out where to start.
If even that sounds confusing, paste the original post into whatever AI tool you use and ask it to help you follow the steps. I'm trying to help you get started. Curiosity and persistence matter here.
Update: The original workflow used plan mode. I no longer use plan mode regularly. The durable part is speaking your goals, providing real context, and learning by using the tools. Read the newer note on X.
Read the original and replies on X →We need better ways to direct many agents
I want a development environment that lets me coordinate lots of agents, mix models and harnesses, and connect them to a backlog of work.
I've been using Ghostty with some automation around it. I probably need something more complete, because I'm clicking too many things and making too many decisions just to keep the work moving.
Give agents a map of the territory
Give agents a map of the territory, distilled into as few tokens as you can. The first context they load matters. A clear, dense map lets them explore with tools instead of starting from one long, messy document.
For larger codebases, I often include an architecture file with a Mermaid diagram of the system. It is token-efficient and usually puts the agent on the right path.
More work will start inside model tools
People are starting to do the work itself inside tools from the model companies. Software companies should assume customers will want to bring their data and product capabilities into those tools.
Trying to reproduce every model capability inside an application may become a losing race. In many cases, it will make more sense to let the model tools use the product's data and actions directly.
Today's tools contain yesterday's hard work
At one of my first software jobs in the mid-2000s, I had a coworker who was a wizard with grep, sed, awk, regular expressions, xargs, and tail. He'd pipe them together like some sort of wild spell to solve a problem. I never knew what he was doing.
Meanwhile, I was writing hundred-line Java programs to do the same things.
I sometimes think about how his hard work, and the work of people like him who shared what they knew on StackOverflow, is one of the reasons we can just do things now.
Start with what the model builders publish
The teams building the models know a lot about how to use them, and some of that knowledge is available in the skills they publish. The skill-creator skill is a good example: instructions from people at the model labs who have spent time figuring out what works.
At the time of this post, my advice was to start with those existing skills or have the model ask you questions to build the context, rather than write it all yourself. You still need taste and enough knowledge of the work to judge what comes back.
Update: By August, I was finding it useful to write more of the instructions myself, especially for skills I'd use repeatedly. I like to pretend I'm explaining the work to a new employee. Read the newer note on X.
Read the original and replies on X →Use normal work as feedback
One way to improve an agent is to collect its traces along with a signal of whether its actions were correct. In the example I was responding to, that signal came from whether a code change was accepted during normal PR review.
Feed those results, the traces, and the agent's context into a different model to look for improvements. Use what it finds to change the agent's context, then track correctness over time to see whether the changes help.
The useful part is that people can review PRs as they already do. Getting that feedback without asking them to take on another task is a design problem worth spending time on.
Use the tools before hiring someone to implement them
If you have not spent real time using the tools, you will have a weak filter for deciding whether someone else knows what they are doing. Before hiring outside help, use an agent on a problem from your own job for at least a week.
You do not need to become an expert first. You need to see what the tools do well and where they fail so you can ask better questions and recognize practical advice.
Classical machine learning still matters
Classical machine learning remains useful. Many business problems need classification or regression, not a generative model.
Language models can now help people explore data, write the surrounding code, test approaches, and learn the underlying methods. Better AI tools make conventional machine learning more accessible; they do not make it irrelevant.