# Aither

> An AI-native Astro theme that believes text itself is beautiful.

---

## ✨ Почему Astro-Theme-Aither

URL: https://astro-theme-aither.pages.dev/ru/posts/why-astro-theme-aither/
Date: 2026-01-03
Category: Design
Tags: Design, Astro
Description: AI-нативная тема для Astro, которая верит, что текст сам по себе прекрасен.

AI-нативная тема для Astro, которая верит, что текст сам по себе прекрасен. Astro-Theme-Aither создана для читателей, которые приходят ради слов, а не ради украшений.

## Философия дизайна

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

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

## Типографика

Гарнитура шрифта — это визуальная идентичность. Каждая страница использует единый стек системных шрифтов без засечек — чистый, быстрый и единообразный на всех платформах. Типографические параметры следуют Apple Human Interface Guidelines:

- **Размер шрифта** — базовый 17px, оптимальный для комфортного чтения с экрана
- **Высота строки** — 1.47, дающая каждой строке пространство для «дыхания» без нарушения потока чтения
- **Межбуквенный интервал** — -0.022em, тонкое уплотнение, делающее основной текст отполированным
- **Шкала заголовков** — 31px → 22px → 19px → 17px, чёткая иерархия без экстремальных размеров
- **Ширина чтения** — ограничена 65–75 символами в строке, где глаз отслеживает текст с максимальным комфортом

Это практики, основанные на данных десятилетий исследований читаемости с экранов и типографических стандартах Apple.

## Построен на Astro

Astro — лучший фреймворк для контентных сайтов сегодня. Он по умолчанию генерирует статический HTML — никакого клиентского JavaScript, пока вы явно не подключите его. Архитектура островов означает, что интерактивные компоненты гидратируются независимо, а остальная часть страницы остаётся статичной.

В Astro-Theme-Aither интерактивных островов минимум:

- **Переключатель темы** — Light / Dark / System с анимацией кругового раскрытия через View Transitions API
- **Переключатель языка** — плавное переключение локали с сохранением в localStorage
- **Определение локали** — автоматическое определение языка браузера с предложением переключиться
- **Мобильная навигация** — адаптивное бургер-меню

Всё остальное — чистый HTML и CSS, загружается мгновенно.

## Возможности

- **Tailwind CSS v4** — `@theme` дизайн-токены с полной настройкой палитры для светлой/тёмной тем
- **Типографика Apple HIG** — параметры основного текста 17px / 1.47 / -0.022em
- **View Transitions API** — анимация кругового раскрытия при переключении темы
- **i18n** — мультиязычная поддержка с автоматическим определением языка браузера
- **Закрепление постов** — закрепление важных постов в верхней части списка
- **Content Collections** — типобезопасный Markdown с валидацией frontmatter на этапе сборки
- **Тёмная тема** — Light / Dark / System с сохранением в localStorage
- **SEO** — Open Graph, канонические URL, мета-описания для каждого поста
- **RSS + Sitemap** — автогенерация, без настройки
- **Google Analytics** — опционально, работает в Partytown Web Worker
- **Тестирование** — Vitest юнит-тесты + Playwright E2E, интегрированы в CI
- **Cloudflare Pages** — рабочий процесс деплоя с PR-превью

## Для кого это

Если вы верите, что хороший текст говорит сам за себя, и хотите тему, которая уважает это убеждение:

- **Персональные блогеры**, которые хотят, чтобы их тексты были на первом плане
- **Технические писатели**, которым нужна отличная отрисовка блоков кода и чёткое форматирование прозы
- **Мультиязычные авторы**, которым нужен встроенный i18n с автоматическим определением языка браузера
- **Разработчики**, ценящие качественную кодовую базу, которую можно уверенно расширять

Пишите о чём угодно — типографика сделает это красивым.

---

## 📝 Руководство по Markdown

URL: https://astro-theme-aither.pages.dev/ru/posts/markdown-guide/
Date: 2026-01-02
Category: Tutorial
Tags: Markdown, Guide
Description: Полное руководство по всем поддерживаемым возможностям Markdown в Astro-Theme-Aither

Этот пост демонстрирует все возможности Markdown, поддерживаемые Astro-Theme-Aither. Используйте его как справочник при написании собственных постов. Добавьте эту страницу в закладки — она охватывает весь спектр доступных вам форматирующих средств.

## Заголовки

