adrkit

Память решений для планов, созданных людьми и агентами — записи архитектурных решений, которые машиночитаемы, проверяемы в CI и понятны агентам, не покидая git.

Большинство ADR-инструментов — это шаблон Markdown и генератор статических сайтов. Это фиксирует решение, но не заставляет решение работать. adrkit рассматривает запись как типизированные данные с телом Markdown и добавляет одно поле — affects, — чтобы инструмент мог ответить на вопрос «какие решения управляют этим pull request?» и поместить ответ туда, где принимается следующее решение.

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

CLI публикуется как @adrkit/cli и предоставляет бинарный файл adr. Публикуемые артефакты рассчитаны на Node 22+:

npx @adrkit/cli lint                 # validate the corpus in docs/adr
npx @adrkit/cli explain src/payments/api.ts   # which decisions govern this file?

Или добавьте его в проект (в репозиториях, ориентированных на Bun, можно использовать bun add -D @adrkit/cli / bunx):

npm i -D @adrkit/cli

Чистая библиотека устанавливается отдельно: npm i @adrkit/core @adrkit/evaluator.

См. руководство по быстрому старту и полный справочник команд.

Related MCP server: agentic-os-mcp

Выберите отправную точку

Использование контейнера

Начиная с первого согласованного релиза, содержащего ADR-0032, релизы публикуются как мультиархитектурный OCI-образ в ghcr.io/mbeacom/adrkit. В автоматизации закрепляйте неизменяемый тег vX.Y.Z; vX и latest перемещаются только после завершения этого согласованного релиза:

docker run --rm --read-only --network none \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z lint

docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z mcp

Команда MCP держит stdin открытым, поскольку MCP использует stdio. Её монтирование репозитория доступно только для чтения, что соответствует контракту сервера; в конфигурации MCP-клиента используйте абсолютный путь на хосте. Для команд CLI, которые намеренно выполняют запись (new или migrate без --dry-run), опустите --read-only и суффикс :ro у монтирования. Образ запускается от непривилегированного пользователя node; на хосте с другим UID/GID добавьте --user "$(id -u):$(id -g)". На хостах с SELinux добавьте соответствующую метку bind-mount (например, :Z).

Образ по умолчанию трактует нераспознанный селектор как подкоманду adr. Явные селекторы — cli/adr/adrkit, mcp/adrkit-mcp, ci/adrkit-ci и queue-action/adrkit-queue-action. --help по умолчанию описывает эти селекторы; cli --help открывает справочник команд CLI. Контейнер также резервирует -h, container-help и --container-help; остальные подкоманды справки CLI, например help lint, проходят без изменений.

Соберите тот же исходный код локально с помощью Docker или Podman. Целевые образы конкретного назначения cli, mcp, ci и queue-action изолированы для локальной политики и проверки SBOM; реестр публикует только универсальный целевой образ adrkit:

docker build -f Containerfile -t adrkit:local .
docker build -f Containerfile --target mcp -t adrkit-mcp:local .
docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  adrkit-mcp:local

Две точки входа CI сохраняют существующий контракт среды выполнения GitHub Actions: они ожидают GITHUB_WORKSPACE, полезную нагрузку события и окружение репозитория, значения INPUT_* и токен. Для размещённых GitHub Actions Actions на основе репозитория остаются более простым интерфейсом: mbeacom/adrkit/packages/ci@v0 и mbeacom/adrkit/packages/ci/queue@v0. Публикация и восстановление контейнера описаны в docs/RELEASING.md.

Как это выглядит

adr queue выводит очередь ревью как детерминированную проекцию корпуса, доступную только для чтения — побайтово идентичную для одинаковых входных данных:

# ARB Queue — 2026-07-25

Corpus fingerprint: `96e7f3185c5bb89bd1c87e10a28dcbef66703f381d3f14ea486ceaf29903cb00`
7 item(s) | 0 corpus finding(s) | 0 item(s) with findings

