Help CenterGetting startedBest practices
Best practices
Getting started

Best practices

The first half is a few habits that make QU Studio easier to work with. Each one says what to do, why, and gives an example. The second half lists common situations by "I want to…", and walks through what to tell Q, what happens, and what you need to do.

New here? Start with Where to start; how each feature works is in the Guide. Q is the default name; you can rename it on its page.

In QU Studio your attention should go to three things only: saying what you want, making the calls, and accepting the work. Everything below is about making those three take less effort.

A few words first

WordIn one sentence
QYour project assistant. You tell Q what you want; Q splits it into tasks, hands them out, keeps track, and calls you when you need to decide. Q doesn't write code itself.
SessionA conversation with an AI coding assistant (an agent, like Claude Code or Codex). Sessions are what actually write code.
TopicA place to talk with Q about one thing. The whole story of that work stays in it.
Discussion topicA topic for talking only, not building. While an idea isn't settled, talk it through here first, then build once you've reached a conclusion.
TaskOne item on the board: what to do and how to tell it's done. Every task has a number, like QS-13.
AcceptanceWhen a session finishes, you take a look to see if it's right. If it is, click "Done"; if not, click "Send back" and say what's wrong.
PrototypeWhat the UI should look like, drawn first and built only after you approve it.
VersionA batch of changes collected and shipped together, like 0.5.0.

A few more words come up below:

  • Main (mainline): the "official" copy of the project's code. Changes only go into it once the task is accepted.
  • Main computer: the computer where Q lives. If you only have one computer, it's that one.

Part 1: A few habits

1. Telling Q about something: what you want and how to check it, not how to build it

What to do

  • Start with the result you want: who uses it, where, and what they see.
  • Then say how you'll know it's done (this is called acceptance criteria): how you'll check it once it's finished, ideally as points you can tick off one by one.
  • How to build it (which library, which file) usually doesn't need saying; leave that to the session. Only say it when you really have a hard requirement, like "no new dependencies".
  • Pass along anything you have to go on: paste screenshots straight in; send web pages, tweets or video links straight over, and Q reads them. Q can't read pages that need logging in; paste the text or a screenshot instead.

Why

Q splitting the work, the session doing it, and you accepting it at the end all go back to the same "what we want". When the result is clear, the session can pick a good way to get there. When the acceptance criteria are clear, accepting means ticking them off one by one rather than going on gut feeling.

Example

Not great"Change that date function in utils to use dayjs."
Better"Order times in the order list show as 2026-11-21T08:30:00Z; show them like 'Nov 21, 16:30' instead. Done when: both the list and the details page are right, and dates not in this year show the year."

2. Main chat, topics, discussion topics, looking after it yourself: what each is for

What to do

You want toUse
Ask a quick question, check progress, arrange things across projectsQ's main chat ("Q" at the top of the left sidebar)
Do one specific thing that takes several stepsA topic: tell Q "start a separate topic"
Talk through the direction while you haven't made up your mindA discussion topic: tell Q "let's discuss this first", and once you're done, say "let's go with that"
Change a line or two, and close it when doneI'll look after it: open a session yourself and just say it

Why

Progress and results go back to the topic Q handed the work out from. The whole story of one piece of work stays in one place, and the main chat doesn't fill up.

Keep talking and building apart: while an idea isn't settled, talk it through in a discussion topic first, without changing code; once you've reached a conclusion, open a topic to do the work. Don't discuss and change code at the same time: every change of mind during the discussion sends half-built code back for rework.

Example

What to say

In the main chat: "What's blocking others today?"

A topic: "Add a dark mode switch to the home page; follow the system, and let people switch by hand too."

A discussion topic: "I'm thinking about adding points to the membership program. Let's talk through the design first, no rush to build it." Afterwards: "Let's go with that, option two."

3. One topic per version, closed once it ships

What to do

  1. When you're collecting work into a release, tell Q "create version 0.5.0".
  2. Give the version its own topic: "Start a separate topic just for 0.5.0."
  3. Say everything that goes into this version in that topic, and have Q split it into tasks and put them into 0.5.0.
  4. Keep about 3 to 5 tasks in progress at once in one topic; if there are more, split them across several topics.
  5. To find out what's left, ask, or look at the versions page ("Versions" in the left sidebar). When it's all done, say "ship 0.5.0".
  6. Once it has shipped, end the topic, and open a new one for the next version.

