winget install --id=co2lab.Anchors -e Anchors ties spec, feature and test together through a shared identity code, then confronts each artifact against the rules declared in anchors.yaml. It maps the project as a graph, propagates change from the anchor outward, and gates every step — so work guided by AI stays anchored to what was decided.
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.
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.
| A doutrina | o conceito, agnóstico de ferramenta — os 6 pilares e o mecanismo comum | os *.md desta raiz |
| O CLI | a ferramenta em Go que uma IA opera para exercitar o ciclo | cmd/ · CLI.md |
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…).
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.
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.
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.
| área | comandos | o que entrega |
|---|---|---|
| Estrutura | init | configura o anchors.yaml a partir das pastas e da linguagem do projeto, sem propor estrutura; semeia o CONTRIBUTING.md |
| Mapa | map build, map show, governs | o grafo de dependências; quem rege quem |
| Propagação | impact, stale | a onda de uma mudança; o que ficou desatualizado |
| Fila | watch, queue, next, done, drop, reclaim | o watcher em background enfileira; a IA puxa |
| Qualidade | check, judge, doctor | gates determinísticos e de julgamento por IA; saúde sistêmica |
| Identidade | code | gera/valida um código de cenário único (evita colisões) |
| Confiança | ingest, coverage | ingere JUnit/lcov do runner; cobertura por cenário, do diff, e delta |
| Relatórios | report | 6 perspectivas em docs/: tests, quality, structure, config, issues, inconsistencies |
| A ponte IA | guide (+ guide plan/spec/code/feature/test/guide) | o playbook e as réguas embutidas que a IA lê para operar |
Detalhes e decisões de arquitetura em CLI.md e
DECISIONS.md.
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:
SPCRX-V01…) tem um teste que passou?
(semântico, não cobertura de linha)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.
Na ordem da rota — da origem ao acabamento. Cada um responde a uma pergunta que uma sessão futura faz ao chegar no projeto.
| # | Pilar | Pergunta que responde | Documento |
|---|---|---|---|
| 1 | Estrutura de Projeto | quais camadas existem e como se organizam? | STRUCTURE.md |
| 2 | Planejamento | para onde vamos, em que ordem, onde paramos? | PLANNING.md |
| 3 | Spec | o que esta coisa deve ser? | SPEC.md |
| 4 | Rastreabilidade | como as peças se conectam? | TRACEABILITY.md |
| 5 | Propagação | quando algo muda, como a mudança percorre tudo até fechar? | PROPAGATION.md |
| 6 | Qualidade | isto está bom o suficiente? | QUALITY.md |
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.
Todos os pilares compartilham um mecanismo, definido em CONCEPT.md:
anchors.graph.yaml.todo/doing/done), imutável, aberta só por
confronto, que nunca reabre (recorrência é issue nova).@no-test, --no-block, maturação). Dispensa a exigência, nunca o registro.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.
CONCEPT.md — a fundação: a âncora, a maturidade, o grafo, a
sincronia, as issues. Todos os pilares o pressupõem.STRUCTURE →
PLANNING → SPEC →
TRACEABILITY → PROPAGATION →
QUALITY.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.
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.
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.
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.