opencode-ansible: Agent-Native Infrastructure as Code mit OpenCode

OpenSpec vs. the Specification Framework Landscape: Why DevOps Needs AI-Native Specs

A technical comparison of OpenSpec against OpenAPI, ADRs, RFCs, BDD/Gherkin, and traditional project management — and why the AI agent era demands a fundamentally different approach to change management.

Die Infrastruktur-Lücke beim Agentic Coding

KI-Coding-Agenten haben die Art und Weise, wie wir Applikationscode schreiben, transformiert. Sie erstellen Projektgerüste, implementieren Features, beheben Bugs und führen Refactorings mit zunehmender Zuverlässigkeit durch. Doch es gibt einen Bereich, in dem die meisten Agenten immer noch Schwierigkeiten haben: das Infrastruktur-Management.

Der Grund dafür ist simpel. Applikations-Codebases folgen gut verstandenen Konventionen – TypeScript-Projekte folgen src/, Frameworks geben Dateipfade vor und Linter erzwingen die Formatierung. Infrastruktur-Repositories hingegen sind oft idiosynkratisch. Jeder DevOps-Engineer hat seinen eigenen Ansible-Stil, seine eigene Variablenbenennung und seine eigene Rollenstruktur. Ein KI-Agent, der in ein unbekanntes Ansible-Repo geworfen wird, hat keine Möglichkeit zu erschließen, ob Variablen in defaults/main.yml oder vars/main.yml hingehören, ob Tasks name: mit oder ohne Doppelpunkt verwenden oder ob die Konvention eine Rolle pro Playbook oder viele Rollen ist.

opencode-ansible löst dies durch die Bereitstellung eines agent-nativen Infrastruktur-Skeletts – ein öffentliches Ansible-Repository, das speziell für AI-first Operations strukturiert ist.

Architektur

Das Repository ist um drei Ebenen der Agenten-Interaktion organisiert:

Ebene 1: Der Agenten-Kontrakt

Zwei Dateien definieren, wie Agenten mit dem Repository interagieren:

AGENTS.md — Der Kontext-Kontrakt für den Agenten. Er enthält die Projektübersicht, die Betriebsprinzipien (deklarativ statt imperativ, idempotente Operationen, agentenfreundliches YAML), die vollständige Konvention der Rollenstruktur, Anforderungen an die Task-Benennung inklusive Beispielen sowie das Protokoll für Änderungen, dem die Agenten folgen müssen. Ein Agent, der das Repository betritt, liest zuerst diese Datei.

SKILL.md — Eine OpenCode-Skill-Definition, die automatisch geladen wird, wenn der Agent erkennt, dass er in einem Ansible-Repository arbeitet. Sie bietet Dokumentationen zu den Fähigkeiten, Schnellbefehle und Links zu verfügbaren Skripten.

Ebene 2: Die Ausführungsstruktur

opencode-ansible/
├── .opencode/agents/         # Three agent roles
│   ├── sysadmin.yaml         # Day-to-day operations
│   ├── deployer.yaml         # Application deployment
│   └── security.yaml         # Security posture
├── inventory/
│   ├── hosts.yml             # Host definitions
│   └── group_vars/           # Hierarchical variables
├── roles/                    # Reusable roles
│   ├── sysctl/               # Kernel tuning
│   ├── docker/               # Docker engine
│   └── ...                   # User-defined roles
├── playbooks/
│   ├── site.yml              # Master playbook
│   ├── bootstrap.yml         # Initial host setup
│   ├── security.yml          # Firewall + SSH hardening
│   ├── monitoring.yml        # Prometheus/node_exporter
│   └── docker.yml            # Docker deployment
├── role-skeletons/           # Scaffold templates
│   ├── config-deploy/        # Config file deployment
│   ├── docker-compose-service/ # Docker Compose services
│   ├── systemd-wrapper/      # Systemd service units
│   ├── pip-package/          # Python package installation
│   └── sysctl-tune/          # Kernel parameter tuning
├── scripts/
│   ├── new-role              # Scaffold new roles
│   └── validate              # Lint + syntax check
├── AGENTS.md
├── SKILL.md
├── Makefile
└── ansible.cfg

Das Verzeichnis .opencode/agents/ definiert drei spezialisierte Agenten-Personas. Wenn OpenCode eine Infrastruktur-Anfrage erhält, wird diese basierend auf der Intention an den entsprechenden Agenten geroutet – ein Security-Audit geht an den security-Agenten, ein Deployment an den deployer-Agenten und die routinemäßige Wartung an den sysadmin-Agenten.

Ebene 3: Guardrails

Das Skelett bettet Sicherheitsmechanismen ein, die Agenten vor der Durchführung von Änderungen nutzen müssen:

• make try — Führt ansible-playbook --check --diff gegen localhost aus.
• make lint — Führt ansible-lint sowie eine Syntax-Validierung aus.
• ./scripts/validate — Kombinierter Lint- und Syntax-Check für CI-Pipelines.

Diese werden in AGENTS.md als obligatorische Pre-Commit-Schritte referenziert. Ein Agent, der die Validierung überspringt, verletzt sein eigenes Betriebsprotokoll.

