Использование цепочки инструментов сборки

Чему вы научитесь

Закончив этот урок, вы сможете:

✅ Использовать pnpm validate для проверки формата и полноты файлов правил
✅ Использовать pnpm build для генерации AGENTS.md и test-cases.json
✅ Понимать процесс сборки: parse → validate → group → sort → generate
✅ Настроить GitHub Actions CI для автоматической валидации и сборки
✅ Извлекать тестовые случаи для автоматической оценки LLM
✅ Использовать pnpm dev для быстрого процесса разработки (build + validate)

Текущие проблемы

Если вы поддерживаете или расширяете библиотеку правил React, вы могли столкнуться с этими проблемами:

✗ После изменения правила забыли проверить формат, что привело к ошибкам в сгенерированном AGENTS.md
✗ Файлов правил становится все больше, ручная проверка полноты каждого файла занимает слишком много времени
✗ После отправки кода обнаружилось, что какому-то правилу не хватает примеров кода, что влияет на эффективность проверки PR
✗ Хотите автоматически проверять правила в CI, но не знаете, как настроить GitHub Actions
✗ Не понимаете процесс сборки build.ts, при возникновении ошибок не знаете, с чего начать поиск

Когда использовать этот метод

Когда вам нужно:

🔍 Проверить правила: перед отправкой кода убедиться, что все файлы правил соответствуют спецификации
🏗️ Сгенерировать документацию: из Markdown-файлов правил создать структурированный AGENTS.md
🤖 Извлечь тестовые случаи: подготовить тестовые данные для автоматической оценки LLM
🔄 Интегрировать CI: автоматизировать валидацию и сборку в GitHub Actions
🚀 Быстрая разработка: использовать pnpm dev для быстрой итерации и проверки правил

🎒 Подготовка перед началом

Перед началом убедитесь:

Предварительная проверка

Завершено Введение в Agent Skills
Установлены Agent Skills и вы знакомы с базовым использованием
Знакомы со спецификацией написания правил React (рекомендуется сначала изучить Написание правил лучших практик React)
Имеете базовый опыт работы с командной строкой
Знакомы с базовым использованием менеджера пакетов pnpm

Основная идея

Роль цепочки инструментов сборки:

Библиотека правил Agent Skills по сути — это 57 независимых Markdown-файлов, но Claude нужен структурированный AGENTS.md для эффективного использования. Цепочка инструментов сборки отвечает за:

Разбор файлов правил: извлечение из Markdown полей title, impact, examples и т.д.
Проверка полноты: проверка, есть ли у каждого правила title, explanation и примеры кода
Группировка и сортировка: группировка по главам, сортировка по заголовку в алфавитном порядке, присвоение ID (1.1, 1.2...)
Генерация документации: вывод форматированного AGENTS.md и test-cases.json

Процесс сборки:

