co2-lab/anchors：面向 AI 辅助开发的 spec-first 连续性框架

Um framework spec-first de continuidade para desenvolvimento assistido por IA.

Mantém um projeto coerente ao longo do tempo — através de âncoras: documentos que guiam o trabalho na ida e o confrontam na volta, e não podem mentir sobre o código.

A spec vem antes do código, e continua sendo a verdade depois dele — não é documentação escrita a posteriori. Tudo mais (plano, mapa, testes, gates) deriva dela e é confrontado contra ela.

O problema

Uma sessão de IA é sem memória entre invocações. A sessão acaba, o contexto some, e a próxima — outro agente, outro dia, outro humano — recomeça sem as regras, sem saber o que já foi decidido, sem saber onde o trabalho parou. O projeto cresce em código, mas a direção não persiste. E os testes ficam verdes enquanto requisitos inteiros seguem sem prova.

O Anchors ataca isso projetando os artefatos certos no repositório — as âncoras — e dando a uma IA uma ferramenta para operá-las: manter o mapa de dependências, propagar mudanças, medir a qualidade, e registrar o que diverge.

O nome vem da escalada: para subir uma parede você crava âncoras, pontos fixos que dizem para onde ir, seguram a corda para você não cair e demarcam por onde passou. No Anchors, âncoras são os documentos que nos acompanham na escalada do projeto — specs, planos, features, guides, docs.

Duas partes

A IA não precisa saber o Anchors de cor — ela pergunta ao binário (anchors guide), aprende o fluxo, e opera com os comandos. O Anchors não embute IA: ele é a ferramenta que a IA usa, em qualquer cliente (Claude Code, GPT, Gemini…).

Instalação

Homebrew (macOS e Linux) — o caminho recomendado:

brew install --cask co2-lab/tap/anchors
anchors --version

Binário da release, para quem não usa Homebrew. Há build para macOS e Linux, amd64 e arm64, além de .deb, .rpm e .apk:

# escolha o pacote do seu sistema em:
#   https://github.com/co2-lab/anchors/releases/latest

gh release download --repo co2-lab/anchors \
  --pattern 'anchors_*_darwin_arm64.tar.gz' --output anchors.tar.gz
tar -xzf anchors.tar.gz anchors
sudo install anchors /usr/local/bin/anchors

go install, se você já tem Go:

go install github.com/co2-lab/anchors/cmd/anchors@latest
anchors --version

Do fonte, se você vai mexer no Anchors:

git clone https://github.com/co2-lab/anchors && cd anchors
go install ./cmd/anchors

O go install não funcionava antes da v0.1.78: o go.mod vivia em cli/ e declarava o módulo como se estivesse na raiz, então o Go baixava o módulo e não achava pacote nenhum — nem pelo caminho declarado, nem com o cli/. Se você bateu nesse erro, atualize: @latest já resolve.

Começando

Num projeto qualquer:

anchors init            # configura o anchors.yaml (por P&R; lê as pastas do projeto como camadas)
anchors map build       # constrói o mapa de dependências a partir dos arquivos
anchors doctor          # saúde do ecossistema: órfãos, colisões, buracos de cobertura
anchors check --all     # roda os gates de qualidade; abre issues; carimba o mapa
anchors report all      # gera os relatórios em docs/anchors/

O CLI só lê texto — nunca parseia código. As anotações que ele entende (identidade, @noPropagation…) vivem em comentários; os marcadores por linguagem são configuráveis. Assim ele é agnóstico de stack.

O fluxo, dirigido pela IA

A IA lê anchors guide e opera este ciclo — o watcher enfileira o trabalho, a IA puxa da fila (a conversa nunca fica presa):

  planejar ──▶ especificar ──▶ mapear ──▶ implementar ──▶ testar ──▶ confrontar
     │             │             │            │             │            │
 guia de plano   .spec.md    map build   código+feature  testes    check / doctor
                                                                        │
                                          issue ◀── divergência que a IA não resolve

Cada arquivo salvo faz o watcher enfileirar a próxima task (spec→implementar, feature→testar…). A IA não precisa lembrar o que vem depois; a fila diz.

O que o CLI faz hoje

Detalhes e decisões de arquitetura em CLI.md e DECISIONS.md.

O que dá confiança no entregável

O melhor indicador de um ciclo bem-sucedido é não ter bugs no final. Além de exigir testes, o Anchors mede a qualidade deles a partir do artefato que o runner já gera:

• por cenário — cada requisito da spec (SPCRX-V01…) tem um teste que passou? (semântico, não cobertura de linha)
• do diff — as linhas que você mudou estão cobertas? (pega o bug na linha nova)
• delta — a cobertura caiu desde a última medição? (pega regressão)

E gates que um script não computa ("esta tela respeita a arquitetura?") viram gates de julgamento por IA: a IA lê os pontos de conformidade do guide, confronta o alvo item a item, e o veredito entra na mesma mecânica (carimbo + issue) — envelhecendo se o alvo mudar.

Os pilares

Na ordem da rota — da origem ao acabamento. Cada um responde a uma pergunta que uma sessão futura faz ao chegar no projeto.

