What I learned designing software interfaces for coding agents
Lessons from agent-facing tools for Relay, Figma, Outline, and Jira: bounded context, guarded writes, structured output, evidence, and instructions.
My recent side projects share one question: how should a coding agent interact with software that was designed for a person?
I approached that question as a senior frontend engineer who uses coding agents heavily. I do not have deep training in machine learning or LLM engineering, and coding agents produced most of the implementation in these projects. My work was to identify the friction, define the behavior I expected, review the generated changes, test them, and keep tightening the requirements.
I now maintain four projects around that work:
- Relay gives an agent a browser board for showing work and collecting structured human feedback.
- figma-lens lets an agent find and inspect Figma designs through bounded visual evidence.
- outline-cli exposes Outline search, reading, and guarded updates through a direct CLI.
- jira-cli gives agents short-lived commands for Jira Server work, with JSON output and previewed changes.
They are personal tools, so I do not claim production scale or broad adoption. They have given me a practical set of interface rules for software that an agent needs to operate.
Return data the caller can check
An agent should not need to interpret decorative terminal output to learn whether a command succeeded. Structured output makes the result easier to validate, pass to another step, and compare in a test.
Relay returns answers, notes, comments, annotations, and edited blocks as JSON. Its instructions tell the agent to read every feedback channel because a note beside a selected option may change what that selection means.
outline-cli returns JSON and offers ids, summary, and full views. jira-cli also returns JSON and gives mutating commands a preview state. Stable fields and exit behavior matter more than conversational wording when another program is the caller.
Deterministic output gives the surrounding program something definite to inspect, even when the model's behavior varies.
Give context a zoom level
Agents can waste context by fetching everything available. They can also make poor decisions from a result that is too small. The interface needs a way to move from overview to detail.
figma-lens uses a staged workflow. scout returns an overview of a board and its states. focus or focus-set retrieves the chosen screen. detail renders a few important child groups at source size. Larger artifacts stay in a local cache while stdout carries a compact navigation manifest.
The workflow matters as much as the commands. An agent first locates the correct state, then chooses one visual baseline, then opens only the evidence needed for the implementation. It should not dump a complete Figma tree into its context.
outline-cli applies a similar idea to documents. A search can return IDs or summaries before the agent opens one document in full. A local index can help resolve a remembered title, but the instructions require another read when the current content matters.
The useful abstraction is progressive disclosure. Give the agent enough information to choose the next read, then let it ask for a narrower and richer result.
Make reads easy and writes deliberate
The risk changes when a command moves from inspection to mutation. I wanted that boundary to be visible in both the tool contract and the instructions.
figma-lens is read-only. outline-cli requires performAction:true for mutations. Its delete flow goes further: the agent must first read the document with delete arming enabled, then return the resulting short-lived receipt with the delete request. The receipt is checked against the target.
jira-cli previews changes by default. Posting a comment or making another change requires --perform-action, after the caller has had a chance to inspect the issue and proposed action.
These gates do not decide whether an action is authorized. The user's request still sets that boundary. Their job is to stop an accidental write from looking like an ordinary read and to preserve a review point in the flow.
Put the evidence beside the decision
Agents often ask good questions in a poor medium. A terminal description of two layouts makes the user remember which paragraph referred to which option. A request to review a long plan makes precise feedback awkward.
Relay lets an agent place a diagram, image, diff, table, or code sample beside the question it is asking. A person can comment on a chart point, table cell, selected sentence, diagram node, or image region. The returned annotation identifies its target, so the agent does not have to infer what "that part" meant.
Evidence is also important before code generation. figma-lens treats screenshots as the visual source and structured evidence as the source for copy, geometry, and typography. Its guidance says that returning a screenshot path is not the same as viewing the screenshot. The agent must open the image, inspect important details at source size, and compare the finished interface with the selected baseline.
This reflects a lesson from frontend work: a design name or a layer tree is not enough to establish visual fidelity. The review surface should carry the artifact that a person or agent is expected to judge.
Treat instructions as part of the interface
A JSON schema can describe the arguments to focus or documents.info. It cannot fully explain when to call them, how much data to request, or when to stop.
Each of these tools has an agent skill or bundled guide that describes the operating sequence. The figma-lens skill says to scout before focusing, view returned screenshots, and avoid broad tree dumps. The Outline guidance says to search in a compact view, read the selected document before editing, and set the action flag only for a requested write. Relay explains when a board helps and when a brief chat reply is enough. The Jira skill keeps reads, previews, and executed actions distinct.
I have come to treat those instructions as another product surface. They need examples, failure conditions, and explicit limits. When an agent repeatedly misuses a correct command, I first inspect the default and the workflow. Adding another sentence to a long prompt may leave the same ambiguity in place.
Design for interruption and partial progress
Human review does not follow a tool call's timeout. Relay can open a board in detached mode, return its ID, and let the agent wait for the result separately. Answers and comments autosave while the board is open. A timeout tells the agent to check the existing board's result; it should not create a replacement and lose the draft.
The same principle appears in smaller forms elsewhere. outline-cli checks an expected document revision before applying a patch. Figma inspection keeps artifacts in a cache so a later, narrower command can reuse them. These interfaces preserve enough state to resume safely after the human, network, or calling runtime interrupts the sequence.
The scope of this work
These projects show that I can identify agent workflow problems, define tool contracts and safety boundaries, test behavior, and refine instructions from failures. My frontend experience helps with review interfaces, information hierarchy, and the points where a person needs to inspect or approve something.
They do not make me an applied AI or machine-learning engineer. I did not train models, build the underlying agent clients, or personally write most of the code in these repositories. I also do not present concept work as proven production infrastructure.
The area I can defend is narrower: designing practical interfaces between coding agents, existing platforms, and the people supervising the work. The detailed project notes cover Relay, figma-lens, outline-cli, and jira-cli.