C4-Builder
Разработчик или AI-агент [Person]

Пишет markdown и диаграммы PlantUML, D2 или BPMN и хранит их в git рядом с кодом.

Правит модель и проверяет каждую правку[c4builder check]
C4-Builder [CLI, поддерживаемый форк]

Архитектура как код, которую агент пишет, проверяет и читает

Собирает папку markdown и диаграмм в сайт документации. Рендер локальный и детерминированный, проверка диаграммы занимает секунды, плагины публикуют спеки OpenSpec и контракты OpenAPI рядом с C4-моделью.

npm i -g @alfacapital-tech/c4builder
Собирает[c4builder --site -w]
Документация [сайт на docsify]

Этот сайт собран c4builder из папки docs/ репозитория.

 Журнал решений [плагин openspec]

Спеки и change'и проекта: почему c4builder устроен именно так.

Агент проверяет себя сам

  1. Правка. Агент меняет .puml или .md в src/: добавляет контейнер, связь, страницу.
  2. Проверка. c4builder check рендерит диаграмму тем же движком, что и сборка, и возвращает код выхода и номер строки с ошибкой. Без сети и без человека.
  3. Сборка. c4builder --site -w пересобирает сайт на каждое сохранение, и человек видит результат в браузере.
$ c4builder check src/context.puml
✗ src/context.puml: строка 12: Fatal parsing error
$ c4builder check src/context.puml
✓ src/context.puml
$ c4builder
built in 1.9 seconds

Подробнее — на странице «Агенты».

Для агентов

Скиллы

Как устроен проект, цикл правка → check → сборка, конвенции C4-PlantUML, установка и диагностика — в двух скиллах для Claude Code, Codex, Cursor и других агентов. В новом проекте агента встречает AGENTS.md.

npx skills add AlfaCapital-Tech/C4-Builder/skills

llms.txt

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

  • llms.txtОглавление со ссылками на страницы
  • llms-full.txtПолный текст с исходниками диаграмм

Подробнее — на странице «Агенты».

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

npm

npm i -g @alfacapital-tech/c4builder
c4builder --new --name demo -y
cd demo
c4builder --site -w

Node.js 22.17+. Java 17+ по желанию: если её нет, c4builder скачает JRE сам. Graphviz не нужен.

Docker

docker run --rm -v "$PWD:/pwd" \
  ghcr.io/alfacapital-tech/c4builder:latest \
  c4builder

В образе Node, JRE, PlantUML, шрифты и D2. Его же можно взять образом job'а в CI.

Чем форк отличается от upstream

Оригинальный C4-Builder не развивается с 2024 года. В Альфа-Капитале на нём собирается архитектурный репозиторий на сотню с лишним диаграмм, поэтому мы продолжаем проект и развиваем его под работу с агентами.

Офлайн и детерминированно
PlantUML-jar, шрифт и движки — в пакете, раскладку считает Smetana. Одинаковые SVG на ноутбуке, в CI и в Docker; сеть при сборке не нужна.
Проверка отдельных диаграмм
c4builder check с кодом выхода и номером строки — для агентов, pre-commit-хуков и CI.
Плагины
openspec публикует спеки и change'и на сайте, openapi — офлайн-страницы swagger-ui для контрактов сервисов.
D2 и PNG
Второй движок диаграмм и растеризация через resvg тем же шрифтом.
BPMN-процессы
BPMN 2.0 XML без координат: сборка проверяет модель, раскладывает пулы и дорожки и рисует процесс в стандартной нотации bpmn.io.
Поддержка
TypeScript, golden-тесты рендера, CI на каждый pull request, релизы в npm и GHCR.

Документация