Hi, I'm Filipe!
PT

Published on 5 min read

Autopilot guide: from SPEC.md to a pull request with Claude Code

This guide is for people who already use Claude Code and want to run autopilot from the Claude Code Playbook on a real project. Autopilot takes a SPEC.md with acceptance criteria and works on its own, with no questions, until every criterion is verified and a pull request is open. The commands below are the same as in the repository’s README and guide 9.

What you need

  • Plan: a Claude Pro, Max or Team subscription logged in to Claude Code. Autopilot refuses to run on API-key billing, on usage-based Enterprise plans, or with usage credits turned on, because there every token is paid. AUTOPILOT_ALLOW_CREDITS=1 overrides this, at your own cost.
  • Claude Code: v2.1.259 or later, for the --permission-prompts none option. From v2.1.305 it also re-checks whether a limit lifted early.
  • Permissions: auto mode, or AUTOPILOT_PERMISSION_MODE=dontAsk if your organization disables auto mode. /goal needs a trusted folder and hooks enabled.
  • System: macOS or Linux (WSL2 works) with bash, git and jq. For the final pull request, gh has to be logged in.

Install

Clone the repository and install just the autopilot part:

git clone https://github.com/filipejesse/claude-code-playbook ~/claude-code-playbook
cd ~/claude-code-playbook
./install.sh --dry-run
./install.sh --autopilot-only

--dry-run shows what the full install would change, without applying anything. --autopilot-only installs just what autopilot uses: the autopilot command, /autopilot-spec, /open-pr, the verifier agent, the guard and PR-doc hooks and the permission rules. If you want the whole playbook, run ./install.sh with no option. All of it is reversible with ./install.sh --uninstall.

The spec with /autopilot-spec

Open Claude Code in the project folder, which can be empty, and describe what you want to build. The example from guide 9:

mkdir ~/Repos/my-app && cd ~/Repos/my-app && claude
> /autopilot-spec a personal finance tracker that imports bank CSVs and shows monthly charts

That interview is the only time Claude asks you anything. After it, Claude writes SPEC.md, with the acceptance criteria and one verification command, scaffolds the repository and commits.

It is worth spending time here. Every criterion has to be checkable by a command, because that is how Claude will prove it is done. “The page looks nice” cannot be checked; “the accessibility test passes on both pages” can. If a criterion in the draft is vague, replace it with something a command can confirm.

Start, follow and stop

autopilot start
autopilot log
autopilot status
autopilot stop

autopilot start runs in the background and survives closing the terminal. autopilot log follows what it is doing. autopilot status shows the state, the branch, the commits and PROGRESS.md. autopilot stop stops the run, and a later autopilot start resumes the same session.

The autopilot loopYou answer the /autopilot-spec interview, which writes SPEC.md with the criteria and one verification command. Then you run autopilot start. Claude repeats the loop of working, verifying and committing, waiting for usage limits to reset when they run out, until every criterion is verified. It then ends with AUTOPILOT_DONE.md and a pull request. If only a person can unblock something, it takes the side exit: it writes AUTOPILOT_BLOCKED.md and stops./autopilot-specinterviewSPEC.md+ verification commandautopilot startwork, verify, commitwaits out usage limitsAUTOPILOT_DONE.md + PRAUTOPILOT_BLOCKED.md
The autopilot loop. The dashed line is the exit when only a person can unblock the work.

Under the hood, the runner uses Claude Code’s /goal: after each turn a separate evaluator checks the condition, and Claude continues until it is met. The condition requires every SPEC.md criterion verified and AUTOPILOT_DONE.md written. When a decision is needed, Claude makes it, logs it in DECISIONS.md and continues. To get through usage limits, CLAUDE_CODE_RETRY_WATCHDOG=1 makes the request wait until the reset time, for both the 5-hour and the weekly windows. If the process dies, the runner resumes the same session with growing backoff, from 1 to 15 minutes, and three runs in a row with no change to the repository mark the work as blocked.

How a run ends

There are two possible endings:

  • AUTOPILOT_DONE.md: every criterion, the command that proved it and the pull request URL.
  • AUTOPILOT_BLOCKED.md: when only a person can unblock the work, such as a credential, a paid service or a product decision the spec cannot settle.

The work is on an autopilot/<date> branch. If the repository has a GitHub remote, Claude opens a PR with its PR doc, which includes a Mermaid sequence diagram and other diagrams. Reviewing and merging is up to you: Claude never merges.

Before a long run

  • Usage credits. With credits on, the plan limit does not stop requests: they continue on paid credits. On Pro and Max, turn them off at claude.ai/settings/usage. On Team and Enterprise, only an Owner can.
  • Weekly window. One long run can use a large share of the weekly allowance that your interactive work also needs. Start big projects when you can spare it, or set AUTOPILOT_MODEL=sonnet.
  • Isolation. Do your first runs inside a VM, a container or a disposable user account, on a repository you can throw away. The hooks block a short list of dangerous commands, but they are a last line of defence, not a sandbox. bypassPermissions mode only belongs inside a disposable VM or container.
  • Laptop. Keep it plugged in. Autopilot keeps the machine awake with caffeinate on macOS or systemd-inhibit on Linux, but closing the lid still sleeps most Macs unless an external display is attached.

A real example: this blog

This blog’s infrastructure and design were built in autopilot runs:

  • Ready for Cloudflare Pages. 16 criteria, including security headers with a CSP, a bilingual 404 page, an edge redirect and a CI workflow. The final verification passed 23 unit tests, 107 checks over the build and 114 end-to-end tests, and the PR’s CI check was green. Along the way, Claude noticed that a pattern in .gitignore was hiding a test folder that had never reached the repository, recreated the tests and logged why in DECISIONS.md.
  • The “Hi, I’m Filipe!” visual identity. 17 criteria, from color tokens with measured contrast to keyboard focus and reduced motion. It closed with 48 unit tests, 123 checks over the build, 141 end-to-end tests and 20 reviewed screenshots, with 6 dated critiques and what changed after each one. Both ended the same way: an AUTOPILOT_DONE.md with the evidence for each criterion and a PR waiting for my review.

Then came automatic deploy on merge: a CI job that, once verification passes on a push to main, publishes exactly the tested dist/ to Cloudflare Pages. The merge, and with it the deploy, is still mine.

Wrapping up

If you landed here first, the playbook announcement explains why it exists and which autopilot limitations are still open. For run reports or corrections, open an issue on the repository.

Sources

Leia este artigo em português