Engineering playbook — Luis Carrera

This playbook is the set of standards I put in place when I lead a team. It exists so that nobody has to guess what “finished” means, what a good review looks like or when a release can go out. It applies the same way to people and to AI coding agents, because the rules are about the work, not about who typed it.

Some of it describes what I already do in my current role at a B2B SaaS for auto-repair shops. The rest is prescriptive: it is how I set up a team, written as rules. I have led teams of up to 40 people at the IPN, and I keep the rules short enough that a team can actually follow them.

Definition of done

A task is done when every box below is checked. The list is the same for a one-line fix and for a feature, because the cost of a missing check is paid later and by someone else.

The Done criterion was written when the task started, and it can be verified by a person who did not write the code.
Checks that prove concrete numbers pass. A green check alone is not proof: a test that returns 200 only shows that a route answered, so the check asserts an exact count, a total or a time limit.
The gate was broken on purpose at least once, so I know it can fail.
The code review is approved by someone who can explain the change.
QA passed in the QA environment, with the failure, evidence and steps recorded for anything that did not pass.
The change was validated again in production after the release.
For data changes: dry run, QA, production and a reconciliation against the source, in that order.
The documentation is updated: the README, the runbook or the decision record that the change touches.
Nothing is left pending without an owner and a date.

Two details make this list work. First, the Done criterion is written at the start, in the task itself, under a line called “Objective (Done criterion)”. If the criterion cannot be written, the task is not ready to start. Second, “done” is a claim about the real result, so before anyone writes “ready” they open the file, run the query or read the number.

Code review

Review is where a team’s standards become visible. I read in a fixed order, because the order decides what gets attention when time is short.

Correctness against the criterion. Does the change do what the Done criterion says, and nothing else?
Data safety. Migrations and writes get the closest look: is there a dry run, is the script idempotent or marked single-use, does it overwrite columns that people fill in by hand, and is every column in an insert decided instead of omitted?
Security. No secrets in logs, in errors or in test fixtures. A real example from my QA work: a socket server printed the session token in clear text in its log. I reported it with evidence and it was fixed. After that, “what does this print?” became a standing review question.
Tests that can fail. A test that cannot fail is not a test. I ask where the test would break if the code were wrong.
Readability. Names, structure and comments that explain why, not what.

Every comment carries a label, so the author knows what is required:

blocking: the change cannot merge until this is resolved.
suggestion: an improvement the author may take or leave, with a reason if they leave it.
question: I do not understand something; an answer is enough, and it may become a code comment.

Size and speed matter as much as depth. A pull request changes less than 400 lines; larger work is split into steps that each leave main working. The first review happens in less than one business day, because a review that waits for days teaches people to stack unreviewed work.

Code generated by an AI agent is reviewed with the same bar as code written by a person. The person who approves it must be able to explain it line by line. If they cannot, it is not approved, no matter how clean it looks or how many tests pass.

The review checklist has one mandatory box, copied literally into every pull request template:

Every query that reads in pages has an ORDER BY on a unique key

It exists because of a real bug: a query that reads page after page without a stable order lets the database return rows in any order from one page to the next. Pages repeat or skip records, and totals shrink without any error. The full story is in the pagination postmortem.

Branches and releases

The branching model is deliberately boring.

Branches are short-lived and start from main.
Every change reaches main through a pull request. The CI runs the build, the type check and the tests on each pull request, and a failing check blocks the merge.
Merges are squash merges, so each change is one commit with a clear message.
main is always deployable. If it is not, fixing it is the first priority of the team.

Releases are weekly and pass a two-stage QA gate. The first stage is the QA environment: every ticket is tested there and either approved or sent back to rework. The second stage is production: after the deploy, each ticket is checked again with real data and real volumes. The two stages have different criteria, so they are recorded separately and never merged into one verdict. The detailed case is in the QA release gate.

A hotfix follows a shorter path with the same rules: a branch from main, a small pull request, a review that happens the same day, and a production validation immediately after the deploy. A hotfix is never a reason to skip the second stage.