## Queue Items

| # | ID | Title | Tier | SLA State | Deadline | Approvals | Objections |
|---|----|-------|------|-----------|----------|-----------|------------|
| 1 | `0005` | Gate proposals with a deterministic-first evaluator … | arb | within-sla | 2027-01-18 | 0/- | 0 |
| 2 | `0015` | Validate descriptors against Backstage field formats … | arb | within-sla | 2027-01-25 | 0/- | 0 |

В CI Action @adrkit/ci комментирует управляющие решения в PR, которых они касаются, — только чтение, только комментарии, без базы данных, без утверждений. См. Использование в CI.

Для агентов: MCP-сервер

Самый отличительный инструмент: @adrkit/mcp — это локальный только для чтения-сервер Model Context Protocol, который позволяет агенту получить предыдущие решения — включая отклонённые и заменённые — прежде чем предлагать то, что уже пробовали. Никаких записей, ни HTTP/аутентификации, ни доступа к модели, эмбеддингам или сети, ни постоянного индекса. Он предоставляет ровно четыре инструмента:

Запустите его против корпуса репозитория:

npx @adrkit/mcp             # or the adrkit-mcp bin
adrkit-mcp --cwd /path/to/repo --dir docs/adr

--cwd (переменная окружения ADRKIT_MCP_CWD) должен быть корнем рабочего дерева Git; --dir (переменная окружения ADRKIT_MCP_DIR, по умолчанию docs/adr) разрешается внутри него. stdout несёт только кадры JSON-RPC; диагностика идёт в stderr; кладбище включено по умолчанию. Полные контракты инструментов см. в руководстве по настройке MCP и packages/mcp/README.md.

Для рабочих процессов на основе спецификаций: расширение Spec Kit

Spec Kit ведёт вас от specify к plan, затем к tasks и implement. Чего он не делает — так это не проверяет только что созданный план на соответствие уже принятым вами решениям и не фиксирует новые решения, которые этот план содержит, — поэтому каждая функция начинается с пустого контекста и заново пересматривает решённые вопросы.

@adrkit/spec-kit замыкает этот цикл:

Плюс один хук after_plan, который предлагает запустить проверку. Он опционален по построению, и хуки могут вызывать только команды, которые не выполняют запись, — draft намеренно недоступен из любого хука, потому что хук фазы планирования, создающий записи без запроса, фабриковал бы память решений, а не фиксировал её.

Привязан к Spec Kit >=0.13.0,<0.16.0 и протестирован на 0.13.0, 0.14.4 и 0.15.1. Он доступен в каталоге сообщества Spec Kit; настройку см. в README пакета.

Для любого кодинг-агента: плагин

Spec Kit — это один из рабочих процессов. Место, где планы теперь реально пишутся, — внутри кодинг-агента, который понятия не имеет о существовании вашего корпуса решений.

packages/adapters/agent-plugin упаковывает тот же цикл в переносимые компоненты агента — устанавливаемые в GitHub Copilot CLI, Claude Code, opencode и во всё, на что нацелен APM:

copilot plugin marketplace add mbeacom/adrkit && copilot plugin install adrkit@adrkit
/plugin marketplace add mbeacom/adrkit        # Claude Code, then /plugin install adrkit@adrkit
apm install mbeacom/adrkit/packages/adapters/agent-plugin --target opencode

Каждый компонент вызывает CLI adr через оболочку, поэтому установите и его, если ещё не сделали этого, — npm i -g @adrkit/cli или добавьте @adrkit/cli в проект. Компоненты ищут его в $ADRKIT_CLI, затем в ./node_modules/.bin/adr, затем в PATH.

Он намеренно поставляется без конфигурации MCP: Copilot CLI запускает MCP-серверы плагина вне рабочей области и вне любого Git-репозитория, поэтому сервер adrkit завершает работу во время initialize. MCP вместо этого настраивается отдельно для каждого проекта — см. README плагина для настройки под конкретный хост и ADR-0028. Расширение backfill утверждено документом ADR-0034.