O fluxo de trabalho que os interliga não é um pilar — é um desenho, que pode mudar ou ter várias perspectivas. Os componentes que operam dentro dele é que são os pilares.

O pilar Spec é o que faz o Anchors ser spec-first: nada se implementa sem uma spec que diga o que construir primeiro, e ela continua sendo a verdade contra a qual o código é confrontado — nunca documentação escrita depois do fato.

As duas ideias que sustentam tudo

• Maturidade é o topo. Um projeto é maduro quando tem todos os seus pilares implementados e vigorosos — não é um número num artefato, é a presença e o vigor dos pilares no todo.
• Âncoras não podem mentir. Cada âncora é confrontada contra a realidade. Quando diverge, ou o trabalho está errado (corrige) ou a âncora ficou para trás (atualiza). O framework detecta e apresenta a divergência — nunca arbitra sozinho. Vale a cada mudança, de forma incremental: só se reconfere o mínimo que a mudança tocou.

O mecanismo comum

Todos os pilares compartilham um mecanismo, definido em CONCEPT.md:

• Âncora — documento que aponta, segura a corda e/ou demarca. As estruturais regem para dentro; as de consumo (como docs) são geradas para fora — âncoras, mas não pilares.
• Grafo — as âncoras e suas dependências formam um grafo material, versionado, de arestas tipadas (muitos-para-muitos). É o anchors.graph.yaml.
• Sincronia — cada aresta sabe se está em dia (carimbo por relação); a Propagação usa isso para espalhar a invalidação de forma incremental.
• Issue — quando um confronto falha e o Anchors não pode resolver sozinho, registra uma issue: arquivo em pasta-estado (todo/doing/done), imutável, aberta só por confronto, que nunca reabre (recorrência é issue nova).
• Opt-out honesto — dispensar uma exigência de forma explícita, registrada e datada (@no-test, --no-block, maturação). Dispensa a exigência, nunca o registro.
• Dois planos — o vivo (âncoras + grafo, a verdade atual) e o histórico (issues resolvidas, laudos, datados e imutáveis). Nunca se contradizem.

Por onde começar a ler

Vai USAR o Anchors num projeto? Comece por USING.md — que arquivos o projeto precisa ter, como escrever uma spec, o que cada gate cobra e o que fazer quando algo não bate. Os documentos abaixo explicam o CONCEITO; o USING.md explica a prática.

1. CONCEPT.md — a fundação: a âncora, a maturidade, o grafo, a sincronia, as issues. Todos os pilares o pressupõem.
2. Os pilares, na ordem da rota: STRUCTURE → PLANNING → SPEC → TRACEABILITY → PROPAGATION → QUALITY.
3. O CLI — CLI.md para o estado da ferramenta, comando a comando, com o que já foi validado contra um projeto real.

Cada pilar é auto-contido, mas aponta para os outros onde se tocam.

Estado do projeto

Em construção, e honesto sobre isso. A doutrina dos 6 pilares está escrita e revisada; o CLI exercita o ciclo inteiro e foi validado contra uma prova de conceito real, não-trivial — um app mobile + backend serverless com um grafo de dependências de porte substancial. Os comandos acima existem e rodam; o roadmap e os furos conhecidos estão em CLI.md.

O Anchors é o conceito — independente de qualquer ferramenta. Duas instâncias reais o exercitam: uma ferramenta/IDE que o aplica e o workspace de prova de conceito real (incompleto e imaturo de propósito — prova o mecanismo, não a completude). Elas ilustram o conceito; não o definem.

Nada aqui está cravado na pedra. Estes documentos são o conceito saindo da cabeça e encontrando seu lugar — refinados conforme o framework amadurece.

O idioma do projeto

Tudo neste repositório é escrito em INGLÊS — identificadores, comentários, specs, features, testes, documentos de doutrina. A única exceção é o CATÁLOGO DE TRADUÇÃO (internal/i18n/locales/*.json), que existe justamente para guardar todos os idiomas que o produto fala.

Quem lê o produto lê no idioma que o projeto declarar: o lang: do anchors.yaml governa as mensagens do CLI, os guides embutidos e as seções do template de spec — em pt-BR, en e es. O que o USUÁRIO lê é traduzido; o que se ESCREVE no repositório é inglês.

A regra é uma só porque a mistura não fica onde nasce. A doutrina no topo de cada gate é a matéria-prima da spec dele; a spec vira feature, a feature vira título de teste. Um idioma no começo dessa cadeia se propaga por ela inteira — medido aqui: as specs saíram em português porque a doutrina estava, as features saíram em inglês, e a mesma unidade acabou partida em dois idiomas.

O code-language (bloqueante) defende a parte que o compilador enxerga: os IDENTIFICADORES. Comentário e texto ao usuário ele não lê — o primeiro porque inferir idioma de prosa é chute, o segundo porque o catálogo já o resolve. Estarem fora do alcance do GATE não os põe fora da POLÍTICA: ali a régua é a revisão.

Licença

Elastic License 2.0 — o código é aberto para ler, usar, modificar e distribuir, inclusive comercialmente. A única restrição relevante: não oferecer o Anchors a terceiros como serviço hospedado ou gerenciado.

_{O conceito é independente de qualquer ferramenta. Ele permanece verdadeiro sem elas.}