Skip to content

AI-assisted operations

Claude Code and Codex help plan, implement, and review repository changes. The repository remains the shared source of truth, and the operator remains responsible for decisions that affect the live system.

Starting a task

The amount of process scales with the change. A small documentation correction can go straight from inspection to editing and a focused check. Work with meaningful design choices, operational risk, or several stages starts with a short plan.

Every tracked change begins by fetching the current origin/main, reading the relevant repository instructions and files, and creating a task branch in a separate git worktree.

Before substantive work, the agent recommends a model and reasoning effort only when the choice could materially affect quality, cost, or latency. It also defines the goal, scope, non-goals, acceptance criteria, and who owns implementation and review.

Codex normally plans and implements while Claude Code reviews the resulting diff. Separate branches and worktrees keep concurrent sessions from editing the same working tree.

For work likely to span sessions, the agreed plan can be tracked as a goal and the agent keeps a concise status or handoff document current. Completed design detail remains available in Git history; only durable operating facts belong in the main documentation.

In Codex, /plan is the normal next step while an outcome is still being shaped. /goal can track agreed multi-step work, and /review starts an independent review after substantive changes. An unrelated task starts with /new; /clear is reserved for discarding the current thread.

Decisions and risk

Agents inspect the repository before asking questions. An operator checkpoint is used only when an unresolved choice could materially change behavior, permissions, data handling, external exposure, recovery, or accepted risk. The checkpoint explains the consequences and recommends a default where the repository provides enough evidence.

Security-sensitive changes receive a focused threat-model pass. Important invariants and failure cases are mapped to implementation locations and tests, including unauthorized, repeated, interrupted, and partial-failure cases where they apply. Passing automation or receiving an AI review with no findings is not treated as proof that a system is secure.

Implementing and reviewing

Changes are made in small stages and checked with the repository's existing tests and validation commands. The normal local test entrypoint is:

bash tests/run.sh

It renders documentation-only fixtures under .generated-test/ and then runs the Bash test suite without touching the production .generated/ configuration. Documentation changes also use mkdocs build --strict.

The reviewer receives a read-only change scope and reports concrete, evidence-based findings. The author verifies each finding against the actual code, fixes valid issues, and requests another review after non-trivial corrections. A pull request and CI provide the integration path to main; CI runs the test suite, validates all four Compose projects, scans for secrets, and checks shell, monitoring, and Ansible configuration.

Operational boundaries

  • Live deployments, remote access, service restarts, and host changes require explicit operator authorization.
  • Credentials and private deployment data never enter commits, review bundles, documentation, or broad diagnostic output. See Security boundaries.
  • Diagnostics query only the specific non-secret property needed. If a secret appears unexpectedly, that diagnostic path stops and the affected credential is rotated or revoked before work continues.
  • After substantive changes, public-safe operating facts are synchronized into committed documentation. Machine-local coordination and credentials remain outside version control.