What goes where
Which file owns which content, system prompt, test files, setup/teardown, rules, and procedures, and how to decide.
AskUI Desktop separates three concerns that are easy to mix up:
- Who the agent is: the system prompt (
prompts/): capabilities, device facts, app knowledge, report format. - What to do on this run: test files (
tests/): the steps for each scenario. - Shared lifecycle:
setup.md,teardown.md,rules.md: what runs around groups of tests.
Getting this right is what makes a project maintainable: when a run misbehaves, you know which file to open.
| Content | File |
|---|---|
| Agent identity and global rules | prompts/system_capabilities.md |
| Facts about the test machine the screen doesn't show | prompts/device_information.md |
| App knowledge: navigation, state indicators, quirks | prompts/ui_information.md |
| Report structure and status vocabulary | prompts/report_format.md |
| Behaviour for one suite only | <folder>/rules.md |
| Shared preconditions | <folder>/setup.md |
| Shared cleanup | <folder>/teardown.md |
| Reusable step sequences | procedures/<name>.md |
| One test scenario | tests/<name>.md |
The system prompt (prompts/)
Assembled once at run start, applies to every test. Four files with four lifecycles, keeping them separate means a change to one never risks the others:
system_capabilities.md: essentially constant; you rarely edit it.device_information.md: changes per machine; swap it to retarget.ui_information.md: grows as you learn the app; your biggest lever.report_format.md: typically shared org-wide.
What to write in each: Agent behavior.
Test files (tests/)
A test file describes what to do in this specific scenario, nothing else:
- Belongs in a test file: the scenario's steps with expected results, credentials by name, procedure calls.
- Doesn't belong: app knowledge (→
ui_information.md), device facts (→device_information.md), steps every test needs (→ setup/teardown), sequences shared between tests (→ procedures).
How to write the steps themselves: Writing good tests.
Setup, teardown, and rules
Three conventional files per test folder, picked up automatically,
setup cascades outer-first, teardown unwinds in reverse
(details). The one to remember:
when a suite needs different behaviour, add a rules.md in its folder,
don't edit system_capabilities.md, which changes every test in the
project.
Procedures (procedures/)
A sequence used by more than one test or setup file, called explicitly from a step, fixed in one place (details). Setup/teardown run automatically for a folder; a procedure only runs where a step calls it.
What the agent may do
Keep a run's reach to what the test needs, least-privilege accounts, an opt-in toolbox, scoped tools, secrets, and what belongs in review.
Agent behavior
How to shape the way the agent acts, what to write in each prompt file, error discipline, device facts, UI knowledge, the report contract, and per-folder rules.