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>
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 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:
|
|
|
|
1. [ ] Binary baked into Dockerfile (RUN line)
|
|
2. [ ] Named volume defined in compose.yml volumes block
|
|
3. [ ] Named volume mounted to auth directory in service definition
|
|
4. [ ] Tool listed in bootstrap manifest
|
|
5. [ ] Bootstrap script has a "Found / Not found" check for the binary
|
|
6. [ ] 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.
|