dot_ai

dot_ai — это набор workflow-инструментов для разработки с AI-агентами.

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

Проще говоря: dot_ai превращает “попросить AI что-то сделать” в повторяемый проектный процесс.

Зачем Это Нужно

AI-агенты полезны, но с ними легко уйти в хаос:

• инструкции расходятся между инструментами;
• промпты становятся устным знанием;
• агенты пропускают планирование или тесты;
• проектные решения остаются только в истории чата;
• “готово” часто заявляется, но не проверяется.

dot_ai отвечает на это набором проектных артефактов:

• workflow-навыки с правилами входа и выхода;
• ТЗ для нетривиальных изменений;
• валидаторы состояния workflow и согласованности артефактов;
• шаблоны для установки системы в другой проект;
• тесты и локальные eval-проверки для самих правил.

Цель проекта — не заменить инженерное мышление. Цель — сделать AI-assisted разработку более проверяемой, повторяемой и управляемой.

Что Внутри

dot_ai содержит:

• AGENTS.md и CLAUDE.md — входные инструкции для агентов;
• workflow-навыки в skills/;
• runtime-копии навыков для Codex и Claude в .agents/skills/ и .claude/skills/;
• проектные правила в rules/;
• установочные шаблоны в templates/;
• валидаторы в scripts/;
• проектную память и историю релизов в .ai/;
• регрессионные тесты в tests/.

Основной workflow:

1. plan-release — создать версионированное ТЗ и ветку.
2. implement-spec-stage — реализовать текущий этап ТЗ.
3. write-tests — добавить или усилить тесты.
4. integrate-release — обновить changelog/version artifacts и выполнить merge.
5. deploy-release — выполнить deploy после merge.

Есть также короткий маршрут:

1. apply-small-fix — небольшой фикс без ТЗ.
2. integrate-release
3. deploy-release

Быстрый Старт

Склонировать репозиторий:

git clone <repo-url>
cd dot_ai

Запустить тесты:

uv run pytest -q

Проверить синхронизацию source/runtime-копий навыков:

uv run python scripts/validate_source_sync.py

Запустить локальные deterministic eval-проверки:

uv run python scripts/run_local_evals.py

Установить dot_ai в другой проект через install-навык:

/install path/to/project

или попросить агента:

установи dot_ai в path/to/project

Установленный проект получает root workflow validator scripts/validate_workflow_state.py — обязательный artifact, проверяемый verify_install.py при установке и обновлении.

Структура Репозитория

Путь	Назначение
AGENTS.md	Главные инструкции workflow для Codex
CLAUDE.md	Главные инструкции workflow для Claude
.ai/ARCHITECTURE.md	Архитектура проекта
.ai/DECISIONS.md	Границы продукта и проектные решения
.ai/CHANGELOG.md	История релизов
.ai/specs/	Активные и архивные ТЗ
skills/	Канонические workflow-навыки
.agents/skills/	Runtime-копии навыков для Codex
.claude/skills/	Runtime-копии навыков для Claude
rules/	Исходные правила для установки в проекты
templates/	Файлы, используемые при установке
init/SKILL.md	Workflow установки
scripts/	Валидаторы и служебные скрипты
tests/	Регрессионные тесты
docs/	Исследования и best practices

Как Работать с dot_ai

Большинство значимых изменений должны проходить через workflow:

1. Создать ТЗ через plan-release.
2. Реализовать один этап через implement-spec-stage.
3. Добавить тесты через write-tests.
4. Выполнить merge через integrate-release.

Для маленьких исправлений используется маршрут small-fix.

Главное правило: сначала редактируется product source.

Канонические файлы находятся здесь:

• skills/
• rules/
• templates/
• init/

Runtime-копии производятся из source-файлов. Не редактируйте .agents/skills/ или .claude/skills/ напрямую, кроме случаев, когда вы сознательно синхронизируете их из skills/.

Полезные Команды

Запустить все тесты:

uv run pytest -q

Запустить lint:

uv run ruff check .

Проверить синхронизацию source/runtime:

uv run python scripts/validate_source_sync.py

Синхронизировать source-навыки в runtime-копии:

uv run python scripts/sync_source.py

Проверить текущее состояние workflow:

uv run python scripts/validate_workflow_state.py --step implement-spec-stage

Запустить локальные eval-проверки:

uv run python scripts/run_local_evals.py

Философия Проекта

dot_ai построен вокруг нескольких идей:

• Явный workflow лучше процесса, который живёт только в чате.
• ТЗ полезно, когда задача нетривиальна.
• Инструкции для агентов должны версионироваться, тестироваться и ревьюиться.
• Runtime-инструкции должны оставаться синхронизированными с source-инструкциями.
• Локальные deterministic-проверки надёжнее, чем надежда на поведение модели.
• AI должен помогать инженеру думать, а не скрывать состояние работы.

Чем dot_ai Не Является

dot_ai — это не:

• runtime-фреймворк;
• IDE;
• пакет, который импортируется в код приложения;
• замена инженерному ревью;
• гарантия, что AI-агент всегда поведёт себя правильно.

Это структурный операционный слой для проектов, которые активно используют AI-агентов.

Текущая Зрелость

У проекта уже есть реальная внутренняя структура: версионированные ТЗ, валидаторы, регрессионные тесты, проверки синхронизации и зафиксированные границы продукта.

При этом проект продолжает развиваться. Установочный слой и eval-слой стоит дальше автоматизировать и подтверждать end-to-end тестами на внешних fixture-проектах.

Что Читать Дальше

• .ai/ARCHITECTURE.md — как устроен репозиторий.
• .ai/DECISIONS.md — чем проект является и чем не является.
• .ai/source-of-truth.md — как связаны source, runtime и installed layers.
• AGENTS.md — workflow-контракт для Codex.
• init/SKILL.md — алгоритм установки.
• docs/best_practice/summary.md — research-backed принципы, на которых построен дизайн.