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

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

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

AI Factory

https://github.com/lee-to/ai-factory

AI Factory — основа этого подхода: среда для AI-разработки, которая настраивает контекст, скиллы, интеграции и рабочие процессы вокруг агента. В README она описана как способ перестать тратить время на конфигурацию и начать строить: один запуск подготавливает проект, определяет стек, подключает практики и даёт агенту воспроизводимый workflow.

Для манифеста это важный пример: хорошие практики не должны жить только в голове или в промптах. Их нужно упаковывать в команды, скиллы, проверки и повторяемые сценарии.

HLV

https://github.com/lee-to/hlv

HLV — инструмент для spec-driven разработки, где человек описывает что должно быть сделано, LLM пишет код, а независимый Rust-бинарник проверяет доказательства: контракты, трассируемость, планы, gates и соответствие результата спецификации.

Это пример идеи «доверяй, но проверяй» в жёсткой форме: код не является источником истины, источником истины становятся контракты и проверяемые инварианты.

AI Workspace

https://github.com/lee-to/ai-workspace

AI Workspace — CLI и MCP-сервер для памяти между проектами. Он позволяет шарить файлы, директории и заметки между связанными репозиториями, чтобы агент видел общий контекст, а не начинал каждый разговор внутри одного изолированного проекта.

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

AI Tester

https://github.com/lee-to/ai-tester

AI Tester — инструмент для end-to-end проверки скиллов, системных промптов и агентных runtime. Он запускает реальные сценарии в изолированном git-sandbox, записывает tool-call trace и проверяет поведение декларативными YAML-assertions.

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

Но сам факт tool-use не гарантирует правильность результата. Агент может выбрать правильный инструмент и всё равно неверно интерпретировать вывод, пропустить edge case или решить, что задача завершена слишком рано. Инструменты повышают проверяемость, но не отменяют критерии качества, логи, тесты и человеческий контроль.

mcpunit

https://github.com/lee-to/mcpunit

mcpunit — CI-grade аудит качества MCP-серверов. Он проверяет названия tools, описания, схемы входов, опасные возможности, размер ответов и другие свойства, которые напрямую влияют на то, как агент понимает и использует MCP-инструменты.

Это пример того, что инфраструктура для агентов тоже нуждается в линтинге. MCP-сервер — это контракт, которому агент доверяет, поэтому его качество должно измеряться до того, как агент начнёт им пользоваться.

AIF Handoff

https://github.com/lee-to/aif-handoff

AIF Handoff — автономная Kanban-доска, где AI-агенты планируют, реализуют и ревьюят задачи по стадиям: backlog, planning, plan ready, implementing, review, done. В ней workflow AI Factory превращён в управляемый процесс с runtime-профилями, subagents, review-loop и явной передачей человеку, когда автоматизация перестаёт сходиться.

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

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

Суть: AI Native — это не один удачный промпт, а повторяемый цикл: исследование → план → критерии проверки → реализация → проверка → обновление правил и артефактов.

Почему это важно:

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

Базовый цикл убирает случайность:

1. Исследование — модель изучает код, документы, референсы, ограничения и предыдущие решения.
2. План — появляется последовательность действий, а не хаотичный набор правок.
3. Критерии проверки — заранее понятно, что должно получиться и как это подтвердить.
4. Реализация — выполняется ограниченный набор изменений.
5. Проверка — запускаются тесты, ревью, ручные сценарии, аудит другой моделью.
6. Обновление процесса — ошибка превращается в правило, тест, чеклист, скилл или артефакт.

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

План проверки

Перед реализацией полезно явно записать:

Задача:
Ожидаемый результат:
Что должно измениться:
Что не должно измениться:
Проверки:
- unit-тесты
- интеграционные тесты
- ручной сценарий
- проверка логов
- проверка edge cases

Критерии готовности:
- ...

Такой шаблон снижает риск, что модель выполнит видимую часть задачи и пропустит важное ограничение. Особенно это важно для задач, где ошибка выглядит как «почти правильно»: интерфейс открылся, но edge case сломан; тест зелёный, но контракт изменился; текст написан, но факт не проверен.

Чем отличаются близкие шаги

Декомпозиция, микрозадачи, план и критерии проверки похожи, но отвечают на разные вопросы:

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

Если эти понятия смешать, процесс начинает повторяться по кругу. Модель вроде бы «планирует», но не знает критериев готовности. Или получает «одну задачу», которая на самом деле является целым проектом. Разделение этих уровней делает работу спокойнее: сначала разбей, потом выбери следующий кусок, затем зафиксируй порядок и только после этого проверяй результат.

