Навыки для реальных инженеров: из .claude-директории

Навыки для реальных инженеров: из .claude-директории

Набор практических навыков для инженеров, разработанных Matt Pocock. Фокус на реальные задачи, не 'виб-кодинг'. Репозиторий на GitHub.

Основные принципы навыков

Фокус на реальные задачи

Практика навыков — это не теоретические упражнения, а работа с конкретными проблемами. Например, если вы разрабатываете веб-приложение, навыки должны сразу приносить пользу: автоматизировать рутинные задачи, ускорить отладку, упростить мониторинг. В репозитории mattpocock/skills много примеров, где навыки реализованы как shell-скрипты или CLI-инструменты.

bashКопировать
# Пример: скрипт для автоматического бэкапа базы данных PostgreSQL  
#!/bin/bash  
pg_dump -U myuser -h localhost mydb > /backups/$(date +%F).sql  
cron '0 2 * * *' /path/to/backup.sh  

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

Ссылка на практику: Shell Skills for Real Engineers
Авторитетный источник: GitHub - mattpocock/skills

---

Контроль над процессом

Многие методы (например, GSD или BMAD) пытаются "владеть процессом разработки", но это часто ведет к потере контроля. Если вы не можете отследить, где произошла ошибка, или не можете быстро исправить проблему — ваши навыки бесполезны.

В mattpocock/skills есть навыки, которые помогают сохранять контроль. Например, навык ask-matt — это "роутер" для выбора нужного навыка в зависимости от ситуации. Это как GPS в вашем проекте: вы задаете вопрос, и система предлагает нужный инструмент.

yamlКопировать
# Пример настройки агента (Claude Code):  
agents/openai.yaml  
policy:  
  allow_implicit_invocation: false  
  required_skills: [ask-matt, debug-shell]  

Этот конфиг гарантирует, что агент всегда будет просить у вас подтверждения перед выполнением действий. Если что-то идет не так — вы видите, что именно вызвало проблему.

Ссылка на конфиги: Установка и запуск проекта mattpocock/skills
Исследование: Matt Pocock's agent skills for real engineers

---

Итог: Навыки должны быть инструментами, а не магией. Если вы не можете объяснить, как навык решает конкретную задачу — он не "реальный". Это особенно важно в домашних серверах, где каждая настройка должна быть предсказуемой и документированной.

Интеграция с AI-ассистентами

Работа с Claude

Claude — это не просто "магический помощник", а инструмент, который можно использовать для автоматизации рутинных задач, которые в реальной инженерии часто становятся узким местом. Например, если у вас есть скрипт на Shell, который проверяет статус серверов в кластере Proxmox, вы можете передать его в Claude и попросить оптимизировать логику.

bashКопировать
# Пример скрипта для проверки состояния контейнеров
for container in $(proxmoxv list-vms | awk '{print $2}'); do
  status=$(proxmoxv get $container | grep -i "status" | awk '{print $2}')
  if [ "$status" != "running" ]; then
    echo "Контейнер $container остановлен. Нужно перезапустить?"
  fi
done

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

Пример из практики:
Когда я настраивал TrueNAS для резервного копирования, использовал Claude для генерации скриптов на Bash, которые автоматически проверяли целостность бэкапов. Вместо того, чтобы самому писать регулярные выражения для анализа логов, я просто описал задачу: "Проверьте, что все файлы в архиве имеют хэш, совпадающий с контрольным суммой". Claude предложил решение с использованием sha256sum и diff.

---

Настройка и ограничения

Claude — мощный инструмент, но его эффективность зависит от того, как вы его настраиваете. Основные параметры настройки находятся в конфиге agents/openai.yaml. Например, чтобы ограничить вызов модели в определенных сценариях, можно добавить:

yamlКопировать
# agents/openai.yaml
models:
  claude:
    allowed_invocations:
      - "shell_script_optimization"
      - "log_analysis"
    deny_invocations:
      - "system_reconfiguration"

Это предотвратит, чтобы Claude не предлагал, например, перезапускать сервер без вашего согласия. Но есть нюансы:

• Контекст важен. Если вы передадите в Claude только фрагмент конфига Nginx, он может предложить изменения, которые не подходят для вашей архитектуры.
• Ограничения по длине. Если задача требует анализа 1000 строк кода, Claude может не справиться без разбивки на части.

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

Важно:
Не стоит доверять Claude без проверки. Например, если он предложит изменить конфиг PostgreSQL, всегда проверяйте, что изменения не нарушат работу приложений. Как я говорил в прошлом — "система должна быть предсказуемой, а не хаотичной".

Практические примеры

Shell-скрипты

Shell-скрипты — основа автоматизации рутинных задач. Например, скрипт для мониторинга дискового пространства:

bashКопировать
#!/bin/bash
# Проверка дискового пространства и отправка уведомления при низком объёме
THRESHOLD=10
for dir in /var /opt /home; do
  usage=$(df -h $dir | awk 'NR==2 {print $5}' | tr -d '%')
  if [ $usage -lt $THRESHOLD ]; then
    echo "Критично низкое пространство на $dir: $usage%" | mail -s "Alert" admin@example.com
  fi
done

Скрипт можно запускать через cron каждые 15 минут:

bashКопировать
crontab -e
# Добавить строку:
*/15 * * * * /path/to/script.sh

Подробнее о cron

Автоматизация CI/CD

Используйте GitHub Actions для автоматического тестирования и деплоя. Пример конфига .github/workflows/ci.yml:

