better-result — скиллы для агентов
better-result
Два скилла библиотеки better-result: аудит обработки ошибок в TypeScript-проекте с поэтапным внедрением Result и переход с версии 2.x на 3.0 с кодмодом
- 2 001 ★ репозитория
- Последний коммит
- MIT
Расширенный доступ
Почему такой уровень
- Скилл внедрения правит исходный код проекта и запускает команды форматирования, линтера, проверки типов и тестов
- Скрипт переноса записывает изменения в файлы проекта по флагу `--write`
- Ветка аудита пишет файл отчета в документацию репозитория
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add skills/better-resultОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Скилл внедрения правит исходный код проекта и запускает команды форматирования, линтера, проверки типов и тестов
- Скрипт переноса записывает изменения в файлы проекта по флагу `--write`
- Ветка аудита пишет файл отчета в документацию репозитория
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
better-result — библиотека типа `Result` для TypeScript без зависимостей: функция явно возвращает успех или ожидаемую ошибку, а `Result.gen` собирает шаги в линейную цепочку и останавливается на первой неудаче. В репозитории лежат два скилла, которые помогают агенту ввести ее в чужой проект. Скилл `adopt-better-result` работает в двух ветках. В ветке аудита агент читает инструкции репозитория и манифесты, проверяет установленную версию и API, обходит все области рабочего кода и ведет отчет по найденным путям ошибок. Для каждого пути он подбирает вид (ожидаемая ошибка, дефект или иное), решает вопрос о границах, где данные уходят за пределы процесса, и ранжирует вертикальные срезы миграции: срез — один путь ошибки от источника до места обработки. Единственное изменение репозитория на этом этапе — файл отчета в принятом месте документации, а при его отсутствии `docs/better-result-adoption.md`. Ветка среза запускается только после явного согласия на один названный срез: агент прослеживает путь ошибки от источника до места обработки, переводит его на `Result` и `TaggedError`, запускает форматирование, линтер, проверку типов и тесты и предлагает следующий срез. Скилл `migrate-better-result-3` переводит проект с версии 2.x на 3.0. Агент составляет перечень затронутых мест, запускает скрипт `migrate-tagged-error-v3.mjs` с флагами `--list`, `--write` и `--check` для замены синтаксиса `TaggedError`, переносит удаленные вспомогательные функции сериализации на проверяемые кодеки, разбирает изменения вывода типов в `tryRecover`, `matchError` и `Result.partition`, обновляет зависимость и прогоняет тесты.
Для кого. Для TypeScript-разработчиков, которые хотят перевести обработку ошибок в проекте на типизированный `Result` по шагам или обновить уже использующий библиотеку проект с версии 2.x.
Подходит, если
- Нужно оценить, где в проекте теряются или смешиваются ошибки, и получить план внедрения `Result` с очередью срезов
- Решено перевести на `Result` один модуль или границу, и агент должен довести срез от источника ошибки до обработки
- Проект использует better-result 2.x, и надо перейти на 3.0, не ломая работу вызовов
- Нужно автоматически заменить синтаксис `TaggedError` версии 2 и проверить, что старого синтаксиса не осталось
- Надо заменить удаленные `Result.serialize`, `Result.deserialize` и `Result.hydrate` кодеками со схемами
Не подходит, если
- Проект не на TypeScript: библиотека требует TypeScript 5.4 или новее и поставляется только как ESM
- Нужно переписать весь проект одним заходом: скилл внедрения намеренно работает срезами и ждет согласия на каждый
- Вы хотите готовую библиотеку без обсуждения: скиллы лишь помогают внедрению, а сама библиотека ставится отдельно командой `npm install better-result`
- Проект уже построен на Effect: у него собственная модель ошибок, и скиллы better-result к нему не относятся
Пример запроса к агенту
Проведи аудит обработки ошибок в этом репозитории скиллом adopt-better-result и предложи, с какого среза начать внедрение ResultОграничения
Скиллы рассчитаны на проекты на TypeScript и версии better-result 2.x и 3.0. Ветка аудита не меняет рабочий код: она пишет только отчет и останавливается на согласовании, поэтому перед внедрением нужен второй запрос с названным срезом. Скрипт `migrate-tagged-error-v3.mjs` меняет только форму наследования `TaggedError`. Аннотации вида `TaggedErrorClass<Tag, Props>` приходится править вручную. Сгенерированный и сторонний код скилл оставляет в стороне.
После обновления деревья `Result` с ошибками `TaggedError` в тестах нельзя сравнивать структурно, потому что ошибки стали итерируемыми; такие проверки нужно разделить на статус и поля ошибки. Для внутреннего обмена между своими сервисами можно взять `serializeUnsafe` и `deserializeUnsafe`: при нарушении контракта они паникуют. На публичных и сохраняемых границах скилл советует безопасные методы. Лицензия MIT.
Как отключить. Уберите скиллы из каталога скиллов агента. Библиотека остается в проекте: удалите ее командой вашего менеджера пакетов, например `npm uninstall better-result`, и откатите правки, внесенные срезами, через историю Git. Файл отчета `docs/better-result-adoption.md` удалите вручную.
Частые вопросы
Какие ошибки считаются ожидаемыми, а какие дефектами?
Ожидаемой служит ошибка, на которую вызывающий код может осмысленно отреагировать: неверный ввод, отсутствующая запись, отклоненные учетные данные, недоступный внешний сервис, сбой проверки данных на границе. Неожиданные сбои в обратных вызовах и нарушенные инварианты библиотека представляет как `Panic`, а не расширяет тип ошибки до `unknown`.
Что такое вертикальный срез?
Один путь ошибки от источника через вызывающие функции до места, где ее обрабатывают или передают через границу. Скилл переводит на `Result` весь путь, а не отдельные функции вразброс, и только после согласия на названный срез.
Как установить библиотеку и что ей нужно?
Командой `npm install better-result`, также подойдут `pnpm add` и `bun add`. Нужен TypeScript 5.4 или новее, пакет только в формате ESM и без зависимостей на этапе выполнения. Документация лежит на better-result.dev.
Как проверить, что перенос синтаксиса закончен?
Скрипт `migrate-tagged-error-v3.mjs` запускают с `--check`: он завершится успешно, когда вызовов фабрики версии 2 в коде не осталось. Дополнительно скилл просит поискать двухаргументные `TaggedErrorClass`, кроме сгенерированных и сторонних файлов.
Зачем в репозитории скилл audit-better-result-dependents?
Он лежит в `.agents/skills` и нужен сопровождающим: проверяет, не ломает ли изменение API известные зависимые проекты Prisma и Better T Stack. Для пользователей библиотеки он не предназначен, в списке установки его нет.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
СкиллыСкилл по Effect v4 для TypeScript: схемы, сервисы и слои, конфигурация, повторы, кэши, потоки, HTTP-клиент и тесты с виртуальным временем
Скилл для агентов с конвенциями TypeScript: типы, дискриминированные объединения, функции, именование, структура, React и тесты, подгружается по темам
Скилл /improve: сильная модель проверяет репозиторий и пишет самодостаточные планы правок, а исполнение отдаете более дешевой модели
CLI на Rust для TypeScript и JavaScript: мертвый код, дубликаты, циклы, сложность и границы архитектуры по одному графу, есть MCP-сервер и скиллы
Oxc — скиллы миграции на Oxlint и Oxfmt
Oxc migration skills
Два официальных скилла Oxc: агент переводит проект с ESLint на линтер Oxlint и с Prettier или Biome на форматтер Oxfmt
Скилл для ревью кода по многим языкам и фреймворкам: архитектура, производительность, безопасность, антипаттерны и типичные ошибки
Коротко о README
Описание библиотеки начинается с примера валидации порта и трех принципов: сделать сбои явными, писать многошаговые процессы по порядку и разделять ожидаемые ошибки и дефекты. Далее идут модель, пошаговая сборка оформления заказа на `Result.gen`, преобразования, восстановление, повторы, коллекции и границы транспорта, карта API, переход со второй версии и раздел для агентов со ссылкой на скилл внедрения. Отдельный файл в папке со скиллами объясняет установку и ручное подключение. В репозитории есть тесты типов и выполнения, сайт документации и заметки по исследованию.
Бейдж для README
Исходный SKILL.md
--- name: adopt-better-result description: Adopt better-result in an existing TypeScript codebase. Use for a repository-wide error-handling audit and proposal, or for implementing a named vertical slice with TaggedError and Result. --- # Adopt better-result Start with evidence, then work at the scale named by the user. ## Choose the branch - **Audit branch:** Use when the user requests a repository-wide audit or proposal, or has not named an implementation slice. Complete the audit branch before changing production code. - **Named-slice branch:** Use when the user explicitly requests implementation of a function, module, boundary, or previously proposed slice. Limit evidence collection to that slice and its propagation path. An approved slice from the audit branch continues through the named-slice branch. ## Audit branch: repository-wide proposal ### 1. Establish the repository and API facts Read the repository instructions, package manifests, source layout, test commands, and architecture documentation. Determine whether `better-result` is installed and which version/API is available. Prefer installed types and source over remembered APIs. Map every production-code area before studying individual failures. Exclude generated and vendored code from the audit; inspect tests for intended behavior. **Complete when:** every production-code area is listed, the validation commands are known, and the available `better-result` API has been verified. ### 2. Audit every production-code area Follow [`references/repository-audit.md`](references/repository-audit.md). Trace search evidence into end-to-end failure paths, keep grouped sites accountable with counts, and record obscured paths as unknown. Write the audit to the repository's established documentation or planning location, falling back to `docs/better-result-adoption.md`. **Complete when:** the report satisfies the coverage and completion requirements in `repository-audit.md`. ### 3. Design the target model Apply the failure taxonomy in [`references/tagged-errors.md`](references/tagged-errors.md) and make each boundary decision with [`references/result-boundaries.md`](references/result-boundaries.md). Add the proposed dispositions, user-facing mappings, boundary decisions, and ranked vertical migration slices to the report. Recommend the best first slice and explain why it is bounded and valuable. **Complete when:** every catalogued failure has a disposition, every boundary has a recorded codec decision, and one first slice is recommended. ### 4. Present the approval gate Present the report and recommendation. The audit branch's only repository change is the report. **Complete when:** the report is presented. An explicit approval of one named vertical slice starts the implementation branch; otherwise the run ends here. ## Named-slice branch: implementation