The Test Suite As a Second Brain

Note-taking enthusiasts call their extensive collection of interconnected notes their second brain, a notion popularized by people such as Tiago Forte. The basic idea is that you outsource your understanding of a topic into a set of small, "atomic" notes. Each note is about exactly one idea. Notes can link to each other, and by following threads in this web of knowledge, you can then make new connections and uncover novel ideas.

I feel that, for a software project, a good test suite plays a similar role. If the tests are well-crafted, they are atomic encapsulations of the ideas and concepts that make up the project: For this input, we expect that output or behaviour, and so on. And because the tests can be executed and verify that the program adheres to them, they don't lie or get stale the way a piece of documentation does.

This becomes especially valuable with AI agents. Due to their somewhat stochastic nature, it's beneficial to outsource as much as possible to deterministic processes.

Prompt, but verify

By all means explain in your CLAUDE.MD or AGENTS.MD file how you want things to be done. But go further! Add all sorts of automated, deterministic, static checking:

• A linter for code style (and with tools like ruff you can go far beyond simple formatting; it finds common security issues as well)

• Unit tests for correctness and to catch regressions (just be careful the agent doesn't disable or override them 🤷‍♂️)

• Static code quality analysis with tools like CodeScene (Luca Rossi of the Refactoring newsletter reports fantastic results with that tool)

And don't hesitate to hand-roll your own static checkers for things you care about and that are relevant for your project and in your domain. Leave the agent free to focus on messy stuff and take the clearcut things off its plate. (Plus, it goes without saying, even if you don't want to use AI at all, enforcing the easy stuff via automated checks is great for human devs, too...)