This project provides guidance documents for using Large Language Models (LLMs) to generate and modify code for the ArduPilot autopilot platform.
Four usage modes are supported:
- Claude Code - Anthropic's CLI tool for interactive development with Claude
- Codex - OpenAI's coding agent for interactive repository work
- Gemini CLI - Google's CLI tool for interactive development with Gemini
- Chat-based LLMs - Traditional prompt-based code generation with any LLM
The playbooks contain rules and constraints that ensure generated code is safe, testable, and consistent with ArduPilot development standards.
These are assumptions ArduPilot's maintainers hold about how the code fits together - what shared state promises, which layer decides, what a library may know about the vehicle - that no single diff shows. Each is a general principle, with the review or bug that exposed it as its example, and each was confirmed on its own before it went into the playbooks, which hold generated code and reviews to it. Every rule has its own page, so a review or a PR can link to the one it means.
Proposed rules that are still waiting for confirmation, and rejected ones with the reason, are in RULES_PROPOSED.md.
| Rule | Principle | Confirmed |
|---|---|---|
| ARCH-1 | Shared state is a contract between subsystems | 2026-10-13 |
| ARCH-2 | Test for what you need, not for what usually comes with it | 2026-10-13 |
| ARCH-3 | Lower layers detect, higher layers decide | 2026-10-14 |
| ARCH-4 | A feature not every vehicle needs costs nothing to the users who do not use it | 2026-10-14 |
| ARCH-5 | Safety logic is judged by what it does when it is wrong | 2026-10-14 |
| ARCH-6 | Do not break what users already have | 2026-10-14 |
| ARCH-7 | Prefer the simplest design that does the job | 2026-10-14 |
| ARCH-8 | Reuse before you write | 2026-10-14 |
| ARCH-9 | The main loop never waits | 2026-10-14 |
| ARCH-10 | Nothing from outside is trusted | 2026-10-14 |
| ARCH-12 | Memory is paid for only where it is used | 2026-10-16 |
| ARCH-13 | A driver change holds for every variant and failure it can meet | 2026-10-16 |
| ARCH-14 | Do not add code before it is used, and remove what your change leaves unused | 2026-10-16 |
| ARCH-15 | internal_error is for the impossible, not the unexpected | 2026-10-16 |
| ARCH-16 | Use the weakest spatial reference the job needs, and name the one you use | 2026-10-16 |
| ARCH-17 | Libraries carry no vehicle-specific code; the vehicle moderates them | 2026-10-16 |
| ARCH-18 | Data crosses from a driver's thread to the main loop only at the frontend's copy | 2026-10-16 |
| ARCH-19 | New behaviour is opt-in, and lands as the last and smallest commits of a PR | 2026-10-16 |
Claude Code is Anthropic's official CLI tool that provides an interactive development experience. It can read your codebase, make edits, run commands, and understand project context.
-
Install the playbooks into your ArduPilot repository:
cd /path/to/ardupilot curl -fsSL https://raw.githubusercontent.com/fossuav/aap/main/install-claude.sh | bash
-
Start Claude Code:
claude
Claude Code will automatically read the CLAUDE.md files and use them to guide its responses.
The install script places the following files:
| File | Purpose |
|---|---|
CLAUDE.md |
Build system, architecture overview, C++ development guidelines |
libraries/AP_Scripting/CLAUDE.md |
Lua scripting patterns, applet structure, parameter system |
libraries/AP_Scripting/CLAUDE_CRSF_MENU.md |
CRSF (Crossfire) menu implementation |
libraries/AP_Scripting/CLAUDE_VEHICLE_CONTROL.md |
Vehicle control APIs, movement commands, RC input |
libraries/AP_NavEKF3/CLAUDE.md |
EKF3 navigation filter reference and analysis methodology |
libraries/AP_HAL_ChibiOS/hwdef/CLAUDE.md |
ChibiOS board porting and hwdef.dat creation |
ArduPlane/CLAUDE.md |
Plane flight modes, log analysis, QuadPlane operations |
Tools/autotest/CLAUDE.md |
Autotest authoring conventions, event-wait patterns, Lua applet test patterns |
.claude/settings.json |
Project permissions and hooks — auto-allows the skill scripts and a few read-only tools (not blanket python3/git/rm), enforces rules. Also switches off Claude commit/PR attribution via attribution. Machine-specific allows go in settings.local.json |
.claude/skills/*/SKILL.md |
Slash command skills (see table below) |
.claude/skills/log-analyze/log_extract.py |
Log extraction tool used by /log-analyze |
.claude/skills/log-analyze/flow_cal_check.py |
Verifies optical-flow scale/orientation against GPS truth (per-axis scaler check) used by /log-analyze |
.claude/skills/log-analyze/flow_imu_check.py |
Does the optical flow measure motion? Flow against the integrated IMU over short windows, no GPS needed, by flow quality and height, used by /log-analyze |
.claude/skills/log-analyze/log_health.py |
Memory, stacks, internal errors, log-buffer and end-of-log sweep -- did the autopilot die or the vehicle? used by /log-analyze |
.claude/skills/log-analyze/thrust_check.py |
Measured throttle-to-thrust map against the vehicle's own calibration, mixer-clip filtered, used by /log-analyze |
.claude/skills/log-analyze/gyro_fft.py |
Pre- against post-filter gyro spectra, per-band attenuation and notch coverage -- is the filtering working? used by /log-analyze |
.claude/skills/log-analyze/rate_response.py |
Closed-loop rate response per axis: under-damped, under-gained or saturated, used by /log-analyze |
.claude/skills/log-analyze/filter_phase.py |
Phase cost of the configured filter chain, and what a proposed change buys, used by /log-analyze |
.claude/skills/log-analyze/baro_thst_cal.py |
Fits BARO1_THST_SCALE (and checks BARO_THST_FILT) from a fixed-vehicle throttle ramp, used by /log-analyze |
.claude/skills/log-analyze/rate_band.py |
Which axis owns an oscillation band above 10 Hz, whether D is driving it, and an A/B between two logs, used by /log-analyze |
.claude/skills/log-analyze/batch_fft.py |
ISBH/ISBD batch-sampler spectrum per IMU, pre- and post-filter, in physical units, used by /log-analyze |
.claude/skills/log-analyze/baro_health.py |
Baro against EKF through spool-up, lift-off and hover, vibration/clipping and vertical-loop state -- is the altitude chain usable? used by /log-analyze |
.claude/skills/log-analyze/replay_sweep.py |
Replays real flight logs through the current build and reports resets and peak excursion per re-run core, with a before/after compare, used by /log-analyze |
.claude/skills/autotest/autotest_env.py |
Per-clone autotest environment shared by the two scripts below — own log tree, own port slot, so two clones can run autotests at once |
.claude/skills/autotest/autotest_results.py |
Autotest result parser used by /autotest to summarise pass/fail and extract failure context |
.claude/skills/autotest/run_autotest.py |
Timed autotest runner used by /autotest — wraps autotest.py with a wall-clock timeout, lock pre-check and per-clone isolation |
.claude/skills/hwdef-check/hwdef_check.py |
Helper used by /hwdef-check to run DMA, board-ID, file-presence, BIDIR/bdshot, and commit-structure checks on a new-board PR |
.claude/skills/pr-checks/ci_failures.py |
Helper used by /pr-checks to download a PR's failed CI job logs and extract the failing tests/build errors |
.claude/skills/prepare-for-push/grant_push.py |
Mints the short-lived push authorisation the git pre-push hook requires — run for you when you type /prepare-for-push, never on Claude's initiative |
.claude/hooks/pre_bash_check.py |
PreToolUse hook — enforces git commit and safety rules, gates push/rebase/reset/amend on an authorisation token, and scans scripts passed to an interpreter so a guarded command cannot be hidden in a wrapper |
.claude/hooks/post_edit_check.py |
PostToolUse hook — checks C++ edits for common violations |
.claude/githooks/pre-push |
Git-level hook (via core.hooksPath) — refuses any push without a grant, and always refuses force-pushing or deleting master/main. Git runs it itself, so wrapping git push in a script does not evade it |
Skills are invoked as /command in Claude Code. They pre-authorize necessary tools so common operations run without repeated permission prompts.
Read-only skills (safe, no side effects):
| Command | Description |
|---|---|
/boards [search] |
List and search available board targets |
/find-code <feature> |
Find where features, modes, commands, or messages are implemented |
/find-param <NAME> |
Find parameter definitions, ranges, units in source code |
/build-options [search] |
Search compile-time feature flags (AP_*_ENABLED defines) |
/style-check [files] |
Check code style with astyle dry-run and whitespace checks |
/hwdef-info <board> |
Show board hardware definition (MCU, UARTs, pins, sensors) |
/hwdef-check <PR> |
Review an hwdef PR — worktree checkout, DMA/board-ID/file/commit/BIDIR checks, playbook pass, draft review comment |
/explain <topic> |
Explain ArduPilot code, architecture, or subsystems |
/lua <task> |
Write or modify Lua applets (loads playbook + API docs) |
/lua-crsf <menu> |
Write CRSF transmitter menu scripts with crsf_helper |
/lua-vehicle <task> |
Lua vehicle control, movement, RC input |
/log-analyze <logfile> |
Analyze DataFlash .bin logs (messages, params, events, plots) |
/pr-checks [PR] |
Download a PR's failing CI checks and identify the failing tests/build errors |
/aap-update |
Compare local playbook version with GitHub and install updates |
Write skills (local only — compile, run tests, launch simulator, edit code):
| Command | Description |
|---|---|
/build <vehicle> [--board board] |
Configure and build firmware |
/check [test_name] |
Build and run unit tests (Google Test) |
/autotest <vehicle> [test] |
Run SITL integration/behavior tests |
/sitl <vehicle> [options] |
Launch interactive SITL simulator |
/swd-debug |
Flash and debug a board over SWD with OpenOCD and GDB when USB/serial is dead |
/pr-review [PR] [--quick] |
Review your own PR the way a maintainer will, then fix what it finds - CI gates, parallel review, Codex cross-check, bounded fix loop; --quick for a push that answers review findings |
Authorisation skill (you invoke this — Claude cannot):
| Command | Description |
|---|---|
/prepare-for-push <branch> [--force] [--allow ops] |
Grant Claude a short-lived, branch-scoped permission to push. Without it every push is refused. --status shows the current grant, --revoke cancels it |
Hooks automatically enforce key CLAUDE.md rules that Claude might otherwise ignore. They run as PreToolUse/PostToolUse checks configured in .claude/settings.json, plus one hook that git itself runs.
| Hook | Event | Enforces |
|---|---|---|
pre_bash_check.py |
PreToolUse (Bash) | No git clean, no Claude co-author in commits, commit messages must have subsystem prefix. Gates push/rebase/reset/amend on a /prepare-for-push grant, blocks --no-verify and core.hooksPath tampering, and scans scripts passed to an interpreter so a guarded command cannot hide in a wrapper |
post_edit_check.py |
PostToolUse (Edit/Write) | No printf() in C++ flight code (use gcs().send_text()) |
githooks/pre-push |
git pre-push |
Refuses any push not covered by an unexpired, branch- and remote-scoped grant. Always refuses force-pushing or deleting master/main |
Hooks that block (exit code 2) provide feedback to Claude explaining the rule violation, so it can fix the issue and retry.
A Claude Code PreToolUse hook only ever sees the command string, so a guarded command hidden inside a helper script (bash helper.sh) slips straight past it — this happened in practice. githooks/pre-push is run by git itself and cannot be wrapped around, which makes it the real enforcement point for pushes; pre_bash_check.py now also reads the contents of scripts handed to an interpreter, closing the wrapper route for the other guarded operations.
The hook only gates pushes that come from a Claude Code session, which it detects by looking for a claude process among its own ancestors (with the CLAUDE* environment variables as a fallback where /proc is not readable). Pushing by hand from your own terminal is unaffected and needs no token. The single exception is a force-push or delete of master/main, which the hook questions even for a human — pass --no-verify if you really mean it. For Claude that case is refused outright. A push started in-session with the ! prefix counts as a Claude push, since it really is a child of the claude process.
This is a guardrail against unrequested and accidental pushes, not a security boundary: an agent with a broad python3 permission could still run grant_push.py itself. Keep settings.json narrow (the shipped one has no blanket python3 grant), and if you want a grant to be unambiguously yours, run it in-session with the ! prefix rather than letting Claude run it:
! python3 .claude/skills/prepare-for-push/grant_push.py my-branch --force
To remove the playbook files from ArduPilot:
cd /path/to/ardupilot
curl -fsSL https://raw.githubusercontent.com/fossuav/aap/main/uninstall-claude.sh | bashCodex uses AGENTS.override.md files for repository guidance and can load skills from .codex/skills. The override filename is deliberate: it takes precedence over any existing ArduPilot AGENTS.md.
-
Install the playbooks into your ArduPilot repository:
cd /path/to/ardupilot curl -fsSL https://raw.githubusercontent.com/fossuav/aap/main/install-codex.sh | bash
-
Start Codex from the repository root.
Codex will read the AGENTS.override.md files and use the installed skills as workflow guides for common ArduPilot tasks.
The install script places the following files:
| File | Purpose |
|---|---|
AGENTS.override.md |
Build system, architecture overview, C++ development guidelines |
libraries/AP_Scripting/AGENTS.override.md |
Lua scripting patterns, applet structure, parameter system |
libraries/AP_Scripting/CODEX_CRSF_MENU.md |
CRSF (Crossfire) menu implementation |
libraries/AP_Scripting/CODEX_VEHICLE_CONTROL.md |
Vehicle control APIs, movement commands, RC input |
libraries/AP_NavEKF3/AGENTS.override.md |
EKF3 navigation filter reference and analysis methodology |
libraries/AP_HAL_ChibiOS/hwdef/AGENTS.override.md |
ChibiOS board porting and hwdef.dat creation |
ArduPlane/AGENTS.override.md |
Plane flight modes, log analysis, QuadPlane operations |
Tools/autotest/AGENTS.override.md |
Autotest authoring conventions, event-wait patterns, Lua applet test patterns |
.codex/skills/*/SKILL.md |
Codex skills for the same workflows as the Claude slash commands |
.codex/skills/log-analyze/log_extract.py |
Log extraction tool used by the log analysis skill |
.codex/skills/log-analyze/flow_cal_check.py |
Verifies optical-flow scale/orientation against GPS truth (per-axis scaler check) used by the log analysis skill |
.codex/skills/autotest/autotest_env.py |
Per-clone autotest environment shared by the two scripts below — own log tree, own port slot, so two clones can run autotests at once |
.codex/skills/autotest/autotest_results.py |
Autotest result parser used by the autotest skill |
.codex/skills/autotest/run_autotest.py |
Timed autotest runner used by the autotest skill — wall-clock timeout, lock pre-check and per-clone isolation |
.codex/skills/hwdef-check/hwdef_check.py |
Helper used by the hwdef review skill |
.codex/skills/pr-checks/ci_failures.py |
Helper used by the PR checks skill |
Codex installs no Claude-style permissions or hooks; command approval remains controlled by the Codex environment.
To remove the Codex playbook files from ArduPilot:
cd /path/to/ardupilot
curl -fsSL https://raw.githubusercontent.com/fossuav/aap/main/uninstall-codex.sh | bashThe Gemini CLI provides a similar interactive development experience using Google's Gemini models.
-
Install the playbooks into your ArduPilot repository:
cd /path/to/ardupilot curl -fsSL https://raw.githubusercontent.com/fossuav/aap/main/install-gemini.sh | bash
-
Start Gemini:
gemini
Gemini will automatically read the GEMINI.md files and use them to guide its responses.
The install script places the following files:
| File | Purpose |
|---|---|
GEMINI.md |
Build system, architecture overview, C++ development guidelines |
libraries/AP_Scripting/GEMINI.md |
Lua scripting patterns, applet structure, parameter system |
libraries/AP_Scripting/GEMINI_CRSF_MENU.md |
CRSF (Crossfire) menu implementation |
libraries/AP_Scripting/GEMINI_VEHICLE_CONTROL.md |
Vehicle control APIs, movement commands, RC input |
To remove the playbook files from ArduPilot:
cd /path/to/ardupilot
curl -fsSL https://raw.githubusercontent.com/fossuav/aap/main/uninstall-gemini.sh | bashFor traditional chat-based LLMs (ChatGPT, Claude web, Gemini web, etc.), you can manually provide playbook context.
To generate code, the LLM requires the following context:
- API Documentation (docs.lua) This file is the definitive source for all ArduPilot-specific Lua function signatures and is the final authority on correct API usage.
- AI Playbook This file(s) is the rule definitions for code generation telling the LLM what it may and may not do. Without this the LLM will go easily off track
- Code Digest (digest.txt) This file contains a snapshot of existing code and tests within the ArduPilot repository. It provides the LLM with the necessary examples to create new code. Unfortunately this digest tends to be quite large and can easily overflow the LLM's context window so it is often necessary to abandon it in favour of merely the first two items.
- Install gitingest
- Run
gitingest libraries/AP_Scripting -e '*.cpp' -e '*.c' -e '*.h' -e '*.txt' - A LUA digest will be generated in digest.txt
- Run
gitingest Tools/autotest -i arducopter.py -i vehicle_test_suite.py - An autotest digest will be generated in digest.txt
The process for generating code is as follows:
- Write a Prompt: Clearly describe the required functionality. Focus on what the code should do, not the implementation details.
- Example Prompt: "Create a script to control the brightness of my drone's NeoPixel LEDs using an RC switch. It should support three levels: off, medium, and high."
- Provide Context: Give the LLM your prompt, AI playbook, API documentation and, optionally, the digest-lua.txt file.
- Generate Artifacts: The LLM will generate a complete ArduPilot Applet (in the case of lua), which includes:
- A .lua script file.
- A .md documentation file explaining how to set up and use the script.
- Generate Autotest: For every applet, the LLM should offer to generate a corresponding SITL autotest file. This allows you to verify the script's functionality in a safe, simulated environment.
aap/
├── claude/ # Claude Code playbooks (CLAUDE.md files)
│ ├── CLAUDE.md # Root playbook (build, architecture, C++)
│ ├── ArduPlane/
│ │ └── CLAUDE.md # Plane log analysis, flight modes, QuadPlane
│ ├── libraries/
│ │ ├── AP_Scripting/ # Lua scripting playbooks
│ │ │ ├── CLAUDE.md
│ │ │ ├── CLAUDE_CRSF_MENU.md
│ │ │ └── CLAUDE_VEHICLE_CONTROL.md
│ │ ├── AP_NavEKF3/ # EKF3 navigation filter
│ │ │ └── CLAUDE.md
│ │ └── AP_HAL_ChibiOS/hwdef/ # ChibiOS board porting
│ │ └── CLAUDE.md
│ ├── Tools/
│ │ └── autotest/ # Autotest authoring playbook
│ │ └── CLAUDE.md
│ ├── hooks/ # Claude Code hooks (rule enforcement)
│ │ ├── pre_bash_check.py # PreToolUse: git commit, safety checks
│ │ └── post_edit_check.py # PostToolUse: C++ code quality checks
│ └── skills/ # Claude Code skills (slash commands)
│ ├── boards/SKILL.md # /boards - list/search board targets
│ ├── find-code/SKILL.md # /find-code - find feature implementations
│ ├── find-param/SKILL.md # /find-param - find parameter definitions
│ ├── build-options/SKILL.md # /build-options - search feature flags
│ ├── style-check/SKILL.md # /style-check - check code formatting
│ ├── hwdef-info/SKILL.md # /hwdef-info - board hardware definitions
│ ├── explain/SKILL.md # /explain - explain code/architecture
│ ├── lua/SKILL.md # /lua - write/modify Lua applets
│ ├── lua-crsf/SKILL.md # /lua-crsf - CRSF menu scripts
│ ├── lua-vehicle/SKILL.md # /lua-vehicle - vehicle control from Lua
│ ├── build/SKILL.md # /build - configure and compile
│ ├── check/SKILL.md # /check - run unit tests
│ ├── autotest/SKILL.md # /autotest - run SITL integration tests
│ ├── sitl/SKILL.md # /sitl - launch SITL simulator
│ ├── hwdef-check/ # /hwdef-check - review an hwdef PR
│ │ ├── SKILL.md
│ │ └── hwdef_check.py
│ ├── pr-review/ # /pr-review - review and fix your own PR
│ │ ├── SKILL.md
│ │ └── pr_review.py
│ └── log-analyze/ # /log-analyze - analyze flight logs
│ ├── SKILL.md
│ └── log_extract.py
├── codex/ # Codex playbook templates installed as AGENTS.override.md
│ ├── AGENTS.md # Root playbook template (build, architecture, C++)
│ ├── ArduPlane/
│ │ └── AGENTS.md # Plane log analysis, flight modes, QuadPlane
│ ├── libraries/
│ │ ├── AP_Scripting/
│ │ │ ├── AGENTS.md
│ │ │ ├── CODEX_CRSF_MENU.md
│ │ │ └── CODEX_VEHICLE_CONTROL.md
│ │ ├── AP_NavEKF3/
│ │ │ └── AGENTS.md
│ │ └── AP_HAL_ChibiOS/hwdef/
│ │ └── AGENTS.md
│ ├── Tools/
│ │ └── autotest/
│ │ └── AGENTS.md
│ └── skills/ # Codex skills and helper scripts
├── gemini/ # Gemini CLI playbooks (GEMINI.md files)
│ ├── GEMINI.md # Root playbook (build, architecture, C++)
│ └── libraries/AP_Scripting/ # Lua scripting playbooks
│ ├── GEMINI.md
│ ├── GEMINI_CRSF_MENU.md
│ └── GEMINI_VEHICLE_CONTROL.md
├── cpp/ # C++ playbooks for chat-based LLMs
│ └── AI_PAIR_PROGRAMMING_PLAYBOOK_CPP.md
├── lua/ # Lua playbooks for chat-based LLMs
│ ├── AI_PAIR_PROGRAMMING_PLAYBOOK.md
│ ├── AI_CRSF_MENU_PLAYBOOK.md
│ ├── AI_VEHICLE_CONTROL_PLAYBOOK.md
│ ├── AI_GIT_FORMAT_PATCH_PLAYBOOK.md
│ └── docs.lua # Lua API documentation
├── install-claude.sh # Install Claude playbooks to ArduPilot
├── uninstall-claude.sh # Remove Claude playbooks from ArduPilot
├── install-codex.sh # Install Codex playbooks to ArduPilot
├── uninstall-codex.sh # Remove Codex playbooks from ArduPilot
├── install-gemini.sh # Install Gemini playbooks to ArduPilot
├── uninstall-gemini.sh # Remove Gemini playbooks from ArduPilot
├── RULES_PROPOSED.md # Architectural rules awaiting confirmation (not installed)
├── rules/ # One page per confirmed architectural rule (not installed)
│ ├── ARCH-<n>.md # Generated from the rule's text in claude/CLAUDE.md
│ └── generate.py # Writes the pages and the README index; --check finds stale ones
└── README.md
The /pr-review skill is adapted from Andrew Tridgell's /reviewprs dev-call review command. The dual-reviewer pipeline, the head-hash skip, the parallel-agent handling and most of the review rules it applies come from there; the implementation in this repository is our own.
This project is licensed under the GNU General Public License v3.0. See COPYING.txt for details.