Pitch: O Claude escreve código rápido, mas esquece as regras do projeto a cada sessão. Fiz uma CLI open source pra resolver isso.

Uso Claude Code todo dia pra escrever código. É rápido, entende contexto grande, e na maioria das vezes acerta. Mas tem um problema que me incomodava toda semana: ele não lembra das decisões que o time já tomou.

Meu projeto tem convenções. Arquivos de comando vão numa pasta específica e seguem um padrão de export. Erros são tratados com um helper customizado, não com console.error(). A gente usa styleText() do Node pra output no terminal, não chalk. Dependências novas precisam de aprovação antes de entrar no package.json.

Nada disso é complicado. Mas o Claude não sabe. Ele lê os arquivos, sim. Mas não entende o porquê das coisas serem do jeito que são. Aí em cada sessão nova ele importa barrel file que a gente baniu, sugere biblioteca que não usamos, inventa padrão de erro diferente. E eu corrijo. Na sessão seguinte, tudo de novo.

Tentei colocar essas regras no CLAUDE.md. Funciona parcialmente. O problema é que CLAUDE.md é texto. O Claude lê como sugestão. Às vezes segue, às vezes não. E você nunca tem certeza se o código gerado respeitou as convenções até ler tudo manualmente.

O que eu queria era simples: que a IA lesse minhas regras antes de escrever código, e que existisse uma checagem automática pra pegar o que ela errasse. O mesmo fluxo pra humano e pra IA.

O que é o Archgate

É uma CLI open source que faz duas coisas:

Guarda as decisões de arquitetura do projeto em arquivos markdown estruturados (com frontmatter YAML). A IA lê esses arquivos como contexto antes de escrever qualquer linha.
Permite escrever checagens automáticas em TypeScript puro (.rules.ts) que validam se o código segue as decisões. Roda em milissegundos, local ou no CI.

Instalação:

curl -fsSL https://cli.archgate.dev/install-unix | sh
archgate init

Ou via npm:

npm install -g archgate
archgate init

O archgate init cria a pasta .archgate/adrs/ com um exemplo. Você edita o exemplo pra descrever uma convenção real do seu projeto. Roda archgate check. Se o código violar a regra, ele mostra o arquivo, a linha, e qual decisão foi violada. Exit code 1 bloqueia merge no CI.

Como funciona na prática

Um ADR (Architecture Decision Record) é um arquivo markdown assim:

---
id: ARCH-001
title: Estrutura de comandos CLI
domain: commands
rules: true
files: "src/commands/**/*.ts"
---

O corpo do arquivo descreve a decisão em linguagem natural: o contexto, o que fazer, o que não fazer. É isso que a IA lê.

Do lado desse arquivo, existe um .rules.ts com as checagens:

import { defineRules } from "archgate/rules";

export default defineRules({
  "command-exports-register-function": {
    description: "Comandos devem exportar register*Command()",
    check: async (ctx) => {
      for (const file of ctx.scopedFiles) {
        const content = await ctx.readFile(file);
        if (!content.match(/export\s+function\s+register\w+Command/)) {
          ctx.report.violation(file, 1, "Arquivo de comando não exporta register*Command()");
        }
      }
    },
  },
});

TypeScript puro, sem DSL, sem dependência extra. A API do ctx tem glob(), grep(), readFile(), readJSON(). Você escreve a checagem que quiser.

Quando a IA (ou um humano) escreve código, archgate check roda todas as regras e reporta violações. No CI, é um archgate check no pipeline. Tem GitHub Action pronta: archgate/check-action@v1.

Os plugins pros editores

Além da CLI, existem plugins pra cinco editores:

Claude Code: plugin completo com agent de desenvolvimento + skills de revisão, captura de padrões, e criação de ADRs
Cursor: agent de desenvolvimento + skills de governança
VS Code: extensão que distribui as regras pro GitHub Copilot
GitHub Copilot: contexto de ADR via extensão do VS Code
OpenCode: bundle de agents (developer + 4 subagents)

O plugin faz uma coisa importante: antes da IA escrever código, ele roda archgate review-context que retorna um resumo compacto (umas 20 linhas) só com as regras que se aplicam aos arquivos sendo alterados. A IA lê isso em vez de fazer grep no projeto inteiro tentando adivinhar as convenções.

Na prática, isso corta uns 67% do consumo de tokens por tarefa. Menos tool calls, menos loops de descoberta, e a IA acerta mais de primeira.

O que aprendi postando no Reddit

Postei o Archgate no r/softwarearchitecture dois meses atrás. O post teve 40+ upvotes e 24 comentários, a maioria dizendo a mesma coisa: "isso é overengineered, dá pra fazer com CLAUDE.md".

Eles tinham razão em parte. A versão original tinha um servidor MCP rodando como processo separado. Era complexidade desnecessária. Removi completamente. Agora tudo passa pela CLI, que é um binário standalone compilado com Bun (~55MB, sem dependência de runtime).

A outra crítica era sobre tokens. Um comentário específico dizia: "tive experiência ruim com MCP tools que gastam muitos tokens no início da sessão, mesmo quando não são usados". Isso me levou a repensar toda a integração. Os plugins agora usam a CLI diretamente em vez de MCP.

A terceira crítica era sobre o nome ADR pra regras granulares. ADRs tradicionais documentam decisões grandes ("usamos PostgreSQL"). As regras do Archgate podem ser granulares ("tratamento de erro usa o helper X"). Mantive o termo ADR porque o formato funciona pros dois níveis. Uma decisão grande e uma convenção pequena têm a mesma estrutura: contexto, decisão, consequências. O que muda é a granularidade.

Números

~3.700 downloads/mês no npm
v0.33.1 (era v0.26 quando postei no Reddit)
32 estrelas no GitHub
macOS, Linux, Windows
Apache-2.0
Docs em português: cli.archgate.dev

É pequeno ainda, mas tá crescendo constante.

Stack

TypeScript + Bun
Compila pra binário standalone com bun build --compile --bytecode
Schemas com Zod
CLI com Commander.js
Linter: Oxlint, Formatter: Oxfmt
CI: GitHub Actions
Distribuição: npm thin shim + install script + proto plugin
Site: Astro + Tailwind (archgate.dev), docs com Astro Starlight (cli.archgate.dev)

O projeto dogfoods ele mesmo. O código do Archgate é governado pelos próprios ADRs que ele define. Se eu violo minhas próprias regras, archgate check pega antes do CI.