adrkit

사람과 에이전트가 작성한 계획을 위한 결정 메모리 — 기계가 읽을 수 있고 CI에서 강제할 수 있으며 에이전트가 이해할 수 있는 아키텍처 결정 레코드. git을 벗어나지 않습니다.

대부분의 ADR 도구는 마크다운 템플릿과 정적 사이트 생성기입니다. 그 도구는 결정을 기록할 뿐, 결정이 무언가를 실행하게 하지는 않습니다. adrkit은 레코드를 마크다운 본문을 가진 타입 있는 데이터로 취급하고 affects 필드 하나를 추가합니다. 덕분에 도구는 *"이 풀 리퀘스트에 적용되는 결정은 무엇인가?"*라는 질문에 답하고, 그 답을 다음 결정이 내려지는 곳에 놓을 수 있습니다.

빠른 시작

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를 포함하는 첫 동기화 릴리스부터, 릴리스는 ghcr.io/mbeacom/adrkit의 다중 아키텍처 OCI 이미지로 게시됩니다. 자동화에서는 불변 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는 stdio를 사용하므로 MCP 명령은 stdin을 계속 엽니다. 저장소 마운트는 서버 계약에 따라 읽기 전용입니다. MCP 클라이언트 구성에서는 절대 호스트 경로를 사용하세요. 의도적으로 쓰기를 수행하는 CLI 명령(new, 또는 --dry-run 없는 migrate)에서는 --read-only와 마운트의 :ro 접미사를 생략하세요. 이미지는 루트가 아닌 node 사용자로 실행됩니다. 호스트의 UID/GID가 다른 경우 --user "$(id -u):$(id -g)"를 추가하세요. SELinux 호스트에서는 적절한 바인드 마운트 레이블(예: :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를 예약합니다. 그 외에 help lint 같은 CLI 도움말 하위 명령은 변경 없이 그대로 전달됩니다.

동일한 소스를 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에서 @adrkit/ci Action은 해당 결정과 관련된 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로 나갑니다. 묘지(graveyard)는 기본적으로 포함됩니다. 전체 도구 계약은 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

모든 컴포넌트는 adr CLI를 셸로 호출하므로, 아직 설치하지 않았다면 그것도 설치하세요 — npm i -g @adrkit/cli 또는 프로젝트에 @adrkit/cli를 추가하면 됩니다. 컴포넌트는 $ADRKIT_CLI, ./node_modules/.bin/adr, PATH 순서로 CLI를 찾습니다.

의도적으로 MCP 구성 없이 배포됩니다. Copilot CLI는 플러그인의 MCP 서버를 워크스페이스 외부, 그리고 어떤 Git 저장소 외부에서도 시작하므로 adrkit 서버는 initialize 중에 종료됩니다. MCP는 대신 프로젝트별로 연결됩니다. 호스트별 설정은 플러그인 README와 ADR-0028을 참조하세요. 백필 확장은 ADR-0034에 의해 승인되었습니다.

상태: 현재 이 저장소에서 설치할 수 있으며 npm 패키지와 독립적으로 버전이 관리됩니다. 이 플러그인은 현재 코딩 에이전트 호스트 내에서 context -> check -> backfill -> draft 루프를 사용할 수 있게 합니다.

백필 워크플로는 사람이 후보를 선택하기 전까지 읽기 전용입니다. 소스 라우팅, 증거 임계값, 상태 처리, /adr-backfill → /adr-draft 핸드오프는 가이드를 참조하세요.

ADR-0007에 따라 독립적으로 버전이 관리됩니다. 원래의 context/check/draft/queue 워크플로는 ADR-0014의 **1단계(rung 1)**에 있습니다. 여기에는 설치된 호스트에 대한 단위 및 계약 테스트 커버리지와 유지보수자 검증이 포함됩니다. v0.2.0 백필 추가분은 계약 및 정적 호스트 검증을 거쳤고, 후보 조정과 쓰기 없음을 입증하는 새로운 기능적 Copilot 합성 소비자 실행이 있습니다. 플러그인에 대한 영구 참조 저장소 실행이나 외부 검증은 존재하지 않습니다.

문제

조직에서 무언가를 결정합니다. 하지만 6개월 후에는 아무도 기억하지 못하고, 결정은 다시 논쟁이 되며, 코드는 합의된 내용에서 벗어납니다. 이제 에이전트도 계획을 작성합니다. 누구도 검토할 수 없을 정도로 빠르게, 그리고 이미 결정되고 기각된 내용에 대한 기억 없이 말입니다.

아이디어

결정 레코드를 마크다운 본문을 가진 타입화된 데이터로 취급하고, 모든 것을 바꾸는 필드 하나를 추가하세요 — 결정이 무엇을 관장하는지 선언하는 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"
---

이제 도구는 *"이 풀 리퀘스트를 관장하는 결정은 무엇인가?"*에 답할 수 있고, 답을 실제로 다음 결정이 이루어지는 곳에 놓을 수 있습니다.

기능

• adr lint — 레코드를 검증하고, 대체(supersession) 순환을 잡아내며, 서로 조용히 모순되는 결정을 찾습니다. 코퍼스 디렉터리 아래의 마크다운이 검색 불가능할 때 경고하므로 "checked 0 records"가 절대 조용히 지나치지 않습니다.

• adr migrate --from madr — 기존 MADR 코퍼스를 제자리에서, 추가적으로, 현재 도구를 깨뜨리지 않고 채택합니다. MADR 3.x frontmatter, MADR 2.x * Status: 불릿, Nygard ## Status 섹션에서 상태, 날짜, 결정자를 읽습니다. --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 선언을 포함하여 변경된 파일 집합을 관장하는 결정을 나열합니다. 마커 읽기는 파일 3,000개, 동시 읽기 16개, 파일당 선언 64개, 배치당 선언 10,000개로 제한되며 모두 --json으로 보고됩니다. 마커 주장과 스캔 경고는 종료 코드에 절대 영향을 미치지 않습니다.

• adr evaluate <proposal> --snapshot <bundle.json> --date YYYY-MM-DD — 제안 ADR과 변경 불가능한 오프라인 스냅샷 번들에 대해 결정적이고 모델이 필요 없는 Pass 0을 실행합니다. 11가지 루브릭 규칙을 적용하고, 입증된 트리거에서 단 한 명의 지정된 활성 인간(또는 명시적 unresolved)으로 에스컬레이션하며, 풍부한 Pass0Report와 스키마 호환 evaluationPatch를 반환합니다. 모델, 네트워크, 시계, (라이브러리에서는) 파일시스템을 읽지 않으며, 라우팅만 합니다 — 승인, 영속화, 쓰기를 절대 하지 않습니다.

• adr queue — ARB 운영 큐를 출력합니다. 코퍼스의 review 메타데이터(티어, SLA 상태, 승인, 이의)를 Markdown 또는 QueueReport v1 JSON으로 읽기 전용, 결정적 프로젝션입니다. 또한 관리형 이슈 Action이기도 합니다.

• CI 주석 — @adrkit/ci GitHub Action이 해당 결정을 건드리거나 명시적으로 선언하는 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 — 또는 "구조화된 MADR"이 아닌가?

adrkit의 frontmatter는 엄격한 MADR 상위 집합이므로 이는 "MADR의 대안"이 아닙니다. 기존 코퍼스를 제자리에서 adr migrate --from madr로 마이그레이션할 수 있습니다. 차이는 레코드가 존재한 후에 일어나는 일입니다.

템플릿 — 더 구조화된 MADR 변형을 포함하여 — 결정을 작성하는 방법을 표준화합니다. 그러나 다음은 하지 않습니다:

• CI에서 강제하지 않습니다 — adrkit은 affects를 해석하고, 자신이 관장하는 파일을 변경하는 PR에 관장 결정을 주석으로 답니다.

• "이 PR을 관장하는 결정은 무엇인가?"에 답하지 않습니다 — 그러려면 산문이 아니라 타입화된 affects 필드에 대한 순수하고 재현 가능한 매처가 필요합니다(ADR-0009).

• 에이전트가 묘지를 검색하게 하지 않습니다 — 읽기 전용 MCP 서버가 rejected/superseded/deprecated 레코드를 표면화하여 에이전트가 이를 다시 제안하지 않게 합니다.

린터, 리졸버, 에이전트, CI 잡에 넘겨줄 수 있는 스키마는 제목 규칙과는 다른 산출물입니다. 이것이 전체 논지입니다.

프로젝트 상태

adrkit은 아직 pre-1.0이지만, 여러 표면은 지금 바로 사용할 준비가 되었습니다. 이 표는 요약 버전입니다:

설계 약속

이것들은 바람이 아니라 강제됩니다. 각 항목은 그것을 결정한 레코드로 연결됩니다.

도그푸딩

이 프로젝트의 모든 결정은 이 프로젝트 자신이 관장합니다. 저장소의 첫 커밋은 자체 결정 코퍼스입니다 — docs/adr/를 참조하세요. 평가자 루브릭도 여기에서 자체적으로 버전 관리됩니다. 게시된 평가자는 현재 결정적 Pass 0만 구현하며, 이후 패스는 릴리스된 동작이 아닌 문서화된 설계 목표로 남아 있습니다.

라이선스

Apache-2.0 — LICENSE를 참조하세요.

예외: schema/의 내용물은 CC0로 추가 릴리스됩니다. 스키마는 공유 계약이 되는 것이 목적이므로, 경쟁 구현체가 라이선스 고려 없이 채택할 수 있어야 합니다.

도구 체인

Bun으로 빌드되었습니다 — ADR-0010을 참조하세요. Bun은 개발 의존성일 뿐입니다. 이 프로젝트에서 게시된 어떤 것도 Bun을 요구하지 않습니다. CLI, GitHub Action, MCP 서버는 Node를 대상으로 하며 CI에서 Node 22와 24로 스모크 테스트됩니다.

기여

CONTRIBUTING.md를 참조하세요. "Your first PR" 온램프를 포함합니다. 기여에는 DCO 서명이 필요하며, 자격 증명이 구성되지 않은 깨끗한 클론에서 빌드되어야 합니다.