Используйте `##` для заголовков разделов, `###` для подразделов и `####` для под-подразделов. Избегайте `#` в тексте поста — заголовок поста уже отображается как заголовок верхнего уровня.

### Заголовок третьего уровня

Заголовки третьего уровня идеально подходят для разделения секции на отдельные темы. Они создают визуальную иерархию, не будучи слишком заметными.

#### Заголовок четвёртого уровня

Заголовки четвёртого уровня подходят для мелких подразделов. Используйте их экономно — если структура требует глубины больше четырёх уровней, стоит перестроить контент.

### Рекомендации по заголовкам

Несколько рекомендаций для эффективного использования заголовков:

- **Не пропускайте уровни** — переходите от `##` к `###`, никогда от `##` сразу к `####`. Пропуск уровней нарушает структуру документа и может сбить с толку программы чтения экрана.
- **Пишите информативные заголовки** — «Настройка» лучше, чем «Всякое про установку». Читатели просматривают заголовки, прежде чем решить, читать ли раздел.
- **Используйте обычный регистр** — пишите с заглавной только первое слово и имена собственные.

## Абзацы и переносы строк

Обычный текст абзаца течёт естественно. Оставляйте пустую строку между абзацами для их разделения.

Это второй абзац. Старайтесь, чтобы каждый абзац был сосредоточен на одной идее для лучшего восприятия.

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

Одиночные переносы строк внутри абзаца (без пустой строки) обрабатываются как пробел, а не как новая строка. Если нужен жёсткий перенос без начала нового абзаца, завершите строку двумя пробелами или используйте тег `<br>` — хотя на практике это редко нужно.

## Выделение

- **Жирный текст** с помощью `**двойных звёздочек**`
- *Курсивный текст* с помощью `*одинарных звёздочек*`
- ***Жирный курсив*** с помощью `***тройных звёздочек***`
- ~~Зачёркнутый~~ с помощью `~~двойных тильд~~`

### Когда использовать каждый стиль

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

*Курсив* используется для выделения внутри предложения, названий книг и публикаций, технических терминов при первом упоминании и иностранных фраз. Он даёт более мягкое выделение, чем жирный.

~~Зачёркивание~~ полезно для отображения исправлений, устаревшей информации или выполненных пунктов в журнале изменений. У него более узкая область применения, но он ценен, когда необходим.

## Ссылки

