12. Working with AI¶
Has this ever happened to you? You asked an AI to fix a figure and the result looked plausible, but you could not tell what it had changed or how. The next time you asked the same, it fixed it differently.
The key idea: in fig-atlas an AI runs the same commands a person does, on your behalf. It shows what will change before changing any file, and goes ahead after you have checked. So the result is the same whichever AI you use, and you always know what changed.
How the AI works¶
- An AI assistant (Claude Code, Gemini CLI, Antigravity, opencode, Cursor, Codex, ...) is connected to fig-atlas's list of tools and uses them (how to connect). Creating a project, attaching a bundle, building, viewing a figure, promoting and retiring are all tools.
- A tool that changes files returns only a preview (what will change) when first called. The AI shows it to you and applies it only when you agree.
- The AI reads and follows the repository's rules file (
AGENTS.md): read raw data only, never delete config comments, ask before changing colours or design, and more (chapter 13). - When the same task was done by a person with commands, by opencode and by Antigravity, the result files were identical down to the last byte (test of 2026-10-08).
What to hand over, and what to judge yourself¶
| You can hand to the AI | You judge yourself |
|---|---|
| Creating projects, attaching bundles, building | Which data to show in which figure |
| Changing config values (sizes, ranges, layout) | Colour and design decisions that change a figure's meaning |
| Fixing check errors in the config | Whether a warning can stay |
| Summarising results, drafting legends | What the figure claims, and the limits of the claim |
| Promoting and retiring, updating the mapping table | Which figure becomes Figure what (the storyline) |
| Listing "what changed" for a revision record | The "why" of the revision |
| Drafting a new kind of figure | Whether it is the shape you wanted |
Good requests, weak requests¶
| Weak request | Good request | Why |
|---|---|---|
| "Make the figure prettier" | "Make panel b's text the same size as panel a's and move the legend to the upper right" | You can only check the result if it is clear what to change. |
| "Plot this data" | "Attach raw_data/…/volcano_bundle to the lab's exploratory project lab-acute-1d-de and build it" |
The project it goes into decides the names and folders. |
| "Fix all the errors" | "Fix the preflight errors in the config. Ask me first if colours or design have to change" | The AI does not make meaningful decisions on its own. |
| "Put the numbers in" | "Turn the anchor count in Figure 2's legend into a live number the analysis records" | Hand-typed numbers drift from the data (chapter 9). |
Bringing in a new figure¶
The AI works in a different order depending on whether you have a bundle, plotting code you wrote, or only a capture or sketch of the figure you want (Case A, B, C). In particular, when there is only a shape and no code (Case C), there is always a step where the AI has its interpretation confirmed before drawing. Details are in 5. Three entry points.
What to check after the AI's work¶
- [ ] Was it applied only after you saw the preview (what will change) and agreed?
- [ ] Is what changed the config, with the raw data (
raw_data/) untouched? - [ ] Are the config's explaining comments still there?
- [ ] Are there 0 preflight errors, and have you been told what the warnings are?
- [ ] Are the numbers in the legend live numbers?
- [ ] For a paper figure, do the storyline's Figure number and the project name match?
An AI can make mistakes. But in this tool everything the AI does stays as changes to the config, so you can see what changed and undo it.
Previous: 11. Into the paper: a figure's life · Next: 13. The rules on one page