Notes — Maxim Beregov

How this site came together

Tue, 29 Sep 2026 03:30:00 +0300

I built this site together with AI in one long session. The most interesting part wasn’t the code but how the idea of what the site should be kept changing.

A brand book made for me — but not for this

Some time ago I had a brand book made: neon green, a space tunnel, a pixel font, headings in small caps. The first version of the site followed it to the letter. It came out neat and recognisable — and I liked it less than the plain layout before it.

README for people, AGENTS.md for agents

Tue, 29 Sep 2026 02:00:00 +0300

Every repository of mine — from a Go library to a wrapper around someone else’s image — has four files: README.md, CONTRIBUTING.md, CHANGELOG.md and AGENTS.md. All four are required, with no exceptions by repository type.

There is one main rule: README, CONTRIBUTING and CHANGELOG are written by a person for a person. AGENTS.md is written by an agent for an agent. They don’t mix in either direction.

Why one text won’t do

A document addressed to both readers serves neither. The person is put off by machine density: lists of commands, invariants, prohibitions with no explanation. The executor is put off by everything else: introductions, reasons, invitations to “read this to get the idea”. In the end each reads half and misses what matters.

Write the lesson down now, not at the end

Mon, 28 Sep 2026 19:00:00 +0300

I used to put notes off until later: finish the task, then write down what I learned. Then “later” came, and half of it was gone. Especially the most valuable part: why we chose this option and not the one next to it.

Now the rule is different: a decision, a lesson, a procedure or an important fact appears — I write it down right away, as a short note in a shared inbox folder, and carry on working.