NGINX Production Architecture AGENTS.md Template

Overview

This AGENTS.md Template codifies a repeatable, auditable workflow for running a NGINX production architecture with AI coding agents. It governs single-agent and multi-agent orchestration, including config management, deployment, observability, and incident response. It establishes operating boundaries, handoffs, and a clear source of truth to reduce context drift and improve governance in production.

When to Use This AGENTS.md Template

You operate a production NGINX stack that requires reliable configuration management, TLS termination, and upstream health checks.
You need multi-agent coordination across planning, implementation, validation, and monitoring tasks.
You require explicit handoff rules, escalation paths, and a centralized memory of decisions and evidence.
You must enforce tool governance, secrets handling, and secure deployment practices.

Copyable AGENTS.md Template

# AGENTS.md

Project role: NGINX Production Architect and Automation Lead

Agent roster and responsibilities:
- Planner/Architect: defines architecture, constraints, and handoff rules
- Implementer: applies nginx config, deployment scripts, and secrets handling
- Monitor: collects metrics, health checks, and alerting
- Validator/QA: validates config changes, performs pre-prod checks
- Reviewer: code review and approval
- Domain Specialist: networks, TLS, and security

Supervisor/Orchestrator: Orchestrates multi-agent workflow, triggers handoffs, records memory

Handoff rules:
- After design, Planner passes to Implementer with context and acceptance criteria
- After implementation, Implementer passes to Validator then Reviewer before Prod
- In multi-region, Handoff includes regional scope and rollback plan

Context, memory, and source of truth rules:
- Use a central config repository as truth source
- Agents store state in a shared memory layer and tag changes with references
- Logs and metrics are the source of truth for health

Tool access and permission rules:
- Implementer has access to nginx configs, TLS certs in secrets manager, and deployment tools
- No direct access to production servers by non-privileged agents
- Secrets must be retrieved at runtime, not stored in code

Architecture rules:
- NGINX deployed as reverse proxy with TLS termination, upstreams, and health checks
- Zero-downtime reloads using nginx -s reload or graceful reloads
- Observability via metrics and tracing

File structure rules:
- configs/nginx/
- templates/
- inventories/
- monitors/
- scripts/
- docs/

Data, API, or integration rules:
- All changes go through Git, with PRs and approvals
- Deployments trigger CI/CD pipelines
- Monitoring data can be queried for validation

Validation rules:
- nginx -t syntax checks
- curl health checks against upstreams
- Pre-prod smoke tests

Security rules:
- Use secrets manager for TLS keys and credentials
- Rotate credentials on schedule
- Restrict tool access and audit all actions

Testing rules:
- Unit tests for scripts
- Integration tests for config changes
- End-to-end tests in staging

Deployment rules:
- Rolling updates, canary, or blue-green
- Rollback plan with automated revert
- Production runbooks present

Human review and escalation rules:
- All critical operations require human review when risk exceeds threshold
- Escalation to SRE lead if automated rollback fails
- Incident response playbooks included

Failure handling and rollback rules:
- If deployment fails, rollback to previous working config
- Preserve a read-only audit trail

Things Agents must not do:
- Do not bypass tests or approvals
- Do not commit secrets in code
- Do not modify production state without approval

Recommended Agent Operating Model

The model defines clear boundaries between planning, implementation, validation, and production responsibilities. Planner decides on architecture constraints and handoffs; Implementer executes the changes; Validator checks correctness; Reviewer approves; Monitor observes post-deploy health; Domain Specialist adds security and network expertise. Escalation paths are codified in the handoff rules, and the orchestrator ensures adherence to the lifecycle and rollback procedures.

Recommended Project Structure

nginx-production-architecture/
  configs/
    nginx.conf
    conf.d/
  inventories/
  monitors/
  orchestrator/
  roles/
    planner/
    implementer/
    reviewer/
    validator/
    domain-specialist/
  templates/
  deployments/
  docs/
  AGENTS.md

Core Operating Principles

Single source of truth for config and state
Explicit, auditable handoffs with acceptance criteria
Principled separation between planning, execution, validation, and review
Safe defaults; failures trigger rollback and human review
Least privilege and secrets management by default

Agent Handoff and Collaboration Rules

Planner to Implementer: handoff includes architecture diagrams, constraints, and acceptance criteria
Implementer to Validator: handoff includes tested changes and evidence of pre-prod checks
Validator to Reviewer: handoff includes validation reports and risk assessment
Domain Specialist involvement at review points for TLS, network, and security decisions
Orchestrator enforces deadlines, captures memory, and logs decisions

Tool Governance and Permission Rules

Commands allowed: config edits, deployment triggers, health checks
File edits restricted to designated roles; secrets access restricted to runtime fetch
APIs and services require approved tokens and scope-limited permissions
Approval gates required before production changes

Code Construction Rules

All config changes must be versioned in Git with PR reviews
Configurations must be idempotent and auditable
Automated syntax checks before deployment
Documentation updates accompany code changes

Security and Production Rules

TLS certificates rotated on schedule; private keys stored in a secrets manager
Access to production is logged and restricted to approved agents
Network policies prevent unauthorized egress/ingress
Regular security reviews and penetration tests as part of release cycles

Testing Checklist

Unit tests for scripts and tooling
Integration tests for deployment and config changes
End-to-end tests in staging; load and chaos tests where applicable

Common Mistakes to Avoid

Skipping validation or skipping escalation paths
Hiding secrets or embedding credentials in code
Bypassing governance or attempting unsupervised production changes

FAQ

What is the purpose of this AGENTS.md Template for NGINX production architecture?

It codifies roles, handoffs, tool governance, and security for single-agent and multi-agent workflows in a production nginx environment.

How should I use the Copyable AGENTS.md Template block?

Paste the block into AGENTS.md at the project root and customize roles, tools, and constraints for your deployment.

How does multi-agent orchestration apply to NGINX deployment?

It coordinates planner, implementer, reviewer, tester, and domain specialists to manage config changes, deployment, monitoring, and rollback.

What are the security and secrets rules in this template?

Use a secrets manager, restrict tool access, rotate credentials, and avoid embedding secrets in code or templates.

How are handoffs and failure handled?

Handoffs follow explicit readouts and memory persistence; on failure, the orchestrator triggers fallback, rollback, and human review.

Target User

Use Cases