Масштаб процесса

AI Native-подход не должен превращаться в ритуал ради ритуала. Уровень процесса должен соответствовать цене ошибки.

Минимальный уровень подходит для маленькой задачи:

цель → ограничение → результат → проверка

Проектный уровень нужен для обычной инженерной задачи:

референсы → план → реализация → тесты → ревью

Командный уровень нужен для большого проекта:

артефакты → правила → чеклисты → CI → handoff → аудит

Агентный уровень нужен для систем с несколькими агентами:

роли → права → инструменты → trace → security gates → human approval

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

Один цикл в разных профессиях

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

Программист:

исследовать код → написать план → реализовать → запустить тесты → обновить чеклист

Дизайнер:

бриф → референсы → варианты → критерии оценки → ревью → финальный макет

Аналитик:

источники → проверка данных → гипотезы → риски → отчёт → список ограничений

Менеджер:

цель → ограничения → варианты решения → риски → план коммуникации → контроль результата

Автор текста:

тема → тезисы → структура → черновик → редактура → фактчекинг

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

Начни с себя, а не с модели

Суть: Если ИИ выдаёт слабый результат, сначала проверь постановку задачи, контекст и критерии качества.

Почему это важно:

Самая частая ошибка — сделать вывод «модель не справляется» после первого неудачного ответа. Иногда модель действительно не подходит для задачи. Но сначала стоит проверить то, чем управляешь ты: ясность запроса, полноту контекста, актуальность референсов и способ проверки результата. Большая часть плохих ответов возникает не из-за «глупости» модели, а из-за слабой постановки задачи и отсутствия обратной связи.

Смена мышления начинается с простого шага: вместо «ИИ плохой» — «что в моём процессе позволило получить такой результат?».

Превращай провалы в шаблоны

Суть: Каждый плохой ответ — это материал для будущих инструкций.

Почему это важно:

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

Алгоритм:

1. Получил плохой результат.
2. Спроси себя: что конкретно не так? Стиль? Структура? Формат? Глубина?
3. Сформулируй, как должно быть.
4. Запиши это как правило в инструкции, шаблон или референс.
5. В следующий раз — подай это модели заранее.

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

Ты создаёшь память для ИИ

Суть: LLM не помнит тебя. Память — это то, что ты ей подаёшь каждый раз.

Почему это важно:

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

Работа с ИИ — это постоянное формирование внешней памяти:

• Системные инструкции — кем должна быть модель в твоём контексте.
• Шаблоны задач — как ставятся типовые задачи.
• Референсы — как выглядит эталонный результат.
• Правила поведения — что нельзя делать ни при каких условиях.

Чем лучше эта память — тем выше качество ответов. Без неё каждый новый чат — это попытка объяснить всё заново.

Держи модель в тонусе

Суть: Без рамок LLM расплывается. Твоя задача — постоянно задавать и удерживать эти рамки.

Почему это важно:

Модель стремится к усреднению: она отвечает «как в большинстве случаев». Но тебе не нужен усреднённый ответ — тебе нужен правильный. Удержание модели в рамках — это активная работа:

• Проверяй каждый значимый результат на соответствие требованиям.
• Возвращай модель к инструкциям, если она начинает их игнорировать.
• Корректируй шаблоны, когда замечаешь системный сбой.
• Не принимай «достаточно хорошо» за «правильно».

Это бесконечный процесс. Модель не научится сама — её учишь ты, каждый раз.

Автоматизация начинается с мышления, а не с кода

Суть: Настоящая автоматизация — это не скрипт, это система работы с ИИ, которую ты построил.

Почему это важно:

Люди часто думают, что «автоматизация с ИИ» — это написать промпт и получить результат. На самом деле автоматизация — это:

• Наработанная библиотека шаблонов и инструкций.
• Чёткие критерии качества результата.
• Процедура проверки и доработки.
• Обратная связь: каждый провал превращается в улучшение шаблона.

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

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

Логируй каждый шаг

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

Почему это важно:

Без логов отладка превращается в гадание. С ними — ты точно видишь, что произошло до ошибки, с какими данными и в каком состоянии.

Что логировать в обычных AI-вызовах:

• prompt или ссылку на версию промпта
• input и ключевые параметры
• model, reasoning budget, temperature и другие настройки
• output или важные фрагменты ответа
• decision — какое решение принято по ответу
• validation result — какая проверка подтвердила или отклонила результат
• ошибки с полным стектрейсом

Что логировать в агентных системах:

