Skip to content

Commit 6e80737

Browse files
thymikeeclaude
andauthored
docs(agent-setup): keep one canonical agent rule (#3396)
* docs(agent-setup): keep one canonical agent rule with per-client placement Collapse the recommended, Cursor .mdc, and CLAUDE.md rule copies into one copyable rule and point each client section at it, with a placement table. Cursor keeps its required frontmatter; Claude Code no longer overwrites an existing CLAUDE.md. The startup contract test now requires a single rule block that starts work immediately. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(agent-setup): require the open-first line first; leave a visible Cursor placeholder Co-Authored-By: Claude Opus 5.5 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 2dc0ced commit 6e80737

2 files changed

Lines changed: 67 additions & 42 deletions

File tree

‎scripts/__tests__/agent-setup-startup-contract.test.ts‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,25 @@ const MANDATORY_STARTUP_PROBES = [
2121
},
2222
] as const;
2323

24+
const RECOMMENDED_RULE_HEADING = '## Recommended agent rule';
25+
26+
function readCanonicalRule(content: string): string {
27+
const sectionStart = content.indexOf(RECOMMENDED_RULE_HEADING);
28+
assert.notEqual(sectionStart, -1, 'agent setup must have a recommended agent rule section');
29+
const sectionEnd = content.indexOf('\n## ', sectionStart + RECOMMENDED_RULE_HEADING.length);
30+
const section = content.slice(sectionStart, sectionEnd === -1 ? undefined : sectionEnd);
31+
const ruleBlocks = [...section.matchAll(/^```text\n([\s\S]*?)^```$/gm)];
32+
assert.equal(ruleBlocks.length, 1, 'recommended agent rule section must hold one rule block');
33+
return ruleBlocks[0][1];
34+
}
35+
2436
function assertOpenFirstSetup(content: string): void {
37+
assert.ok(
38+
readCanonicalRule(content).split('\n')[1]?.startsWith(OPEN_FIRST),
39+
'canonical agent rule must start normal work with open right after its scope line',
40+
);
2541
const openFirstRules = content.split(OPEN_FIRST).length - 1;
26-
assert.equal(openFirstRules, 3, 'recommended, Cursor, and Claude rules must start with open');
42+
assert.equal(openFirstRules, 1, 'client setup must reference the canonical rule, not copy it');
2743
for (const probe of MANDATORY_STARTUP_PROBES) {
2844
assert.doesNotMatch(
2945
content,
@@ -46,3 +62,17 @@ for (const probe of MANDATORY_STARTUP_PROBES) {
4662
);
4763
});
4864
}
65+
66+
test('agent setup contract rejects a rule that defers the open-first instruction', async () => {
67+
const content = await readFile(AGENT_SETUP, 'utf8');
68+
const openFirstLine = content.split('\n').find((line) => line.startsWith(OPEN_FIRST));
69+
assert.ok(openFirstLine);
70+
const deferred = content
71+
.replace(`${openFirstLine}\n`, '')
72+
.replace(
73+
'Keep mutating commands against one session serial.\n',
74+
`Keep mutating commands against one session serial.\n${openFirstLine}\n`,
75+
);
76+
assert.notEqual(deferred, content);
77+
assert.throws(() => assertOpenFirstSetup(deferred), /right after its scope line/);
78+
});

‎website/docs/docs/agent-setup.md‎

