Skip to content

AGENTS.md

Latest commit

 

History

History
93 lines (74 loc) · 7.13 KB

AGENTS.md

File metadata and controls

93 lines (74 loc) · 7.13 KB
Raw

AGENTS.md

This file provides context for AI coding agents contributing to the DevOps Engineer learning path.

Context

This repository is part of the TP-Coder-Innovation-Hub learning platform. It contains educational content (README guides, code examples, diagrams, and labs) that teach DevOps engineering from entry-level to senior practitioners. The content is designed for self-paced learning and instructor-led workshops.

Audience

  • Beginner learners: Career changers, CS students, junior engineers new to DevOps. They understand basic programming but have limited infrastructure experience.
  • Intermediate practitioners: Engineers with 1-3 years of experience who have used Docker and CI/CD but want deeper understanding and production-grade skills.
  • Advanced architects: Engineers designing CI/CD platforms, Kubernetes clusters, or internal developer platforms. They need architectural guidance, not tutorials.

How to Help

  • Teach the "why" behind every tool and practice. A learner who memorizes kubectl apply without understanding declarative state management will struggle when things break. Explain the mental model, then the commands.
  • Provide complete, runnable examples. Dockerfiles, GitHub Actions YAML, and Kubernetes manifests should work as-is or with minimal substitution (image names, URLs).
  • Use Mermaid diagrams for architecture and pipeline visualizations. They render natively on GitHub.
  • Reference 2026 ecosystem standards. Prefer GitHub Actions over Jenkins, Prometheus over Nagios, ArgoCD over Flux for initial learning (ArgoCD has stronger UI and documentation for newcomers).
  • Include security as a default, not an addendum. Every Dockerfile example should use non-root users. Every pipeline should include a scanning step.
  • Structure content with progressive depth. Start with the concept, add implementation details, then advanced patterns. Learners naturally navigate by their experience level.
  • When comparing tools, be honest about tradeoffs. Kubernetes is powerful but complex. Serverless is simple but has limits. No tool is universally correct.
  • Structure code examples with comments that explain intent, not syntax. The reader already knows what RUN does in a Dockerfile; they need to know why this layer is structured this way.

How NOT to Help

  • Do not recommend Kubernetes for everything. If a learner is deploying three services on a single server, Docker Compose is the correct answer. Kubernetes is a premature optimization in that context.
  • Do not skip security steps in pipeline examples. A CI/CD example without image scanning or dependency auditing teaches dangerous habits.
  • Do not present opinionated choices as universal truths. Trunk-based development is recommended, but GitFlow has legitimate use cases in regulated industries. Acknowledge both.
  • Do not use deprecated tooling or patterns. As of 2026: avoid Docker Hub in favor of GHCR or cloud registries, avoid Jenkins shared libraries in favor of GitHub Actions, avoid bare latest tags in production.
  • Do not generate placeholder content. Every section must be complete, accurate, and publishable. No "TODO: fill this in" or "insert diagram here."
  • Do not over-abstract. A learner reading about CI/CD does not need a custom Terraform module framework. They need a working pipeline they can understand end-to-end.

Key Concepts

Learners are expected to understand these terms when referenced:

  • CI/CD: Continuous Integration and Continuous Deployment/Delivery
  • Immutable artifact: A build output (container image, binary) that is never modified after creation, only promoted or replaced
  • Declarative vs imperative: Declaring desired state (K8s YAML, Terraform) vs issuing step-by-step commands (shell scripts)
  • GitOps: Using Git as the single source of truth for infrastructure and application state
  • Observability: Metrics, logs, and traces that allow understanding system behavior without prior knowledge of failure modes
  • Golden path: An opinionated, supported default workflow for a common engineering task
  • DORA metrics: Deployment Frequency, Lead Time for Changes, Mean Time to Recovery, Change Failure Rate
  • Feature flag: A mechanism to toggle application behavior without deploying new code
  • Platform engineering: The discipline of building internal developer platforms that provide self-service infrastructure

DevOps Guidelines (2026)

The ecosystem has converged on the following toolchain. Use these as defaults unless the learner's context demands otherwise:

Category Default Tool Alternatives
Version Control Git + GitHub GitLab, Bitbucket
CI/CD GitHub Actions GitLab CI, CircleCI
Container Runtime Docker with BuildKit Podman (edge cases)
Container Orchestration Kubernetes (managed: EKS/GKE/AKS) Docker Compose (small scale)
Package Management Helm Kustomize (overlay-only workflows)
Infrastructure as Code Terraform Pulumi (teams preferring general-purpose languages)
GitOps ArgoCD Flux (simpler setups)
Metrics Prometheus + Grafana Datadog (commercial)
Logs Grafana Loki ELK Stack (existing investments)
Traces OpenTelemetry + Jaeger Grafana Tempo
Security Scanning Trivy (images), tfsec (Terraform) Grype, Checkov
Feature Flags Unleash (self-hosted) LaunchDarkly (commercial)
Platform Portal Backstage Port, Humanitec (commercial)
FinOps Infracost Kubecost (K8s-specific)

Workflow Defaults

  • Branching strategy: Trunk-based development with short-lived feature branches
  • Commit style: Conventional commits (feat:, fix:, ci:, docs:)
  • Versioning: Semantic versioning, automated via semantic-release
  • Container base images: Alpine or distroless, pinned by digest in production
  • Deployment strategy: Canary for user-facing services, rolling for internal services
  • Secrets management: External secrets operator with vault backend; never in Git, never in environment variables in manifests

Repository Structure

devops-engineer/
  README.md          # Primary learning guide (this repo's core content)
  AGENTS.md          # AI agent context (this file)
  examples/          # Runnable code examples
    docker/          # Dockerfiles and compose files
    github-actions/  # CI/CD workflow YAML files
    kubernetes/      # K8s manifests and Helm charts
    terraform/       # IaC examples
    observability/   # Prometheus rules, Grafana dashboards, OTel config
  labs/              # Hands-on exercises with instructions
  solutions/         # Reference solutions for labs