• agent_id, роль и цель агента
• доступные инструменты
• tool calls и tool results
• промежуточные решения
• handoff между агентами
• финальный результат
• ошибки, retries и остановки по safety-gate

Tool-use сам по себе не гарантирует правильность. Агент может выбрать правильный инструмент, но неверно интерпретировать вывод, пропустить edge case или решить, что задача выполнена слишком рано. Поэтому лог должен фиксировать не только факт вызова инструмента, но и то, как результат был использован и чем проверен.

Что нельзя логировать:

• секреты, токены и API-ключи
• пароли и приватные ключи
• персональные данные без необходимости
• чувствительные customer data
• приватный код, если для отладки достаточно ссылки на версию или хеша

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

Для агентных систем логом становится не только текст ответа, но и последовательность действий: какие инструменты были вызваны, с какими аргументами, в каком порядке и к чему это привело. Поэтому тестировать нужно даже инструкции и скиллы. AI Tester решает именно эту задачу: запускает реальные сценарии в изолированном git-sandbox, сохраняет tool-call trace и проверяет поведение декларативными assertions.

Пример — плохо:

try:
    result = call_ai(prompt)
    process(result)
except Exception:
    print("Error")

Пример — хорошо:

logger.info("Sending prompt", extra={"model": model, "prompt_len": len(prompt)})
result = call_ai(prompt)
logger.info("Response received", extra={"tokens": result.usage})
process(result)

Проверяй работу в несколько итераций разными сессиями

Суть: Не доверяй результату одной сессии — аудитируй в чистой, желательно другой моделью.

Почему это важно:

Одна сессия накапливает bias — модель «защищает» свои решения. Чистая сессия видит код свежим взглядом, а другая модель ловит другие классы ошибок.

Процесс:

• Выполни задачу → попроси структурированный handoff
• Открой чистую сессию (другая модель) → аудит
• Замечания → новая сессия → исправления
• Повторяй пока аудит чистый

Обычное саммари легко теряет важные детали: ограничения, edge cases, причины решения, временные костыли, альтернативы. Проси не пересказ, а рабочий handoff:

Сделано:
Изменённые файлы:
Почему принято такое решение:
Что проверено:
Что не проверено:
Риски:
Оставшиеся вопросы:
Что важно не забыть в следующей сессии:

Так следующая сессия получает не красивый отчёт, а актуальный артефакт передачи работы.

Пример — плохо:

Сессия 1: напиши фичу → готово → мержим

Пример — хорошо:

Сессия 1 (Opus): фича → handoff
Сессия 2 (Sonnet): аудит → замечания
Сессия 3 (Opus): исправления → handoff
Сессия 4 (Sonnet): аудит → ok → мержим

AI Factory: используй aif-verify для автоматической проверки что реализация действительно выполнена.

Одна задача — один промпт

Суть: Не отправляй AI весь репорт с десятью проблемами — отправляй по одной задаче за раз в чистой сессии.

Почему это важно:

Когда AI получает длинный список задач, качество решения каждой падает. Модель пытается охватить всё сразу, путает контекст между задачами, забывает детали и делает поверхностные исправления. Чистая сессия на одну задачу даёт максимум внимания и качества.

Здесь «задача» — не бизнес-задача целиком. «Сделать биллинг», «починить авторизацию» или «добавить интеграцию» для модели слишком крупно. Микрозадача — это законченный контролируемый шаг:

• поправить конкретный класс
• найти нужную функцию
• проверить один модуль
• написать один тест
• изменить один контракт
• реализовать один action, controller или use case
• проверить одну гипотезу

Большая задача остаётся у человека или координатора. Модель получает один проверяемый фрагмент внутри неё.

Процесс:

• Получи репорт с N проблемами
• Сессия-координатор: отправь задачу #1 в чистую сессию
• Чистая сессия: реализация задачи #1
• Сессия-координатор: проверь, что задача #1 выполнена
• Если не выполнена — итерируй между сессиями до завершения
• Переходи к задаче #2 в новой чистой сессии

Пример — плохо:

Промпт: "Исправь баг с авторизацией И добавь валидацию форм И обнови стили
кнопок И почини пагинацию И добавь логирование"

Пример — хорошо:

Сессия-координатор: "Задача #1 — исправь баг с авторизацией" → чистая сессия
Сессия-координатор: "Задача #1 выполнена?" → проверка → ok
Сессия-координатор: "Задача #2 — добавь валидацию форм" → чистая сессия
...