Lines changed: 36 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,26 @@ Skills come from the GitHub repository, not the npm package. The [agent-device s
2929

3030
## Recommended agent rule
3131

32-
Add this as a project rule or custom instruction if your agent client supports one:
32+
Add this rule to your agent client's project rules or custom instructions. [Set up your client](#set-up-your-agent-client) shows where the file goes for each client.
3333

3434
```text
35-
Use agent-device only for app/device automation tasks. For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot. For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`. For exploratory QA, read `agent-device help dogfood`. For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`. For React Native JavaScript heap growth, heap snapshots, allocation hotspots, or retained-object leaks, read `agent-device help cdp`. For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
35+
Use agent-device only for app/device automation tasks.
36+
For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot.
37+
For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`.
38+
For exploratory QA, read `agent-device help dogfood`.
39+
For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`.
40+
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
41+
For React Native JavaScript heap growth, heap snapshots, allocation hotspots, or retained-object leaks, read `agent-device help cdp`.
42+
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
3643
37-
Use MCP tools or the CLI in the integrated terminal. If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the command the same way the user would from a normal terminal session and run that absolute path instead. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`. Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version. MCP exposes structured tools backed by the agent-device client; it does not expose generic shell execution. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close` where the target supports capture and selectors; otherwise follow target-specific help. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
44+
Use MCP tools or the CLI in the integrated terminal.
45+
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the command the same way the user would from a normal terminal session and run that absolute path instead. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`.
46+
Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version.
47+
MCP exposes structured tools backed by the agent-device client; it does not expose generic shell execution.
48+
Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close` where the target supports capture and selectors; otherwise follow target-specific help.
49+
Use current refs such as `@e3` for exploration and selectors for durable replay.
50+
Keep mutating commands against one session serial.
51+
Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
3852
```
3953

4054
## MCP server
@@ -81,13 +95,26 @@ In MCP registries, the server is listed as `io.github.callstack/agent-device` (n
8195

8296
Some agent clients run commands with a different `PATH` than your normal shell, so a global install that works in your terminal can be missing in the agent's terminal or MCP server. Run `command -v agent-device` in your own terminal and give the agent that absolute path, or use it as the MCP server `command`. If the path is under a version manager or a package-manager global bin directory, check your shell startup files for how that directory gets on `PATH`; the agent client may not load them.
8397

98+
## Set up your agent client
99+
100+
Each client reads the [recommended agent rule](#recommended-agent-rule) from its own location:
101+
102+
| Client | Where the rule goes | Client-specific wrapper |
103+
| --- | --- | --- |
104+
| Cursor | `.cursor/rules/agent-device.mdc` | Required `.mdc` frontmatter above the rule |
105+
| Codex | `AGENTS.md` in the project root | None |
106+
| Claude Code | `CLAUDE.md` in the project root | None; an `# agent-device` heading keeps it separate from other instructions |
107+
| Windsurf, Cline, Goose, and others | The client's project rules or custom instructions | Whatever the client requires for a rules file |
108+
109+
The sections below cover each client, including MCP setup.
110+
84111
## Cursor
85112

86113
Cursor can use the CLI or MCP tools. Use the CLI when you want every command visible in the terminal. Add MCP when you want Cursor Agent to discover `agent-device` tools directly from chat.
87114

88115
### Cursor: use the CLI
89116

90-
Create a project rule:
117+
Create the rule file with the frontmatter Cursor requires:
91118

92119
```bash
93120
mkdir -p .cursor/rules
@@ -97,23 +124,11 @@ description: Use agent-device for app and device automation
97124
alwaysApply: true
98125
---
99126
100-
Use agent-device only for app/device automation tasks.
101-
For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot.
102-
For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`.
103-
For exploratory QA, read `agent-device help dogfood`.
104-
For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`.
105-
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
106-
For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help cdp`.
107-
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
108-
109-
Use the CLI in Cursor's integrated terminal.
110-
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the absolute binary path instead of using `npx -y agent-device@latest`.
111-
Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close` where supported; otherwise follow target-specific help.
112-
Keep mutating commands against one session serial.
127+
REPLACE THIS LINE with the recommended agent rule from https://oss.callstack.com/agent-device/docs/agent-setup#recommended-agent-rule
113128
EOF
114129
```
115130

116-
Then ask Cursor Agent to run:
131+
Open `.cursor/rules/agent-device.mdc` and replace the placeholder line with the [recommended agent rule](#recommended-agent-rule). Then ask Cursor Agent to run:
117132

118133
```bash
119134
agent-device open <app-or-url> --platform ios --foreground
@@ -158,7 +173,7 @@ If the MCP server fails to start because Cursor can't find the global binary, us
158173

159174
## Codex
160175

161-
Put the [recommended rule](#recommended-agent-rule) in `AGENTS.md` or the project instructions, then let Codex run `agent-device` in the terminal:
176+
Paste the [recommended agent rule](#recommended-agent-rule) into `AGENTS.md` in the project root, or into the project instructions, then let Codex run `agent-device` in the terminal:
162177

163178
```bash
164179
agent-device open <app-or-url> --platform ios --foreground
@@ -174,27 +189,7 @@ Claude Code can use `agent-device` from the terminal or from the VS Code extensi
174189

175190
### Claude Code: use the CLI
176191

177-
Put this in `CLAUDE.md`:
178-
179-
```bash
180-
cat > CLAUDE.md <<'EOF'
181-
# agent-device
182-
183-
Use agent-device only for app/device automation tasks.
184-
For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot.
185-
For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`.
186-
For exploratory QA, read `agent-device help dogfood`.
187-
For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`.
188-
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
189-
For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help cdp`.
190-
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
191-
192-
Use the CLI in the integrated terminal.
193-
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the absolute binary path instead of using `npx -y agent-device@latest`.
194-
Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close` where supported; otherwise follow target-specific help.
195-
Keep mutating commands against one session serial.
196-
EOF
197-
```
192+
Open `CLAUDE.md` in the project root, creating it if it doesn't exist. Add an `# agent-device` heading and paste the [recommended agent rule](#recommended-agent-rule) below it. Keep any instructions already in the file.
198193

199194
Then ask Claude Code to run:
200195

@@ -242,7 +237,7 @@ You can still run CLI commands in the integrated terminal for long-running or ma
242237

243238
If the client supports `mcpServers`, use the [MCP server](#mcp-server) configuration, then tell the agent to use MCP tools or terminal CLI commands for device work.
244239

245-
If the client supports project rules or custom instructions, add the [recommended agent rule](#recommended-agent-rule). If it doesn't, ask the agent to open the requested app and continue from the initial interactive snapshot; point it to a help topic only when the task is specialized or a command is unclear.
240+
If the client supports project rules or custom instructions, paste the [recommended agent rule](#recommended-agent-rule) there, inside any wrapper the client requires for a rules file. If it doesn't, ask the agent to open the requested app and continue from the initial interactive snapshot; point it to a help topic only when the task is specialized or a command is unclear.
246241

247242
## Related pages
248243

0 commit comments

Comments
 (0)