AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: argocd-gitops-declarative

ArgoCD GitOps Declarative Application & Self-Healing Standard

Declarative GitOps continuous delivery with ArgoCD. Forbids manual imperative kubectl commands; mandates versioned Application CRDs, automated sync policies with selfHeal and prune enabled, and sync wave ordering.

Prohibited Anti-Pattern: AI recommends manual kubectl edit/patch commands creating uncontrolled cluster drift away from Git.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: ArgoCD GitOps Declarative Application & Self-Healing Standard - Declarative GitOps continuous delivery with ArgoCD. Forbids manual imperative kubectl commands; mandates versioned Application CRDs, automated sync policies with selfHeal and prune enabled, and sync wave ordering.
globs: argocd/**/*.yaml, gitops/**/*.yaml, apps/**/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/argocd-gitops-declarative"
---

# ArgoCD GitOps Declarative Application & Self-Healing Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: AI recommends manual kubectl edit/patch commands creating uncontrolled cluster drift away from Git.

## System Constraints
You are a GitOps and continuous delivery specialist. In an ArgoCD environment, NEVER run manual 'kubectl apply' or 'kubectl edit' in production clusters. All infrastructure and application state must be declaratively declared in Git. Use ArgoCD Application CRDs with automated selfHeal, prune, and sync waves for deterministic deployment sequences.

## Strict Guidelines
- Never perform manual hotfixes via kubectl in production; push commits to the GitOps repository to trigger automated reconciliation.
- Configure automated syncPolicy with prune: true (removes deleted resources) and selfHeal: true (reverts manual cluster tampering).
- Use ArgoCD sync waves ('argocd.argoproj.io/sync-wave') to sequence dependencies (e.g. CRDs and databases before application pods).
- Prevent infinite sync loops by properly configuring ignoreDifferences for fields managed by cluster controllers (e.g., HPA replica counts).

## Bad vs Good Implementations
### Declarative ArgoCD Application with Auto-Sync & Prune vs Manual kubectl Drift

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Manual cluster edits create invisible state drift that breaks disaster recovery and automated rebuilds.
```yaml
# ANTI-PATTERN: Manual imperative kubectl commands causing GitOps drift
# kubectl patch deployment web -p '{"spec":{"replicas":10}}'
# Result: When Git syncs, manual patch is unexpectedly overwritten, or cluster drifts permanently!
```

#### Production Standard (Correct)
> **Standard**: Declarative Application CRD guarantees Git remains the single source of truth, automatically healing unauthorized manual cluster modifications.
```yaml
# PRODUCTION STANDARD: Declarative ArgoCD Application Manifest
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-api-cluster
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/acme-corp/gitops-manifests.git
    targetRevision: main
    path: environments/production/api
  destination:
    server: https://kubernetes.default.svc
    namespace: api-production
  syncPolicy:
    automated:
      prune: true     # Automatically deletes resources removed from Git
      selfHeal: true  # Reverts manual edits made directly on cluster
      allowEmpty: false
    syncOptions:
      - CreateNamespace=true
      - PruneLast=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
```

### Database Migration Sequencing via Sync Waves

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Deploying migrations and pods without ordering triggers race conditions and downtime.
```yaml
# ANTI-PATTERN: Application pod and DB migration deployed concurrently
# Web pod crashes with 'Table not found' before migration completes!
```

#### Production Standard (Correct)
> **Standard**: Sync waves ensure database migrations finish successfully before traffic-serving application pods roll out.
```yaml
# PRODUCTION STANDARD: ArgoCD Sync Wave Ordering
# 1. Database migration runs in Wave 0
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration-job
  annotations:
    argocd.argoproj.io/sync-wave: "0"
    argocd.argoproj.io/hook: Sync
# ...
---
# 2. Application Deployment only starts in Wave 1 after migration succeeds
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-service
  annotations:
    argocd.argoproj.io/sync-wave: "1"
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

ArgoCD Application Inspector
Inspect ArgoCD sync status, health checks, and diffs between Git and cluster.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

ArgoCD GitOps Scaffolder
Scaffold App-of-Apps patterns and declarative ArgoCD manifests.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: ArgoCD GitOps Declarative Application & Self-Healing Standard

ArgoCD GitOps Declarative Application & Self-Healing Standard defines an industrial-grade behavioral standard for devops engineering. Declarative GitOps continuous delivery with ArgoCD. Forbids manual imperative kubectl commands; mandates versioned Application CRDs, automated sync policies with selfHeal and prune enabled, and sync wave ordering. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI recommends manual kubectl edit/patch commands creating uncontrolled cluster drift away from Git. Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftAI recommends manual kubectl edit/patch commands creating uncontrolled cluster drift away from Git.Critical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Never perform manual hotfixes via kubectl in production

Never perform manual hotfixes via kubectl in production; push commits to the GitOps repository to trigger automated reconciliation.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Configure automated syncPolicy with prune

Configure automated syncPolicy with prune: true (removes deleted resources) and selfHeal: true (reverts manual cluster tampering).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Use ArgoCD sync waves ('argocd.argoproj.io/sync-wave') to sequence dependencies (e.g. CRDs and databases before application pods).

Use ArgoCD sync waves ('argocd.argoproj.io/sync-wave') to sequence dependencies (e.g. CRDs and databases before application pods).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Prevent infinite sync loops by properly configuring ignoreDifferences for fields managed by cluster controllers (e.g., HPA replica counts).

Prevent infinite sync loops by properly configuring ignoreDifferences for fields managed by cluster controllers (e.g., HPA replica counts).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is ArgoCD GitOps Declarative Application & Self-Healing Standard critical for AI coding assistants?

Declarative GitOps continuous delivery with ArgoCD. Forbids manual imperative kubectl commands; mandates versioned Application CRDs, automated sync policies with selfHeal and prune enabled, and sync wave ordering. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI recommends manual kubectl edit/patch commands creating uncontrolled cluster drift away from Git.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

ArgoCD