Навыки реальных инженеров: коллекция .agents
Коллекция практических навыков и инструментов для инженеров, собранная в .agents. Реальные решения, проверенные в производстве, без лишней болтовни.
Что такое .agents и почему они важны
Навыки реальных инженеров: коллекция .agents
Что такое .agents и почему они важны
.agents — это коллекция готовых инструментов для автоматизации инфраструктуры, которая позволяет инженерам быстро разворачивать и управлять агентами в различных средах. В отличие от ручного копирования скриптов, .agents предоставляет структурированный подход, где каждый агент имеет определённую роль и может быть развернут в одно действие.
Представьте, что у вас есть набор готовых блоков Lego, а не отдельные кирпичики, которые нужно лепить вручную. С .agents вы получаете готовые решения, которые можно сразу использовать в продакшене.
Определение агентов
.agents — это набор YAML-шаблонов, которые описывают конфигурацию агентов для различных задач мониторинга, логирования и автоматизации. Каждый агент включает в себя:
- Базовую конфигурацию systemd-сервиса
- Необходимые переменные окружения
- Настройки подключения к центральным системам
Пример базового агента для мониторинга
yaml# .agents/monitoring/prometheus-node-exporter.yml
apiVersion: v1
kind: Service
metadata:
name: node-exporter
description: "Агент экспорта метрик системных ресурсов"
spec:
ports:
- protocol: TCP
port: 9100
targetPort: 9100
selector:
app: node-exporter
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: node-exporter
labels:
app: node-exporter
spec:
selector:
matchLabels:
app: node-exporter
template:
metadata:
labels:
app: node-exporter
spec:
containers:
- name: node-exporter
image: prom/node-exporter:latest
ports:
- containerPort: 9100
resources:
limits:
cpu: 200m
memory: 256Mi
args:
- --path.rootfs=/host
hostNetwork: true
hostPID: true
Определение агента в контексте инфраструктуры
bash# .agents/base/agent-definition.sh
#!/bin/bash
# Определяет базовую структуру агента
AGENT_NAME="${1:-default-agent}"
AGENT_TYPE="${2:-monitoring}"
AGENT_PORT="${3:-8080}"
# Создаёт директорию агента
mkdir -p ~/.agents/$AGENT_NAME
cat > ~/.agents/$AGENT_NAME/config.yml << EOF
name: $AGENT_NAME
type: $AGENT_TYPE
port: $AGENT_PORT
health_check: "/health"
log_path: "/var/log/$AGENT_NAME.log"
EOF
echo "Агент $AGENT_NAME определён типа $AGENT_TYPE на порту $AGENT_PORT"
Преимущества перед обычными скриптами
1. Предсказуемость конфигураций
.agents обеспечивает предсказуемость благодаря YAML-схемам. Каждый агент имеет чётко определённую структуру, что устраняет "решение на коленке", которые часто возникают при ручном копировании скриптов.
bash# Сравнение: ручной скрипт vs .agents подход
# Ручной скрипт (рискованный подход)
cat > deploy-agent.sh << 'EOF'
#!/bin/bash
# Копипаста из разных источников
# Нет проверки
# Нет документации
# Может сломать систему
EOF
# .agents подход (предсказуемый)
cat > .agents/stable-agent.yml << 'EOF'
apiVersion: v1
kind: Agent
metadata:
name: stable-agent
version: "1.0"
description: "Стабильный агент для критичных систем"
spec:
image: company/stable-agent:1.0
resources:
cpu: "200m"
memory: "256Mi"
health_check:
endpoint: "/health"
interval: "30s"
monitoring:
metrics_port: 9090
logs_port: 9091
EOF
2. Готовность к продакшену
Агенты из .agents включают в себя:
- Проверки работоспособности
- Настройки логирования
- Ресурсные ограничения
- Интеграции с мониторинговыми системами
yaml# .agents/production/agent-with-monitoring.yml
apiVersion: v1
kind: Agent
metadata:
name: production-agent
environment: "production"
spec:
service:
name: prod-agent
ports:
- name: metrics
port: 9090
targetPort: metrics
- name: logs
port: 9091
targetPort: logs
monitoring:
prometheus:
enabled: true
scrape_interval: "15s"
metrics_path: "/metrics"
alerting:
enabled: true
alertmanager: "http://alertmanager:9093"
rules:
- name: "AgentDown"
condition: "agent_health == 0"
duration: "5m"
action: "restart"
logging:
driver: "loki"
endpoint: "http://loki:3100"
format: "json"
resources:
requests:
cpu: "100m"
memory: "128Mi"
limits:
cpu: "500m"
memory: "512Mi"
3. Простота масштабирования
Добавление новых агентов в кластер — это просто копирование YAML-файла и изменение селектора. Нет необходимости править скрипты вручную.
bash# Масштабирование с .agents
# Шаг 1: Копируем шаблон
cp .agents/monitoring/node-exporter.yml .agents/monitoring/node-exporter-worker.yml
# Шаг 2: Редактируем селектор
sed -i 's/app: node-exporter/app: node-exporter-worker/' .agents/monitoring/node-exporter-worker.yml
# Шаг 3: Разворачиваем
kubectl apply -f .agents/monitoring/node-exporter-worker.yml
# Ручной скрипт потребовал бы редактирования множества файлов и ручной установки
4. Документация и читаемость
Каждый агент в .agents само-документирован:
yaml# .agents/database/postgres-agent.yml
apiVersion: v1
kind: Agent
metadata:
name: postgres-agent
description: "Агент для мониторинга PostgreSQL баз данных"
documentation: |
Этот агент собирает метрики производительности PostgreSQL:
- Количество активных соединений
- Размер запросов
- Задержки операций I/O
- Использование памяти
Для настройки используйте поля:
- connection_string: строка подключения к БД
- collect_interval: интервал сбора метрик
version: "2.1"
spec:
image: company/postgres-agent:2.1
dependencies:
- postgresql-client
- libc6
config:
connection_string: "postgresql://user:pass@host:5432/db"
collect_interval: "30s"
metrics:
- name: "connections_active"
type: "gauge"
help: "Количество активных соединений"
- name: "query_time_avg"
type: "histogram"
help: "Среднее время выполнения запросов"
Заключение
.agents — это переход от "решений на коленке" к предсказуемым, продакшен-готовым решениям. Инженеры получают готовые блоки, которые можно сразу использовать, масштабировать и поддерживать. Это устраняет риск копипасты, обеспечивает документацию и позволяет фокусироваться на важных задачах, а не на рутинной настройке агентов.
Используя .agents, вы получаете коллекцию инструментов, которая работает сразу после установки, а не после ночи ручной настройки. Это системный подход, который соответствует современным требованиям к инфраструктуре — предсказуемости, автоматизации и надёжности.
Основные навыки для современных инженеров
Основные навыки для современных инженеров
Коллекция .agents — это набор практических навыков и инструментов, которые я отобрал за 12 лет работы с инфраструктурой. Здесь только решения, которые доказали свою эффективность в производстве, без теории, которая никогда не применяется на практике.
Работа с LLM и промптами
Для инженеров LLM — это не панацея, а инструмент, который нужно знать использовать. Эффективная работа с промптами начинается с понимания, что вы просите не просто ответ, а конкретный результат.
Основные принципы промпт-инжиниринга:
bash# Пример: запрос структурированного ответа от LLM
cat > prompt_template.txt << 'EOF'
Ты — DevOps-инженер с 10-летним опытом работы в инфраструктуре.
Дай мне пошаговую инструкцию по [КОНКРЕТНАЯ ЗАДАЧА] с учетом:
1. Безопасности (согласно Best Practices)
2. Предсказуемости конфигурации
3. Возможности отладки
Включи контекст: версии, зависимости, потенциальные проблемы.
EOF
Структура эффективного промпта:
- Контекст — укажите вашу роль и опыт
- Задача — четкое описание того, что нужно получить
- Ограничения — безопасность, производительность, предсказуемость
- Формат — структура ответа, которая удобна для вас
Пример реального промпта для настройки Nginx:
bash# Запрос к LLM для настройки обратного прокси
cat > nginx_config_prompt.txt << 'EOF'
Напиши полную конфигурацию Nginx для:
- Сайта example.com на порту 443
- TLS-сертификата от Let's Encrypt
- HTTP->HTTPS редиректа
- Предсказуемой перезагрузки без простоя
Включи комментарии, объясняющие каждый блок конфигурации.
Используй переменные окружения для путей к сертификатам.
EOF
Практический совет: всегда проверяйте ответ LLM вручную. LLM может сгенерировать красивый код, но без понимания того, что происходит внутри, вы рискуете получить неработающее решение.
Интеграция Claude Code
Claude Code — это не просто IDE с ИИ-помощником, а инструмент, который может стать частью вашей инженерной практики, если правильно его настроить.
Базовая интеграция:
yaml# .github/workflows/claude-code-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
claude-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Claude Code
run: |
npm install -g @anthropic/claude-code
claude-code --init
- name: Code Review
run: |
claude-code review \
--file-pattern "*.js" "*.ts" \
--severity medium \
--format json \
> review-results.json
Конфигурация Claude Code для инженерной работы:
bash# Настройка Claude Code для системного инжиниринга
cat > .claude-config.json << 'EOF'
{
"context_window": "large",
"temperature": 0.1,
"max_tokens": 4000,
"system_prompt": "Ты — DevOps-инженер с 10-летним опытом работы в инфраструктуре. Всегда давай конкретные команды, конфигурации и инструкции по отладке. Предпочитаешь предсказуемые, повторяемые решения. Избегаешь GUI, когда можно написать конфиг вручную.",
"tools": [
"bash",
"docker",
"kubernetes",
"git",
"systemd"
]
}
EOF
Пример использования Claude Code для анализа конфигурации:
bash# Анализ конфигурации системы с помощью Claude Code
claude-code analyze \
--file /etc/systemd/system/nginx.service \
--check \
--format detailed \
--output analysis-report.md
Практический опыт:
За последние пять лет я настроил Claude Code так, чтобы он работал как расширение моей инженерной памяти. Вместо того, чтобы заново изобретать велосипед, Claude Code помогает мне находить решения, которые я уже тестировал, но забыл детали.
Ключевые настройки для инженерной работы:
bash# Оптимизация Claude Code для инженерных задач
claude-code configure \
--context-window 32k \
--temperature 0.0 \
--max-tokens 8000 \
--tool-timeout 300 \
--retry-attempts 3
Совет по безопасности: всегда проверяйте команды, сгенерированные Claude Code, перед их выполнения. Даже ИИ может совершать ошибки, особенно когда дело доходит до критически важных систем.
Эти навыки — основа, на которой строится вся коллекция .agents. Они проверены годами практики и работают как в домашней лаборатории, так и в производственных средах размером с корпорацию.
Развёртывание и мониторинг в продакшене
Развёртывание и мониторинг в продакшене
Настройка продакшн-инфраструктуры — это не про красивые диалоги, а про предсказуемость. В реальности инженер сталкивается с двумя проблемами: как не сломать то, что уже работает, и как понять, когда это сломается. Ниже два блока, которые я применяю везде, где бы ни развертывался новый сервис.
Настройка инфраструктуры
Определяем единообразие через код
В продакшне я храню всю конфигурацию в Git-репозитории. Это позволяет быстро откатиться, если что-то пошло не так, и дает возможность проводить ревизии кода.
bash# Пример структуры репозитория .agents
agents/
├── inventory/
│ ├── production.yml
│ └── staging.yml
├── configs/
│ ├── nginx/
│ │ ├── proxy.conf
│ │ └── ssl.conf
│ └── docker/
│ └── compose.prod.yml
└── scripts/
├── deploy.sh
└── healthcheck.sh
Инвентарь через Ansible
Для управления хостами я использую Ansible — это позволяет избежать ручной работы и дает предсказуемость при развертывании.
yaml# inventory/production.yml
---
all:
hosts:
vinny-puh:
ansible_host: 192.168.1.10
ansible_user: alexey
domain: example.com
pjatochek:
ansible_host: 192.168.1.11
ansible_user: alexey
domain: example.com
children:
app:
hosts:
vinny-puh:
pjatochek:
storage:
hosts:
sovа:
ansible_host: 192.168.1.12
Docker Compose для продакшена
Вместо монолитного развертывания я использую Docker Compose с сетевой изоляцией и переменными окружения.
yaml# configs/docker/compose.prod.yml
version: '3.8'
services:
app:
build: ./app
container_name: app-prod
restart: unless-stopped
environment:
- NODE_ENV=production
- DB_HOST=db.prod.internal
networks:
- app_net
- monitoring
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
db:
image: postgres:15
container_name: db-prod
restart: unless-stopped
environment:
- POSTGRES_DB=prod_db
- POSTGRES_USER=prod_user
volumes:
- db_data:/var/lib/postgresql/data
networks:
- app_net
nginx:
image: nginx:alpine
container_name: nginx-prod
ports:
- "80:80"
- "443:443"
volumes:
- ./configs/nginx:/etc/nginx/conf.d
- ssl_certs:/etc/nginx/ssl
depends_on:
- app
networks:
- app_net
- monitoring
networks:
app_net:
driver: bridge
monitoring:
external: true
volumes:
db_data:
ssl_certs:
Настройка SSL через Let's Encrypt
Для предсказуемости SSL я использую certbot в автоматическом режиме.
bash# scripts/deploy-ssl.sh
#!/bin/bash
DOMAIN="example.com"
EMAIL="alexey@example.com"
certbot certonly \
--webroot \
--webroot-path=/var/www/certbot \
--email "$EMAIL" \
--agree-tos \
--no-eff-email \
-d "$DOMAIN"
# Перезапускаем nginx для применения сертификата
docker-compose -f configs/docker/compose.prod.yml exec nginx nginx -s reload
Наблюдение и алертинг
Сбор данных через Prometheus
Для мониторинга я использую Prometheus с node_exporter на каждом хосте и экспортерами для контейнеров.
yaml# configs/prometheus/prometheus.yml
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'node'
static_configs:
- targets: ['vinny-puh:9100', 'pjatochek:9100']
- job_name: 'docker'
docker_sd_configs:
- host: unix:///var/run/docker.sock
relabel_configs:
- source_labels: [__meta_docker_container_name]
target_label: __address__
regex: '/(.*)/'
replacement: '${1}:9323'
- job_name: 'app'
static_configs:
- targets: ['app-prod:8080']
Графана для визуализации
Конфигурация дашборда для предсказуемости работы системы.
json{
"dashboard": {
"title": "Production Infrastructure",
"panels": [
{
"title": "CPU Usage",
"type": "graph",
"targets": [
{
"expr": "avg by (instance) (rate(cpu_usage_total[5m]))",
"legendFormat": "{{instance}}"
}
]
},
{
"title": "Memory Pressure",
"type": "graph",
"targets": [
{
"expr": "node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes * 100",
"legendFormat": "{{instance}}"
}
]
}
]
}
}
Алертинг через Alertmanager
Настройка алертов для предсказания проблем до того, как они станут критическими.
yaml# configs/alertmanager.yml
global:
resolve_timeout: 5m
route:
receiver: 'default'
group_by: ['alertname']
routes:
- match:
severity: 'critical'
receiver: 'pagerduty'
- match:
severity: 'warning'
receiver: 'email'
receivers:
- name: 'default'
webhook_configs:
- url: 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK'
- name: 'pagerduty'
pagerduty_configs:
- integration_key: 'YOUR_PAGERDUTY_KEY'
severity: 'critical'
description: '{{ template "pagerduty.default.description" . }}'
- name: 'email'
email_configs:
- to: 'alexey@example.com'
subject: '[{{ .CommonLabels.Severity | upper }}] {{ .CommonLabels.Alertname }}'
Healthcheck скрипты
Для предсказуемости я использую healthcheck скрипты, которые проверяют не только работоспособность, но и бизнес-логику.
bash# scripts/healthcheck.sh
#!/bin/bash
# Проверка доступности базы данных
if ! pg_isready -h db.prod.internal -U prod_user; then
echo "CRITICAL: Database is not responding"
exit 1
fi
# Проверка API ответа
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://app-prod:8080/health)
if [ "$HTTP_STATUS" -ne 200 ]; then
echo "WARNING: API returned status $HTTP_STATUS"
exit 1
fi
# Проверка дискового пространства
THRESHOLD=85
USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ "$USAGE" -gt "$THRESHOLD" ]; then
echo "CRITICAL: Disk usage $USAGE% exceeds $THRESHOLD%"
exit 1
fi
echo "All systems operational"
exit 0
Автоматизация алертов
Для предсказуемости я использую Prometheus правила алертинга.
yaml# configs/prometheus/alerts.yml
groups:
- name: system
rules:
- alert: HighCPU
expr: avg by (instance) (rate(cpu_usage_total[5m])) > 0.8
for: 2m
labels:
severity: 'warning'
annotations:
summary: "Высокая нагрузка на CPU на {{ $labels.instance }}"
description: "Нагрузка CPU превышает 80% в течение 2 минут"
- alert: DiskSpaceLow
expr: (node_filesystem_avail_bytes / node_filesystem_size_bytes) * 100 < 15
for: 1m
labels:
severity: 'critical'
annotations:
summary: "Низкий остаток места на {{ $labels.instance }}"
description: "Осталось менее 15% свободного места на {{ $labels.mountpoint }}"
Логирование через Loki
Для предсказуемости и отслеживания проблем я собираю логи в Loki.
bash# Пример отправки логов в Loki
curl -X POST "https://loki.internal/loki/api/v1/push" \
-H "Content-Type: application/json" \
-d '{
"streams": [
{
"stream": {"job": "app", "instance": "app-prod"},
"values": [["'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'", "Application started"]]
}
]
}'
Обмен данными между сервисами
Для предсказуемости я использую переменные окружения и secrets, а не хардкод.
bash# Пример безопасного развертывания с переменными окружения
docker-compose -f configs/docker/compose.prod.yml up -d
# Проверка работоспособности через curl с использованием переменных окружения
curl -f http://localhost:8080/health || {
echo "Healthcheck failed, restarting service"
docker-compose -f configs/docker/compose.prod.yml restart app
}
Эти практики дают предсказуемость в продакшне: вы знаете, что сломается, когда, и как это исправить. Нет места для случайностей — только для предсказуемых решений, проверенных в реальных условиях.
Практические кейсы и советы
Пример CI/CD пайплайна
В проекте .agents мы используем контейнеризированные агенты для стабильной доставки. Вот практический пример пайплайна для GitLab CI:
yaml# .gitlab-ci.yml
stages:
- test
- build
- deploy
variables:
DOCKER_DRIVER: overlay2
DOCKER_TLS_CERTDIR: "/certs"
default:
image: docker:latest
services:
- docker:dind
test_unit:
stage: test
script:
- echo "Запуск unit-тестов в изолированном контейнере"
- |
docker run --rm \
--network=host \
-v $(pwd)/app:/workspace \
-w /workspace \
test-agent:${CI_COMMIT_SHA} \
pytest -v --cov=app
build_image:
stage: build
script:
- echo "Сборка Docker-образа с хешированием по коммиту"
- |
docker build --pull \
--build-arg COMMIT=${CI_COMMIT_SHA} \
--tag registry.example.com/app:${CI_COMMIT_SHA} \
--tag registry.example.com/app:latest \
.
- docker push registry.example.com/app:${CI_COMMIT_SHA}
- docker push registry.example.com/app:latest
only:
- main
deploy_stable:
stage: deploy
script:
- echo "Разворачивание через .agents с health-check"
- |
curl -X POST "https://agents.example.com/deploy" \
-H "Authorization: Bearer $DEPLOY_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"image\": \"registry.example.com/app:${CI_COMMIT_SHA}\",
\"version\": \"${CI_COMMIT_SHA}\",
\"health_check\": \"/health/live\"
}"
environment: production
only:
- main
Ключевые моменты, которые реально работают:
- Изолированные тестовые среды — каждый запуск получает чистый контейнер, что устраняет «работает у меня» проблемы
- Хеширование образов по коммиту — предсказуемость сборки, легко откатиться
- Health-check в развертывании — .agents сразу сообщает, если что-то пошло не так
- Двойное тегирование (конкретный + latest) — безопасная ротация, не теряя стабильности
Трики для отладки
1. Быстрая диагностика зависших контейнеров
bash# Определить, что застряло и почему
docker ps --filter "status=exited" --format "ID: {{.ID}} | Image: {{.Image}} | Status: {{.Status}}"
# Просмотреть логи всех контейнеров в одном месте
docker logs $(docker ps -q) --tail 50 2>/dev/null | grep -E "(ERROR|WARNING|FAIL|timeout)"
# Перезапустить только проблемные контейнеры
for container in $(docker ps --filter "status=exited" --format "{{.ID}}"); do
echo "Перезапуск $container"
docker start "$container"
done
2. Оптимизация использования памяти в .agents
bash# Найти контейнеры, которые потребляют больше памяти, чем нужно
docker stats --no-stream | awk 'NR>1 && $3 > 200 {print $1, $3, $4}'
# Ограничить память для конкретного агента
docker run -d \
--name debug-agent \
--memory="512m" \
--memory-swap="768m" \
debug-image:latest \
/bin/bash -c "while true; do sleep 30; done"
# Проверить реальное использование через cgroup
cat /sys/fs/cgroup/memory/docker/debug-agent/memory.usage_in_bytes
3. Сбор логов из нескольких источников
bash# Объединить journald, Docker и .agents в один поток
journalctl -u docker --since "10 minutes ago" | \
grep -E "(docker|agent)" | \
awk '{print strftime("%H:%M:%S"), $0}' > /tmp/debug.log
# Добавить логи .agents (если они пишут в stdout)
curl -s "https://agents.example.com/logs?since=600&format=json" | \
jq -r '.[] | "\(.timestamp) \(.message)"' >> /tmp/debug.log
# Отфильтровать только ошибки
grep -i "error\|fail\|critical" /tmp/debug.log | tail -20
4. Быстрая проверка работоспособности стека
bash# Проверить цепочку: .agents → Docker → Network → Service
for host in agent1 agent2 agent3; do
echo "=== Проверка $host ==="
# Health-check .agents
if curl -s "https://$host/health" | grep -q "healthy"; then
echo "✓ .agents работает"
else
echo "✗ .agents недоступен"
fi
# Проверить Docker daemon
if ssh "$host" "docker info --format '{{.Name}}'" >/dev/null 2>&1; then
echo "✓ Docker daemon работает"
else
echo "✗ Docker daemon недоступен"
fi
# Проверить сетевое соединение
if ping -c 1 "$host" >/dev/null 2>&1; then
echo "✓ Сеть доступна"
else
echo "✗ Сеть недоступна"
fi
done
Эти трики проверены в производстве с кластером из 3-х агентов, обслуживающим микросервисы. Главное — автоматизировать рутину, а ручную работу оставлять для действительно важных случаев.