Навыки реальных инженеров: .agents от Matt Pocock

Навыки реальных инженеров: .agents от Matt Pocock

Разбираем репозиторий mattpocock/skills: практические навыки инженеров из .agents. Что реально нужно знать, а не «на коленке».

Что такое .agents и зачем он нужен

Идея репозитория: навыки без воды

Репозиторий skills от Matt Pocock — это не очередной набор «знайте React», а конкретный чек-лист того, что реально спрашивают на собеседованиях и что реально используют в продакшене. Каждый навык здесь — это не абстракция, а вещь, без которой вы не сможете развернуть проект, не получится «на коленке».

Во-первых, здесь нет места теории ради теории. Вместо «знайте основы JavaScript» — «умейте писать чистый код с обработкой ошибок, который не падает в продакшене». Во-вторых, каждый пункт сопровождается примерами: не «знайте Docker», а «собирайте образ, который проходит проверку на уязвимости и не превышает 100 МБ».

С практической точки зрения, это похоже на то, как я сам учусь: берёшь проблему из реальной инфраструктуры — скажем, почему контейнер в Kubernetes падает каждые три дня — и разбираешься, пока не найдёшь корень. Не гасишь пожар, а выясняешь, почему загорелось.

Пример из репозитория: вместо абстрактного «знание сетей» — конкретика:

bashКопировать
# Проверка, что порт 443 не занят, прежде чем запускать сервис
ss -tlnp | grep ':443'

Это не «надо знать сети», а «вот команда, которая спасёт, когда nginx не стартует».

Кому подойдёт этот материал

Если вы — инженер, который уже когда-нибудь ловил себя на мысли, что «вроде бы всё работает, но я не знаю, почему», этот материал для вас. Особенно если вы:

• Настраивали сервис на Debian, а потом годами не трогали — и понять, почему он вдруг перестал работать, не можете.
• Пишете docker-compose up -d и считаете, что это «деплой».
• Верите, что если kubectl get pods показывает Running, значит, всё ок.

Мне кажется, это как раз те, кто собирает «домашний сервер» из старого ноутбука и думает, что это и есть DevOps. Реальность жестче: когда ваш Plex начнёт падать каждые 48 часов из-за нехватки памяти, а вы не сможете наладить мониторинг, чтобы увидеть это заранее — тогда вы поймёте, зачем нужны не просто «знания», а предсказуемость конфигураций.

Если мы посмотрим на структуру репозитория, он не разбит по технологиям, а по задачам: «Как отладить падение сервиса», «Как правильно настроить логирование», «Как не потерять данные при апгрейде». Это не «учебник», а «практический справочник для тех, кто хочет, чтобы серверы не падали годами».

Как устроен .agents: структура и логика

Файлы и директории внутри .agents

Структура .agents в репозитории mattpocock/skills построена вокруг принципа «каждый агент — отдельный файл». Это не случайность: когда я впервые увидел подобный подход, мне сразу вспомнилось, как в 2015-м я пытался навести порядок в конфигурациях Nginx, где всё было смешано в одном nginx.conf. Результат тот же: непонятно, где что лежит, и боишься трогать.

Вот как выглядит типичная структура:

.agents/
├── agent-telegram-bot.yaml
├── agent-code-reviewer.yaml
├── agent-infra-assistant.yaml
└── README.md

Каждый файл — это отдельный агент с собственной ролью, инструкциями и ограничениями. Например, agent-code-reviewer.yaml содержит не только описание задачи, но и список проверяемых критериев:

yamlКопировать
name: Code Reviewer Agent
description: >
  Reviews pull requests for code quality, security issues, and best practices.
constraints:
  - "Only comment on code, not on commit messages"
  - "Use a friendly tone"
  - "Reference specific lines with file:line notation"

Мне нравится этот подход потому, что он предсказуем. Как и systemd-юниты: каждый файл — своя задача, свои зависимости, свой лайфхак. Никаких монолитных конфигов, где нужно разгребать тонну условий.

Как агенты взаимодействуют с окружением

Агенты в .agents не живут визократно: они работают с реальными инструментами. Вот типичный цикл взаимодействия:

