Greenfield по технологии, brownfield по бизнес-правилам

Сегодня в комментариях к чужой статье про greenfield и brownfield в эпоху AI вспомнил свою миграцию 200К строк JS в TypeScript. Тогда я не думал в этих терминах. Теперь вижу: проект был greenfield и brownfield одновременно, и путаница между ними стоила нам двух недель дебага в середине миграции.

Я думал: раз меняем весь стек, это чистый лист

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

Я думал: раз тесты зелёные, поведение сохранилось

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

Что сработало: golden-master тесты перед тем, как подпускать агента

Не юнит-тесты на новую логику, а снимок текущего поведения на самых страшных модулях. Прогнали типичные и граничные кейсы через старый код, зафиксировали вывод, потом сравнивали с новым на каждом шаге. Разница ловилась мгновенно, до ревью, до продакшена. Три раза снапшот показал расхождение, которое человек на ревью пропустил бы, слишком похоже на «просто более чистый код».

Главный вывод

В greenfield-части задачи вопрос «правильно ли мы строим» решается быстрой обратной связью и итерацией. В brownfield-части вопрос другой: «сохранили ли мы то, что уже работает». Агент одинаково уверенно предлагает и то, и другое решение, разницу видно только через инструмент вроде golden-master, не через код-ревью на глаз.

Если в проекте есть куски старше пары лет, перед тем как звать агента туда, стоит сначала спросить не «как сделать красиво», а «что именно нельзя сломать, и как я об этом узнаю раньше продакшена».

Пишу об этом подробнее в канале @ai_in_prod.

archkit v0.1 — генератор TypeScript-библиотек с Clean Architecture: от спека до npm за один день

Неделю назад опубликовал на npm первый пакет, @autosergach/archkit. Одна команда:

npx @autosergach/archkit create my-lib

И получаешь TypeScript-библиотеку с Clean Architecture из коробки: domain, application, ports, рабочий use case и пять зелёных тестов. Не «hello world», а каркас который показывает как слои должны выглядеть. Ниже как это устроено и четыре грабли по дороге к npm publish.

Что внутри

my-lib/
├── src/
│   ├── domain/      # User, DomainError
│   ├── application/ # createUser use case
│   ├── ports/       # UserRepository interface
│   └── index.ts
├── tests/           # InMemoryUserRepository + 5 тестов
└── package.json     # ESM, strict TS, vitest 3, eslint 9

pnpm install && pnpm test, пять зелёных с первого запуска. Стек намеренно современный: ESM only, Node 20+, TypeScript 5.7+, vitest 3.2, eslint 9 flat config.

Архитектура изнутри

Забавно, что archkit изнутри устроен точно так же, как проект который генерирует: порты и адаптеры до мозга костей. Монорепо: приватный archkit-core (весь движок) и @autosergach/archkit (то что на npm). tsup бандлит core через noExternal, потребитель ставит один пакет.

FileSystemPort с двумя адаптерами: InMemoryFileSystemAdapter для тестов и NodeFileSystemAdapter для продакшена. Pipeline в три шага: buildInitPlan, renderTemplate, executePlan. С --dry-run третий шаг не выполняется.

Тесты: 35 + 3

35 unit-тестов гоняют весь движок через in-memory, без диска, меньше секунды на весь suite. 3 e2e-теста запускают настоящий pnpm install && pnpm test в os.tmpdir(). Именно они дают уверенность что сгенерированный проект работает у пользователя, и поймали несколько багов в шаблоне до публикации.

Один день с Claude Code

Весь v0.1.1, от пустой папки до npm publish, написал за одну сессию, примерно шесть часов. 9 атомарных коммитов: Claude Code писал код, я проверял и коммитил. До Claude Code такой объём занял бы неделю, и тесты я бы срезал.

4 урока из npm publish

1. cac и --no-X флаги. При --skip-install cac выставляет skipInstall: true по умолчанию, неявно. Фикс: проверять === true, а не !== undefined. Потерял час пока разобрался.

2. npm проверяет similarity, а не только занятость. archkit свободное имя, но npm отклонил из-за заброшенного arch-kit (2022, 12 загрузок). Ушёл в scoped namespace @autosergach/archkit, зато все следующие пакеты там же.

3. workspace:* в dependencies. Приватного archkit-core нет в registry. Если он в dependencies, npm падает при install у потребителя. Перенести в devDependencies, tsup бандлит его в dist.

4. Granular npm tokens и 2FA. Granular-токен с правами publish не проходит без «Bypass 2FA for publish». Опция выключена по умолчанию, нигде не выделена жирным. Получил 403.

Что дальше

v0.2: NestJS плюс React fullstack шаблон и --ai-ready флаг, который автогенерирует CLAUDE.md, .claude/settings.json, agents.md. Пишите в Issues если есть что сказать.

npm: https://www.npmjs.com/package/@autosergach/archkit
GitHub: https://github.com/autosergach/archkit

npx @autosergach/archkit create my-lib
cd my-lib && pnpm install && pnpm test
# → 5 passing