Warum konventionelle Ansible-Repos bei Agenten scheitern

Traditionelle Ansible-Repositories kodieren Konventionen implizit. Häufige Anti-Pattern, die KI-Agenten verwirren:

Das opencode-ansible-Skelett eliminiert diese Fehlerquellen, indem es jede Konvention explizit und auffindbar macht.

Das Rollen-Skelett-System

Die wichtigste Design-Entscheidung ist das Rollen-Skelett-System. Wenn ein Agent eine neue Rolle erstellen muss (z. B. nginx), erfindet er die Struktur nicht aus dem Nichts. Er referenziert das entsprechende Skelett:

# Example: Agent creating an nginx role
# 1. Agent reads role-skeletons/config-deploy/
# 2. Agent copies structure to roles/nginx/
# 3. Agent populates:
#    - defaults/main.yml with all configurable values
#    - tasks/main.yml with idempotent tasks
#    - handlers/main.yml with reload/restart handlers
#    - templates/nginx.conf.j2 with service-specific Jinja2
# 4. Agent validates with make lint
# 5. Agent dry-runs with make try
# 6. Agent commits with descriptive message

Dies garantiert, dass jede Rolle im Repository denselben Konventionen folgt, unabhängig davon, welcher Agent sie wann erstellt hat.

Real-World Use Case: Memory Management

Ein praktisches Beispiel dafür, warum diese Struktur wichtig ist, ist das Management von Arbeitsspeicher in einem heterogenen Cluster.

Betrachten wir ein Setup mit 7 Hosts: GPU-Server (DGX Spark, AI-Nodes), Webserver, Datenbank-Hosts und Entwicklungs-Workstations. Jeder hat unterschiedliche Speicheranforderungen:

• GPU-Server benötigen Hugepage-Konfigurationen und vm.overcommit für vLLM/llama.cpp
• Datenbank-Hosts benötigen Swappiness-Tuning für Neo4j
• Workstations benötigen Speicherlimits für containerisierte Dienste

Ohne einen strukturierten Ansatz verteilen sich diese Konfigurationen über sysctl-Dateien, Docker-Daemon-Configs und Service-Unit-Dateien. Mit opencode-ansible besitzt die sysctl-Rolle bereits die Struktur für das Tuning von Kernel-Parametern, die group_vars/-Hierarchie trennt die Konfiguration pro Host-Typ, und das Monitoring-Playbook liefert die Observability-Ebene.

Ein Agent kann einen neuen Memory-Tuning-Parameter hinzufügen, indem er roles/sysctl/defaults/main.yml bearbeitet, die Host-Gruppenvariable in inventory/group_vars/ ergänzt und dies mit make try verifiziert – alles innerhalb der etablierten Konventionen.

Integration in bestehende Ansible-Deployments

Das Skelett ist darauf ausgelegt, adaptiert und nicht komplett übernommen zu werden. Wenn Sie bereits ein Ansible-Setup haben:

1. Kopieren Sie AGENTS.md und SKILL.md in Ihr bestehendes Repo – diese Dateien sind additiv und stehen nicht im Konflikt mit der bestehenden Struktur.
2. Passen Sie Ihre Rollenstruktur im Laufe der Zeit an die Konventionen des Skeletons an – beginnen Sie mit der Benennung von Tasks und gehen Sie dann zu den Rollen-Skeletons über.
3. Fügen Sie role-skeletons/ hinzu – erstellen Sie Templates aus Ihren bisher besten Rollen, damit Agents diese replizieren können.
4. Fügen Sie das Verzeichnis .opencode/agents/ hinzu – definieren Sie Agent-Rollen, die Ihren operationalen Mustern entsprechen.

Der Wert steigt exponentiell mit der Weiterentwicklung des Repos, da jede neue Rolle und jedes Playbook denselben Konventionen folgt, die die Agents bereits verstehen.

Das große Ganze: Operationale Konsistenz in der Skalierung

Agent-native Infrastrukturverwaltung bedeutet nicht, DevOps-Engineers zu ersetzen. Es geht darum, die „Context-Switching Tax“ zu eliminieren, die die Arbeit an der Infrastruktur verlangsamt.

Ein Senior Engineer, der 30 Server über 3 Umgebungen hinweg verwaltet, verbringt die meiste Zeit mit Kontextwechseln: Er prüft, welche Server welche Konfigurationen haben, verifiziert, ob eine Änderung etwas beschädigt, und erinnert sich an die exakte Konvention, die dieses spezifische Repo verwendet. Ein AI-Agent, der die Konventionen versteht, Validierungen automatisch ausführt und Änderungen erzeugt, die den etablierten Mustern entsprechen, reduziert diesen Overhead drastisch.

Das opencode-ansible Skeleton ist das Infrastruktur-Äquivalent zu einem gut strukturierten Application Template – es schreibt Ihre Playbooks nicht für Sie, aber es macht jede Interaktion zwischen Mensch, Agent und Infrastruktur vorhersehbar und zuverlässig.

Das Repository ist öffentlich auf GitHub unter der MIT-Lizenz verfügbar.