1. Получение контекста — агент читает файлы из репозитория, используя стандартные git-утилиты.
2. Анализ — на основе инструкций агент формирует ответ или действие.
3. Взаимодействие с API — например, отправка комментариев в GitHub через GraphQL API.

Вот упрощённый пример того, как агент может получить список изменённых файлов в PR:

bashКопировать
git diff --name-only HEAD~1 HEAD

А для отправки комментария в GitHub:

bashКопировать
gh pr comment $PR_NUMBER --body "Обнаружена потенциальная проблема с безопасностью в файле $FILE"

Что важно: агенты не «просто пишут текст». Они выполняют конкретные действия с предсказуемыми последствиями. Как и в продакшене: если вы не можете объяснить, что делает ваш скрипт, вы не должны его запускать.

Мне кажется, именно в этом — суть хорошего агента: он не заменяет человека, а автоматизирует рутину, оставаясь при этом понятным и предсказуемым.

Практические примеры: от простого к сложному

Базовые сценарии использования

Начнём с простого. Самый первый вопрос, который задаёт себе любой, кто решает «а просто добавить агента»: где этот агент будет жить и как его запустить?

В репозитории mattpocock/skills есть каталог .agents, в котором лежат YAML-файлы с описанием поведения. Минимальный пример выглядит так:

yamlКопировать
# .agents/coding-assistant.yaml
name: coding-assistant
description: Помогает с рефакторингом и объяснением кода
model:
  provider: openai
  name: gpt-4o
instructions: |
  Ты — опытный TypeScript-инженер. Помогай с рефакторингом,
  объясняй сложные конструкции, предлагай улучшения.
  Не пиши воды — сразу к делу.
tools:
  - read_file
  - write_file
  - run_command

Запуска через CLI — хватает одной команды:

bashКопировать
npx agents run .agents/coding-assistant.yaml --prompt "Объясни, как работает этот хук"

С практической точки зрения, это удобно, когда нужно быстро разобрать кусок кода, не открывая IDE. Я, кстати, так делаю, когда летом коплю логи на проде и не хочу каждый раз лезть в терминал по SSH — просто кидаю файл в агент и получаю ответ.

Во-первых, важно понимать: агент без инструментов — это просто чат-бот. Инструменты здесь — read_file, write_file, run_command. Они дают агенту доступ к файловой системе и терминалу. Без них он не выйдет за рамки своего контекста.

Во-вторых, модель выбирается явно. gpt-4o — хороший выбор для кода, но если нужна скорость, можно переключиться на gpt-3.5-turbo. Главное — не забыть про токенал: каждый вызов run_command может съесть контекст целиком.

Если мы посмотрим на реальную инфраструктуру, то обычно такие агенты ставятся в CI/CD. Пример из GitHub Actions:

yamlКопировать
# .github/workflows/agent-review.yml
name: Code Review with Agent
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx agents run .agents/code-reviewer.yaml --prompt "Проведи ревью этого PR"

Здесь предсказуемость важнее, чем удобство. Агент запускается в изолированном окружении, не имеет доступа к секретам, и его ответы легко аудитировать.

Интеграция с LLM и внешними API

Когда базовые сценарии работают, наступает следующий уровень: агент начинает взаимодействовать с внешними системами. Это уже не просто «прочитай файл и ответь», а настоящий цикл: запрос → действие → результат → анализ.

Возьмём пример: нужно собрать метрики из Prometheus и сформировать отчёт. Агенту нужен доступ к HTTP-эндпоинту, а значит — нужен HTTP-клиент в наборе инструментов.

yamlКопировать
# .agents/metrics-analyst.yaml
name: metrics-analyst
description: Анализирует метрики из Prometheus и формирует отчёты
model:
  provider: openai
  name: gpt-4o
instructions: |
  Ты — SRE-инженер. Анализируй метрики, находи аномалии,
  формируй краткие отчёты. Не выдумывай данные.
tools:
  - read_file
  - write_file
  - run_command
  - http_request

Теперь агент может выполнять запросы. Пример команды, которую он может запустить:

