thisalex.com

Taming Claude Code

2026-01-27T00:00:00+00:00

I was recently giving masterclasses for colleagues and friends about Claude Code and realized it makes sense to share some tips I show there.

WARNING </div> </div>

⚠️ Target audience: Senior Developers. Coding agent is not a suitable tool for beginners. </div> </div>
"Computers are good at following instructions, but not at reading your mind." © Donald Knuth
Many different speakers would tell you that you have to become a manager to work with coding agents. It frightens a lot of programmers. The good news is: That is a lie! Such an approach might work if all you need is a crude prototype, but it would probably fail dramatically if you persist. A much better strategy is to take the role of a systems analyst or software architect. Coding agents do not have expertise to choose a good solution. They choose the most common solution for the context they have. And our goal is to:

Provide the agent with more relevant context</li>
Guide the agent toward a better solution</li> </ol>
Doing this interactively for each of the tasks is extremely tiresome, so it is a good idea to reuse as much as possible. And Claude Code has some very good tools for such reuse.
Skills</h2>
Think about every practice you try to enforce on your projects. You should probably make a Skill</a> for it. A Skill is a very efficient approach for transferring knowledge into your agentic alter-ego. It is a markdown document accompanied by additional files which can include both additional documentation and pre-built tools for specific tasks. The main markdown file has a short description text which will always be present in the context. The agent is instructed to check its current objective with this description and it will deep-dive if there is a match. You can encode your VCS/branching preferences in one skill (my local skill encodes my personal rules for using jj</a>) and an approach to writing code-comments in another skill. My toolset has skills for the way I want python-tools to be created (and Claude writes a lot of temporary python tools!) and how reactivity should be done in Dioxus</a> apps. I have several dozen of them and add more constantly.
And while some skills are shareable, the majority of them depends on your personal tastes and preferences and just wouldn't make a lot of sense for anyone else. And that is a good thing. Don't rush to look for curated lists and marketplaces of skills. Create your own.
Claude Code can configure itself</h2>
And when I say "create your own", I don't mean to literally write them by hand. Jump to the meta-level: tell Claude Code to do it for you.

Take a look at the recent Claude Code docs for writing skills and create a skill for …. Ask me questions about how I want it to work. </blockquote>
"Ask me questions" is a very important part. You don't want Claude to make decisions on your behalf. You want it to get details from you. As long as you know what to ask beforehand — write it at once, but oftentimes you can't quite find the correct words — that's OK. Claude is a fine interviewer. And you can do many iterations of questions gradually increasing the amount of detail. In some extreme cases I even suggest you start the process by making a plan</a> for a detailed interview: Ask Claude to do some research and prepare a file with 20 questions and designated places for your answers. It will require some effort, but the result would be worth it.
Same thing applies to generic instructions:

