convez.ai
SkillProdutividadeIntermediário
auspexlabs

ADR-Light

auspexlabs/ADRLight

Ledger append-only tipado para rastreabilidade completa de decisões e eventos em projetos

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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/ADRLight

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
—
Issues abertas
1
Contribuidores
2

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:

TypeWhat it records
DECA decision took effect
DEFWork consciously deferred, with an explicit revisit_when condition
HYPA hypothesis with candidate interventions, a test matrix, and results — promoted to a DEC when a winner emerges
DISA discovery that corrects how an existing signal should be interpreted
INCAn incident: defect found, root cause, blast radius (the cause record)
OUTAn outage: severity, duration, damage (the impact record)
BOTA 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.

Ver o original no GitHub

Bom para

Relacionados