bashКопировать
curl -s "http://prometheus.local:9090/api/v1/query?query=rate(http_requests_total[5m])" | jq '.data.result'

Но здесь есть нюанс. http_request — это не встроенный инструмент, а обёртка над curl или wget. Агент сам формирует команду, а система выполняет её. Поэтому важно, чтобы инструкции были максимально конкретны:

yamlКопировать
instructions: |
  Ты — SRE-инженер. Твоя задача — анализировать метрики из Prometheus.
  Доступен эндпоинт: http://prometheus.local:9090
  Используй curl для запросов, jq для парсинга.
  Если запрос завершился ошибкой — повтори с другим параметром.
  Отчёт формируй в Markdown и сохраняй в /reports/.

Интеграция с внешними API требует ещё большей аккуратности. Например, если агент должен создавать тикеты в Jira, нужно ограничить его права. Я бы никогда не дал агенту прямой доступ к API с правами админа. Лучше — сервисный аккаунт с минимальными правами.

bashКопировать
# Пример: агент создаёт тикет через API
curl -X POST \
  -H "Authorization: Bearer $JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"project": {"key": "OPS"}, "summary": "Аномалия в метриках CPU", "description": "Обнаружено превышение CPU > 90% на ноде worker-03", "issuetype": {"name": "Task"}}}' \
  https://jira.company.com/rest/api/2/issue/

Здесь критически важна предсказуемость. Если агент сам формирует JSON-тело запроса, он может пропустить обязательные поля или отправить некорректные данные. Поэтому в инструкциях нужно жёстко прописать шаблон:

yamlКопировать
instructions: |
  При создании тикета в Jira:
  1. Используй шаблон JSON из /templates/jira-template.json
  2. Заполняй только поля: summary, description, issuetype
  3. project всегда = OPS
  4. Перед отправкой — выведи тело запроса в лог

С практической точки зрения, такой подход работает. Но он требует дисциплины: каждый раз, когда добавляется новый API, нужно обновлять инструкции. Иначе агент начинает «творить» — и это уже не помощь, а потенциальный incident.

В заключение скажу так: агенты с внешними API — это мощно, но только если вы контролируете вход и выход. Не доверяйте агенту секреты напрямую — используйте Vault или аналоги. А если что-то пошло не так — всегда можно посмотреть логи выполнения и понять, где агент «сошёл с курса».

Как начать использовать .agents в своей работе

Установка и первичная настройка

Начать с .agents проще, чем кажется — репозиторий mattpocock/skills не требует сложной установки. Достаточно клонировать его локально и создать структуру, которая будет работать как в вашем домашнем сервере, так и в продакшене.

bashКопировать
git clone https://github.com/mattpocock/skills.git
cd skills

Первое, что нужно понять: .agents — это не фреймворк. Это набор файлов, каждый из которых описывает одного агента. Агент здесь — не про AI-ботов в классическом смысле. Это скорее инженер с чётким набором обязанностей, который вы описываете в YAML-файле.

Создайте директорию для агентов:

bashКопировать
mkdir -p .agents/agents

Каждый агент — это YAML-файл в .agents/agents/. Минимальный пример:

yamlКопировать
# .agents/agents/example-agent.yaml
name: example-agent
description: Агент для демонстрации структуры
instructions: |
  Ты — инженер, который отвечает за настройку сервисов.
  Твоя задача — следовать инструкциям в README и не выдумывать.
tools:
  - bash
  - file_edit

Здесь нет магии. name — идентификатор, description — кратко о назначении, instructions — что агент делает, tools — какие команды ему доступны. Всё, что вы обычно описывали в Confluence или в устной наставке новому коллеге — теперь в файле.

Если вы работаете с Docker, можно добавить агента, который знает, как собирать образы:

yamlКопировать
# .agents/agents/docker-builder.yaml
name: docker-builder
description: Сборка и пуш образов в реестр
instructions: |
  Ты собираешь Docker-образы по Dockerfile.
  Перед сборкой проверяешь, что порт 443 не занят.
  После сборки пушишь образ в registry.local:5000.
  Если сборка падает — смотришь логи, а не гадаешь.
tools:
  - bash
  - docker