Mention /a, /b, and /c skills in your global CLAUDE.md. I want these to be very visible to agents. </blockquote>
Knowledge Base</h2>
I suggest everyone find a way to take notes about things you find interesting. It can be as simple as a collection of text/markdown files or as complicated as an automated pipeline which summarizes the articles which you find useful. The important part is to teach Agents how to find information there (yes, that's one more skill I suggest you create). Being able to reference something local without resorting to web-search capabilities is extremely useful:

I want you to apply the approach from that article by Martin Fowler I read last week </blockquote>
A habit of information hoarding finally pays off 🤪

anticipation </div> </div>

p.s. You probably noticed that I didn't say anything about project-level CLAUDE.md files — that was intentional. I find them to be less useful than most people consider them to be. I guess I should write a separate article about that. </div> </div>
Links Elsewhere</h3>

Comment at Mastodon</a></li>
Discuss at LinkedIn</a></li>
Discussion at lobste.rs</a></li> </ul>

Recording terminal animations with ASCIInema

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

In the previous article</a> I was using terminal animations to illustrate examples of using the 'jj' command line tool. The need to figure out how to do that delayed the article. But now I know how to do it and I can share this knowledge.
Preamble</h2>

ASCIInema is not the only tool for recording terminal sessions, but it is the one which worked for me reliably.</li>
I use Fish shell on macOS, but my solution should not be difficult to adapt to other shells.</li> </ol>
Recording</h2>
Official "Getting Started" page</a> of ASCIInema has all the details about installing on different systems. In my case, I used Homebrew to install it:
brew install asciinema</code></pre> Then, I added the following functions to my ~/.config/fish/config.fish</code> file:
# Asciinema recording function with custom dimensions function arecc # Arguments: $argv[1] = columns, $argv[2] = rows # Get current date/time for filename set -l datetime (date +"%Y%m%d_%H%M%S") set -l filepath ~/Movies/asciinema_$datetime.cast # Launch fish with autosuggestions disabled and custom alias # Note the escaped quotes for the alias set -l init_commands "set -g fish_autosuggestion_enabled 0; alias jj=\"jj --no-pager\"" # Launch asciinema with fish using the commands asciinema rec --cols $argv[1] --rows $argv[2] --command "fish -C '$init_commands'" $filepath echo "Recording saved to $filepath" end # Asciinema recording function with default dimensions (80×24) function arec arecc 80 24 end</code></pre> What's going on here:

The arecc</code> function takes two arguments: the number of columns and rows for the terminal window and arec</code> is a wrapper for it with default values of 80 and 24 which I used for all of my videos</li>
All of the recordings are saved in ~/Movies</code> directory with a timestamp in the filename. They looked like Movies/asciinema_20250420_021157.cast</code></li>
I used a subshell with custom initialization commands:

set -g fish_autosuggestion_enabled 0</code> disables the autosuggestions in the terminal. otherwise Fish would pollute the output with suggestions which are relevant to my environment, but not useful for the video</li>
alias jj="jj --no-pager"</code> forces jujutsu not to use pager for jj status</code> and other commands. I wanted to show the linear flow and pager would redraw the screen and show only output of the single command.</li> </ul> </li> </ul> That's pretty much it. To start recording, I just run arec</code> in the terminal and then execute several commands I want to record. When I am done, I press Ctrl+D</code> to stop the recording.Using in article</h2> The files are saved in a compact format which is trivially parsed and displayed by asciinema-player</a> js library. So, I just needed to: Put asciinema-player.min.js, asciinema-player.css and and my recorder cast-sessions into the static</code> directory of my zola-powered blog. I added the following lines to the header.html</code> partial of the template: <link rel="stylesheet" type="text/css" href="/asciinema-player.css" /> <script src="/asciinema-player.min.js"></script></code></pre> Finally, I added the blocks like this to the markdown-source of the article: <div id="ascii-jj-describe"></div> <script> AsciinemaPlayer.create( "/jujutsu-different-approach/jj-describe.cast", document.getElementById("ascii-jj-describe"), { rows: 5, idleTimeLimit: 0.2, }, ); </script></code></pre> I create a <div></code> container and connect js-player to it, passing some settings. rows</code> limits the height of the player to 5 lines (which is enough for this animation)</li> idleTimeLimit</code> is set to 0.2 seconds to fast-forward thru the pauses in the recording. I am not the fastest person in the world and this setting makes sure that you do not suffer from this :)</li> </ul>
Jujutsu: different approach to versioning 2025-04-20T00:00:00+00:00 In the previous article</a> I told about my history with different version control systems and how I ended up using Jujutsu. This part will focus on why I think it is an important improvement over the git's status-quo and why I use it daily. The way of Git</h2> Let's start by defining the aforementioned status-quo. Typical user sees interaction with Git as moving files between 3 stages: Files are edited in the file system. Git doesn't know anything about them. Some of the commands can compare the changed parts against other stages (think git status</code> or git diff</code>).</li> Some [parts] of the files are added to the "staging area" using git add [--interactive]</code> command. These changes are not yet part of the tracked history, but Git knows about them.</li> Proper content-snapshot with identifier and metadata is injected into the repository using git commit</code> command.</li> </ol> Linus called this system "the stupid content tracker</a>" because at its core it doesn't try to do anything smart. It doesn't try to understand the content, it doesn't try to understand the changes, it doesn't try to understand the history. It just stores the snapshots and the metadata. In the grand scheme of things, it is up to the user to make sense of it. And to be effective with git, users have to make sense of it. Install Jujutsu</h2> Jujutsu</a>, a VCS which I started to use recently, makes some very different choices. Let's see how it handles this. I will be talking about the concepts and showing the commands. If you want to follow along, you can install it and try it out in parallel. On macOS with Homebrew</a> it is as simple as brew install jj</code>. You can find instructions for other platforms on the official site</a>. Jujutsu allows you to work with arbitrary git repositories. You can use both git</code> and jj</code> at the same time. Adding jujutsu support to repo is as simple as running jj git init --colocate</code> in it. Jujutsu will detect existing git repository and will configure itself to transparently sync with it.

thisalex.com

Taming Claude Code

Links Elsewhere</h3> Comment at Mastodon</a></li> Discuss at LinkedIn</a></li> Discussion at lobste.rs</a></li> </ul>

Recording terminal animations with ASCIInema

Preamble</h2> ASCIInema is not the only tool for recording terminal sessions, but it is the one which worked for me reliably.</li>

Jujutsu: different approach to versioning

Links Elsewhere</h3>

Comment at Mastodon</a></li>
Discuss at LinkedIn</a></li>
Discussion at lobste.rs</a></li> </ul>