Статус: уже сегодня устанавливается из этого репозитория и версионируется независимо от npm-пакетов. Он делает цикл context -> check -> backfill -> draft доступным внутри текущих хостов кодинг-агентов.

Рабочий процесс backfill доступен только для чтения, пока человек не выберет кандидата. См. руководство: маршрутизация источников, пороги доказательств, обработка статусов и передача /adr-backfill → /adr-draft.

Независимо версионируется согласно ADR-0007. Исходный рабочий процесс context/check/draft/queue находится на ступени 1 ADR-0014 — покрытие модульными и контрактными тестами плюс проверка мейнтейнером на установленных хостах. Дополнение backfill в v0.2.0 прошло контрактную и статическую валидацию на хостах и имеет свежий функциональный прогон синтетического потребителя Copilot, подтверждающий сверку кандидатов и отсутствие операций записи. Для плагина не существует постоянного прогона на эталонном репозитории или внешней валидации.

Проблема

Ваша организация принимает решение. Через шесть месяцев никто его не помнит, решение оспаривается заново, а код расходится с тем, о чём договорились. Теперь агенты тоже пишут планы — быстрее, чем кто-либо успевает их рецензировать, и без памяти о том, что уже было решено и отклонено.

Идея

Рассматривайте запись о решении как типизированные данные с markdown-телом и дайте ей одно поле, которое меняет всё, — affects, объявляющее, чем управляет это решение:

---
id: "0042"
title: Use server-side rendering for authenticated routes
status: accepted
reversibility: one-way-door
blastRadius: cross-team
affects:
  - type: path
    pattern: "apps/web/app/\\(authed\\)/**"   # ( and ) are glob syntax — escape them
  - type: package
    pattern: "next@>=16"
---

Теперь инструмент может ответить на вопрос «какие решения управляют этим pull request?» — и поместить ответ туда, где на самом деле принимается следующее решение.

Что он делает

• adr lint — проверяет записи, находит циклы замещения, обнаруживает решения, которые молча противоречат друг другу. Предупреждает, когда markdown в каталоге корпуса не обнаруживается, поэтому случай «проверено 0 записей» никогда не проходит молча.

• adr migrate --from madr — принимает существующий корпус MADR на месте, аддитивно, не ломая ваши текущие инструменты. Читает статус, дату и deciders из frontmatter MADR 3.x, пунктов * Status: MADR 2.x и разделов ## Status Nygard. --rename также переименовывает каждый файл в <id>-<slug>.md.