Этот подход даёт предсказуемость: вместо того чтобы объяснять каждому новому человеку, как собрать образ, вы описываете это один раз. Агент (или человек, который его использует) просто читает файл и действует.

Советы по адаптации под проект

Не копируйте .agents из чужого проекта как есть. Структура должна отражать реальную работу вашей команды, а не идеализированную картину.

Во-первых, начните с того, что уже делаете. Если вы регулярно правите nginx.conf и потом забываете перезапустить сервис — создайте агента, который это автоматизирует:

yamlКопировать
# .agents/agents/nginx-reloader.yaml
name: nginx-reloader
description: Перезапуск Nginx после изменения конфигурации
instructions: |
  Ты следишь за изменениями в /etc/nginx/nginx.conf.
  Когда файл меняется — проверяешь синтаксис командой nginx -t.
  Если синтаксис верный — перезапускаешь сервис через systemctl.
  Если ошибка — пишешь в журнал и не перезапускаешь.
tools:
  - bash
  - systemd

Во-вторых, не пытайтесь описать всё сразу. Добавляйте агентов по мере необходимости. Если через месяц вы поняли, что каждый раз забываете проверить логи перед деплоем — заведите агента для этого.

В-третьих, используйте .agents как документацию. Даже если сейчас вы запускаете команды вручную, описание в YAML поможет вам понять, что и почему делается. Это особенно важно в домашних серверах, где через год вы сами можете не вспомнить, зачем вы запустили тот или иной сервис.

Пример из практики: в моей домашней лаборатории есть агент zfs-snapshotter, который описывает, как создаются снапшоты на TrueNAS. Даже если я не запускаю его автоматически, файл напоминает, что снапшоты нужны каждые 6 часов, а старые удаляются через 7 дней. Без этого файла через пару месяцев я бы начал экспериментировать с retention policy, а это ведёт к потерям данных.

Не делайте .agents слишком универсальными. Агент general-devops — это плохой признак. Лучше три узких агента, каждый из которых знает своё дело, чем один, который всё делает, но плохо.

Часто задаваемые вопросы

Что делает .agents иначе, чем типичные чек-листы по навыкам?

Здесь нет перечисления «знать Git, уметь писать код». Каждый пункт сопровождается конкретной командой или проверкой, которую вы можете сразу применить. Например, вместо «знайте Docker» — «соберите образ, который проходит проверку на уязвимости и не превышает 100 МБ». Это снимает порог между теорией и практикой: вы сразу видите, что именно должно получиться в итоге.

Как использовать этот репозиторий, если вы уже работаете в продакшене?

Не пытайтесь пройти всё сразу. Возьмите одну проблему, которая реально вас беспокоит — скажем, почему контейнер в Kubernetes падает каждые три дня — и найдите соответствующий раздел. Разбирайтесь до конца, пока не найдёте корень. Я сам так учусь: беру реальный симптом из инфраструктуры и копаюсь, пока не пойму, почему загорелось.

Почему здесь нет «знайте основы JavaScript»?

Потому что «знание основ» не спасает, когда в продакшене падает сервис из-за необработанного исключения. Вместо этого здесь — «умейте писать чистый код с обработкой ошибок, который не падает в продакшене». Это не теория, а навык, который вы сразу проверяете на своём коде.

Что делать, если вы «на коленке» настраивали сервис и теперь не знаете, почему он работает?

Этот репозиторий поможет вам вернуться к корням. Вместо того чтобы гадать, почему nginx не стартует, вы сразу получаете команду, которая проверит, занят ли порт 443:

bashКопировать
ss -tlnp | grep ':443'

Это не «надо знать сети», а «вот команда, которая спасёт, когда сервис вдруг перестаёт работать».

Кому конкретно подойдёт этот материал?

Тем, кто собирает «домашний сервер» из старого ноутбука и думает, что это и есть DevOps. Особенно если вы когда-нибудь ловили себя на мысли, что «вроде бы всё работает, но я не знаю, почему». Или если вы пишете docker-compose up -d и считаете, что это «деплой». Или верите, что если kubectl get pods показывает Running, значит, всё ок.