--- title: "Engineering checklist: all 32 rules ยท Agent Wranglers" url: https://agentwranglers.se/playbook/engineering/checklist updated: 2026-10-20 licence: "All rights reserved" --- # Engineering checklist By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20. Every rule in the engineering playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it. **For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/checklist`. ## Rules as code - [ ] **Required** [Check every rule in code](https://agentwranglers.se/playbook/engineering/rules-as-code/check-every-rule-in-code): Every rule a project follows must have a check in code that anyone can run again and that ends in a plain pass or fail. - [ ] **Required** [Run one check of everything before every deploy](https://agentwranglers.se/playbook/engineering/rules-as-code/run-one-check-before-every-deploy): Run every check against the whole project with one command, and let the deploy go ahead only when all of them pass. - [ ] **Required** [Fail the build on broken rules](https://agentwranglers.se/playbook/engineering/rules-as-code/build-gates): Make the build fail on rules that must always hold, so a broken build can never ship. - [ ] **Recommended** [Enforce the writing style in code](https://agentwranglers.se/playbook/engineering/rules-as-code/enforce-the-writing-style-in-code): Check the writing of every page and document in the build, so the language stays plain and short as more people and AI tools write. ## Build, test and deploy - [ ] **Required** [Unit test the tricky parts](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/unit-tests-for-the-tricky-parts): Test logic that can break silently on its own, without a network, a database or a browser. - [ ] **Required** [Stamp every build with its version](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release): Give every build a version and the commit it came from. Show both in the running app, and tag each release in version control. - [ ] **Required** [Deploy in one step and roll back by itself](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/atomic-deploys-with-rollback): Upload next to the live copy, swap in one step, health-check, and put the old copy back if the check fails. - [ ] **Required** [Give the server a health check](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/health-check-and-rollback): Give the server a health check address that tests its dependencies, so deploys and monitors know when it is broken. - [ ] **Recommended** [Run the tests inside the container build](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/container-build-gated-by-tests): Make it impossible to produce a deployable image from untested code. - [ ] **Recommended** [Release to a small share first](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/staged-rollouts): Send a new release to a small share of traffic first, compare it with the old one, and roll back by itself when errors rise. ## Version control and review - [ ] **Required** [Keep every change in version control](https://agentwranglers.se/playbook/engineering/version-control-and-review/everything-in-version-control): Keep code, settings, build scripts, infrastructure and database changes in version control. Only secrets stay out. - [ ] **Required** [Make small changes on short-lived branches](https://agentwranglers.se/playbook/engineering/version-control-and-review/small-changes): Merge small changes often. A branch lives for at most 5 working days, and a change does one thing. - [ ] **Required** [Protect the main branch](https://agentwranglers.se/playbook/engineering/version-control-and-review/protect-the-main-branch): Nobody pushes straight to the main branch. Every change arrives through a pull request with passing checks and an approved review. - [ ] **Required** [Run the checks on every change](https://agentwranglers.se/playbook/engineering/version-control-and-review/continuous-integration): Run the full check on a clean machine for every push and pull request, not only on a developer's computer. - [ ] **Required** [Fix a broken main branch first](https://agentwranglers.se/playbook/engineering/version-control-and-review/keep-main-green): When the check fails on the main branch, fixing it comes before any other work. Revert the change that broke it if a fix takes longer than an hour. - [ ] **Recommended** [Update dependencies in small automatic steps](https://agentwranglers.se/playbook/engineering/version-control-and-review/automated-dependency-updates): Let a bot open a pull request for each dependency update, and merge it when the checks pass. ## Running in production - [ ] **Required** [Make builds repeatable](https://agentwranglers.se/playbook/engineering/running-in-production/reproducible-builds): The same commit always gives the same build. Pin the language version, the tools and every dependency. - [ ] **Required** [Keep settings outside the code](https://agentwranglers.se/playbook/engineering/running-in-production/settings-outside-the-code): Read everything that differs between test and production from the environment. Never edit code to deploy somewhere else. - [ ] **Required** [Log, track errors and alert](https://agentwranglers.se/playbook/engineering/running-in-production/logs-and-alerts): Write structured logs, collect every unhandled error in one place, and alert a person when errors or response times jump. - [ ] **Required** [Watch the service from outside](https://agentwranglers.se/playbook/engineering/running-in-production/monitoring-uptime): Watch the service from outside your own network, and alert a person when it stops answering. - [ ] **Required** [Keep secrets in a secrets store](https://agentwranglers.se/playbook/engineering/running-in-production/secrets-store): Keep passwords, keys and tokens in a secrets manager or the platform's encrypted store. Give them to the app when it starts, and rotate them on a schedule. - [ ] **Recommended** [Separate deploying from releasing](https://agentwranglers.se/playbook/engineering/running-in-production/deploy-is-not-release): Ship unfinished or risky features switched off, and turn them on with a flag when they are ready. ## Documentation - [ ] **Required** [Get a new person running with one command](https://agentwranglers.se/playbook/engineering/documentation/readme-quick-start): Start the README with what the project does in one sentence, then one command that installs and runs it from a clean checkout. - [ ] **Required** [Change the docs in the same pull request](https://agentwranglers.se/playbook/engineering/documentation/docs-with-the-change): Keep docs in the repository next to the code they describe, and update them in the pull request that changes the behaviour. - [ ] **Required** [Test the docs in the build](https://agentwranglers.se/playbook/engineering/documentation/tested-docs): Check every link in the docs and run every code sample as a test in CI. - [ ] **Required** [State each value in one document and link to it](https://agentwranglers.se/playbook/engineering/documentation/one-home-per-value): Write each limit, time or threshold, such as a session length or a retry count, in one document only. Every other document links there. - [ ] **Recommended** [Keep decision records with a status](https://agentwranglers.se/playbook/engineering/documentation/decision-records): Number each decision record, give it a status, and replace it with a new record instead of editing it once accepted. - [ ] **Recommended** [Keep runbooks next to the code they run](https://agentwranglers.se/playbook/engineering/documentation/runbooks-in-repo): Write a runbook in the repository for every task a person does by hand in production. Turn each step into a script when you can. - [ ] **Recommended** [Generate reference docs from the code](https://agentwranglers.se/playbook/engineering/documentation/generated-reference): Build reference docs for every public interface from the code or contract, never by hand. - [ ] **Recommended** [Keep a changelog written for users](https://agentwranglers.se/playbook/engineering/documentation/user-changelog): Keep a dated changelog that tells users what changed for them in each release, written in their words. - [ ] **Recommended** [Draw diagrams as code](https://agentwranglers.se/playbook/engineering/documentation/diagrams-as-code): Write diagrams as text in the repository, with a diagram language such as Mermaid, PlantUML or D2, never only as an exported image. - [ ] **Recommended** [Give every doc an owner and a review date](https://agentwranglers.se/playbook/engineering/documentation/doc-ownership): Give every guide and runbook an owner and a last-reviewed date, and flag any doc not reviewed in 6 months.