From 81fad536f924693290ee2d49c53f01b9f8749b0c Mon Sep 17 00:00:00 2001 From: Grant Date: Thu, 7 May 2026 22:35:43 +0000 Subject: [PATCH] docs: add CLAUDE.md with behaviour rules and terminal conventions --- CLAUDE.md | 249 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..049fcee --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,249 @@ +# Argonaut 3 — ROV Autonomous Inspection System +This file defines how Claude should behave when working in this repository. +Prioritise correctness, safety, and field-operational reliability above all else. +This is a real autonomous vehicle system. Code runs on hardware in water. + +--- + +# Project Identity + +- **Project:** Argonaut 3 — Autonomous Underwater ROV Inspection System +- **Company:** SymbyTech +- **Vehicle:** Argonaut 3 based on the BlueROV2 Heavy (Blue Robotics) +- **Target:** Hull and jacket surveys, no human operator during field operations +- **Status:** Active development — Phase 2 (dev infrastructure) complete + +--- + +# Tech Stack + +- **Primary language:** Python 3 (ROS2 nodes), C++ reserved for latency-critical paths only +- **Framework:** ROS2 Jazzy Jalisco +- **Vehicle OS:** BlueOS (Blue Robotics) on Raspberry Pi 4 +- **Autonomy compute:** Raspberry Pi 5, Ubuntu 24.04 LTS +- **MAVLink bridge:** MAVROS +- **Container runtime:** Docker (ARM64 images via buildx + QEMU) +- **Registry:** Harbor (self-hosted) — `registry.symbytech.com` +- **Source control:** Gitea (self-hosted) — `git.symbytech.com` +- **GCS:** Cockpit (BlueOS extension) +- **Dev simulation:** BlueOS internal ardupilot-manager SITL (ArduSub 4.5.7) +- **Package manager:** pip (Python), colcon (ROS2 workspace) + +--- + +# Repository Structure + +``` +rov-autonomy/ +├── src/ +│ ├── rov_interfaces/ # Custom ROS2 messages and services — shared contracts +│ ├── rov_navigation/ # State estimation, EKF, depth fusion +│ ├── rov_perception/ # Camera nodes, feature detection +│ ├── rov_control/ # Failsafe monitor, motion controller +│ ├── rov_mission/ # Mission executor, waypoint sequencing +│ ├── rov_bringup/ # Top-level launch files +│ └── rov_simulation/ # DEV ONLY — mock publishers, test scenarios +├── Dockerfile # ARM64 image build — targets RPi5 +├── docker-entrypoint.sh # Container startup — sources ROS2 + workspace +└── CLAUDE.md # This file +``` + +**Critical rule:** `rov_simulation` is dev-only. Never include it in production builds or deploy it to vehicle hardware. + +--- + +# Core Principles + +- **Asset preservation over mission completion.** A recovered vehicle can repeat a mission. A lost vehicle cannot. +- **Field-operational from day one.** The same codebase runs in dev and field — environment is selected by config, not by code changes. +- **Safety is continuous, not reactive.** Failsafe monitoring runs at all times, not only on failure. +- **Prefer simple, readable solutions.** This code may be read under pressure in the field. +- **No premature optimisation.** Correctness first, performance when measured. +- **Keep functions small and single-purpose.** +- **Do not introduce new dependencies without explicit approval.** Each dependency is a liability on embedded hardware. + +--- + +# Code Style + +- Follow PEP 8 for Python +- Use consistent formatting already present in the file being edited +- Prefer explicit code over clever shorthand +- Always add full inline comments — every function, every non-obvious line +- Use meaningful variable and function names — no abbreviations unless standard ROS2/MAVLink convention +- Avoid deeply nested logic (>3 levels) +- No commented-out code in final output +- All ROS2 nodes must have a module-level docstring listing: purpose, subscribed topics, published topics, services + +--- + +# ROS2 Rules + +- All custom messages live in `rov_interfaces` — do not define messages inside other packages +- Always declare parameters explicitly with `declare_parameter()` before `get_parameter()` +- Load configuration from YAML files via launch — do not hardcode values in nodes +- Use `self.get_logger()` for all logging — never `print()` +- Timers must be named and cancellable when rate changes are required +- Topic names use the `/rov/` prefix namespace for all custom topics +- Always include a `Header` with timestamp in custom messages +- Destroy nodes cleanly in `finally` blocks + +--- + +# Failsafe Rules + +**These are safety-critical. Do not change without explicit instruction and design review.** + +- Assessment states: GREEN / AMBER / RED — defined in `FailsafeStatus.msg` +- Assessment runs continuously at dynamic rates: 5 Hz (GREEN), 20 Hz (AMBER), 50 Hz (RED) +- Priority order is fixed — see `ROV_Failsafe_Design_v2.0.md` +- All thresholds are configurable via YAML — never hardcode safety values +- `EMERGENCY_SURFACE` is the last resort — it must never be the first response +- Comms timeout default: 2 seconds — configurable per deployment +- Battery thresholds: warning 25%, return 20%, critical 12%, emergency 8% + +--- + +# Package-Specific Rules + +**rov_interfaces** +- Changing a message definition requires updating all nodes that use it +- Constants in messages use ALL_CAPS naming +- Never remove a field from a message without confirming no node depends on it + +**rov_control** +- `failsafe_monitor.py` must always be the first node started in any launch file +- Do not modify the priority order in `_apply_failsafe_priority()` without design review + +**rov_mission** +- Waypoints are loaded from YAML files — never hardcoded +- The breadcrumb buffer must be cleared at mission start and never between waypoints +- Entry point is recorded once at mission start — do not update it during flight + +**rov_simulation** +- Every file in this package must have the `DEV ONLY — NOT FOR DEPLOYMENT` warning in its docstring +- Scenario names must be documented in the node docstring +- Never subscribe to real hardware topics from simulation nodes + +**rov_bringup** +- Launch files must load config from the package share directory — never from absolute paths +- The `env` argument selects between `dev` and `field` configs — always provide a default of `dev` + +--- + +# Docker / Build Rules + +- Target architecture: `linux/arm64` — always build with `--platform linux/arm64` +- Build script: `~/build-rov.sh [tag]` — defaults to `:dev` +- Never build x86 images for the vehicle — they will silently fail on RPi5 +- The `rov_simulation` package must be excluded from production image builds +- Do not modify the `Dockerfile` base image without checking ROS2 Jazzy compatibility + +--- + +# Git Rules + +- Commit messages follow conventional commits format: `feat:`, `fix:`, `docs:`, `refactor:` +- Do not commit directly to `master` without instruction +- Keep commits focused — one logical change per commit +- Always commit config changes alongside the code that depends on them +- Branch: `master` is the working branch for this project + +--- + +# Dev Environment + +**Terminal conventions (always use these labels):** +- `[SERVER]` — SSH session on SymbyTech server (192.168.1.175 / Tailscale: 100.104.236.104) +- `[VM]` — SSH session on BlueOS VM (192.168.122.89 / Tailscale: 100.84.141.120) +- `[GIT]` — Git Bash on laptop +- `[LAPTOP]` — Windows Command Prompt on laptop + +**Key addresses:** +- BlueOS: `http://100.84.141.120` +- Cockpit: via BlueOS sidebar +- Harbor: `https://registry.symbytech.com` +- Gitea: `https://git.symbytech.com` + +**BlueOS session requirements:** +- Enable Pirate Mode (skull icon) each session — resets due to no bootstrap container +- Cockpit MAVLink2REST: `ws://100.84.141.120/mavlink2rest/ws/mavlink` +- Vehicle network connection: `100.84.141.120` + +--- + +# Testing + +- `rov_simulation` provides mock publishers for all MAVROS topics +- Five test scenarios: `nominal`, `low_battery`, `comms_loss`, `depth_warning`, `all_clear` +- Dev stack launch: `ros2 launch rov_simulation dev_stack.launch.py scenario:=` +- Do not remove existing test scenarios without confirming intent +- Add new scenarios for any new failsafe condition added to the design + +--- + +# Claude Behaviour Rules + +- Always read existing code in a file before modifying it +- Always read the relevant design document before implementing a feature +- Always check message definitions in `rov_interfaces` before writing node code +- Explain assumptions before making architectural changes +- If requirements are unclear, ask before implementing +- Prefer incremental changes over large rewrites +- Never delete code without confirming intent +- If a safer or simpler approach exists, suggest it before proceeding +- Do not refactor unrelated code +- Do not optimise prematurely + +--- + +# What Claude SHOULD do + +- Implement features step-by-step with verification at each step stating if feedback is expected +- Fix bugs with minimal disruption to surrounding code +- Add comments to every function and non-obvious block +- Highlight safety risks when they exist +- Suggest better approaches when appropriate +- Verify file structure and entry points after creating new nodes + +--- + +# What Claude should NOT do + +- Do not restructure the package layout unless explicitly asked +- Do not introduce new Python packages without approval +- Do not rewrite working code for style +- Do not assume missing requirements — ask +- Do not hardcode thresholds, addresses, or paths +- Do not deploy or reference `rov_simulation` in production launch files +- Do not change the failsafe priority order without design review +- Do not use `print()` — always use `self.get_logger()` +- Do not build x86 Docker images for vehicle deployment + +--- + +# When Uncertain + +1. Stop implementation +2. State the ambiguity clearly +3. Provide a suggested approach with trade-offs +4. Wait for confirmation before proceeding + +--- + +# Key Design Documents + +All in the Claude project knowledge base: + +| Document | Purpose | +|---|---| +| `ROV_Project_Handover_v2.3.md` | Master reference — architecture, environment, commands | +| `ROV_Failsafe_Design_v2.0.md` | Failsafe state machine, sensor roadmap, priority order | +| `Argonaut3_UI_Design_v1.1.md` | Cockpit extension and widget specifications | + +Always use the highest version +--- + +# Notes + +This is a production-oriented autonomous safety system. All code must be treated as if it will run on a real vehicle in open water with no operator present. Safety, correctness, and reliability are non-negotiable.