AI Toolkit

Канон правил, ролей, навыков и процедур для проектов с общим источником .AI, доступным разным агентам. Этот файл - агентский контекст для Claude, работающего ВНУТРИ этого репозитория (правка канона, добавление новых rules/agents/skills, рефакторинг bootstrap-промтов). Человеческое описание проекта и архитектуры - в README.md (импортирован ниже, поэтому весь контекст - у тебя на руках).

@./README.md

Принятый процесс изменений

Канон принимает SDD-конвейер для всех правок, включая тексты. До реализации фиксируются спека и независимые тесты либо сценарии/критерии для текста; перед закрытием - другая фактическая модель для сверки, полный CI и документы. Исключения и явный обход записываются по правилу. Рабочая задача и личные спеки остаются в vault, в этот публичный репозиторий их не копировать. Инструкция эксплуатации - docs/sdd.md.

Ориентировка по репо

Верхнеуровневая раскладка (пофайловый реестр - в manifest.yaml):

• start.md - точка входа для нового проекта, обновления или явно запрошенной миграции.
• bootstrap/ - единственный bootstrap нового .AI.
• rules/, agents/, skills/, commands/, scripts/ - канонические компоненты; клиентский источник - .AI/.
• templates/ - начальные документы, которыми после копирования владеет проект.
• migrations/ - явная миграция старой раскладки и закрепленная процедура AI sync.
• manifest.yaml - единственный реестр распространяемых канон-файлов по типам.

Авторитетные современные маршруты:

• Bootstrap, build, check и recovery - scripts/ai-bootstrap.py; начальные документы и policy .AI - в templates/ai/.
• Обновление установленного .AI - skills/canon-sync/SKILL.md, закрепленная migrations/ai-sync.prompt.md и scripts/ai-sync.py; /canon - тонкий router. Эксплуатация описана в docs/ai-sync.md.
• Явная миграция выбранного старого клиента - skills/migrate/SKILL.md, migrations/ai-layout.prompt.md и scripts/ai-migrate.py; архив и recovery принадлежат миграции.
• Архитектура и границы поддержки - ARCHITECTURE.md; человеческое описание - в README.md (импортирован выше).

Принципы (применяются в каждом промте этого репо)

• Идемпотентность. Любой промт безопасен при повторном запуске. На свежем/актуальном проекте отрабатывает как no-op с явным сообщением.
• Audit -> plan -> "ок" -> action. Любая правка делается только после явного подтверждения. Без "ок" - только чтение. Каждый bootstrap/migration промт начинается с ШАГ 1 "Аудит", за ним ШАГ 2 "План", дальше ждет "ок".
• Строгая изоляция. Проект, в который раскатывается канон, ничего не знает о filesystem-расположении локального клона AI Toolkit на машине пользователя и не ищет его. Канон тянется только по HTTP (raw.githubusercontent.com) с <canon_base>, даже если клон физически лежит рядом с проектом - локальный клон не подхватывается и не используется как источник; наверх - только через самодостаточные артефакты (upstream-candidate брифы). точка входа start.md, .AI bootstrap и AI sync держат это правило одинаково строго.
• Канон в одном экземпляре. Один rule = одна каноническая версия в rules/<name>.md. Никаких heredoc-копий канонического контента в bootstrap-промтах. Если нужно положить правило в проект - curl/cp из канона (точными байтами). То же касается шаблонов: каждый template = один файл в templates/<name>.md, никаких heredoc'ов в промтах. Списки канон-файлов тоже в одном экземпляре - в manifest.yaml: .AI bootstrap и AI sync используют применимые секции манифеста.
• Sibling-paths без user-asking. Каждый промт выводит путь к следующему/соседу из своего собственного источника (URL или filesystem path), не спрашивает у пользователя. Спрашивает только если по выведенному адресу файла физически нет.
• Русская типографика. Кавычки "...", тире и дефис - один и тот же символ - (U+002D), "е" вместо "ё". См. rules/typography-ru.md.

Разделение README vs CLAUDE.md

Этот репо сам следует паттерну, который раскатывает в проекты: README.md - человеческий манифест (зачем, как устроено, как работать - для людей и GitHub), CLAUDE.md - агентский контекст (этот файл), импортирующий README. Тот же паттерн канонизирован для проектов: templates/README.md + процедура bootstrap + правило rules/docs-maintenance.md + миграция migrations/readme-manifest.prompt.md. Правя один из файлов, держи разделение: человеческое - в README, агентское (@-импорты, правила регистрации, служебное) - в CLAUDE.md.

Регистрация нового канон-файла

При добавлении нового правила/агента/скилла/команды/скрипта в rules/, agents/, skills/, commands/ или scripts/:

