ADR-Light
auspexlabs/ADRLight
Ledger append-only tipado para rastreabilidade completa de decisões e eventos em projetos
Ver no GitHubSkill para Claude que mantém um ledger append-only tipado de eventos que alteram a trajetória de um projeto. Registra decisões (DEC), deferrals (DEF), hipóteses (HYP), descobertas (DIS), incidentes (INC), outages (OUT) e correções humanas (BOT) em um arquivo único e pesquisável, com links causais entre eventos.
Instalação
npx convez-ai auspexlabs/ADRLight1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Documentar trajetória arquitetural completa de projetos com IA
- Registrar e correlacionar incidentes (causa) com outages (impacto)
- Rastrear hipóteses testadas e decisões que emergiram delas
- Manter deferências explícitas com condições de revisão
- Capturar momentos onde intuição humana corrigiu over-claims de IA
Veredito

Ferramenta sólida e pragmática para governança de decisões em projetos agentos. O design append-only, single-file e tipado resolve problemas reais (diffs triviais, sem colisão de IDs, rastreabilidade causal). Prova de conceito em produção com 169 decisões validou a abordagem; especialmente útil em ciclos rápidos human+AI.
README
A tradução para o português deste README ainda está na fila.
ADR-Light
A Claude Code skill for maintaining a single append-only decision ledger — a typed, causally-linked record of every event that changes a project's trajectory.
Why not just ADRs?
Classic Architecture Decision Records record decisions, one file each. Real projects produce more kinds of trajectory-changing events than decisions:
| Type | What it records |
|---|---|
| DEC | A decision took effect |
| DEF | Work consciously deferred, with an explicit revisit_when condition |
| HYP | A hypothesis with candidate interventions, a test matrix, and results — promoted to a DEC when a winner emerges |
| DIS | A discovery that corrects how an existing signal should be interpreted |
| INC | An incident: defect found, root cause, blast radius (the cause record) |
| OUT | An outage: severity, duration, damage (the impact record) |
| BOT | A human correction: human intuition caught and overrode an AI over-claim or mistake ("caught the bots") |
Entries link into a causal DAG via triggered_by, supersedes, and resolves edges, so "why is the system shaped this way?" is answerable by following edges — by humans or by coding agents, months later.
Everything lives in one grep-able file. One file means trivial diffs, no index to maintain, a single ID allocator (which prevents the ID-collision failure mode that one-file-per-record systems hit), and a single thing to point an agent at.
Design principles
- The ledger is the durable layer. RFCs and plans are ephemeral deliberation — they get absorbed and deleted. Ledger entries never do.
- INC explains, OUT quantifies. When a defect causes service impact, both records are filed and cross-referenced, because forensics and damage accounting are separate workstreams that close at different times.
- Work items are edges, not entries. The ledger records events; mutable task state belongs in a tracker.
- The format evolves in-band via dated format-change notes — old entries are never retrofitted.
Install
# Per-project
mkdir -p .claude/skills/adr-light && cp SKILL.md .claude/skills/adr-light/
# Or globally
mkdir -p ~/.claude/skills/adr-light && cp SKILL.md ~/.claude/skills/adr-light/
Then tell your agent to start a ledger, or just make a decision — the skill suggests entries at decision moments and never appends without confirmation.
Provenance
Extracted from a production ML pipeline project where the ledger accumulated 169 decisions, 27 deferrals, hypotheses with multi-run test matrices, and paired incident/outage records over ~4 months of human+agent development. The rules in the skill — ledger-allocated IDs, the OUT⇄INC pairing, append-only with status-line-only edits — each exists because it solves a real problem in agentic development and operations management.
The BOT (human-correction) type was added from a sibling research ledger, where human-in-the-loop catches of AI over-claims proved worth recording as first-class, terminal events — the moments a person's intuition overrode confident-but-wrong model output.