d5ef629a54
Architecture, overview, homelab build plan, agent handbook, ADRs, and agent operating rules. All sensitive operational details sanitized (real IPs, hostnames, client names replaced with generic placeholders). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.3 KiB
Proactive Engineering Behaviour
These rules are written for Claude Code but the concepts apply to any AI agent system.
Before Any Task: System Consistency Check
Before starting any work, scan for known failure patterns and surface them explicitly. Do not wait for the operator to discover them. A good engineer notices the thing adjacent to the reported problem.
Check in particular:
- Settings allow list: does any rule auto-approve a class of commands that should require human confirmation?
- Hook chain: is every hook wired into settings AND executable?
- Tool manifest: does every tool listed have a named volume in compose.yml?
- compose.yml: does every named volume have a corresponding entry in the
volumes:block at the top? - Dockerfile: does every tool in the manifest appear in the Dockerfile?
After Any Fix: Propagation Check
After fixing a problem, ask: "what else has this same underlying issue?"
Examples:
- Fixed a missing volume for Codex → check Gemini has one too
- Fixed a broken hook → check all hooks are executable and wired
- Fixed a stale doc → check all docs referencing the same system state
The "What Layer Does This Live On?" Question
Before suggesting any install or configuration step inside a running container, explicitly state which Docker layer it targets:
| Layer | Survives | Notes |
|---|---|---|
| Image (Dockerfile RUN) | Everything | Requires image rebuild to change |
| Named volume | Restart + rebuild, NOT compose down -v |
Auth/config persistence |
| Bind mount | Everything | Host filesystem |
| Container overlay | Nothing — EPHEMERAL | Wrong layer for anything durable |
If the answer is "container overlay": stop. That is the wrong layer.
New Tool Checklist (from ADR-001)
No new CLI tool is complete until ALL of these are done:
- Binary baked into Dockerfile (RUN line)
- Named volume defined in compose.yml volumes block
- Named volume mounted to auth directory in service definition
- Tool listed in bootstrap manifest
- Bootstrap script has a "Found / Not found" check for the binary
- Documentation updated with tool entry
Partial completion = broken. A tool with binary but no volume loses auth on compose down. A tool with volume but no binary vanishes on image rebuild.