Skip to content

Supervising Agent Work

This page is for people who direct a coding agent but do not write code themselves: analysts, product managers, and domain experts building tools for problems they know better than any developer. The agent writes the code. Your job is to decide what it should build, notice when it does something risky, and check whether the result works. HELIX calls this division human authority: humans decide, agents draft.

You do not need syntax, algorithms, or framework internals for that job. You need a working model of your system, the habit of writing intent down before the agent starts, and three questions you ask before you accept any change.

Write intent before the agent builds

HELIX puts intent over inference. If you have not written down what “done” looks like, the agent will define it, and its definition will be whatever it managed to produce. Start with the smallest artifact stack in the Manual HELIX Recipe: a short vision or product brief, then a feature specification whose acceptance criteria say what must be true, how someone can tell, and what must not break.

If writing that from a blank page is hard, ask the HELIX skill to grill you. Grill mode asks one question at a time, offers a recommended answer for each, and writes nothing until you agree on what is wanted. The answers become the acceptance criteria.

Tests, lint rules, and CI checks are acceptance criteria too: ones the computer checks on every change. You do not have to write them. You do have to read their names and confirm they describe what you asked for.

Know the structure before the first line of code

For a new project, write the charter or product vision and the architecture document’s System Context and Deployment sections with the agent before it writes code. For an existing project, read them before you change anything, and update them in the same change when you move something. The charter says what the project is for and what it does not do. System Context and Deployment say what runs where, where the source of truth for the data lives, which outside services it depends on, and how it gets deployed. If the project has no architecture document, ask the agent to draft one from the code and have the project’s owner confirm it; until then the draft is a hypothesis. Then ask the agent to explain the code against these documents.

Treat existing code as evidence of what the system does today, not as the authority on what it should do. When code and the governing documents disagree, the documents win, and the disagreement is a finding to resolve.

Three questions before you accept a change

What changed?

Read the summary and the list of changed files, not only the agent’s description of them. Agents add things nobody asked for: a second programming language, a new dependency, their own virtual environment, or database-specific workarounds in code meant to run on more than one database. Agents also under-deliver while claiming done, leaving stubs or placeholders on the path you asked for. The scope-discipline concern names both failures; remove what the change did not need and reopen what it did not finish.

How do I know it works?

A report that the work is finished is a claim (evidence over confidence). The verification concern requires observed evidence of the running system: run the tool the way its users will and compare the result to your acceptance criteria. To check the code against the documents without reading the code, ask the HELIX skill to align and read its findings.

How do I undo it?

Most changes under version control can be reverted. Some cannot: deleting data, sending a message to another person, running a schema migration, publishing a release. HELIX’s base stop triggers make the agent stop and ask before each of these, and also before adding a dependency, pushing or merging, reading secrets, making very large edits, or applying infrastructure changes, whatever its autonomy level. Treat any action whose undo takes more than reverting a commit the same way: you decide, and the agent prepares the action and waits. HELIX’s workflow principles say to prefer reversible decisions.

A HELIX review report opens with the same three lines: what changed, evidence it works, how to undo it. Read those three before the rest of the report.

Keep changes small

Ask for one small change at a time, merged once CI passes and a reviewer approves. A short diff is one you and your reviewer can read line by line, including everything the agent added. Long-lived branches drift and become harder to review.

Where to go next