[Встроенная ссылка](https://astro.build) с синтаксисом `[текст](url)`.

Ссылки также могут указывать на другие посты вашего сайта с помощью относительных путей. Используйте информативный текст ссылки — «прочитайте руководство по markdown» лучше, чем «нажмите сюда». Хороший текст ссылки помогает и читателям, и поисковым системам понять, куда она ведёт.

Вы также можете создавать ссылки, вписывающиеся в контекст, используя описательный якорный текст, естественно читающийся в предложении. Например: [документация Astro](https://docs.astro.build) подробно описывает все возможности.

## Списки

Маркированный список:

- Первый пункт
- Второй пункт
  - Вложенный пункт
  - Ещё один вложенный пункт
- Третий пункт

Нумерованный список:

1. Первый шаг
2. Второй шаг
   1. Подшаг один
   2. Подшаг два
3. Третий шаг

Список задач:

- [x] Настроить проект
- [x] Написать первый пост
- [ ] Развернуть в продакшен

### Советы по форматированию списков

Списки — один из самых эффективных инструментов веб-текста. Они разбивают плотный текст, делают информацию просматриваемой и чётко передают последовательности или коллекции элементов.

**Используйте маркированные списки**, когда у элементов нет определённого порядка — функции, требования, варианты или примеры.

**Используйте нумерованные списки**, когда последовательность важна — шаги процесса, ранжированные элементы или инструкции, которые нужно выполнять по порядку.

**Используйте списки задач** для отслеживания прогресса, чек-листов проекта или списков дел. Они отображаются как интерактивные чекбоксы во многих средствах просмотра Markdown, хотя в статическом блоге выглядят как визуальные индикаторы.

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

## Цитаты

> Цель абстракции — не в том, чтобы быть расплывчатым, а в том, чтобы создать новый семантический уровень, на котором можно быть абсолютно точным.
>
> — Эдсгер Дейкстра

Вложенные цитаты:

> Первый уровень
>
> > Второй уровень
> >
> > > Третий уровень

### Использование цитат

Цитаты служат нескольким целям помимо цитирования известных людей:

- **Указание источников** — при ссылке на другую статью, книгу или документ
- **Выделение важного** — акцент на важной информации или предупреждениях
- **Стиль email-цитирования** — показ того, что кто-то сказал в разговоре, на который вы отвечаете
- **Выносные цитаты** — привлечение внимания к ключевому фрагменту вашей собственной статьи

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

## Код

Встроенный `код` с обратными кавычками. Используйте встроенный код для имён функций вроде `getPublishedPosts()`, путей к файлам вроде `src/content/posts/`, команд терминала вроде `pnpm dev` и любых литеральных значений в тексте.

Блок кода с подсветкой синтаксиса:

```typescript
interface Post {
  title: string;
  date: Date;
  description?: string;
  tags?: string[];
  draft?: boolean;
}

function getPublishedPosts(posts: Post[]): Post[] {
  return posts
    .filter((post) => !post.draft)
    .sort((a, b) => b.date.getTime() - a.date.getTime());
}
```

```css
@theme {
  --font-sans: 'system-ui', sans-serif;
  --font-serif: 'ui-serif', 'Georgia', serif;
}
```

### Советы по блокам кода

Всегда указывайте идентификатор языка после открывающих тройных обратных кавычек. Это включает подсветку синтаксиса, которая значительно улучшает читаемость. Распространённые идентификаторы: `typescript`, `javascript`, `css`, `html`, `bash`, `json`, `python` и `markdown`.

Для команд оболочки используйте `bash` или `sh`:

```bash
# Установка зависимостей
pnpm install

# Запуск сервера разработки
pnpm dev

# Сборка для продакшена
pnpm build
```

Для JSON-конфигураций:

```json
{
  "name": "my-blog",
  "version": "1.0.0",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  }
}
```

Делайте блоки кода сфокусированными. Показывайте только нужные строки, а не весь файл. Если нужен контекст, добавьте комментарий о расположении кода.

## Таблицы

| Функция | Статус | Примечания |
|---|---|---|
| Тёмная тема | Поддерживается | Светлая / Тёмная / Системная |
| RSS-лента | Встроена | `/rss.xml` |
| Карта сайта | Автогенерация | Через `@astrojs/sitemap` |
| SEO | Встроен | Open Graph + canonical |

Выравнивание столбцов по правому краю и по центру:

| Лево | Центр | Право |
|:---|:---:|---:|
| Текст | Текст | Текст |
| Длинный текст | Длинный текст | Длинный текст |

### Рекомендации по таблицам

Таблицы лучше всего подходят для структурированных данных с чёткими столбцами и строками. Они идеальны для сравнения функций, параметров конфигурации, параметров API и справочных данных.

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

Выравнивание столбцов контролируется двоеточиями в строке-разделителе:

- `:---` для выравнивания по левому краю (по умолчанию)
- `:---:` для выравнивания по центру
- `---:` для выравнивания по правому краю

Используйте выравнивание по правому краю для числовых данных, чтобы десятичные точки визуально совпадали.

## Горизонтальная линия

Используйте `---` для создания горизонтальной линии:

---

Контент после линии.

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

## Изображения

Изображения поддерживаются стандартным синтаксисом Markdown:

```markdown
![Альтернативный текст](./image.jpg)
```

Эта тема ориентирована на типографику, но изображения работают, когда они необходимы.

### Рекомендации по изображениям

- **Всегда указывайте альтернативный текст** — он необходим для доступности и отображается при неудачной загрузке изображений
- **Используйте информативные имена файлов** — `dashboard-error-state.png` лучше, чем `screenshot-2.png`
- **Оптимизируйте размер файлов** — сжимайте изображения перед добавлением в репозиторий; большие изображения замедляют загрузку страниц
- **Учитывайте поток чтения** — размещайте изображения рядом с текстом, который на них ссылается, а не через несколько абзацев

## Подводя итог

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

Пишите ясно, форматируйте единообразно и дайте типографике делать своё дело.

---

## 👋 Привет, мир

URL: https://astro-theme-aither.pages.dev/ru/posts/hello-world/
Date: 2026-01-01
Category: Tutorial
Tags: Hello, Astro
Description: Добро пожаловать в Astro-Theme-Aither — тему для блога, где типографика определяет дизайн

Добро пожаловать в Astro-Theme-Aither.

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

## Зачем ещё одна тема для блога

В интернете множество тем для блогов, поэтому закономерный вопрос: зачем создавать ещё одну? Ответ кроется в приоритетах. Большинство тем оптимизированы для визуального эффекта — крупные изображения-заставки, сложные макеты, анимированные переходы. Они великолепно смотрятся в демо, но мешают, когда кто-то действительно садится читать статью на 2 000 слов.

Astro-Theme-Aither исходит из другой предпосылки. Контент — это продукт. Задача темы — подать этот контент с должным вниманием: продуманные сочетания шрифтов, щедрые пробелы и вертикальный ритм, делающий чтение длинных текстов комфортным, а не утомительным.

Эта философия распространяется и на технические решения. Тема отправляет примерно 0,5 КБ клиентского JavaScript — ровно столько, сколько нужно для переключения темы. Всё остальное — статический HTML и CSS. Никаких сдвигов макета, индикаторов загрузки и JavaScript-фреймворков, гидратирующихся в фоне. Страница загружается — и вы читаете.

## Начало работы

Запуск занимает всего несколько минут. Вот полный процесс:

1. **Клонируйте репозиторий** — используйте кнопку шаблона GitHub или клонируйте напрямую через `git clone`
2. **Установите зависимости** — выполните `pnpm install` для загрузки всех пакетов
3. **Настройте сайт** — отредактируйте `src/config/site.ts`, указав название сайта, описание и ссылки навигации
4. **Замените примеры контента** — замените посты в `src/content/posts/` собственными Markdown-файлами
5. **Начните разработку** — запустите `pnpm dev` для локального сервера с горячей перезагрузкой
6. **Разверните** — отправьте на GitHub, и встроенный CI-пайплайн автоматически развернёт на Cloudflare Pages

### Структура проекта

Кодовая база организована так, чтобы быть сразу понятной:

```
src/
├── components/     # Переиспользуемые Astro-компоненты
├── config/         # Конфигурация сайта
├── content/        # Ваши Markdown-посты и контент
├── layouts/        # Макеты страниц (Layout.astro)
├── pages/          # Страницы маршрутов
└── styles/         # Глобальный CSS с токенами Tailwind v4
```

У каждой директории чёткая ответственность. Компоненты маленькие и компонуемые. Макеты отвечают за оболочку документа. Страницы определяют маршруты. Контент хранит ваши тексты. Никакой магии — просто хорошо организованные файлы.

### Написание первого поста

Создайте новый `.md` файл в `src/content/posts/` со следующим заголовком:

```markdown
---
title: Заголовок вашего поста
date: 2026-01-15
category: General
description: Краткое описание для SEO и превью в соцсетях
tags: [Topic, Another]
---

Ваш контент начинается здесь.
```

Поля `title`, `date` и `category` обязательны. Поле `description` настоятельно рекомендуется, так как заполняет мета-тег описания и превью Open Graph. Теги необязательны, но помогают читателям находить связанный контент.

## Что вы получаете

Из коробки у вас готовая к продакшену блог-платформа со всеми нужными функциями и без лишнего.

### Контентные возможности

- **RSS-лента** — автоматически генерируется по адресу `/rss.xml`, совместима со всеми ридерами
- **Карта сайта** — автогенерация через `@astrojs/sitemap` для индексации поисковиками
- **SEO мета-теги** — Open Graph, Twitter-карточки и канонические URL на каждой странице
- **Тёмная тема** — трёхпозиционный переключатель (Светлая / Тёмная / Системная) с сохранением в `localStorage`
- **Страницы категорий и тегов** — организованные архивы для просмотра по темам

### Возможности для разработчиков

- **TypeScript повсюду** — strict-режим, полностью типизированные компоненты и утилиты
- **Content Collections** — встроенная система Astro для типобезопасного Markdown с валидацией frontmatter
- **Tailwind CSS v4** — используются `@theme` дизайн-токены для простой настройки цветов, шрифтов и отступов
- **Vitest + Playwright** — юнит-тесты и E2E-тесты, уже интегрированные в CI-пайплайн
- **Cloudflare Pages** — рабочий процесс деплоя с автоматическими PR-превью
- **Google Analytics** — опционально, изолирован в Partytown Web Worker, не блокируя основной поток

### Производительность

Поскольку тема генерирует статический HTML с минимумом JavaScript, производительность отличная по умолчанию. Ожидайте оценки Lighthouse 100 по всем параметрам — Производительность, Доступность, Лучшие практики и SEO. Оптимизировать нечего, потому что нет ничего лишнего.

## Кастомизация

Тема создана быть вашей. Наиболее частые настройки просты:

- **Цвета** — измените CSS-переменные в `src/styles/global.css` для смены всей палитры
- **Шрифты** — замените значения font-family в конфигурации темы Tailwind
- **Навигация** — обновите массив ссылок навигации в `src/config/site.ts`
- **Аналитика** — добавьте идентификатор Google Analytics в конфигурацию сайта

Для более глубоких изменений компонентная архитектура намеренно проста. Нет глубоко вложенных абстракций или сложных паттернов управления состоянием. Каждый компонент делает одно дело, читает свои props и рендерит HTML.

## Заметка о философии дизайна

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

Хороший дизайн невидим. Когда вы читаете статью с этой темой и просто наслаждаетесь текстом, не замечая темы вообще — значит, дизайн работает именно так, как задумано.

Приятного написания.

---

## ИИ-агенты и использование инструментов (пример)

URL: https://astro-theme-aither.pages.dev/ru/posts/ai-agents-and-tool-use/
Date: 2026-01-09
Category: AI
Tags: AI, Agents
Description: Как ИИ-модели выходят за рамки чата, выполняя действия в реальном мире

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

## От чата к действию

Чат-бот отвечает на вопросы. Агент решает задачи. Разница — в автономности: агенты сами решают, какие инструменты использовать, в каком порядке и как обрабатывать ошибки.

Рассмотрим разницу на практике. Вы спрашиваете чат-бота: «Какая погода в Токио?» Он может ответить на основе обучающих данных — которым месяцы или годы, и ответ почти наверняка будет неверным. Вы задаёте тот же вопрос агенту, и он вызывает API погоды, получает текущие данные и возвращает точный, актуальный ответ.

Чат-бот генерирует правдоподобный текст. Агент взаимодействует с миром.

### Спектр автономности

Не все агенты одинаково автономны. Существует спектр:

1. **Чат с инструментами** — модель может вызывать инструменты, но только в прямом ответ на запросы пользователя. Один вызов за ход.
2. **Многошаговые агенты** — модель может цепочкой вызывать несколько инструментов для выполнения задачи, самостоятельно определяя последовательность.
3. **Полностью автономные агенты** — модель работает независимо в течение продолжительных периодов, принимая решения, обрабатывая ошибки и преследуя цели при минимальном контроле человека.

Большинство продакшен-систем сегодня находятся на уровнях 1-2. Полностью автономные агенты — активная область исследований со значительными нерешёнными проблемами безопасности.

## Использование инструментов

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

### Как работает использование инструментов

Механика проста:

1. **Определение инструмента** — вы описываете доступные инструменты модели, включая их имена, параметры и назначение. Обычно это предоставляется как структурированный JSON в системном промпте или через специальное поле API.
2. **Решение** — при обработке запроса пользователя модель решает, будет ли инструмент полезен. Если да, она генерирует вызов инструмента с соответствующими параметрами.
3. **Выполнение** — ваше приложение выполняет вызов (модель не выполняет его напрямую) и возвращает результат.
4. **Интеграция** — модель включает результат инструмента в свой ответ пользователю.

### Пример определения инструмента

```json
{
  "name": "search_documentation",
  "description": "Search the product documentation for relevant articles",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results to return",
        "default": 5
      }
    },
    "required": ["query"]
  }
}
```

Модель видит это определение и знает, что может искать по документации. Когда пользователь задаёт вопрос о продукте, модель генерирует вызов вроде `search_documentation(query="how to reset password")`, ваша система выполняет поиск, а модель использует результаты для составления точного ответа.

### Распространённые категории инструментов

Продакшен-агентные системы обычно предлагают инструменты нескольких категорий:

- **Извлечение информации** — веб-поиск, запросы к БД, чтение файлов, вызовы API
- **Выполнение кода** — запуск Python, JavaScript или shell-команд в песочнице
- **Коммуникация** — отправка email, постинг сообщений, создание тикетов
- **Работа с файлами** — создание, редактирование и организация файлов
- **Системные операции** — деплой кода, управление инфраструктурой, запуск CI-пайплайнов

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

## Агентные циклы

Самый мощный паттерн — агентный цикл: модель планирует шаг, выполняет его, наблюдает результат и решает, что делать дальше. Цикл продолжается, пока задача не завершена или модель не определит, что не может продолжать.

### Цикл на практике

Рассмотрим агента, которому поручено отладить падающий тест:

1. **Планирование** — «Сначала нужно прочитать файл теста, чтобы понять, что он проверяет»
2. **Выполнение** — вызывает `read_file("tests/auth.test.ts")`
3. **Наблюдение** — видит, что тест ожидает статус 200, но получает 401
4. **Планирование** — «Нужно проверить middleware авторизации, чтобы понять, что возвращает 401»
5. **Выполнение** — вызывает `read_file("src/middleware/auth.ts")`
6. **Наблюдение** — находит баг в логике проверки срока действия токена
7. **Планирование** — «Нужно исправить сравнение сроков»
8. **Выполнение** — вызывает `edit_file(...)` с исправлением
9. **Наблюдение** — подтверждает, что правка применена
10. **Планирование** — «Нужно запустить тест для проверки исправления»
11. **Выполнение** — вызывает `run_command("pnpm test tests/auth.test.ts")`
12. **Наблюдение** — тест проходит
13. **Завершение** — сообщает об исправлении пользователю

Каждый шаг включает рассуждение модели о текущем состоянии, принятие решения о дальнейших действиях и адаптацию на основе обнаруженного. Это принципиально отличается от линейного скрипта — агент справляется с неожиданными находками и меняет курс при необходимости.

### Обработка ошибок в цикле

Надёжные агенты должны изящно обрабатывать сбои. Инструмент может вернуть ошибку, файл может не существовать, API может быть ограничен по частоте. Хороший дизайн агента включает:

- **Логику повторов** — повтор при временных сбоях с экспоненциальной задержкой
- **Альтернативные стратегии** — если один подход не сработал, попробовать другой
- **Изящную деградацию** — если задачу нельзя выполнить полностью, выполнить максимум возможного и объяснить, что осталось
- **Лимиты цикла** — максимальное число итераций для предотвращения бесконечных циклов, когда агент застревает

## Проектирование эффективных инструментов

Качество агентной системы сильно зависит от качества инструментов. Плохо спроектированные инструменты ведут к путанице агента и неверным результатам.

### Принципы проектирования инструментов

- **Понятные имена** — `search_users` лучше, чем `query_db_1`. Модель использует имя для решения, когда вызывать инструмент.
- **Описательные параметры** — включайте описания для каждого параметра. Модель читает эти описания, чтобы определить, какие значения передать.
- **Узкий фокус** — каждый инструмент должен делать одно дело хорошо. `read_file` и `write_file` лучше, чем `file_operations` с параметром режима.
- **Полезные ошибки** — возвращайте понятные сообщения об ошибках, помогающие модели понять, что пошло не так и что попробовать вместо этого.
- **Идемпотентность по возможности** — инструменты, которые можно безопасно повторить, упрощают обработку ошибок.

## Риски

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

### Категории рисков

- **Деструктивные действия** — агент с доступом к файловой системе может удалить важные файлы. Агент с доступом к БД может удалить таблицы. Песочницы и границы прав необходимы.
- **Утечка данных** — агент, способный и читать конфиденциальные данные, и делать сетевые запросы, может непреднамеренно (или через prompt injection) передать информацию наружу.
- **Неконтролируемые расходы** — агент в цикле, вызывающий дорогие API, может быстро накопить значительные затраты. Бюджетные лимиты и ограничение частоты — практическая необходимость.
- **Неверные действия, выполненные с уверенностью** — агент может неправильно понять запрос и совершить необратимое действие. Для операций с высокими ставками всегда требуйте подтверждения человека.

### Паттерны безопасности

Продакшен-агентные системы должны реализовывать несколько паттернов безопасности:

1. **Минимальные привилегии** — давайте агенту только инструменты, нужные для конкретной задачи, не более
2. **Песочница** — выполняйте код и файловые операции в изолированных средах
3. **Шлюзы подтверждения** — требуйте одобрения человека для деструктивных или необратимых действий
4. **Журнал аудита** — записывайте каждый вызов инструмента и его результат для проверки
5. **Аварийное отключение** — обеспечьте механизмы немедленной остановки работающего агента
6. **Бюджетные лимиты** — установите жёсткие ограничения на вызовы API, использование токенов и вычислительное время

Цель — не мешать агентам быть полезными, а обеспечить их полезность в чётко определённых границах.