facts CLI
CLI и четыре скилла для разработки от фактов: файл .facts с проверяемыми утверждениями о проекте и их жизненным циклом
- 207 ★ репозитория
- Последний коммит
Расширенный доступ
Почему такой уровень
- Поле `command` выполняет команды оболочки из файла `.facts` на вашей машине при каждой проверке
- Скиллы дают агенту править файл `.facts` и реализовывать факты в коде проекта
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add cli/factsОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Поле `command` выполняет команды оболочки из файла `.facts` на вашей машине при каждой проверке
- Скиллы дают агенту править файл `.facts` и реализовывать факты в коде проекта
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
facts хранит спецификацию проекта в файле `.facts`: каждая строка — одно утверждение вроде «сессии истекают через 24 часа». Утверждению можно приписать тег жизненного цикла: `@draft` (черновая мысль), `@spec` (точное требование, готовое к сборке) и `@implemented` (реализовано и подтверждено кодом). Если у факта есть поле `command`, то это команда оболочки, и код выхода 0 означает, что утверждение верно. Команда `facts check` проверяет все файлы и выполняет команды, а ручные факты остаются непроверенными, пока не добавить `--agent` (пресеты `claude`, `codex`, `opencode` и другие). Ненулевой код выхода удобен для CI. Прочие команды: `facts add`, `edit`, `move`, `remove`, `get`, `list`, `lint`, `fmt`, `init`. К CLI прилагаются четыре скилла: `facts` для чтения и правки файла, `facts-discover` для разбора кодовой базы и классификации фактов, `facts-refine` для превращения черновиков в точные спецификации вместе с вами и `facts-implement` для реализации спецификаций, проверки и смены тега на `@implemented`. Это один бинарник на Rust для Linux, macOS и Windows.
Для кого. Тем, кто ведет проект вместе с кодовым агентом и хочет, чтобы спецификация помещалась на один экран и проверялась командой.
Подходит, если
- Спецификация разрослась до длинного документа, а агент теряет из нее важное
- Нужно видеть, сколько требований реализовано, сколько ждет сборки и сколько остается черновиками
- Требование проверяется простой командой, например `test -f src/main.rs` или `grep`
- В CI нужна проверка, что заявленные свойства проекта все еще выполняются
- Агенту надо дать цикл «черновик, спецификация, реализация» с отметкой о состоянии каждого факта
Не подходит, если
- Нужна подробная проектная документация с диаграммами и обоснованиями: факт задуман как одна короткая строка
- Требования нельзя проверить командой и нет желания проверять их агентом: такие факты остаются непроверенными
- Спецификацию ведет несколько команд в разных форматах, и переводить ее в плоский список утверждений не планируется
- Нужен долгоживущий проект с активной поддержкой: последний коммит репозитория от 3 июня 2026 года
Пример запроса к агенту
Init facts. Потом разбери кодовую базу, добавь факты про аутентификацию и хранение данных и пометь, какие из них уже реализованы.Ограничения
Проверять автоматически можно только факты с командой оболочки. Остальные остаются отметкой `?` до запуска `facts check --agent` с настроенным агентом, а при флаге `--strict` непроверенные факты ломают сборку. Команда из поля `command` выполняется на вашей машине, поэтому чужой `.facts` перед запуском проверки нужно читать.
Проект небольшой, с одним автором. Последний коммит от 3 июня 2026 года, лицензия MIT указана в репозитории. Скиллы устанавливаются командой `facts init` в проект или отдельным менеджером скиллов, а `facts uninit` убирает все.
Как отключить. Команда `facts uninit` убирает `.facts` и установленные скиллы из проекта. Бинарник удаляется тем же способом, каким ставился: `npm uninstall -g @avcodes/facts` или `pipx uninstall facts-cli`.
Частые вопросы
Как поставить facts для агента?
Выполните `npx skills add av/facts`, затем попросите агента выполнить Init facts: он определит стек и создаст `.facts` с первыми утверждениями. Бинарник ставят отдельно: `curl -fsSL https://av.codes/facts.sh | sh`, `npm install -g @avcodes/facts` или `pipx install facts-cli`.
Как выглядит файл `.facts`?
Это обычный markdown и одновременно валидный YAML по разделам: заголовки группируют факты, строка со списком хранит утверждение, а подпункты `command` и `tags` добавляют проверку и метки. Идентификатор факта — короткий хеш от текста.
Что делает `facts check`?
Проверяет структуру файлов и выполняет команды фактов. Код выхода 0 означает, что все прошло, ненулевой — что что-то упало. Для ручных фактов добавьте `--agent claude` или другой пресет, а в CI используйте `--strict` и `-q`.
Чем теги отличаются друг от друга?
`@draft` обозначает черновую мысль. `@spec` обозначает точное требование, готовое к реализации. `@implemented` обозначает сделанное и подтвержденное кодом. Агент сам переводит факты между состояниями через скиллы refine и implement.
Можно ли вести несколько списков фактов?
Да: `.facts` используется по умолчанию, а дополнительные листы называют по смыслу, например `api.facts` или `cli.facts`. Все файлы `*.facts` в корне находятся автоматически, а файлы в подпапках видны только при явном указании `--file`.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыНабор GitHub для разработки от спецификации: CLI specify ставит в проект команды и скиллы для агента, от принципов до реализации
CLI хранит фичефлаги и A/B-тесты Markdown-файлами в репозитории и ставит в Claude Code пять скиллов для их создания и разбора.
CLI на Rust для TypeScript и JavaScript: мертвый код, дубликаты, циклы, сложность и границы архитектуры по одному графу, есть MCP-сервер и скиллы
Три скилла и конфиг clippy: агент пишет, проверяет и переносит код на идиоматичный Rust, а правила проходят в CI
Два скилла для разработки от спецификации: /spec задает вопросы и сохраняет документ в specs/, /spec-impl реализует утвержденную спецификацию по шагам
Задачи, документы, спецификации и решения проекта лежат файлами Markdown в репозитории, а агент читает их через CLI и MCP
Сравнение с похожими
Карточки с тем же главным запросом: чем они отличаются.
Коротко о README
Документация описывает формат файла, таблицу команд с короткими псевдонимами (`ll`, `at`, `rt`) и методологию «разработка от фактов». Проект сам описан файлом `.facts`: 224 факта, из них 154 проверяются командами. Расширенные руководства лежат в вики репозитория.