Field notes on building software people understand Essays and open-source tools

Quality is a team knowing what its software does.

We write about how teams keep that knowledge while coding agents write more of their code. We also build suss, an open-source tool that reads code and writes down what it does, with no model in it.

Example

From one handler to the whole path.

suss reads the handler, follows the functions it calls, checks the app that calls it, and joins it all into one record of the path.

src/accounts.ts the API
1 app.get("/accounts/:id", async (c) => {
2 const account = await db.account.find(c.req.param("id"));
3 if (!account) return c.json({ error: "not found" }, 404); ← 404 when there’s no account // 404 when there’s no account
4 if (account.deletedAt) return c.json({ error: "gone" }, 410); ← 410 once it’s deleted // 410 once it’s deleted
5 await recordAccess(account.id); ← calls recordAccess in src/audit.ts // calls recordAccess in src/audit.ts
6 return c.json(account); ← 200 with every column of the row // 200 with every column of the row
7 });

What we keep writing about

People

When an agent writes the code, a person on the team still owns it. We write about review, ownership and what senior engineers do now.

Attention

Understanding a system takes time and focus. Good tools take on as much of that cost as they can, so people can spend theirs on decisions.

Process

Planning, review, release and on call each depend on knowing what the code does. We look at how each step can find out.

Get the next essay

Follow the RSS feed to see each new essay when it goes up.