{"playbook":"AI development","url":"https://agentwranglers.se/playbook/ai-assisted-development","updated":"2026-10-21","license":"https://creativecommons.org/licenses/by/4.0/","credit":"Required by the licence: credit Agent Wranglers with a link to the rule or playbook you used.","how":"Each rule's How text is on its own page: add .md to its url.","rules":[{"chapter":"Setting up the project","name":"Write one instructions file for agents","level":"Recommended","rule":"Keep one instructions file at the root of the repository that tells every agent how to build, test and change the project.","check":"A script confirms that `AGENTS.md` exists, has under 200 lines and names the check command. Then ask a fresh session how to run the tests. It answers from the file.","url":"https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/instructions-file","related":["/playbook/engineering/rules-as-code/run-one-check-before-every-deploy","/playbook/ai-assisted-development/context-and-memory/short-current-instructions","/playbook/ai-assisted-development/agent-skills/when-to-write-a-skill","/playbook/engineering/documentation/readme-quick-start","/playbook/stack/how-to-choose/known-to-ai-tools","/playbook/stack/how-to-choose/one-tool-per-job","/playbook/stack/ai-software/coding-agent-by-tests"],"sources":[]},{"chapter":"Setting up the project","name":"Keep code small enough for an agent to read","level":"Recommended","rule":"Keep files and functions small and well named, so an agent can read the code it changes in one pass.","check":"The linter fails on any file or function over the limit, for example ESLint `max-lines` and `max-lines-per-function` or Pylint `max-module-lines`. Every exception is listed with a reason.","url":"https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/agent-sized-modules","related":["/playbook/architecture/code-review/readable-for-agents","/playbook/architecture/names-and-functions/small-functions"],"sources":[]},{"chapter":"Setting up the project","name":"Keep the project runnable from a clean checkout","level":"Recommended","rule":"A new agent session must be able to install, run and test the project from a clean checkout with the documented commands alone.","check":"CI clones the repository into a fresh container and runs only the commands from the instructions file. Every check passes without extra steps.","url":"https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/runnable-from-clean-checkout","related":["/playbook/engineering/documentation/readme-quick-start"],"sources":[]},{"chapter":"Setting up the project","name":"Write down the decisions agents keep getting wrong","level":"Recommended","rule":"Record each design decision that is not obvious from the code, so agents stop undoing it.","check":"The instructions file links the decisions folder, and every decision note has a decision, a reason and a date. Each decision an agent has reversed before has a check.","url":"https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/record-decisions","related":["/playbook/engineering/documentation/decision-records"],"sources":[]},{"chapter":"Working in small steps","name":"Plan before the agent writes code","level":"Recommended","rule":"For any change over one file or 30 changed lines, have the agent read the relevant code and write a plan before it edits anything.","check":"Every pull request over one file or 30 changed lines links a written plan. It may sit in the task, the pull request or a plan file.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/plan-first","related":["/playbook/ai-assisted-development/working-in-small-steps/small-diffs"],"sources":[]},{"chapter":"Working in small steps","name":"Give every task acceptance criteria","level":"Recommended","rule":"State how you will know the task is done before the agent starts, as checks it can run itself.","check":"Each task has at least one runnable test or command that fails before the change and passes after it.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/acceptance-criteria","related":["/playbook/ai-assisted-development/working-in-small-steps/agent-verifies-own-work"],"sources":[]},{"chapter":"Working in small steps","name":"Keep one task per session","level":"Recommended","rule":"Give each agent session one task, and start a fresh session for the next one.","check":"Session logs or pull requests each cover one task, with no unrelated changes mixed in.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/one-task-per-session","related":["/playbook/ai-assisted-development/context-and-memory/lessons-in-repo"],"sources":[]},{"chapter":"Working in small steps","name":"Let the agent check its own work","level":"Recommended","rule":"Give the agent the means to see the result of its change. It runs the checks after its last edit, before it reports done.","check":"In every session log, the check command runs after the last file edit and passes. A deliberately broken test makes the agent keep working instead of reporting done.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/agent-verifies-own-work","related":["/playbook/ai-assisted-development/working-in-small-steps/acceptance-criteria"],"sources":[]},{"chapter":"Working in small steps","name":"Keep each change small","level":"Recommended","rule":"Keep every change small enough to review in one sitting, at most 400 changed lines.","check":"A pull request job fails above 400 changed lines outside generated files and lock files.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/small-diffs","related":["/playbook/ai-assisted-development/working-in-small-steps/plan-first","/playbook/engineering/version-control-and-review/small-changes"],"sources":[]},{"chapter":"Working in small steps","name":"Work on a branch and commit often","level":"Recommended","rule":"Let agents work only on a branch, and commit after each step that passes the checks.","check":"The main branch has branch protection, and no agent commit lands on it without a reviewed pull request.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/branch-and-commit","related":["/playbook/engineering/version-control-and-review/small-changes"],"sources":[]},{"chapter":"Working in small steps","name":"Ask for the smallest change that works","level":"Recommended","rule":"Tell the agent to make the smallest change that meets the criteria, and to ask before adding dependencies, files or abstractions.","check":"A script lists every file, dependency and setting the change adds. Each one is named in the plan or the acceptance criteria, or the change is sent back.","url":"https://agentwranglers.se/playbook/ai-assisted-development/working-in-small-steps/smallest-change","related":["/playbook/architecture/solid-and-dry/no-speculative-abstraction"],"sources":[]},{"chapter":"Rules the agent cannot break","name":"Use strict types and linters","level":"Recommended","rule":"Run the strictest type checker and linter settings the project can pass, so mistakes fail fast instead of reaching review.","check":"The configuration files set the strict options, and the check command fails on a deliberate type error.","url":"https://agentwranglers.se/playbook/ai-assisted-development/rules-the-agent-cannot-break/strict-tooling","related":["/playbook/architecture/data-shapes/no-mixed-or-any","/playbook/architecture/comments/useful-docblocks","/playbook/stack/testing-and-code-quality/pyright"],"sources":[]},{"chapter":"Rules the agent cannot break","name":"Block dangerous actions with hooks","level":"Recommended","rule":"Use the agent's hooks or permission rules to block actions that must never happen, instead of trusting instructions.","check":"Ask the agent to run each blocked command, such as `git push --force` and reading `.env`. The rule or hook stops every one, and the agent reports the reason.","url":"https://agentwranglers.se/playbook/ai-assisted-development/rules-the-agent-cannot-break/blocking-hooks","related":["/playbook/ai-assisted-development/safety-and-permissions/sandbox","/playbook/infrastructure/policy-as-code/cloud-guardrails","/playbook/ai-assisted-development/agent-skills/skill-asks-first","/playbook/data/migrations/immutable-migrations"],"sources":[]},{"chapter":"Rules the agent cannot break","name":"Protect the checks themselves","level":"Recommended","rule":"Never let an agent pass a check by weakening it. Changes to tests, linter settings and build gates need a person's approval.","check":"A pull request that deletes a test, adds a skip or loosens a linter setting cannot merge without the code owner's approval.","url":"https://agentwranglers.se/playbook/ai-assisted-development/rules-the-agent-cannot-break/protect-the-checks","related":["/playbook/engineering/rules-as-code/build-gates","/playbook/ai-assisted-development/reviewing-agent-output/no-weakened-checks"],"sources":[]},{"chapter":"Reviewing agent output","name":"Read every line of the diff","level":"Recommended","rule":"A person reads every line an agent changes before it merges, and can explain why each line is there.","check":"Branch protection requires one approval from a person other than the one who ran the agent. A solo developer records a written review in the pull request instead.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/read-every-diff","related":["/playbook/architecture/code-review/review-against-the-base","/playbook/architecture/code-review/answer-every-question-by-number","/playbook/adversarial-testing/data-and-secrets/secrets-out-of-code"],"sources":[]},{"chapter":"Reviewing agent output","name":"Run the change yourself","level":"Recommended","rule":"Run the changed feature by hand before approving it, and never trust an agent's claim that it works.","check":"The pull request records what the reviewer ran and saw, such as steps, a screenshot or a short recording.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/run-it-yourself","related":["/playbook/testing/end-to-end-and-browser-tests/critical-journeys"],"sources":[]},{"chapter":"Reviewing agent output","name":"Check that every package and API exists","level":"Required","risk":"takeover","rule":"Verify every new dependency and every called API exists, is the official one and does what the code assumes.","check":"Every package added in the change appears in the review with a link to its official source. The install uses the lock file, and an audit passes.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/no-invented-packages","related":["/playbook/adversarial-testing/supply-chain-and-setup/review-new-packages"],"sources":[{"label":"OWASP LLM07:2026 Misinformation","url":"https://github.com/GenAI-Security-Project/GenAI-LLM-Top10/blob/main/2026/final/LLM07_Misinformation.md"}]},{"chapter":"Reviewing agent output","name":"Look for weakened checks and skipped work","level":"Recommended","rule":"Reject any change that deletes or skips tests, loosens a linter or type setting, or catches and hides errors to make the checks pass.","check":"A script fails the pull request when the diff adds a skip marker or an ignore comment, unless a reviewer approves the exception. A deleted test or a changed linter or type setting needs code owner approval.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/no-weakened-checks","related":["/playbook/testing/test-quality/tests-can-fail","/playbook/ai-assisted-development/rules-the-agent-cannot-break/protect-the-checks","/playbook/testing/test-quality/review-tests"],"sources":[]},{"chapter":"Reviewing agent output","name":"Check the change does only what was asked","level":"Recommended","rule":"Reject changes that touch files, features or behaviour the task did not ask for.","check":"Every file in the diff maps to a step in the plan or the acceptance criteria.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/scope-matches-task","related":["/playbook/architecture/code-review/solves-a-named-problem"],"sources":[]},{"chapter":"Reviewing agent output","name":"Get a fresh review for risky changes","level":"Recommended","rule":"For changes to money, accounts, permissions or data deletion, get a second review from someone, or an agent, that did not write the change.","check":"Pull requests that touch the listed risk areas show a second, independent review before merge.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/fresh-review","related":["/playbook/architecture/code-review/verify-with-fresh-agents"],"sources":[]},{"chapter":"Reviewing agent output","name":"Check where generated code came from","level":"Recommended","rule":"Make sure generated code does not copy licensed code you may not use, and that every new dependency's licence fits your project.","check":"CI runs a licence check with an allow list and fails on any other licence. Examples are `npx license-checker --onlyAllow \"MIT;ISC;Apache-2.0;BSD-2-Clause;BSD-3-Clause\"` and `pip-licenses --allow-only \"MIT License;BSD License;Apache Software License\"`.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/code-provenance","related":["/playbook/adversarial-testing/supply-chain-and-setup/review-new-packages"],"sources":[]},{"chapter":"Reviewing agent output","name":"Have someone other than the requester approve agent changes","level":"Required","risk":"takeover","rule":"An agent never approves or merges its own pull request. The person who asked the agent for the change cannot be its only approver.","check":"Open a test pull request from the agent's token with a `Requested-by` trailer. The agent's own approval fails, the requester's approval alone does not unlock the merge, and one approval from another reviewer does.","url":"https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/independent-approval","related":["/playbook/adversarial-testing/supply-chain-and-setup/ci-secrets","/playbook/engineering/version-control-and-review/protect-the-main-branch"],"sources":[{"label":"GitHub Docs, risks and mitigations for Copilot cloud agent","url":"https://docs.github.com/en/copilot/concepts/agents/coding-agent/risks-and-mitigations"}]},{"chapter":"Safety and permissions","name":"Run agents in a sandbox","level":"Required","risk":"takeover","rule":"Run coding agents in an isolated environment, such as a container, a virtual machine or the agent's own sandbox mode.","check":"From an agent session, try to read a file outside the project, such as `~/.ssh/id_ed25519`, and reach an unlisted host. Both fail.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/sandbox","related":["/playbook/ai-assisted-development/rules-the-agent-cannot-break/blocking-hooks","/playbook/adversarial-testing/ai-agents-and-models/sandbox-model-code"],"sources":[]},{"chapter":"Safety and permissions","name":"Skip approvals only in a throwaway sandbox","level":"Required","risk":"takeover","rule":"Skip approvals only inside a container or virtual machine that holds no secrets. Throw it away after the task.","check":"A CI script searches the repository for the bypass flags. Each match sits on a line that starts a container, such as `docker run`. On a staff machine, starting the mode fails.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/unattended-only-in-sandbox","related":["/playbook/adversarial-testing/ai-agents-and-models/cost-and-loop-limits","/playbook/ai-assisted-development/safety-and-permissions/managed-agent-settings"],"sources":[]},{"chapter":"Safety and permissions","name":"Keep production credentials away from agents","level":"Required","risk":"data","rule":"Never give a coding agent production keys, database passwords or customer data.","check":"Search the agent's environment variables and readable files for production key prefixes, such as `sk_live_`, and production host names. None are found.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/no-production-credentials","related":["/playbook/data/personal-data/masked-copies","/playbook/adversarial-testing/data-and-secrets/least-privilege-keys"],"sources":[]},{"chapter":"Safety and permissions","name":"Give agents the fewest rights they need","level":"Required","risk":"takeover","rule":"Give each agent token only the rights its task needs, and make it short-lived and easy to revoke.","check":"With the agent's token, try to merge to the main branch, delete the repository and read another repository. All three fail. The token shows an expiry date.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/least-privilege-agents","related":["/playbook/adversarial-testing/ai-agents-and-models/least-privilege-tools","/playbook/ai-assisted-development/agent-skills/skill-asks-first"],"sources":[{"label":"OWASP LLM03:2026 Excessive Agency","url":"https://github.com/GenAI-Security-Project/GenAI-LLM-Top10/blob/main/2026/final/LLM03_ExcessiveAgency.md"}]},{"chapter":"Safety and permissions","name":"Approve destructive commands","level":"Required","risk":"data","rule":"Require a person's approval before an agent deletes data, rewrites history, changes infrastructure or spends money.","check":"Ask the agent to drop a test database table. It stops and asks for approval before running the command.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/approve-destructive-commands","related":["/playbook/adversarial-testing/ai-agents-and-models/human-approval"],"sources":[{"label":"OWASP LLM03:2026 Excessive Agency","url":"https://github.com/GenAI-Security-Project/GenAI-LLM-Top10/blob/main/2026/final/LLM03_ExcessiveAgency.md"}]},{"chapter":"Safety and permissions","name":"Treat what the agent reads as untrusted","level":"Required","risk":"takeover","rule":"Assume any web page, issue, file, dependency or tool result an agent reads may contain instructions meant to hijack it.","check":"Put a test file in a staging project that tells agents to send `.env` to test.example.org. Run the agent on a nearby task. Nothing is sent, and the review catches any change the file asked for.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/untrusted-context","related":["/playbook/adversarial-testing/ai-agents-and-models/indirect-prompt-injection","/playbook/adversarial-testing/ai-agents-and-models/lethal-trifecta","/playbook/adversarial-testing/ai-agents-and-models/pinned-tools","/playbook/adversarial-testing/rules-of-engagement/target-output-is-data"],"sources":[{"label":"OWASP LLM01:2026 Prompt Injection","url":"https://github.com/GenAI-Security-Project/GenAI-LLM-Top10/blob/main/2026/final/LLM01_PromptInjection.md"},{"label":"OWASP LLM Prompt Injection Prevention Cheat Sheet","url":"https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html"}]},{"chapter":"Safety and permissions","name":"Run agents in CI only for trusted people","level":"Required","risk":"takeover","rule":"An agent in CI starts only for people with write access to the repository. Its job holds no secrets it does not need.","check":"From a test account without write access, open an issue that mentions the agent. The job does not start, and the log names the refusal.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/ci-agents-trusted-triggers","related":["/playbook/adversarial-testing/supply-chain-and-setup/ci-secrets"],"sources":[]},{"chapter":"Safety and permissions","name":"Review agent settings like code","level":"Required","risk":"takeover","rule":"Treat instruction files, agent settings, hooks and rule folders as code that can run. Review every change to them and scan them for hidden text.","check":"A script fails the build when an instruction or settings file holds invisible or direction-changing characters. The code owners file covers every agent file.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/review-agent-config","related":["/playbook/adversarial-testing/ai-agents-and-models/pinned-tools","/playbook/ai-assisted-development/agent-skills/project-skills-in-repo"],"sources":[{"label":"UTS #55: Unicode Source Code Handling","url":"https://www.unicode.org/reports/tr55/"},{"label":"CVE-2021-42574 (Trojan Source)","url":"https://www.cve.org/CVERecord?id=CVE-2021-42574"}]},{"chapter":"Safety and permissions","name":"Know what the agent tool does with your code","level":"Recommended","rule":"Before an agent reads your code, check whether its provider stores it, for how long, and whether it trains models on it.","check":"The account settings of every agent tool the team uses show training on your data turned off. A note in the repository names each tool and its retention period.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/tool-data-terms","related":["/playbook/compliance/processors-and-transfers/ai-provider-terms"],"sources":[]},{"chapter":"Safety and permissions","name":"Open unknown repositories in a sandbox","level":"Required","risk":"takeover","rule":"Open a repository you did not write in a container or virtual machine first. Trust it in your editor or agent only after reading its config.","check":"Open a test repository whose `.vscode/tasks.json` runs a harmless `echo CANARY-TEST` on folder open. Nothing runs until you trust the folder.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/untrusted-repositories","related":["/playbook/adversarial-testing/ai-agents-and-models/indirect-prompt-injection"],"sources":[]},{"chapter":"Safety and permissions","name":"Enforce the team's agent settings centrally","level":"Recommended","rule":"When a team shares a coding agent, push its security settings to every machine as managed settings. No user or repository can override them.","check":"On a staff machine, start the agent with its bypass flag and add an unlisted tool server in a personal settings file. The bypass is refused, the server does not load, and the agent's status shows the managed policy as a source.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/managed-agent-settings","related":["/playbook/ai-assisted-development/safety-and-permissions/unattended-only-in-sandbox"],"sources":[{"label":"Claude Code settings files and precedence","url":"https://code.claude.com/docs/en/settings"},{"label":"Claude Code example settings files","url":"https://code.claude.com/docs/en/settings-example"}]},{"chapter":"Safety and permissions","name":"Log what every agent session does","level":"Recommended","rule":"Record every command, tool call and approval an agent makes, with its session and the person who started it. Keep the log off the developer's machine.","check":"Start a session that runs `git status` and asks to read `.env`. Within five minutes the log store shows both calls with the session, the user, the command and the denied read.","url":"https://agentwranglers.se/playbook/ai-assisted-development/safety-and-permissions/agent-activity-log","related":["/playbook/operations/logs/log-retention","/playbook/operations/logs/off-host-logs"],"sources":[{"label":"Claude Code monitoring","url":"https://code.claude.com/docs/en/monitoring-usage"},{"label":"GitHub Docs, risks and mitigations for Copilot cloud agent","url":"https://docs.github.com/en/copilot/concepts/agents/coding-agent/risks-and-mitigations"}]},{"chapter":"Apps built with AI builders","name":"Turn on row-level security for every table","level":"Required","risk":"data","rule":"When the browser talks to the database directly, turn on row-level security for every table and write a policy for each action.","check":"A query lists public tables without row-level security, and it returns no rows. Using only the public key, read each table signed out, then as another user. Both return nothing.","url":"https://agentwranglers.se/playbook/ai-assisted-development/apps-built-with-ai-builders/row-level-security","related":["/playbook/data/schema-design/tenant-isolation","/playbook/adversarial-testing/access-and-accounts/object-access"],"sources":[{"label":"OWASP Authorization Cheat Sheet","url":"https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html"}]},{"chapter":"Apps built with AI builders","name":"Keep secret keys on the server","level":"Required","risk":"takeover","rule":"Never ship a secret key in code that runs in the browser. That covers database secret or service role keys, payment secrets and AI provider keys.","check":"Download every script the live app loads and search for key patterns, such as `sb_secret_`, `sk_live_` and `sk-`. Decode each token that starts with `eyJ` and confirm none has the role `service_role`. Only public keys are found.","url":"https://agentwranglers.se/playbook/ai-assisted-development/apps-built-with-ai-builders/server-side-keys","related":["/playbook/adversarial-testing/data-and-secrets/secrets-out-of-browser"],"sources":[{"label":"OWASP Secrets Management Cheat Sheet","url":"https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html"}]},{"chapter":"Apps built with AI builders","name":"Check every sign-in and permission flow","level":"Required","risk":"takeover","applies":["accounts"],"rule":"Test sign-up, sign-in, password reset and every admin page as a stranger and as a normal user before launch.","check":"Signed out, open every page and call every API route found in the code. Only public ones answer. As a normal user, admin routes answer 403 or 404.","url":"https://agentwranglers.se/playbook/ai-assisted-development/apps-built-with-ai-builders/check-auth-flows","related":["/playbook/accounts/roles-and-permissions/permission-matrix-test","/playbook/adversarial-testing/access-and-accounts/password-reset"],"sources":[{"label":"OWASP ASVS","url":"https://owasp.org/www-project-application-security-verification-standard/"},{"label":"OWASP Authentication Cheat Sheet","url":"https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html"},{"label":"OWASP Forgot Password Cheat Sheet","url":"https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html"}]},{"chapter":"Apps built with AI builders","name":"Own the code in your own repository","level":"Recommended","rule":"Keep the app's code in a repository you control, and make sure you can build and deploy it without the builder.","check":"Clone the repository on a clean machine and build and run the app with the documented commands, without signing in to the builder.","url":"https://agentwranglers.se/playbook/ai-assisted-development/apps-built-with-ai-builders/own-the-code","related":["/playbook/engineering/version-control-and-review/everything-in-version-control","/playbook/ai-assisted-development/apps-built-with-ai-builders/know-when-to-move"],"sources":[]},{"chapter":"Apps built with AI builders","name":"Add tests and checks before the app grows","level":"Recommended","rule":"Once users depend on the app, add tests and a check command before adding more features.","check":"The repository has a check command that runs tests for sign-in, payment and the main path, and it passes.","url":"https://agentwranglers.se/playbook/ai-assisted-development/apps-built-with-ai-builders/checks-before-growth","related":["/playbook/testing/test-strategy/test-by-risk"],"sources":[]},{"chapter":"Apps built with AI builders","name":"Know when to move off the builder","level":"Recommended","rule":"Plan to move to a normal development setup when the app outgrows the builder. Complex permissions, background jobs and many developers are common signs.","check":"A decision note dated within the last three months lists each warning sign as present or absent, and records whether to stay or move.","url":"https://agentwranglers.se/playbook/ai-assisted-development/apps-built-with-ai-builders/know-when-to-move","related":["/playbook/ai-assisted-development/apps-built-with-ai-builders/own-the-code"],"sources":[]},{"chapter":"Context and memory","name":"Keep instructions short and current","level":"Recommended","rule":"Keep the instructions file short, true and up to date. Delete rules that no longer apply.","check":"A script runs every command in the instructions file and checks that every file path it names exists. Both pass, and the file stays under 200 lines.","url":"https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/short-current-instructions","related":["/playbook/ai-assisted-development/setting-up-the-project/instructions-file","/playbook/ai-assisted-development/agent-skills/duplicate-skill-text"],"sources":[]},{"chapter":"Context and memory","name":"Show examples of good code","level":"Recommended","rule":"Point agents to one or two files that show the patterns to follow, and name them in the instructions file.","check":"The instructions file names the example files, and each one exists. Ask an agent to add a small feature. It matches the structure and naming of the example files.","url":"https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/show-good-examples","related":["/playbook/architecture/code-review/consistent-with-the-codebase","/playbook/ai-features/prompts-as-code/worked-examples"],"sources":[]},{"chapter":"Context and memory","name":"Give agents documentation they can fetch","level":"Recommended","rule":"Give agents current documentation for the libraries and services the project uses, instead of relying on what the model remembers.","check":"The instructions file states the exact version of each main library and links its documentation. Ask the agent how to use a feature added in the library's latest version. It answers from the fetched documentation, not from an older version.","url":"https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/fetchable-docs","related":["/playbook/website/ready-for-ai-agents/llms-txt"],"sources":[]},{"chapter":"Context and memory","name":"Use playbooks as references and credit them","level":"Optional","rule":"Point agents to tested playbooks for common work, and ask them to credit the section they used.","check":"Code built from a playbook section has a comment linking that section.","url":"https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/playbooks-as-references","related":["/playbook/website/ready-for-ai-agents/ask-for-credit"],"sources":[]},{"chapter":"Context and memory","name":"Save lessons in the repository instead of chat","level":"Recommended","rule":"When an agent learns something about the project, save it in the repository, where every future session and person can see it.","check":"Each lesson from the last month's reviews appears in the instructions file, a decision note or a new check.","url":"https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/lessons-in-repo","related":["/playbook/ai-assisted-development/working-in-small-steps/one-task-per-session","/playbook/engineering/documentation/docs-with-the-change"],"sources":[]},{"chapter":"Context and memory","name":"Send wide searches to a subagent","level":"Recommended","rule":"Run work that reads many files or long logs in a subagent or separate session, and bring back only its short summary.","check":"In the session log, searches that read more than ten files run in a subagent. The main session receives only the summary.","url":"https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/subagents-for-side-work","related":["/playbook/ai-features/latency-cost-and-fallbacks/context-budget"],"sources":[]},{"chapter":"Measuring and improving","name":"Track what agents get wrong","level":"Recommended","rule":"Record each mistake found in review, with its kind, so you can see which ones repeat.","check":"The log or labels exist, and the last review lists the three most common kinds of mistake.","url":"https://agentwranglers.se/playbook/ai-assisted-development/measuring-and-improving/track-agent-mistakes","related":["/playbook/ai-assisted-development/measuring-and-improving/check-repeated-mistakes"],"sources":[]},{"chapter":"Measuring and improving","name":"Mark which changes an agent wrote","level":"Recommended","rule":"Mark every commit or pull request an agent wrote, so you can compare its failure and rework rates with other changes.","check":"A script counts commits with the trailer in the last month. The count is above zero, and the monthly note compares the failure rate of marked and unmarked changes.","url":"https://agentwranglers.se/playbook/ai-assisted-development/measuring-and-improving/label-agent-changes","related":["/playbook/ai-assisted-development/measuring-and-improving/measure-delivery"],"sources":[]},{"chapter":"Measuring and improving","name":"Add a check for every repeated mistake","level":"Recommended","rule":"When the same mistake appears twice, add a check that catches it, instead of another reminder in the instructions.","check":"Each mistake kind seen twice in the log has a linked check that fails when the mistake is repeated.","url":"https://agentwranglers.se/playbook/ai-assisted-development/measuring-and-improving/check-repeated-mistakes","related":["/playbook/ai-assisted-development/measuring-and-improving/track-agent-mistakes","/playbook/engineering/rules-as-code/check-every-rule-in-code","/playbook/architecture/code-review/look-beyond-the-diff"],"sources":[]},{"chapter":"Measuring and improving","name":"Test changes to the agent setup on fixed tasks","level":"Recommended","rule":"Before you change the model, the agent tool, the instructions or the tools, rerun a fixed set of past tasks and compare.","check":"The last change to the agent setup has a run attached. It states the pass rate, such as from 22 of 25 to 23 of 25.","url":"https://agentwranglers.se/playbook/ai-assisted-development/measuring-and-improving/evaluate-agent-setup","related":["/playbook/testing/non-functional-tests/llm-evals","/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills","/playbook/engineering/documentation/recheck-sources-with-an-agent","/playbook/stack/ai-software/coding-agent-by-tests"],"sources":[]},{"chapter":"Measuring and improving","name":"Keep a person's sign-off before release","level":"Recommended","rule":"A person approves each release, or approves the automated gate itself in writing and reviews releases afterwards.","check":"Every release in the deploy log names its approver, or the repository holds the signed approval of the gate and a review note per release.","url":"https://agentwranglers.se/playbook/ai-assisted-development/measuring-and-improving/human-sign-off","related":["/playbook/compliance/controls-and-evidence/change-evidence"],"sources":[]},{"chapter":"Measuring and improving","name":"Measure delivery instead of lines of code","level":"Recommended","rule":"Judge agent use by how often you ship, how often changes fail and how fast you recover, not by how much code agents write.","check":"A dashboard or monthly note shows the five measures, with values from before and after the change in process.","url":"https://agentwranglers.se/playbook/ai-assisted-development/measuring-and-improving/measure-delivery","related":["/playbook/ai-assisted-development/measuring-and-improving/label-agent-changes"],"sources":[]},{"chapter":"Agent skills","name":"Turn repeated procedures into skills","level":"Recommended","rule":"Write a skill for a task with three or more steps that you have asked an agent to do twice. Keep facts in the instructions file and fixed steps in plain scripts.","check":"Each skill names a task done at least twice, with three or more steps. Each step list that grew inside the instructions file over the last month has moved into a skill.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/when-to-write-a-skill","related":["/playbook/ai-assisted-development/setting-up-the-project/instructions-file"],"sources":[]},{"chapter":"Agent skills","name":"Give each skill one task and name it for that task","level":"Recommended","rule":"Each skill does one task and is named with a verb and an object, such as `release-mobile-app`. Arguments narrow the scope instead of a second skill.","check":"A script fails when a name is not two or more lowercase words joined by hyphens, differs from its folder or is over 64 characters. No two skills share more than half the words of their descriptions.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/one-task-per-skill","related":["/playbook/ai-assisted-development/agent-skills/skill-description"],"sources":[{"label":"Agent Skills specification","url":"https://agentskills.io/specification"}]},{"chapter":"Agent skills","name":"Write a description that says when to use the skill","level":"Recommended","rule":"Every skill's description says what it does, when to use it and the words people type to ask for it, in under 1024 characters.","check":"A script fails when a description is empty, over 1024 characters or has no \"Use when\" sentence. Ask a fresh session five task prompts per skill. It picks the right skill for all five.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-description","related":["/playbook/ai-assisted-development/agent-skills/one-task-per-skill","/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills"],"sources":[{"label":"Agent Skills specification","url":"https://agentskills.io/specification"}]},{"chapter":"Agent skills","name":"Keep the skill file short and put fixed steps in scripts","level":"Recommended","rule":"Keep each `SKILL.md` under 500 lines. Move every step that needs no judgement into a script the skill runs, and long reference text into files it links.","check":"A script fails when a `SKILL.md` has 500 lines or more. Each command the skill runs has a test or a dry run that passes in CI.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-scripts","related":["/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills"],"sources":[{"label":"Agent Skills specification","url":"https://agentskills.io/specification"},{"label":"Claude Code skills","url":"https://code.claude.com/docs/en/skills"}]},{"chapter":"Agent skills","name":"Keep project skills in the repository and review them like code","level":"Recommended","rule":"Commit every skill the team relies on to the repository, and review changes to it like code. Personal skills stay in your home folder and never hold team rules.","check":"The code owners file lists the skills folder. A pull request that changes a skill cannot merge without a code owner's approval.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/project-skills-in-repo","related":["/playbook/ai-assisted-development/safety-and-permissions/review-agent-config","/playbook/adversarial-testing/ai-agents-and-models/pinned-tools","/playbook/website/ready-for-ai-agents/agent-skills-discovery"],"sources":[]},{"chapter":"Agent skills","name":"Ask before a skill changes data or spends money","level":"Required","risk":"data","rule":"A skill that deletes or changes data, deploys, sends messages or spends money shows its plan and waits for a yes. After acting, it runs a check that proves the result.","check":"Run the skill on a test account. It stops before the first change and lists every change. Without a yes it changes nothing, and after a yes its final check passes or it reports the failure.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-asks-first","related":["/playbook/ai-assisted-development/safety-and-permissions/least-privilege-agents","/playbook/ai-assisted-development/rules-the-agent-cannot-break/blocking-hooks"],"sources":[]},{"chapter":"Agent skills","name":"Test each skill and keep it current","level":"Recommended","rule":"Test each skill on a fixed set of three or more tasks before you change it, and keep a log of its runs. A check fails when a skill names a path or command that no longer exists.","check":"Each skill has three or more stored test tasks with results from its last change. The path check passes, and the run log has an entry for every skill in the last 90 days.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills","related":["/playbook/ai-assisted-development/agent-skills/skill-description","/playbook/ai-assisted-development/agent-skills/skill-scripts","/playbook/ai-assisted-development/measuring-and-improving/evaluate-agent-setup"],"sources":[]},{"chapter":"Agent skills","name":"Copying rules the agent already has into a skill","level":"Avoid","rule":"Do not paste the instructions file or another skill's steps into a skill. Two copies drift apart, and the agent follows whichever it read last.","url":"https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/duplicate-skill-text","related":["/playbook/ai-assisted-development/context-and-memory/short-current-instructions"],"sources":[]}]}