• adr explain <path> — выводит все решения, управляющие файлом, и объясняет, почему. Решения достигают файла в двух направлениях, и вывод держит их раздельно: сработал собственный шаблон affects записи (via path: src/**), либо сам файл объявил это решение маркером @adr 0012 в комментарии (declared by src/sync.ts:3). Маркеры позволяют affects оставаться узким — только определяющие файлы, — а окружающий код подключается по одной строке, на любом языке, без изменения схемы. Только записи со статусом accepted сообщаются как управляющие; совпавшие предложения и записи со статусами superseded/rejected/deprecated перечисляются отдельно.

• adr check <files...> — проверяет изменённые записи и перечисляет решения, управляющие набором изменённых файлов, включая входящие объявления @adr. Чтение маркеров ограничено 3000 файлов / 16 параллельных чтений, 64 объявлениями на файл и 10 000 объявлений на пакет; все эти ограничения выводятся в --json; утверждения маркеров и предупреждения сканирования никогда не влияют на код возврата.

• adr evaluate <proposal> --snapshot <bundle.json> --date YYYY-MM-DD — выполняет детерминированный, не использующий модели Pass 0 над ADR-предложением и неизменяемым автономным пакетом-снимком. Применяет одиннадцать правил рубрики, при доказанных триггерах эскалирует на одного указанного активного человека (или явный unresolved) и возвращает подробный Pass0Report плюс совместимый со схемой evaluationPatch. Он не читает ни модель, ни сеть, ни часы или (в библиотеке) файловую систему и маршрутизирует — он никогда не одобряет, не сохраняет и не пишет.

• adr queue — выводит очередь операций ARB: предназначенную только для чтения, детерминированную проекцию метаданных review корпуса (уровни, состояние SLA, одобрения, возражения) в виде Markdown или JSON QueueReport v1; а также Action для управляемых задач.

• CI-комментарий — GitHub Action @adrkit/ci показывает управляющие решения на PR, которые их затрагивают или явно объявляют; совпадения шаблонов отображаются как via, а утверждения маркеров, созданные в PR, — как declared by. Комментарий также различает файлы маркеров, которые не удалось проверить, объявления маркеров, пропущенные из-за предельного лимита безопасности, и утверждения, которые он прочитал, но не смог привязать. Всё это носит рекомендательный характер: такие комментарии никогда не приводят к сбою задания. Он работает только со стандартным GITHUB_TOKEN и деградирует (не вызывая сбоя задания) на токене форка с правами только на чтение.

• MCP-сервер — позволяет агентам получать предыдущие решения, включая отклонённые, прежде чем предлагать то, что уже пробовали.

Он никогда ничего не одобряет. Он маршрутизирует, а решают люди.

Используйте оба CI Action с их плавающего мажорного тега (см. Использование в CI):

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/checkout@v4
  - uses: mbeacom/adrkit/packages/ci@v0

Почему не просто MADR — или «Structured MADR»?

frontmatter adrkit — это строгое надмножество MADR, так что это не «вместо MADR» — вы можете перенять существующий корпус на месте с помощью adr migrate --from madr. Различие в том, что происходит после появления записи.

Шаблон — включая более структурированный вариант MADR — стандартизирует то, как вы пишете решение. Он не позволяет:

• принудительно применять его в CI — adrkit разрешает affects и комментирует управляющие решения на PR, которые изменяют файлы, находящиеся под их управлением;

• отвечать на вопрос «какие решения управляют этим PR?» — для этого нужен чистый воспроизводимый сопоставитель по типизированным полям affects (ADR-0009), а не проза;

• давать агенту доступ к «кладбищу» — MCP-сервер только для чтения показывает записи rejected/superseded/deprecated, чтобы агент перестал предлагать их заново.

Схема, которую можно передать шаблону, резолверу, агенту и CI-задаче, — это иной артефакт, чем соглашение о заголовках. В этом вся суть.

Статус проекта

adrkit всё ещё не достиг версии 1.0, но некоторые поверхности уже готовы к использованию. Эта таблица — краткая версия:

Обязательства по дизайну

Они реализованы принудительно, а не являются благими пожеланиями. Каждое ссылается на запись, которая его определила.

Собственное использование

Каждое решение в этом проекте управляется этим проектом. Первый коммит репозитория — это его собственный корпус решений — см. docs/adr/. Рубрика оценщика тоже версионируется здесь же. Опубликованный оценщик в настоящее время реализует только детерминированный Pass 0; более поздние проходы остаются задокументированными проектными целями, а не выпущенным поведением.

Лицензия

Apache-2.0 — см. LICENSE.

Исключение: содержимое schema/ дополнительно выпускается под лицензией CC0. Схема предназначена для того, чтобы стать общим контрактом; конкурирующие реализации должны иметь возможность принять её вообще без учёта лицензии.

Инструментарий

Собрано с помощью Bun — см. ADR-0010. Bun — только зависимость для разработки. Ничто из опубликованного этим проектом не требует его: CLI, GitHub Action и MCP-сервер ориентированы на Node и проходят дымовое тестирование на Node 22 и 24 в CI.

Вклад в проект

См. CONTRIBUTING.md, включая вводный раздел «Your first PR». Для вклада требуется DCO-подпись, и он должен собираться из чистого клона без настроенных учётных данных.