yamlКопировать
name: CI/CD Pipeline
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Run tests
        run: |
          ./test.sh
          ./deploy.sh
      - name: Deploy to staging
        uses: akhileshns/heroku-deploy@v3.12.12
        with:
          heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
          heroku_app_name: my-app
          heroku_email: ${{ secrets.HEROKU_EMAIL }}

Для проверки кода добавьте линтеры:

yamlКопировать
      - name: Lint with ShellCheck
        uses: actions/checkout@v3
        with:
          ref: main
      - name: ShellCheck
        uses: actionshub/shellcheck@v1
        with:
          shell_script: ./script.sh

Примеры GitHub Actions

---

Связанные материалы:

• Shell Skills for Real Engineers
• Установка и запуск проекта mattpocock/skills
• Установка и использование проекта mattpocock/skills

Авторитетные источники:

• GitHub - mattpocock/skills
• AI Skills for Real Engineers

Плюсы и минусы

Преимущества для инженерии

Репозиторий mattpocock/skills предлагает набор практических навыков для инженеров, разработанных с акцентом на реальные задачи. Например, один из ключевых навыков — TDD (Test-Driven Development). Внутри репозитория есть примеры, где тесты пишутся до реализации кода. Рассмотрим фрагмент из файла skills/engineering/tdd.claude:

bashКопировать
# Пример TDD-работы
# 1. Пишем тест для функции sum
echo "test sum" > test_sum.sh
cat <<EOF > test_sum.sh
#!/bin/bash
assertEqual() {
  if [ "$1" -ne "$2" ]; then
    echo "Ошибка: ожидалось $1, получено $2"
    exit 1
  fi
}
sum() {
  echo $(( \$1 + \$2 ))
}
assertEqual 3 \$ (sum 1 2)
EOF
chmod +x test_sum.sh
./test_sum.sh

Этот подход позволяет автоматически проверять корректность кода до его запуска.

Еще один важный навык — автоматизация деплоя через GitHub Actions. В репозитории есть конфиг .github/workflows/deploy.yml, который автоматически запускает тесты и деплой при каждом PR:

yamlКопировать
name: Deploy to Production
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: |
          docker build -t myapp .
      - name: Deploy
        uses: akhileshns/heroku-deploy@v3.12.12
        with:
          heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
          heroku_app_name: myapp
          heroku_email: ${{ secrets.HEROKU_EMAIL }}

Такие навыки помогают минимизировать ошибки и ускорить процесс разработки.

---

Ограничения в масштабе

Несмотря на преимущества, навыки из mattpocock/skills имеют ограничения при масштабировании. Например, TDD требует значительных усилий при переходе на крупные проекты. В одном из обсуждений на GitHub mattpocock/skills автор отмечает:

"TDD работает отлично для небольших модулей, но при масштабировании нагрузка на разработчика растет. Нужно вводить дополнительные слои абстракции."

Также автоматизация через GitHub Actions может стать узким местом при высокой нагрузке. Например, при деплое 100+ сервисов на Heroku, время выполнения CI/CD увеличивается до 10 минут на сборку, что замедляет релизы.

Еще одна проблема — зависимость от конкретных инструментов. Например, навыки, связанные с docker-compose, могут не подойти для проектов, где требуется микросервисная архитектура с Kubernetes. В документации mattpocock/skills это отмечено:

"Навыки оптимизированы для локальной разработки. Для масштаба требуется адаптация под оркестраторы вроде Kubernetes."

Для решения этих проблем в репозитории есть рекомендации по настройке k3s и Helm для масштабирования, но они требуют дополнительных усилий.

---

Полезные ссылки

• Shell Skills for Real Engineers

• Установка и запуск проекта mattpocock/skills

• Установка и использование проекта mattpocock/skills

• Установка и применение skills из mattpocock/skills

• GitHub - mattpocock/skills: Skills for Real Engineers. Straight from my ...

• skills/skills at main · mattpocock/skills · GitHub

• Matt Pocock's agent skills for real engineers: TDD, - explainx.ai

• mattpocock/skills: Skills for Real Engineers.... | GitGenius

• AI Skills for Real Engineers

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

Как добавить новый skill в директорию .claude, чтобы он был доступен агенту?

Во-первых, разместите файл с нужным именем в каталоге skills. Затем сделайте его исполняемым, добавив в начале строки #!/usr/bin/env bash. После этого обновите файл agents/openai.yaml, указав путь к новому скрипту в списке required_skills. При необходимости перезапустите Claude Code, чтобы он подхватил изменения.

Что делать, если skill требует переменных окружения или секретов?

С практической точки зрения, если skill требует переменных окружения, объявите их в файле .env, который будет загружен автоматически при запуске агента. Можно также передать значения через параметр env в конфигурации skill. При работе с секретами рекомендуется использовать хранилище, например, HashiCorp Vault — популярное решение, и передавать их в переменные через безопасный канал.

Как отладить skill, который завершается ошибкой?

Если skill падает, первым делом включите отладочный вывод, добавив опцию set -x в начале скрипта. Затем проверьте логи агента, они содержат подробные сообщения об ошибке. При необходимости используйте команду ask-matt, чтобы получить рекомендацию по конкретному сценарию.

Можно ли использовать skills в CI/CD пайплайнах?

В CI/CD пайплайнах skills можно вызывать напрямую, но следует отключить неявные вызовы в конфигурации агента. Это гарантирует, что каждый шаг будет выполнен только после вашего подтверждения. Кроме того, рекомендуется фиксировать версии используемых skill в lock-файле, чтобы обеспечить предсказуемость.

Эти вопросы охватывают типичные сценарии применения навыков из .claude-директории.