Does AI manage your infra?
Jesús Pérez
·
The problem is not the tool
What AI does well
✓
Generates syntactically correct YAML
✓
Completes Terraform that never breaks the plan
✓
Fills configuration gaps with reasonable defaults
✓
Translates intent into declarative form
What AI cannot do
✗
Know why that service cannot scale to N replicas
✗
Know the tension between latency and consistency in your system
✗
Remember the decision you made in December and why you rejected the alternative
✗
Understand what cannot break without cross-team coordination
Declarative ≠ understanding.
You describe the desired state, not the why.
You describe the desired state, not the why.
2am — when Terraform won’t talk
What you see when it fails
Error: Error creating Instance:
googleapi: Error 400: Invalid value
for field 'resource.machineType'
# The plan passed. The apply failed.
# What did the agent assume?
# Which region did it pick? Why that type?
# Is there an org constraint it never knew?# What the AI generated (6 weeks ago)
resource "google_compute_instance" "api" {
machine_type = "e2-medium" # "reasonable"
zone = "us-central1-a" # "default"
}
# What your org policy requires
# → only europe-west1, only n2-standard-*
# → the AI didn't know because you never wrote it down eitherThe pattern that repeats
With no explicit model
The AI invents plausible context. You assume it knows. It fails in prod.
With Stack Overflow
You copy code without understanding the assumption. At least you went looking.
With the AI
The agent generates with confidence. Confidence is contagious. So is the error.
The difference from Stack Overflow:
At least there you were actively searching.
With the AI, you delegate the search too.
At least there you were actively searching.
With the AI, you delegate the search too.
Your project lives in your head
What lives only in your head
→
Why this service cannot have more than 3 replicas
→
What happened when we tried to scale in January, and why we failed
→
The tension between the platform team and the product team over who controls networking
→
Which alternative was rejected, and why
→
Which invariant cannot be violated without breaking the agreement with the security team
What lives only in your head cannot be validated.
An agent cannot consult it.
A new teammate cannot consult it.
You cannot consult it yourself in 6 months.
An agent cannot consult it.
A new teammate cannot consult it.
You cannot consult it yourself in 6 months.
The README trap
# My Project
This service does X. It is deployed on GCP.
It uses Terraform. It has 3 environments: dev, staging, prod.
## Architecture
See diagram (out of date since March).
## Decisions
- We chose PostgreSQL because we didn't like MySQL.
- We use gRPC internally.✗
It doesn't say what cannot change
✗
It captures neither the rejected alternatives nor the why
✗
It is not queryable or verifiable — it is prose
✗
It does not reflect the current state —
it reflects the state when it was written
it reflects the state when it was written
The thesis
The ontology is not for the AI.
It is for you.
Formalizing invariants, tensions and current state
forces you to know what is true right now.
forces you to know what is true right now.
The AI benefits as a side effect.
It operates on what you already made clear.
It operates on what you already made clear.
The real value: the act of writing the ontology
is where YOU get clear, not the AI.
is where YOU get clear, not the AI.
Ontology ≠ a list of decisions
A list of decisions
- We chose Kubernetes
- We use Helm for deployments
- PostgreSQL as the primary database
- gRPC between internal services
- OAuth2 for external authentication Captures the what. It captures neither the why,
the rejected alternatives, nor the consequences.
the rejected alternatives, nor the consequences.
An ontology
INVARIANTS
What cannot change without an explicit decision and coordination
ACTIVE TENSIONS
Trade-offs not yet resolved — they live in the system right now
CURRENT → DESIRED STATE
Maturity dimensions. Where you are, where you want to be, what blocks you
ACTIVE GATES
Conditions that must hold before crossing an architectural boundary
It is a queryable graph. Not prose.
The AI can read it. Your CI can verify it. You can reason about it.
The AI can read it. Your CI can verify it. You can reason about it.
Ontoref — three files, three questions
core.ncl
"What IS this project?"
axioms:
- protocol-not-runtime
- self-describing
- sufficient-verification
tensions:
- formalization vs
adoption-friction
- ontology vs reflection
practices:
- ontology-three-file-split
- adr-lifecycle Immutable without a new ADR.
state.ncl
"Where ARE we?"
dimensions:
protocol-maturity:
current: protocol-stable
desired: protocol-stable
horizon: Months
operational-mode:
current: local
desired: daemon
catalyst:
ontoref-daemon-boot Evolves with the project.
gate.ncl
"When are we READY?"
membranes:
protocol-adoption-gate:
permeability: Low
protocol: Observe
active: true
protects:
- protocol stability
- schema versioning
content-vehicle-
convergence:
permeability: High
protocol: Absorb
active: true Crossing conditions.
Typed Nickel · exportable as JSON · queryable from Nu · verifiable in CI
Reflection — what BECOMES
Ontology = what IS
→ Invariants — structural truth
→ Tensions — living trade-offs
→ State — where we are now
Reflection = what BECOMES
→ Operational modes — sequences with a DAG of dependencies
→ ADRs with typed constraints — living decisions, not prose
→ Structured backlog — tensions → tasks
→ Session history — who did what and when
The ontology captures being.
Reflection captures operating on that being.
Reflection captures operating on that being.
A mode as an executable specification ```bash # reflection/modes/new_service.ncl { id = "new_service", trigger = "When adding a new service boundary", steps = [ { id = "draft-adr", actor = "developer", action = "Draft ADR for service boundary decision", }, { id = "verify-invariants", actor = "agent", action = "Check no invariant is violated", depends_on = [{ step = "draft-adr" }], }, { id = "seal-config", actor = "developer", action = "Apply initial config seal", depends_on = [{ step = "verify-invariants" }], }, ], } ```
Not a runbook. A typed acyclic graph.
The AI executes it. The system validates it.
The AI executes it. The system validates it.
AI as an actor, not an oracle
With no formalized ontology
# What the agent receives
"Help me scale this service"
# What the agent assumes
- that it can add replicas freely
- that the current state is the desired one
- that there are no org constraints
- that December's decision is irrelevant
# What it generates
resource "google_compute_instance" {
count = 5 # reasonable, right?
}With a formalized ontology
# What the agent receives (SessionStart hook)
INVARIANT: max-replicas-per-zone = 2
TENSION: scaling vs consistency [unresolved]
CONSTRAINT (adr-003): no horizontal scaling
without explicit capacity review
STATE: backend-maturity = single-stable
→ desired: multi-stable
→ blocker: capacity-review-pending
# What the agent can do
- Ask whether it is warranted given the blocker
- Generate the config within the limits
- Flag that the ADR must be reviewed first The agent operates on what you already made clear.
It stops inventing context because you stopped keeping it implicit.
It stops inventing context because you stopped keeping it implicit.
Who keeps this up to date?
The question that always comes up.
The real problem with the README
✗
Nobody has an incentive to update it —
it is not on the critical path
it is not on the critical path
✗
There is no signal for when it is stale
✗
Updating it takes the friction of free-form writing
✗
There is no verification — it can diverge silently
Ontoref’s design
Pre-commit as enforced synchronization
nickel typecheck on every commit — the declarative layer is never left brokenModes as mandatory procedures
Adding a service runs the mode — the ADR is written as part of the process
Drift detection
sha256(nickel export) — you know when the sealed state differs from the current oneADRs as constraints, not prose
The constraint is machine-readable — CI can verify it, not just read it
The ontology stays current because it is the path.
Not because someone is disciplined.
Not because someone is disciplined.
For the discussion
Thread 1 — Ontology
Isn't a good README enough?
When was the last time yours was up to date?
What sets an ontology apart from a list of decisions?
Structure, queryability, verifiability.
Who maintains this when the project moves fast?
The design makes it mandatory, not optional.
Thread 2 — Infra + AI
Is it different from copying Stack Overflow?
On SO you searched. With the AI, you delegate the search too.
Where is the minimum understanding you need?
Knowing what cannot break. Without that, you have no control.
Do internal platforms solve this, or hide it?
A platform with no ontology just moves the ignorance one level up.
AI can declare your infra.
It cannot understand it for you.
The ontology is the model that forces you to know what is true now.
Reflection is the operation over that model.
The AI is the actor that operates on what you already made clear.
Reflection is the operation over that model.
The AI is the actor that operates on what you already made clear.
Thank you. Questions?
jesusperez.pro · ontoref.dev
Was this useful? Rate it
Got something to add?
Tell me what you think, what you'd suggest, or whether we should keep exploring this topic.
· reads
Perspectives