Why

  • Each topic only holds its own work, so nothing gets mixed up.
  • The older a topic gets, the messier it is inside, and old content gets in the way of new discussions. Closing it once it ships and starting fresh for the next version keeps things cleanest.
  • With too much in progress at once, work waiting for your acceptance piles up, and tasks are more likely to clash.
  • The one-line changelog entry each session writes when handing work in is collected into the version's changelog draft, ready to use when you ship.

Example

What to say

In the "0.5.0" topic: "This version has three things: dark mode, exporting orders to Excel, and a new login page. Put them all in 0.5.0."

A week later: "What's left for 0.5.0?" → once it's all done: "Ship 0.5.0." → after it ships, end the topic.

For projects like websites and backends that go live as soon as they're changed, you don't need to collect versions. (Just keep "Ships as soon as it's merged" on under Project settings › Rules; it's on by default.)

4. Several things at once: stay off the same code, and pin down shared agreements first

What to do

  • Things in progress at the same time should avoid changing the same part of the code where possible.
  • Pin down anything several of them rely on first, then let each go its own way. For example, "how data is passed" between the front end and the back end (this is called an interface): what each field is called, what it means, and how errors are reported. You can create one task just to settle this, and have the other tasks wait for it to finish before starting.

Why

Working at the same time doesn't mean no conflicts. If two things change the same code at the same time, they still clash when put together, and someone has to sort it out. With the agreement pinned down first, both sides write to the same one and fit together at the end.

Example

What to say

"Order export and order filters both change the orders API. First create a task to settle the orders API, and have both wait for it before starting."

5. Tell topics: only come to me about these

What to do

Tell Q plainly: only the kinds of things below come to you, and everything else they decide themselves.

  • Scope: whether to do it, and how much
  • Version numbers
  • Spending money
  • Publishing anything outside

Why

Small things like where a button goes or which comes first, a topic can decide for itself; the calls that are really yours are just these. Deploying, spending money and deleting data are always asked about first by QU, whatever you say.

Example

What to say

"In this topic, apart from scope, version numbers, spending money and publishing anything outside, decide things yourselves; no need to ask me."

6. Changing the UI: prototype first, then build

First-time setup
  • Connect the prototype (Project settings › Prototype › Connect prototype).
  • Register the dev build's start command, so sessions can put screenshots of what they built side by side with the prototype (Project settings › Run & preview). You can have a session read the repo and draft it, and you just click "Approve".
  • For how requests flow, choose "Depends on the prototype" or "Prototype first" (Project settings › Rules).

What to do

  1. Tell Q what you want. Work with a UI gets a prototype drawn first.
  2. Look at the prototype in the right panel (⌘\), and tell the prototype session directly what's off.
  3. When you're happy, click "Finalize". Only then does Q split it into tasks and open sessions to build from it.
  4. When it's done, you look at the prototype and what was built in side-by-side screenshots when accepting.

Why

Whether a UI is right is the hardest thing to put into words. Settling the prototype first turns "what we want" into something you can compare against: the session builds from it, the prototype session checks against it (mismatches go back, up to 2 rounds), and the side-by-side screenshots show you at a glance whether it matches. Changing a prototype is much cheaper than changing code.

Example

What to say

"Add a 'Notifications' group to the settings page with three switches: desktop notifications, sound, and Do Not Disturb hours."

→ The prototype is drawn; you say "put the switches on the right, and make Do Not Disturb two time pickers", and click "Finalize" once you like it. When it's built, you accept it by looking at the side-by-side screenshots.

7. Accepting work without the effort

What to do

  • Start with the top of the task: open the task in "Waiting on you"; at the top are the side-by-side screenshots, tests, acceptance criteria and how much changed.
  • Let Q look first: Q checks the acceptance criteria, tests and changes first, and leaves a one-line suggestion on the task. ("Q › Settings › Check work when it's handed in".)
  • Accept together the ones Q suggests accepting: accept a batch with one click in "Needs you" (⌘J).
  • Say exactly what's wrong when sending back: one specific sentence, with a screenshot if you can. You can also tell Q "send QS-13 back, …".

Why

What can be checked objectively (whether tests passed, whether the acceptance criteria are met, how much changed) goes to the machine and Q; work with failing tests or that can't be merged is already blocked by the system. Your eyes are saved for what takes taste: whether the UI is right and how it feels to use. The more specific you are when sending back, the more likely the session gets it right in one go.

Example

Not great"That's not right, try again."
Better"The button should be at the bottom right, not centered; the text is hard to read in dark mode (screenshot attached). Everything else is fine."

8. "Don't ask me": open things up one kind at a time

What to do

Being asked about everything at first is fine. Once you've seen a kind of thing a few times and you're comfortable, open up that kind:

  • Things Q decides for you: say "don't ask me about these", or agree several times in a row, and Q offers to note it down. You can revoke it any time. ("Q › Settings › Ask you first?".)
  • Commands sessions run: for running tests, running builds, installing dependencies and the like, once you've allowed a kind in a project, the next approval card has an extra checkbox: "Don't ask me about this kind again". You can also tell Q "don't ask me about running tests in this project".
  • Sessions starting helpers on another agent: when you're asked, click "Stop asking".
  • Accepting small changes: turn on "Q accepts" and tick only the task types you're comfortable with, like docs. It only accepts for you when every condition holds (all acceptance criteria ticked, all tests pass, a small change, Q suggests accepting). (Project settings › Q accepts.)

A few kinds always need your OK and can't be opened up: usage and spending money, security and credentials, deploying, deleting data, and anything sent out that can't be taken back.

Why

Trust is earned one kind at a time. Watch it get things right a few times before letting go, and a mistake costs little; if you stop feeling comfortable, you can take it back any time.

Example

You approved "run tests" five times in a row this week; the sixth time, tick "Don't ask me about this kind again" and allow.

9. Sharing work across several computers

What to do

  • Make the always-on computer the main computer: Q, the board and memory all live on the main computer, and when it's asleep they pause too.
  • Set a limit on each: on the "Computers" page, set "Max at once" for each computer. When you don't name a computer, QU looks at which one is less busy and sends the work there automatically.
  • Name the computer when you need something only it has: say, a signing certificate or a test phone plugged in. Tick "Can sign releases" for the one you release from.
  • Let work move to another computer: turn on "Push each turn to the task branch". If a computer goes to sleep, you can "Rerun on another computer". (In project settings.)

Why

Two computers working together can run twice as many sessions at once. Sharing out the work by "who's less busy" is left to the system; you only name a computer when there's a special need.

Example

The Mac mini is always on, so it's the main computer; the MacBook goes to the office during the day. Both are set to run up to 3 at once, and you never think about which one picks up the work.

More in Multiple computers.

10. Running low on quota: switch to the other agent

First-time setup
  • Have both Claude Code and Codex installed and signed in (see Install & sign in to agents).
  • Turn on "Carry on automatically when quota is back" (Settings › General).

What to do

  • The small ring at the bottom left shows how much quota is left at any time; yellow or red means it's nearly used up.
  • When one is nearly used up, the session asks "Continue on Codex?". One click switches it, and the conversation so far comes along.
  • Write a "When to use" for a model preset, like "when Claude's quota is running low", and Q picks by it when handing out work.
  • If it really does run out, the session stops where it is with its changes kept, and carries on automatically once quota comes back.

Why

Subscription quotas are designed for one person's use, and they go fast when several sessions run at once. With both agents ready, when one hits its limit you switch to the other, and the work doesn't have to stop.

Example

Halfway through, the session says Claude is nearly used up and asks whether to switch to Codex. One click, and Codex carries on changing things in the same conversation.

11. Talking to Q with voice input

QU Studio doesn't have voice input of its own. Use the system's dictation or another voice input tool, and speak in Q's chat box, or press ⌃⇧Q and speak in the small box that pops up.

What to do

  • Say it as it comes: say what you want first, then add how you'll check it; Q turns it into tasks.
  • Glance before sending: task numbers, version numbers and your product's own names are the easiest to get garbled, e.g. "QS-13" coming out as "Q is 13".
  • Add a few words when you mention a task: like "the home page dark mode task", so the right one is easy to find even if the number comes out wrong.
  • Get the numbers right for things like accepting, sending back and shipping: if it came out wrong, fix it by hand before sending, so you don't act on the wrong task.

Why

Talking is faster than typing and good for getting a whole idea out in one go; but transcription makes mistakes, and a wrong number is the worst.

Example

What to say

Say: "The home page dark mode one: put the switch at the top right, and following the system is the default."

Before sending you see "QS-13" came out as "Q is 13"; fix it and send.