Исключение: Тривиально связанные микроизменения можно объединять — например, «исправь бордер у кнопки и цвет текста». Здравый смысл важнее формального следования правилу.

AI Factory: используй aif-implement для реализации каждой микрозадачи в изолированной сессии.

Сначала декомпозируй, потом реализуй

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

Почему это важно:

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

Процесс:

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

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

Пример — плохо:

Промпт: "Добавь систему уведомлений с email, push и in-app каналами,
настройками пользователя и историей отправок"

Пример — хорошо:

Декомпозиция:
1. Схема БД для уведомлений (таблица notifications)
2. API эндпоинт создания уведомления
3. In-app канал отправки
4. Email канал отправки
5. Push канал отправки
6. Настройки пользователя (какие каналы включены)
7. История отправок и статусы доставки

План: 1 → 2 → 3 → 6 → 4 → 5 → 7
Реализация: по одной подзадаче за сессию

AI Factory: aif-explore для ресёрча перед стартом, aif-roadmap для декомпозиции, aif-plan для построения плана реализации.

Создавай план в файле, а не в plan mode

Суть: Перед реализацией крупной задачи создай план в markdown-файле с чеклистами, а не полагайся на встроенный plan mode агента.

Почему это важно:

Plan mode хранит план только в контексте текущей сессии. При большой задаче контекст раздувается, и если сессия прервётся — план теряется, работу приходится начинать сначала. Файл с планом решает обе проблемы: он переживает любой сбой сессии и позволяет нескольким агентам работать параллельно над разными задачами из одного плана.

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

В план стоит добавлять не только задачи, но и критерии проверки: какие команды запускать, какие сценарии пройти руками, какие файлы не должны измениться, какие edge cases особенно опасны. Без этого план отвечает только на вопрос «что делать», но не отвечает на вопрос «как понять, что сделано правильно».

Пример — плохо:

> /plan Реализуй систему авторизации с JWT, ролями и refresh-токенами

# Агент строит план в контексте, начинает реализацию.
# Через 40 минут контекст переполняется, сессия падает.
# Весь план и прогресс потеряны — начинаем сначала.

Пример — хорошо:

# PLAN.md — Система авторизации

## Задачи

- [x] Схема базы данных (users, roles, refresh_tokens)
- [x] JWT утилиты (sign, verify, refresh)
- [ ] Middleware авторизации
- [ ] Эндпоинты /login, /register, /refresh
- [ ] Тесты

> Реализуй следующую задачу из PLAN.md, отметь выполненное

# Агент читает файл, видит прогресс, продолжает с middleware.
# При сбое — следующая сессия подхватит с того же места.
# Два агента могут работать параллельно над независимыми задачами.

Рекомендуемые навыки ai-factory:

• aif-plan — создание плана в файле
• aif-improve — доработка и уточнение плана
• aif-implement — реализация задач из плана с отметкой прогресса

Создавай референсы для конкретной темы задачи

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

Почему это важно:

Даже самые продвинутые модели имеют неполные или устаревшие знания о библиотеках, SDK и инструментах. Claude Code не знает досконально собственный Agent SDK, формат скиллов или мету субагентов. Если документация занимает пару страниц — дешевле один раз сформировать референс, чем каждый раз надеяться на память модели или тратить токены на context7 MCP.

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

Хороший референс — это не «документация вообще», а нужный фрагмент знания под конкретное решение. Если задача про Agent SDK, не обязательно тащить весь сайт документации. Часто лучше собрать отдельные референсы по аспектам:

• tools
• tracing
• handoff
• memory
• streaming
• guardrails
• ограничения
• примеры использования
• changelog или актуальная версия

Большой документ рядом с моделью не равен полезному контексту. Референс должен отвечать на вопрос текущей задачи.

Пример — плохо:

> Создай скилл для Claude Code

# Агент генерирует по памяти. Формат устарел, поля неправильные,
# мета не соответствует текущей спецификации.
# Результат: нерабочий скилл, потраченное время на отладку.

Пример — хорошо:

> /aif-reference https://docs.anthropic.com/en/docs/agents-sdk
> /aif-reference https://docs.anthropic.com/en/docs/claude-code/skills

# Агент формирует .ai-factory/references/claude-agent-sdk.md
# и .ai-factory/references/claude-code-skills.md

> Создай скилл для Claude Code

# Агент читает референсы, использует актуальный формат.
# Результат: рабочий скилл с первой попытки.

Рекомендуемые навыки ai-factory:

• aif-reference — создание референсов из URL, документов и файлов
• aif-explore — исследование доступной документации перед началом работы