Hi, I'm Filipe!
PT

Published on 3 min read

I open-sourced my Claude Code playbook

Today I made the repository of my Claude Code Playbook public. It is a practical setup guide for Claude Code, with the principles I follow, plus an installable baseline that configures any machine or VM the same way in one command. It is MIT licensed and not affiliated with Anthropic.

If you already use Claude Code and want to get straight to practice, I wrote a step-by-step autopilot guide, from install to pull request.

Why I made it

I wanted three things from every Claude Code project, and they are what the playbook is organized around:

  • Each project steers Claude well. Lean, layered context, so every session starts knowing how to build, test and ship the repo.
  • Agents keep working while there is capacity. Isolation, a task queue, unattended verification and alerts.
  • Resources are not wasted. Keep context tidy, use the right model for each job, and measure before optimizing.

The part that became the headline of the README is autopilot.

What autopilot does

The idea is to describe a project once and get a verified pull request. You run /autopilot-spec in Claude Code, answer the only interview of the whole process, and come out with a SPEC.md of verifiable acceptance criteria. Then autopilot start puts Claude to work in the background, with no questions and no permission prompts, until every criterion is verified.

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.

The guarantees, as the README states them:

  • Waits out usage limits. When the 5-hour or weekly window runs out, it sleeps until the reset and continues in the same session.
  • Never spends usage credits. It refuses to start, and stops mid-run, if your account would bill paid credits beyond the plan.
  • Stays on its own branch. It never pushes to the default branch, never merges, deploys or spends money. Hooks enforce the riskiest rules, not just the prompt.
  • Survives crashes and stalls. It resumes the same session with backoff, keeps the machine awake, and marks itself blocked after three runs with no progress instead of looping forever.

At the end it writes AUTOPILOT_DONE.md, listing each criterion and the command that proved it, and opens a pull request with a PR doc and Mermaid diagrams. If only a person can unblock the work, such as a credential, a paid service or a product decision, it writes AUTOPILOT_BLOCKED.md and stops.

What is not proven yet

I would rather be clear about the limitations:

  • Waiting at a real usage limit has not been observed end to end yet, because it cannot be triggered on demand. It relies on Claude Code’s documented CLAUDE_CODE_RETRY_WATCHDOG, with a read of the reset time as a fallback, and both paths are covered by tests with a stub.
  • The credits check reads the text of claude -p /usage. If Anthropic rewords it, autopilot fails closed: it refuses to run rather than risk paid usage.
  • Closing a laptop lid still sleeps most Macs, despite caffeinate, unless an external display is attached.
  • PRs need gh. A PR opened through a GitHub MCP server bypasses the hook that requires the PR doc.

And a serious warning: autopilot runs an AI agent unattended, for hours, executing commands without asking you. The guard hooks block a short list of dangerous commands, but they are a last line of defence, not a sandbox. Do your first runs inside a VM, a container or a disposable user account, on a repository you can throw away.

Where to start

The repository has the README with the requirements and nine guides, from principles to autopilot. Reports from real runs are welcome as issues.

To run autopilot on your own project, follow the autopilot guide: it shows every command, how a run ends, and what to set up before a long run.

Sources

Leia este artigo em português