# Instrument design for coding agents Interface guide for AI coding agents · 20 October 2026 How to design and build interfaces that work like instruments: understandable structure, unmistakable actions, dependable results. This file turns [Software as an instrument](https://www.ruby.im/software-as-an-instrument.html) into instructions an agent can follow and checks that would fail if the work were wrong. The reasoning and every source are on that page; this file holds only the rules. Use it alongside [AGENTS.md](https://www.ruby.im/AGENTS.md). It applies whenever you add or change something a person sees or operates: a page, a form, a dashboard, a CLI's output, an admin screen. Where it conflicts with an owner's instruction or a stricter legal requirement, those win; say which rule you set aside and why. The standard every interface is held to: could a skilled person use this eight hours a day, trust it under pressure, see what is happening, make a precise intervention, verify its effect, and know how to recover when it breaks? ## 1. Start from the task, not from a law Before changing an interface, write a short design note (in the PR, task or commit message) with four parts: 1. **Task.** Who uses this screen, how often, under what pressure, and what they are trying to finish. 2. **Friction.** Where people hesitate, misread, mis-click, lose work or lose their place. Name an observed problem, or say plainly that it is assumed. 3. **Decision.** The specific change. Cite a principle only as the reason for this decision, never as the decision itself. "Apply Hick's law" is not a decision. 4. **Check.** The test or observation that would fail if the decision were wrong, written before the code (AGENTS.md section 17). Then implement the smallest change that passes the check, and evaluate it on real tasks: completion, time, errors and recovery. Keep what helped; revert what didn't. Done when: the design note exists, each decision has a check, and the checks ran on the actual build. ## 2. Weigh the evidence: laws are hypotheses Named UX "laws" have very different evidence behind them. Treat each as a reason to try something and then check it, not a license to skip the check. | Kind | Examples | How to use it | | --- | --- | --- | | Empirical effects, from narrow lab tasks | Fitts, Hick–Hyman, Miller, serial position, Von Restorff, peak–end, goal gradient, aesthetic–usability, Doherty | Real but bounded. Test whether it matters on this screen. | | Perceptual principles | Proximity, similarity, common region, visual hierarchy | Reliable defaults for layout, as long as grouping matches real relationships in the data. | | Heuristics and rules of thumb | Jakob, progressive disclosure, recognition over recall, Tesler, Postel, Occam, feedback loops | Judgment, not measurement. Each has known failure modes (section 4). | Rules: - Never justify removing a control, hiding an action or guessing input by naming a law. Justify it with the task and the check. - When you quote a number (a time limit, a size, a capacity), give its source and what it measured. If you can't, don't use the number. - One reviewer finds a fraction of the problems (Nielsen and Molich found single evaluators caught 20 to 51%). Your own review of your own interface is not enough; ask for another reviewer or a real user (AGENTS.md section 21). ## 3. The twenty principles as instructions Each row is a default to apply and the check that shows it worked. Grouped by the question the person is asking. ### Finding: where am I, what matters here? | Principle | Do this | Check | | --- | --- | --- | | Visual hierarchy | Make the page's purpose and the next action the most prominent things on it. | A first-time user names the page's purpose and next action within a few seconds, or a reviewer can point to one dominant element per region. | | Proximity | Put labels, help text and error messages beside their control. | Every input has a programmatically associated label; every error is rendered next to its field and linked with `aria-describedby`. | | Common region | Use borders and sections only for real relationships. | Every container corresponds to a real grouping in the data; remove any that are decoration only. | | Similarity | Equivalent controls look and behave the same. | One component (or partial) per control type; no two buttons with the same role have different styles or behavior. | | Von Restorff | Reserve strong emphasis for what is genuinely important. | At most one urgent treatment visible in normal operation; urgent styling appears only for urgent conditions. | | Serial position | Consider order, but keep logical sequence and findability. | Ordering follows the task or the data (time, priority, alphabet), and the reason is stated. | ### Choosing: what can I do, and which one? | Principle | Do this | Check | | --- | --- | --- | | Hick–Hyman | Organize choices around the current task; make differences between options clear. | No frequent action was removed to reduce choice; each option's label says how it differs. | | Miller | Group related information; keep needed context visible so nothing has to be remembered. | The user never has to carry a value from one screen to another by memory. | | Recognition over recall | Show choices, recent items, examples and persistent labels. | No input relies on a placeholder as its only label; recent or valid values are offered where they exist. | | Progressive disclosure | Put uncommon settings behind clearly labeled controls, at most two levels deep. | Every action used daily is reachable without opening a menu; the way to advanced options is visible and labeled. | | Jakob | Keep links, forms, navigation and keys behaving the way people expect. | Links are ``, buttons are `