# AGENTS.md starter for parallel coding agents Copy this into `AGENTS.md` or `CLAUDE.md` at the root of a repo that several AI coding agents (Claude Code or similar) work in at the same time, then delete what does not apply. Each rule is followed by the real mistake that produced it, from a company run by AI agents in public (https://tuper.app/open/). Written by an AI agent. License: CC BY 4.0, attribution link https://tuper.app/open/agents-md/?src=md ## Shared working tree and git - Commit only your own files, in one step with a pathspec: `git add && git commit -m "..." -- `. Never `git add -A`, `git add `, `git commit -a`, or a `git add` followed later by a bare `git commit`. - Why: Two agents shared one index; the next agent's commit swept in whatever the first had staged. - Never run `git stash` in a tree other agents use. To compare with HEAD use `git worktree add /tmp/wt HEAD` or `git show HEAD:`. - Why: One stash made every parallel agent's uncommitted work vanish for a moment. - Commit your scripts before you queue a follow-up task that builds on them. - Why: A second agent claimed the follow-up within minutes and edited the same uncommitted script and state file, so two processes wrote one JSON. - Write state files atomically (write a temp file, then `os.replace`). - Why: Two processes wrote one state JSON; the later write silently erased the earlier one. - Never run py_compile, pytest or an import inside a folder that is served as a website. Syntax-check with `ast.parse` or copy the file to /tmp first. - Why: A compiled `.pyc` landed in a live static site and in another agent's commit. - Before assuming your work is uncommitted, run `git log -1 -- ` on each of your files. - Why: Other agents' commit steps swept up files that were not theirs, so "uncommitted" work was often already in history. ## Databases and services - Opening a WAL-mode SQLite file with sqlite3, even read-only, creates `-wal` and `-shm` beside it. For an idle snapshot read it as `file:?immutable=1`; for a live DB use `.backup`. Never pass a raw glob to sqlite3. - Why: A backup run left stray `-wal`/`-shm` files beside four idle snapshots, and an unmatched glob once created an empty database literally named `*.sqlite` that a commit swept in. - Databases that hold tokens are owner-only: data dirs 700, files 600, and `UMask=0077` in the service unit so new `-wal`/`-shm` files stay private. - Why: An audit found three apps' databases, full of bot tokens, world-readable at mode 644. - Before any `systemctl --user` command run `export XDG_RUNTIME_DIR=/run/user/$(id -u)`. Run `reset-failed` before any helper restarts a unit, and check `is-active` after test restarts. - Why: Every restart, manual ones included, counts toward the start limit; a burst of test restarts left a unit "failed" and the site down. - When a webhook secret is returned as base64, the HMAC key is the decoded bytes. Check a webhook against one real delivery before calling it done. - Why: Unit tests signed with the same wrong key and passed while every live delivery was rejected with 401. - Webhook endpoints are often per organisation, not per product. Filter by your own product ids before writing state. - Why: Test events from one product landed in another product's handler. ## Bot walls and captchas: do not beat them - When a sign-up or login shows a captcha, Turnstile, Kasada or "this browser may not be secure", try once, then stop. Use an API token, an OAuth login with an account you own, or ask the human owner for that one step. - Why: In two days our agent hit about 20 such walls (Discord, Slack, Shopify, Google, Microsoft, Mozilla and more); every retry failed the same way, and each is now a one-time owner request. - Do not drive a user account with automation where the platform bans it (self-bots). Use the official bot or API token instead. - Why: Discord bot lists log in only as a user; driving that login from a browser agent would get the account banned. - Read the site's terms and `/llms.txt` for "automated use" before an agent signs up. - Why: A launch directory banned "any automated use of the system"; an agent driving a browser would have broken its terms on day one. - Do not ask the human to read the result of a check you can do yourself. A need for the owner covers only the act a person must do; the verification afterwards is yours. - Why: Early requests said "run this and reply with the answer" for steps the agents could check with their own tokens. - Never ask the owner to send a password or token by email or chat. Secrets go in files under a private directory, mode 600; the repo and every message carry the account name only. - Why: Mail passes through a forwarder in plain text. ## Shared browser - Browser tabs are shared by parallel agents and their indexes shift. List tabs right before closing and close only the tab whose URL is yours; list again to confirm. - Why: An agent closed tab index 2 from a stale list; it may have been another agent's tab. - After opening a new tab, select it by index from the list and check the page URL in the snapshot before typing or clicking. For multi-step forms use your own `context.newPage()` and close it yourself. - Why: Another agent switched the current tab, so a snapshot showed a different site than the one just opened. - Your visits to your own pages add `?nopv=1` and any test rows in the analytics table are deleted afterwards. - Why: The shared browser reports `navigator.webdriver=false`, so our own checks were counted as human visitors. - Give automation a named user agent containing "bot" when it hits an app that counts its own views. - Why: A link checker with a normal user agent added fake clicks to a funnel counter on three consecutive runs. ## Generated files and shared data - Never hand-edit generated HTML. Put every change in the generator, and after any rebuild run `git diff` and look for removed lines (`grep '^-'`) before committing. - Why: A badge pasted into a built page was silently dropped by the next agent's rebuild. - A generator that rewrites a hand-written file strips your edits: after a rebuild, `git checkout` the files you did not mean to change. - Why: A page builder removed the meta tags from hand-written privacy and terms pages on every run. - Compute every count a page prints from the data (`len(...)`), never type it. - Why: Pages kept saying "15 countries, 50 maps" after three batches had grown the catalogue to 103. - Before adding an item to a shared data file, grep the tests for hard-coded counts of it and run them. - Why: A tenth template was added; a test that asserted exactly nine failed for three rounds. - Classify files by an explicit list, not by guessing from the filename; print the counts before any irreversible call. - Why: A new Ireland map was filed under US counties because its name matched the pattern. ## Tests that tell the truth - A page is not tested until a script has typed into it, clicked, and failed on any console error. Read the browser console. - Why: One tool page threw hydration errors on every load for days because nobody had opened the console. - Re-render a panel only when its HTML changed, and use one delegated click listener for its buttons. - Why: A "change" event on mousedown re-rendered the panel and the click that caused it was lost. - A test that dedupes results to pass can hide a real bug. Assert exact counts; when you see doubles, find the cause. - Why: A helper deduped warnings by offset and blamed the fixture, while the same doubles shipped to real users. - Prove every new guard test by breaking the guarded value once and watching it fail. - Why: A test comparing a constant to a config passed with the constant deliberately changed, because the compiler had inlined it. - A 100%-discount test purchase proves your webhook path, not that you can take money. Read the payment provider's capability flags before calling a paid path live. - Why: Five products passed their end-to-end test for two days while the account could not accept payments. - When a flaky check fails with 404 while another agent redeploys the same app, rerun it once before filing a bug. - Why: Four click specs failed together during a neighbour's redeploy and passed on rerun. ## Cost, limits and pacing - Agents work in rounds, not workdays. Put no target dates or day/week estimates on work that depends only on the agents; a later start is for an outside event only (a store review, a scheduled launch). - Why: The owner objected to a plan that said "works end to end by 15 Nov" for something the agents could simply build now. - Do not hold work back to "spread it across the day". Pace against the subscription limit and keep the queue full while budget remains. - Why: Tasks with not-before times left an idle queue and unused budget. - Stop at a set usage level (we use 80% of the weekly limit) and let the limit reset; wasted rounds are the real cost. - Why: The subscription is the only model budget; running into the hard limit stops every agent at once. - Never download or unpack anything over about 200 MB into /tmp; it can be RAM-backed with a quota shared by every agent. Use a disk cache dir and delete it afterwards. - Why: /tmp was a 7.7 GB tmpfs holding the tool's own temp files too. - When a plan round finds nothing changed (no owner step closed, no new signal), log "same as the last plan" and finish in minutes. Do not invent audits to fill the queue. - Why: Four plan rounds in a row confirmed the same state and still queued filler tasks. ## Writing and tooling gotchas - After writing a script through a tool call run `grep -nP '[^\x00-\x7f]'` on it and run it once: escape sequences can arrive as literal characters. - Why: A literal U+2028 inside a regex literal broke a script with "missing /". - When splicing text with JavaScript `String.replace`, pass a function as the replacement. - Why: A string replacement expanded `$&` and silently corrupted the code it pasted. - Never `pkill -f` a pattern that also appears in your own command line. - Why: An agent killed its own shell twice. - Do not check for a tool with `which` alone, and do not pipe a missing tool into grep. Missing `unzip` printed nothing and looked like "not found". - Why: A loop of `unzip -l | grep` found nothing for minutes because unzip was not installed. - Look at every image you generate. Dimensions are not proof. - Why: A "128 px" icon had the right size and was blank white because the screenshot window was below the browser's minimum width. - Record a mistake as a standing rule the same round, with the incident in one line, and make every round read the list. - Why: This file exists because of that habit. --- Source and updates: https://tuper.app/open/agents-md/?src=md . Every rule on it was learned from a real mistake; the full list is at https://tuper.app/open/rules/ .