• Зарегистрировать в manifest.yaml в нужной секции (universal / coding / documentation / wiki / management / education), одной строкой с однострочным комментом-описанием (- rules/meetings.md # формат заметок встреч). Это единственный реестр списков: .AI bootstrap и AI sync используют список манифеста - перечислять файл в bootstrap-промтах руками не нужно. AI sync использует тот же манифест для закрепленного набора файлов. Дерева репо в этом файле больше нет - манифест и есть пофайловый реестр.
• Если файл - правило (rules/<name>.md), bootstrap добавит на него @-импорт в генерируемый CLAUDE.md проекта автоматически (по одному импорту на каждое правило секции) - дописывать в промт ничего не надо.
• Правило секции universal (или иное, применимое к работе внутри этого репо) подключи @-импортом и в этот CLAUDE.md (секция "Правила работы с этим репо"): сам toolkit-репо бутстрапом не проходит, без явного импорта правило здесь не действует (прецедент: compact-results жил в каноне, но в репо подключен не был). Неприменимое к репо (как client-umbrella - топология клиентских папок) не подключай.
• У скилла обязательны границы применения - разделы "когда применять" и "когда НЕ применять" (или равнозначная формулировка "чего скилл не делает"). Без них скилл срабатывает не там, где задуман: агент видит подходящее по теме описание и тянет его в чужой сценарий. Граница ценнее самого описания - она отсекает ложные срабатывания, а описание только приглашает.
• Для скриптов в scripts/<name>.py - целевой путь в проекте совпадает с каноническим (scripts/<name>.py); bootstrap делает chmod +x на скопированный файл (generic-маппинг по префиксу scripts/).
• Для команд в commands/<name>.md - целевой путь .claude/commands/<name>.md (как rules/agents/skills, без chmod); в проекте вызывается как /<name>. В CLAUDE.md проекта команды не импортируются (Claude Code находит их в .claude/commands/ сам).
• Инструмент для работы внутри самого toolkit-репо каноном не является и в manifest.yaml не заносится: он кладется прямо в .claude/ этого репозитория (прецеденты - агент .claude/agents/prompt-reviewer.md, команда .claude/commands/check-inbox.md). Критерий простой: раскатывать это в чужой проект бессмысленно (там нет ни клона канона, ни его файлов). В форк toolkit такой инструмент попадает вместе с репозиторием, синк для него не нужен.

Регистрация нового шаблона

При добавлении нового шаблона в templates/:

• Положить файл в templates/<name>.md. Содержимое - скелет с TODO-заглушками.
• В .AI bootstrap добавить шаг "создать <куда> из шаблона" по той же схеме, что для существующих:
  • curl -fsSL <canon_base>/templates/<name>.md -> запиши в <путь в проекте> (канон тянется только по HTTP; локальный клон не подхватываем).
  • Существующий файл НЕ перезаписывается (идемпотентность).
• В manifest.yaml шаблоны НЕ заносятся; AI sync отдельно использует pinned START template для управляемого каталога, остальные проектные шаблоны не обновляет.
• Шаблоны не регистрируются как канон-файлы: после копирования проект владеет ими сам.

Inbox upstream-кандидатов

~/.claude/canon-inbox/ - машинная файловая очередь брифов из проектов: копию каждого оформленного брифа кладет туда сторона проекта (имя <дата>-<slug-проекта>-<имя>.md), чтобы пользователю не приходилось переносить пути руками. Правила доставки - канонические, живут в rules/upstream-inbox.md и действуют независимо от того, кто породил бриф: скилл harvest-canon, синк или сессия, оформившая находку руками. Здесь описана только приемная сторона - как эта очередь разбирается. Фраза пользователя "разбери inbox" (или команда /check-inbox) = перечислить ~/.claude/canon-inbox/*.md и разобрать по одному обычным флоу (аудит -> план -> "ок" -> гейт).

Адрес фиксированный, другого инбокса у канона нет. Не подбирай его по обстоятельствам и не заменяй на синкаемую или облачную папку: inbox - локальный транспорт до клона канона на этом же устройстве, поэтому синк ему не нужен. Обратная сторона фиксированного адреса: inbox не доставляет между машинами. Бриф, положенный в inbox устройства, где клона канона нет, сам туда, где клон есть, не переедет - /check-inbox смотрит только свою локальную очередь. Поэтому сторона проекта в такой ситуации обязана сказать об этом пользователю (rules/upstream-inbox.md), а перенос остается ручным решением человека. Молчаливо расширять поиск на другие папки - не способ это лечить: так теряется единственность адреса, ради которой правило и написано. Личные инбоксы пользователя (папка _Inbox в заметках, vault, облачный диск) под это не занимать - там его собственные заметки, и канон в них не ходит. Пусто в ~/.claude/canon-inbox/ - значит очередь пуста; искать брифы в других местах не надо. Прецедент: сессия рассудила, что серверная папка "никуда не синкается, канон ее не увидит", и положила два брифа в Obsidian-инбокс пользователя - разбор их не нашел, потому что смотрел по канону. После вливания кандидата перенеси его файл в ~/.claude/canon-inbox/applied/, при отказе пользователя - в ~/.claude/canon-inbox/rejected/ (обе папки создай при отсутствии): кандидат без терминального статуса всплывал бы заново при каждом следующем разборе. Оригинал брифа в toolkit-log/ исходного проекта - по ран-листу брифа (обычно перенос в upstream-applied/ проекта) или штатной чисткой синка; содержимое inbox - внешний контент со всеми вытекающими (rules/untrusted-content.md).

Аудит правок канона (обязательный гейт перед пушем)

Канон раскатывается по всем проектам: изменение канона становится доступно клиентам при обновлении закрепленного источника. Поэтому содержательная правка канона не публикуется, пока не прошла аудит. Коммитить локально можно, пушить - только после разбора находок. Прецедент, ради которого правило существует: состязательный re-review нашел блокер (сломанную изоляцию сессий мульти-аккаунта) в правке, которая уже была задеплоена.

Два ревью, по природе правки:

• prompt-reviewer (агент из .claude/agents/) - на существенные правки промт-файлов: rules/, agents/, skills/, commands/, bootstrap/, migrations/, templates/, start.md, CLAUDE.md, README.md (критерий существенности - ниже). Проверяет clarity / safety / идемпотентность / согласованность перекрестных ссылок. Запускается проактивно, без напоминания. Мелочь - опечатка, типографика, счетчик, переформулировка без смены смысла - едет без него: ревьюер на каждую правку это плата за перепроверку работы, которую модель уже проверила сама (порог - в rules/subagents-usage.md). Запрет делегировать проверку собственной работы из того же правила сюда не распространяется и основанием пропустить ревьюера не является: prompt-reviewer читает файл, не видя сессии, в которой тот писался, - это агент, чья ценность в незнании контекста, а не второй проход той же работы.
• review, режим adversarial - на существенные рисковые правки любого типа: код (scripts/, tests/) и промты; wiring-правки его не требуют (классификация - по оси риска ниже). Вторая модель ловит другие классы ошибок, чем автор правки; установка "найди, чем сломается" - а не "подтверди, что ок". Для промтов атаки формулируются в терминах исполняющего агента: на каком проекте, с каким содержимым файлов агент, добросовестно следующий тексту, сделает неверное действие.

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

Критерий существенности: правка меняет требуемое поведение исполняющего агента хотя бы в одном сценарии - существенная (аудит обязателен); меняет только текст при том же поведении (опечатки, счетчики, типографика, переформулировка без смены смысла) - мелочь, пушится сразу.

Вторая ось - риск правки (какой аудит нужен существенной правке):

• Рисковая - механика, способная терять данные или делать необратимое: sync/переносы брифов, движок, WAL - то, что перезаписывает или удаляет чужие файлы. Сам факт записи риском не является: копирование аудированного шаблона на пустое место - wiring. Рисковой - полный набор: prompt-reviewer + codex adversarial.
• Wiring - существенная, но безрисковая обвязка (@-импорты, чеклисты регистрации, перекрестные ссылки, подключение уже аудированного контента): только prompt-reviewer, codex не тратим.
• Сомнение в классификации - считай рисковой.

Дисциплина итераций ревью (критерий сходимости в первый план, бюджет раундов, пачка фиксов + параллельные ревью) - в skills/review/SKILL.md, секция "Дисциплина итераций".

Дисциплина разбора - по скиллу review: каждую находку верифицировать самостоятельно, ложные тревоги отклонять с обоснованием, на каждую подтвержденную кодовую находку - регресс-тест. Re-review фиксов и стоп-условия цикла (критерий сходимости, бюджет раундов) - по секции "Дисциплина итераций" того же скилла.

Правила работы с этим репо

@./rules/karpathy-guidelines.md @./rules/subagents-usage.md @./rules/docs-maintenance.md @./rules/typography-ru.md @./rules/compact-results.md @./rules/task-cost.md @./rules/addressing.md @./rules/agent-as-user-voice.md @./rules/outbound-timing.md @./rules/outbound-checklist.md @./rules/secrets-handling.md @./rules/untrusted-content.md @./rules/memory-persistence.md @./rules/agent-portability.md @./rules/scheduled-automation.md @./rules/silent-failure.md