av/facts

Что такое facts?

av/facts — это workflow и формат спецификаций для управления проектом в виде списка атомарных утверждений в файле .facts. Каждая строка — короткое структурированное утверждение о том, что должно быть верно, с опциональной командой shell, которую машина выполняет для проверки утверждения.

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

Ключевые возможности

• Атомарный формат спецификаций «fact» (.facts): Пишите по одному утверждению на строку в виде простых строк, организованных Markdown-заголовками по доменам.
• Теги жизненного цикла для отслеживания прогресса: Используйте @draft, @spec и @implemented (плюс любые кастомные теги), чтобы показать стадию каждого утверждения в пайплайне.
• Проверка с помощью команд: Для фактов с command команда facts check выполняет её и считает утверждение верным, если команда завершается с кодом 0.
• Автоматизированная проверка и группировка статусов: facts check проверяет файлы на линтинг, выполняет все команды, группирует результаты (например, зелёный — passed, красный — fail, жёлтый — manual); выходит с ненулевым кодом при неудачах.
• Коды выхода и фильтрация, удобные для CI: Фильтруйте проверки по теговым выражениям (например, --tags "mvp and not blocked"), чтобы проверять подмножества спецификаций.
• Переходы и реализация, управляемые агентом, против спецификации: Агент читает лист фактов, берёт @spec-факты, строит их, запускает facts check и тегает прошедшие как @implemented, пока спецификация обновляется сама.

Как использовать facts

1. Установите CLI/инструменты агента (проект предлагает несколько вариантов, включая Rust-бинарник и npx-команду, как описано ниже).
   • Пример: npx skills add av/facts
   • Затем попросите агента запустить Init facts (например, «Init facts»), чтобы обнаружить стек и создать начальный файл .facts.
2. Создайте или отредактируйте файл .facts в документированном формате:
   • Добавляйте заголовки для организации по доменам (например, # auth, # data).
   • Добавляйте по одному утверждению на строку.
   • Тегайте каждый факт метками стадий жизненного цикла, такими как @draft, @spec или @implemented.
   • Для проверяемых утверждений включайте command, которая выходит с 0, когда утверждение верно.
3. Запустите проверку: используйте facts check для линтинга и проверки всех фактов (или --tags для ограничения). Просмотрите, какие прошли, провалились или требуют ручной работы.
4. Итерации с агентом: пишите грубые идеи как @draft, уточняйте в @spec, затем пусть агент реализует @spec-факты и тегает их как @implemented после прохождения facts check.

Случаи использования

• Валидация спецификаций проекта после изменений: Держите живой чеклист того, что должно быть верно, и запускайте facts check после правок, чтобы быстро увидеть, что осталось.
• Преобразование требований в исполняемые проверки: Конвертируйте утверждения «должно быть верно» (типа поведения аутентификации или правил обработки данных) в факты с проверкой на основе команд.
• Управление работой в процессе с жизненным циклом фактов: Используйте @draft → @spec → @implemented для коммуникации прогресса и обеспечения, что каждое утверждение либо реализовано/проверено, либо явно помечено для уточнения.
• Автоматическое обнаружение и классификация кодовой базы: Используйте скилл facts-discover для сканирования кодовой базы и классификации фактов по стадиям, включая добавление пропущенных истин.
• Реализация против спецификации: Используйте flow facts-implement, где агент читает @spec-факты, строит код, проверяет с facts check и обновляет теги.

FAQ

Это facts только формат документации или он реально проверяет утверждения?
Он делает и то, и другое: факты без команд могут проверяться агентом против кодовой базы, а факты с command — путём выполнения команды и проверки кода выхода 0.

Что делает facts check?
Линтит файлы, выполняет все указанные команды, группирует результаты по статусам (pass/fail/manual) и выходит с ненулевым кодом при неудачах.

Как организованы и отслеживаются факты?
Факты живут в файле .facts в структуре, совместимой с Markdown/YAML, с заголовками для организации по доменам и тегами (включая @draft, @spec, @implemented) для отслеживания статуса жизненного цикла.

Можно ли проверить только часть проекта?
Да. facts check поддерживает фильтрацию по тегам через --tags с булевыми выражениями.

Альтернативы

• Тестовые сьюты (unit/integration тесты): Традиционные тесты проверяют поведение, но чеклист .facts подчёркивает человекочитаемые атомарные утверждения и пайплайн жизненного цикла/статусов, а не только автоматизированный pass/fail.
• Статическая документация + code review: Доки фиксируют требования, но обычно не исполняемы напрямую; facts связывает утверждения с проверкой через facts check.
• Инструменты спецификаций с трассировкой требований: Инструменты, связывающие требования с реализацией, дают трассировку, но facts использует формат утверждений построчно с опциональным выполнением команд и переходами по тегам жизненного цикла.