AI development checklist

Every rule in the ai development playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it.

Setting up the project

• Required Write one instructions file for agents
• Required Keep code small enough for an agent to read
• Required Keep the project runnable from a clean checkout
• Recommended Write down the decisions agents keep getting wrong

Working in small steps

• Required Plan before the agent writes code
• Required Give every task acceptance criteria
• Required Let the agent check its own work
• Required Keep each change small
• Required Work on a branch and commit often
• Recommended Keep one task per session
• Recommended Ask for the smallest change that works

Rules the agent cannot break

• Required Use strict types and linters
• Required Protect the checks themselves
• Recommended Block dangerous actions with hooks

Reviewing agent output

• Required Read every line of the diff
• Required Run the change yourself
• Required Check that every package and API exists
• Required Look for weakened checks and skipped work
• Required Check the change does only what was asked
• Recommended Get a fresh review for risky changes
• Recommended Check where generated code came from

Safety and permissions

• Required Run agents in a sandbox
• Required Skip approvals only in a throwaway sandbox
• Required Keep production credentials away from agents
• Required Give agents the fewest rights they need
• Required Approve destructive commands
• Required Treat what the agent reads as untrusted
• Required Run agents in CI only for trusted people
• Required Review agent settings like code
• Required Open unknown repositories in a sandbox
• Recommended Know what the agent tool does with your code

Apps built with AI builders

• Required Turn on row-level security for every table
• Required Keep secret keys on the server
• Required Check every sign-in and permission flow
• Required Own the code in your own repository
• Recommended Add tests and checks before the app grows
• Recommended Know when to move off the builder

Context and memory

• Required Keep instructions short and current
• Required Save lessons in the repository instead of chat
• Recommended Show examples of good code
• Recommended Give agents documentation they can fetch
• Recommended Send wide searches to a subagent
• Optional Use playbooks as references and credit them

Measuring and improving

• Required Add a check for every repeated mistake
• Required Keep a person's sign-off before release
• Recommended Track what agents get wrong
• Recommended Mark which changes an agent wrote
• Recommended Test changes to the agent setup on fixed tasks
• Recommended Measure delivery instead of lines of code