Every release has release notes written for the people who use the product. They avoid technical jargon, because the reader is a customer, not a developer.

One rule keeps roles clean: QA reports, never fixes. A QA report says what failed, shows the evidence and lists the steps to reproduce it. It does not include a suggested fix. The fix belongs to product and development, and a suggested fix pulls QA into design and can hide the real problem.

Onboarding

New people should be productive without needing a hero to explain the system. This is the plan I set up for anyone joining, in order.

Day 1. Accesses are ready before the person arrives. They clone the project and run it locally. The goal of the day is one working local environment, nothing more.
Days 2 and 3. They read the architecture notes and the decision records. The three architecture decision records are listed on the notes page, and they explain why the system is shaped the way it is. They ask questions, and the answers are written back into the documents.
First pull request before the end of day 3. It is small on purpose: a typo, a test or a missing line of documentation. They work with a pair, and the goal is to walk the full path from branch to production once.
30 days. They have shipped several small changes and can explain the review checklist to someone else.
60 days. They own a small area end to end, including its tests and its runbook.
90 days. They review other people’s work and propose one improvement to the process.

Every new person corrects the onboarding document as they go. They are the only people who can see what is missing, and a document that nobody fixes is already out of date. I do not count past onboardings as proof that this works; the plan is a standard I set, and it is judged by the next person who follows it.

Rituals

Meetings are cheap to add and expensive to remove, so each one has to earn its place.

Daily, written. It is posted in the team channel as lists, not tables, because it has to paste cleanly into the chat. It has three parts: done (rework, reported, QA approved, QA in production), pending, and QA pending. It takes a few minutes to write and replaces a standing meeting.
Weekly on Mondays. Three minutes per person, with management and the team. Each person says what they committed to last week, why anything was not finished, and what they commit to this week. The QA queue priority is negotiated here: bugs first, then the React migration, then everything else.
1:1 every two weeks. Thirty minutes, with a fixed agenda: how are you, blockers, progress since last time, feedback in both directions, growth and agreements with an owner and a date. The agenda is in the templates kit.
Sprint planning. One sentence for the sprint goal, a capacity number, and a list of tasks that each have a verifiable Done criterion. The sheet is in the same templates kit.
Postmortem, with no blame. After an incident or a near miss, the team writes what happened, the root cause, what went well, what went poorly and the action items. The question is never “who”, always “what let this happen”. See the pagination postmortem as an example of the format.
Decision records for hard-to-reverse choices. If undoing a decision would be expensive, I write it down with the alternatives I rejected and the measurement that decided it. See ADR 001 on dynamic attributes.
Quarterly delivery metrics review. Once a quarter the team looks at the four DORA delivery metrics: deployment frequency, lead time for changes, change failure rate and time to restore service. They are inputs for a conversation about the process, never a ranking of people. For a live view, see a live DORA dashboard of my public repositories.

Every ritual has an owner and a written output. A meeting that produces no output is a candidate for deletion at the next quarterly review.

How AI agents fit in

AI agents work inside the same definition of done as everyone else. They do not get a lighter checklist because they are fast, and they do not get a heavier one because they are new. What changes is who carries which part of the work.

Rules are written per project. Every project has a CLAUDE.md with the rules the agent must follow: verify the real result before saying “done”, keep scripts idempotent, ask for approval before structural changes, never commit or push unless asked in that turn, and write to production only with a prior dry run and a verification afterward.
The agent proposes, a person decides. The agent drafts code, queries and documents. A person owns the scope, reviews every change, verifies it against real data and decides what ships.
Zero invention. If a figure does not come from the database or a file, the agent marks it and asks. A number without a source does not enter a document.
The review bar does not move. AI-generated code is reviewed like any other, and the approver must be able to explain it.

In my own work, 71 of 243 commits in the repository I use for analysis and operations are co-authored by an AI model. That share is an input for review, not a measure of quality: it tells me how much of the code needs the closest reading. How I direct a team of agents, with roles, plans and a live panel, is described in the AI agent team case study.