rules/*.md (57 файлов)
    ↓
[parser.ts] разбор Markdown
    ↓
[validate.ts] проверка полноты
    ↓
[build.ts] группировка → сортировка → генерация AGENTS.md
    ↓
[extract-tests.ts] извлечение тестовых случаев → test-cases.json

Четыре основные команды:

Команда	Функция	Применимые сценарии
`pnpm validate`	Проверка формата и полноты всех файлов правил	Проверка перед отправкой, валидация CI
`pnpm build`	Генерация AGENTS.md и test-cases.json	После изменения правил, перед публикацией
`pnpm dev`	Выполнение build + validate (процесс разработки)	Быстрая итерация, разработка новых правил
`pnpm extract-tests`	Отдельное извлечение тестовых случаев (без пересборки)	При обновлении только тестовых данных

Следуйте за мной: используйте цепочку инструментов сборки

Шаг 1: Проверка правил (pnpm validate)

Почему При разработке или изменении правил сначала убедитесь, что все файлы правил соответствуют спецификации, чтобы избежать обнаружения ошибок только при сборке.

Перейдите в каталог инструментов сборки:

bash

cd packages/react-best-practices-build

Запустите команду проверки:

bash

pnpm validate

Вы должны увидеть:

bash

Validating rule files...
Rules directory: /path/to/skills/react-best-practices/rules
✓ All 57 rule files are valid

Если есть ошибки:

bash

✗ Validation failed:

  async-parallel.md: Missing or empty title
  bundle-dynamic-imports.md: Missing code examples
  rerender-memo.md: Invalid impact level: SUPER_HIGH

Проверяемое содержимое (исходный код: validate.ts):

✅ title не пустой
✅ explanation не пустой
✅ Хотя бы один пример кода
✅ Включает хотя бы один пример "Incorrect/bad" или "Correct/good"
✅ Уровень impact легален (CRITICAL/HIGH/MEDIUM-HIGH/MEDIUM/LOW-MEDIUM/LOW)

Шаг 2: Сборка документации (pnpm build)

Почему Сгенерируйте AGENTS.md и test-cases.json, используемые Claude, из файлов правил.

Запустите команду сборки:

bash

pnpm build

Вы должны увидеть:

bash

Building AGENTS.md from rules...
Rules directory: /path/to/skills/react-best-practices/rules
Output file: /path/to/skills/react-best-practices/AGENTS.md
✓ Built AGENTS.md with 8 sections and 57 rules

Сгенерированные файлы:

AGENTS.md (находится в skills/react-best-practices/AGENTS.md)
- Структурированное руководство по оптимизации производительности React
- Включает 8 глав, 57 правил
- Сортировано по уровню impact (CRITICAL → HIGH → MEDIUM...)
test-cases.json (находится в packages/react-best-practices-build/test-cases.json)
- Тестовые случаи, извлеченные из всех правил
- Включает bad и good примеры
- Используется для автоматической оценки LLM

Пример структуры AGENTS.md:

markdown

# React Best Practices

Version 1.0
Vercel Engineering
January 2026

---

## Abstract

Performance optimization guide for React and Next.js applications, ordered by impact.

---

## Table of Contents

1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
   - 1.1 [Parallel async operations](#11-parallel-async-operations)
   - 1.2 [Deferring non-critical async operations](#12-deferring-non-critical-async-outputs)

2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
   - 2.1 [Dynamic imports for large components](#21-dynamic-imports-for-large-components)

---

## 1. Eliminating Waterfalls

**Impact: CRITICAL**

Eliminating request waterfalls is the most impactful performance optimization you can make in React and Next.js applications.

### 1.1 Parallel async operations

**Impact: CRITICAL**

...

**Incorrect:**

```typescript
// Sequential fetching creates waterfalls
const userData = await fetch('/api/user').then(r => r.json())
const postsData = await fetch(`/api/user/${userData.id}/posts`).then(r => r.json())

Correct:

typescript

// Fetch in parallel
const [userData, postsData] = await Promise.all([
  fetch('/api/user').then(r => r.json()),
  fetch('/api/posts').then(r => r.json())
])


**Пример структуры test-cases.json**:

```json
[
  {
    "ruleId": "1.1",
    "ruleTitle": "Parallel async operations",
    "type": "bad",
    "code": "// Sequential fetching creates waterfalls\nconst userData = await fetch('/api/user').then(r => r.json())\nconst postsData = await fetch(`/api/user/${userData.id}/posts`).then(r => r.json())",
    "language": "typescript",
    "description": "Incorrect example for Parallel async operations"
  },
  {
    "ruleId": "1.1",
    "ruleTitle": "Parallel async operations",
    "type": "good",
    "code": "// Fetch in parallel\nconst [userData, postsData] = await Promise.all([\n  fetch('/api/user').then(r => r.json()),\n  fetch('/api/posts').then(r => r.json())\n])",
    "language": "typescript",
    "description": "Correct example for Parallel async operations"
  }
]

Шаг 3: Процесс разработки (pnpm dev)

Почему При разработке новых правил или изменении существующих правил требуется быстрая итерация, проверка и сборка всего процесса.

Запустите команду разработки:

bash

pnpm dev

Эта команда выполнит:

Выполнение pnpm build-agents (генерация AGENTS.md)
Выполнение pnpm extract-tests (генерация test-cases.json)
Выполнение pnpm validate (проверка всех правил)

Вы должны увидеть:

bash

pnpm build-agents && pnpm extract-tests
Building AGENTS.md from rules...
Rules directory: /path/to/skills/react-best-practices/rules
Output file: /path/to/skills/react-best-practices/AGENTS.md
✓ Built AGENTS.md with 8 sections and 57 rules

Extracting test cases from rules...
Rules directory: /path/to/skills/react-best-practices/rules
Output file: /path/to/skills/react-best-practices-build/test-cases.json
✓ Extracted 114 test cases to /path/to/skills/react-best-practices-build/test-cases.json
  - Bad examples: 57
  - Good examples: 57

Validating rule files...
Rules directory: /path/to/skills/react-best-practices/rules
✓ All 57 rule files are valid

Рекомендации по процессу разработки:

bash

# 1. Измените или создайте файл правила
vim skills/react-best-practices/rules/my-new-rule.md

# 2. Запустите pnpm dev для быстрой проверки и сборки
cd packages/react-best-practices-build
pnpm dev

# 3. Проверьте сгенерированный AGENTS.md
cat ../skills/react-best-practices/AGENTS.md

# 4. Протестируйте, правильно ли Claude использует новое правило
# (активируйте навык в Claude Code и протестируйте)

Обновление номера версии (необязательно):

bash

pnpm build --upgrade-version

Это автоматически:

Увеличит номер версии в metadata.json (например, 1.0 → 1.1)
Обновит поле version в Front Matter SKILL.md

Вы должны увидеть:

bash

Upgrading version: 1.0 -> 1.1
✓ Updated metadata.json
✓ Updated SKILL.md

Шаг 4: Отдельное извлечение тестовых случаев (pnpm extract-tests)

Почему Если вы только обновили логику извлечения тестовых данных и не нужно пересобирать AGENTS.md, можно выполнить только extract-tests.

bash

pnpm extract-tests

Вы должны увидеть:

bash

Extracting test cases from rules...
Rules directory: /path/to/skills/react-best-practices/rules
Output file: /path/to/skills/react-best-practices-build/test-cases.json
✓ Extracted 114 test cases to /path/to/skills/react-best-practices-build/test-cases.json
  - Bad examples: 57
  - Good examples: 57

Контрольная точка ✅

Теперь проверьте, понимаете ли вы цепочку инструментов сборки:

[ ] Знаете, какие поля правил проверяет pnpm validate
[ ] Знаете, какие файлы генерирует pnpm build
[ ] Знаете процесс разработки pnpm dev
[ ] Знаете назначение test-cases.json
[ ] Знаете, как обновить номер версии (--upgrade-version)
[ ] Знаете структуру AGENTS.md (главы → правила → примеры)

Интеграция GitHub Actions CI

Зачем нужно CI

В командной работе CI может:

✅ Автоматически проверять формат файлов правил
✅ Автоматически собирать AGENTS.md
✅ Предотвращать отправку кода, не соответствующего спецификации

Файл конфигурации CI

Конфигурация GitHub Actions находится в .github/workflows/react-best-practices-ci.yml:

yaml

name: React Best Practices CI

on:
  push:
    branches: [main]
    paths:
      - 'skills/react-best-practices/**'
      - 'packages/react-best-practices-build/**'
  pull_request:
    branches: [main]
    paths:
      - 'skills/react-best-practices/**'
      - 'packages/react-best-practices-build/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: packages/react-best-practices-build
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 10.24.0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
          cache-dependency-path: packages/react-best-practices-build/pnpm-lock.yaml
      - run: pnpm install
      - run: pnpm validate
      - run: pnpm build

Условия запуска CI

CI автоматически запустится в следующих случаях:

Событие	Условие
`push`	Отправка в ветку `main`, и изменены `skills/react-best-practices/` или `packages/react-best-practices-build/`
`pull_request`	Создание или обновление PR в ветку `main`, и изменены указанные пути

Шаги выполнения CI

Checkout кода: actions/checkout@v4
Установка pnpm: pnpm/action-setup@v2 (version 10.24.0)
Установка Node.js: actions/setup-node@v4 (version 20)
Установка зависимостей: pnpm install (использование кэша pnpm для ускорения)
Проверка правил: pnpm validate
Сборка документации: pnpm build

Если любой шаг не удается, CI пометит как ❌ и заблокирует слияние.

На что обратить внимание

Проблема 1: Проверка прошла, но сборка не удалась

Симптом: pnpm validate прошел, но pnpm build выдает ошибку.

Причина: проверка только проверяет формат файлов правил, не проверяет _sections.md или metadata.json.

Решение:

bash

# Проверьте, существует ли _sections.md
ls skills/react-best-practices/rules/_sections.md

# Проверьте, существует ли metadata.json
ls skills/react-best-practices/metadata.json

# Просмотрите конкретную ошибку в логах сборки
pnpm build 2>&1 | grep -i error

Проблема 2: ID правил не непрерывны

Симптом: ID правил в сгенерированном AGENTS.md пропускают номера (например, 1.1, 1.3, 1.5).

Причина: правила сортируются по заголовку в алфавитном порядке, не по имени файла.

Решение:

bash

# Сборка автоматически сортирует по заголовку и присваивает ID
# Если нужен пользовательский порядок, измените title правила
# Например: измените на "A. Parallel" (с A в начале будет排在 раньше)
pnpm build

Проблема 3: В test-cases.json только bad примеры

Симптом: pnpm extract-tests выводит "Bad examples: 0".

Причина: метки примеров в файлах правил не соответствуют спецификации.

Решение:

markdown

# ❌ Ошибка: метки не соответствуют спецификации
**Example:**

**Typo:**

# ✅ Правильно: используйте Incorrect или Correct
**Incorrect:**

**Correct:**

# или используйте метки bad/good (также поддерживаются wrong, usage и другие)
**Bad example:**

**Good example:**

Проблема 4: pnpm validate не удается в CI

Симптом: локально pnpm validate прошел, но CI не удается.

Причина:

Версия Node.js не совпадает (CI использует v20, локально может быть другая версия)
Версия pnpm не совпадает (CI использует 10.24.0)
Разница в окончаниях строк между Windows и Linux

Решение:

bash

# Проверьте локальную версию Node
node --version  # должна быть v20.x

# Проверьте локальную версию pnpm
pnpm --version  # должна быть >= 10.24.0

# Нормализуйте окончания строк (преобразуйте в LF)
git config core.autocrlf input
git add --renormalize .
git commit -m "Fix line endings"

Проблема 5: После обновления версии SKILL.md не обновлен

Симптом: после pnpm build --upgrade-version номер версии в metadata.json изменился, но SKILL.md не изменился.

Причина: формат версии в Front Matter SKILL.md не совпадает.

Решение:

yaml

# Проверьте Front Matter SKILL.md
---
version: "1.0"  # ✅ Должны быть двойные кавычки
---

# Если у версии нет кавычек, добавьте вручную
---
version: 1.0   # ❌ Ошибка
version: "1.0" # ✅ Правильно (добавьте двойные кавычки)
---

Итоги урока

Ключевые моменты:

Проверка (validate): проверка формата правил, полноты, уровня impact
Сборка (build): разбор правил → группировка → сортировка → генерация AGENTS.md
Извлечение тестов (extract-tests): извлечение bad/good примеров из examples
Процесс разработки (dev): validate + build + extract-tests для быстрой итерации
Интеграция CI: GitHub Actions автоматически проверяет и собирает, предотвращая отправку ошибочного кода

Рабочий процесс разработки:

Изменение/создание правил
    ↓
pnpm dev (проверка + сборка + извлечение тестов)
    ↓
Проверка AGENTS.md и test-cases.json
    ↓
Отправка кода → CI автоматически выполняется
    ↓
Проверка PR → слияние в main

Лучшая практика:

Сначала проверьте изменения, затем соберите и отправляйте Команда dev выполняет весь процесс, один шаг — высокая эффективность CI автоматически контролирует, проверка PR становится проще Обновляйте номер версии, не забудьте изменить metadata

Следующий урок

В следующем уроке мы изучим Устранение распространенных проблем.
Вы узнаете:
Решение ошибок сети при развертывании (Network Egress Error)
Обработка неактивации навыков
Устранение сбоев проверки правил (VALIDATION_ERROR)
Исправление неточного обнаружения фреймворка
Решение проблем с правами доступа к файлам

Приложение: Справочник по исходному коду

Нажмите, чтобы раскрыть расположение исходного кода

Обновлено: 2026-01-25

Функция	Путь к файлу	Строки
Определение скриптов package.json	`packages/react-best-practices-build/package.json`	6-12
Функция входа сборки	`packages/react-best-practices-build/src/build.ts`	131-290
Парсер правил	`packages/react-best-practices-build/src/parser.ts`	Весь файл
Функция проверки правил	`packages/react-best-practices-build/src/validate.ts`	21-66
Извлечение тестовых случаев	`packages/react-best-practices-build/src/extract-tests.ts`	15-38
Конфигурация путей	`packages/react-best-practices-build/src/config.ts`	Весь файл
GitHub Actions CI	`.github/workflows/react-best-practices-ci.yml`	Весь файл
Шаблон файлов правил	`skills/react-best-practices/rules/_template.md`	Весь файл

Ключевые константы (config.ts):

RULES_DIR: путь к каталогу файлов правил
METADATA_FILE: путь к файлу метаданных (metadata.json)
OUTPUT_FILE: путь к выходу AGENTS.md
TEST_CASES_FILE: путь к выходу JSON тестовых случаев

Ключевые функции:

build(): основная функция сборки, разбор правил → группировка → сортировка → генерация документации
validateRule(): проверка полноты одного правила (title, explanation, examples, impact)
extractTestCases(): извлечение bad/good тестовых случаев из examples правил
generateMarkdown(): генерация содержимого AGENTS.md из массива Section

Правила проверки (validate.ts:21-66):

title не пустой
explanation не пустой
хотя бы один пример кода
включает хотя бы один пример "Incorrect/bad" или "Correct/good"
уровень impact легален

Рабочий процесс CI:

Условия запуска: push/PR в main, и изменены skills/react-best-practices/** или packages/react-best-practices-build/**
Шаги выполнения: checkout → установка pnpm → установка Node.js → pnpm install → pnpm validate → pnpm build

Использование цепочки инструментов сборки ​

Чему вы научитесь ​

Текущие проблемы ​

Когда использовать этот метод ​

🎒 Подготовка перед началом ​

Основная идея ​

Следуйте за мной: используйте цепочку инструментов сборки ​

Шаг 1: Проверка правил (pnpm validate) ​

Шаг 2: Сборка документации (pnpm build) ​

Шаг 3: Процесс разработки (pnpm dev) ​

Шаг 4: Отдельное извлечение тестовых случаев (pnpm extract-tests) ​

Контрольная точка ✅ ​

Интеграция GitHub Actions CI ​

Зачем нужно CI ​

Файл конфигурации CI ​

Условия запуска CI ​

Шаги выполнения CI ​

На что обратить внимание ​

Проблема 1: Проверка прошла, но сборка не удалась ​

Проблема 2: ID правил не непрерывны ​

Проблема 3: В test-cases.json только bad примеры ​

Проблема 4: pnpm validate не удается в CI ​

Проблема 5: После обновления версии SKILL.md не обновлен ​

Итоги урока ​

Следующий урок ​

Приложение: Справочник по исходному коду ​

Использование цепочки инструментов сборки

Чему вы научитесь

Текущие проблемы

Когда использовать этот метод

🎒 Подготовка перед началом

Основная идея

Следуйте за мной: используйте цепочку инструментов сборки

Шаг 1: Проверка правил (pnpm validate)

Шаг 2: Сборка документации (pnpm build)

Шаг 3: Процесс разработки (pnpm dev)

Шаг 4: Отдельное извлечение тестовых случаев (pnpm extract-tests)

Контрольная точка ✅

Интеграция GitHub Actions CI

Зачем нужно CI

Файл конфигурации CI

Условия запуска CI

Шаги выполнения CI

На что обратить внимание

Проблема 1: Проверка прошла, но сборка не удалась

Проблема 2: ID правил не непрерывны

Проблема 3: В test-cases.json только bad примеры

Проблема 4: pnpm validate не удается в CI

Проблема 5: После обновления версии SKILL.md не обновлен

Итоги урока

Следующий урок

Приложение: Справочник по исходному коду