AI guidelines

Ettin is built by one person and two AI coding agents, and the agents have been in the project since the first week. This page is the set of rules that work is done under, and the reason for them. The companion page, how we use AI, is the account of what the agents actually do and the times it went wrong.

The premise

I’m not using AI to completely automate creating a module and yeet it into the universe.
At the same time, I am no Jason Lim, but I want to make modules. I like projects, so the idea it pick a real thing to build, nothing too crazy, and build it from the first schematic symbol to a board in a rack. Do every step in order, with agents as a collborators that explain, check, draft and script. They never do the actual step.

The alternative is sometimes tempting. Maybe if you already have the skills, that’s a fast way to prototype and there is nothing wrong with it. For someone who does not, it is a way to own a board and learn nothing, and if the board does not work, to have no idea why. I wouldn’t be comfortable with that.

My goal is different. Not to make a product, but to become competent at a craft: a music technology maker who can design, build, debug and ship a Daisy-based Eurorack module from scratch, and then do it again.

The module is the proof of the learning, and the learning is the point.

What it does and does not make me

It does not make me an electrical engineer, and it does not make me an audio DSP expert. The posts on this site are evidence of that. An actual engineer would not have made most of those mistakes I think.

What it does show is that it is possible for one person, or a very small team, to create a hardware instrument from nothing, learn the craft on the way, and ship something good on a small budget/timeline.

Seven months, three board revisions, five boards ordered at a time, one working module in a rack and the next revision on order.

The path always existed, but I think it would have been much more difficult a few years ago.

The guidelines

1. The human is in the critical path, on purpose. Every design decision is mine, and the plan files mark who decided what and when. The agents propose; I decide. In the task tracker, an issue is blocked until I resolve it unless it carries a label that says otherwise, and nothing passes the external review gate without my sign-off. This is slower. The bottleneck is where the learning happens.

2. Step by step, soup to nuts, with a gate at every step. Nothing proceeds until the previous thing has been verified, and verified on hardware where hardware exists. Rev 2 could not be ordered until the output stage and the CV front end had been built and measured on a breadboard. A board goes through bring-up stages A to E and each has a pass condition written before power-on. Rev 3’s keyboard switches and LEDs went through breadboard gates on a spare processor before any copper was drawn. A step that was skipped is a step I did not learn.

3. My hands on the hardware. I solder, I probe, I measure, I listen. I make every edit in the schematic and layout editor myself; the agents never touch it, and when they edit a board file by script it is by agreement, with a backup, and I review the diff. The agents cannot see the bench. Everything they know about a physical board is what I type and what the serial port prints. The physical skill is the one I came here to get.

4. Explain from first principles, then let me do it. When the agent proposes a circuit, it explains why, from the physics up, in terms I can check. When I do not understand a thing, the work stops until I do. The resistor divider, the clamp diode, the thermal relief, the decoupling capacitor: each one on this board is there because I can say why.

5. Verified means verified on the thing. “The build succeeds” is not done. “The behaviour is confirmed on the board” is done. A calibration is a number read off a boot line, a panel fit is a panel on a board, a review finding is checked against the files before it changes anything. An agent’s confidence is not evidence, and neither is mine.

6. Write everything down, failures first. Every stage, every bench session and every mistake goes into a document of record in the repository, with the diagnostic path, not just the fix. The repository is the memory the agents and I share across two machines, and it is what this site is built from. A mistake that is written down is a rule by the next day.

7. The agents are labelled. Every tracker comment an agent writes starts with its name in brackets. Every commit it helped write carries a co-author line. A reader, including me a month later, can always tell which words are mine.

8. The smallest change that teaches the most. No features beyond what was asked. No abstraction for a thing used once. Rev 3 is Rev 2 with the smallest possible delta, so that when something breaks there is one suspect. The same rule applies to the tools: update and pin them once, before the design changes, never during.

9. Honest claims. Ettin is NES-style, but not NES-accurate. When the agent does not know, it says so; when I do not know, I say so, and the open question goes in the file rather than being written around. A page that overclaims is worse than a page that is late.

What it costs and what it buys

It costs time. A person in the critical path is slower than a model that generates a board overnight, and most of the seven months is the time it took me to learn each step well enough to do it. It costs mistakes, which are the content of this site.

It buys a module I understand to the last resistor, a process that caught fatal faults before a board was ordered, a repository that a second person could build from, and the ability to do the next one faster. The product is the module. The goal is the craftsman.