inetgas/arch-compiler

Architecture Compiler: Um Harness de IA em Nível de Arquitetura

Idiomas: English | 简体中文

Nota: A documentação em inglês é a fonte oficial da verdade. Se as traduções divergirem, siga a versão em inglês.

ArchCompiler compila restrições e NFRs em decisões arquiteturais explícitas e revisáveis, com trade-offs claros e impacto de custo.

É um harness de IA em nível de arquitetura construído a partir de três partes: um compilador determinístico, um registro de padrões curado e habilidades de fluxo de trabalho para agentes. Juntos, eles transformam requisitos em arquitetura compilada, roteiam o trabalho por aprovação e re-aprovação quando as decisões arquiteturais mudam, e guiam a implementação contra um contrato arquitetural explícito.

O compilador em si é intencionalmente simples: sem inferência de LLM, sem defaults ocultos e sem lógica de seleção caixa-preta. A inteligência arquitetural reside no registro e na disciplina de fluxo de trabalho transportada por:

• using-arch-compiler
• compiling-architecture
• implementing-architecture

Tags: architecture-as-code, architecture-harness, agent-harness, deterministic-compiler, pattern-registry, nfr-enforcement, ai-governance

Filosofia Central

• Padrões são a base de conhecimento. Toda a lógica arquitetural vive nos arquivos de padrão sob patterns/. O compilador é deliberadamente simples.
• Filtragem baseada em inclusão. Padrões declaram quais condições de especificação eles suportam via regras supports_constraints e supports_nfr. Um padrão é selecionado quando todas as suas regras correspondem à especificação.
• Schema primeiro. schemas/canonical-schema.yaml define o contrato da especificação; schemas/pattern-schema.yaml define o contrato do padrão. Ambos são a fonte da verdade.

---

Início Rápido

Se python não estiver disponível em seu sistema, substitua-o por python3 nos comandos abaixo.

# Instale pipx se necessário (recomendado para aplicativos CLI Python)
brew install pipx

# Instale a CLI a partir do repositório atual
pipx install .

# Compile um exemplo real de especificação (saída para stdout)
archcompiler tests/fixtures/no-advisory-success.yaml

# Compile e escreva artefatos em um diretório
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/

# Modo verbose — comentários inline de padrões + arquivo de padrões rejeitados
archcompiler tests/fixtures/no-advisory-success.yaml -v
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v

# Adicione timestamp UTC aos nomes dos arquivos de saída
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v -t

Configuração de Desenvolvimento

# Crie e ative um ambiente virtual
python3 -m venv .venv
source .venv/bin/activate

# Instale as dependências do repositório para desenvolvimento local
python -m pip install -r tools/requirements.txt
python -m pip install -e .

# Execute o compilador a partir da árvore de origem
python tools/archcompiler.py tests/fixtures/no-advisory-success.yaml

Execute comandos de desenvolvimento a partir da raiz do repositório arch-compiler/. Alguns testes invocam tools/archcompiler.py via um caminho relativo ao diretório de trabalho atual e falharão se você executá-los a partir de um diretório pai.

---

Instale as Habilidades do Agente

Este repositório também fornece habilidades de agente instaláveis.

Codex

Diga ao Codex:

Busque e siga as instruções de https://raw.githubusercontent.com/inetgas/arch-compiler/refs/heads/main/.codex/INSTALL.md

Ou siga as etapas de instalação nativa diretamente:

git clone https://github.com/inetgas/arch-compiler.git ~/.codex/arch-compiler
mkdir -p ~/.agents/skills
ln -s ~/.codex/arch-compiler/skills ~/.agents/skills/arch-compiler

Reinicie o Codex após a instalação.

Importante: os arquivos de habilidade não são suficientes por si só. Os fluxos de trabalho dependem de o repositório completo estar disponível em um caminho local estável para que os agentes possam acessar o compilador, o registro de padrões, os schemas e os adaptadores sem precisar clonar novamente ou depender de /tmp/.

Ou instale as três habilidades diretamente do repositório público:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo inetgas/arch-compiler \
  --path skills/using-arch-compiler skills/compiling-architecture skills/implementing-architecture

Nota do instalador do Codex: ao instalar várias habilidades deste repositório, passe todos os caminhos das habilidades após um único argumento --path. Não repita --path; no instalador atual, apenas o último valor repetido é mantido.

Após a instalação, verifique se os três diretórios existem:

ls ~/.codex/skills | rg 'using-arch-compiler|compiling-architecture|implementing-architecture'

Pontos de Entrada das Habilidades

• skills/using-arch-compiler = escolha o fluxo de trabalho correto e redirecione de volta para a compilação se a arquitetura mudar
• skills/compiling-architecture = compile e finalize a arquitetura
• skills/implementing-architecture = implemente uma arquitetura aprovada

Pré-verificação do Fluxo de Trabalho do Agente

Antes de fluxos de trabalho de compilação ou implementação de arquitetura voltados para o aplicativo, execute o helper de pré-verificação compartilhado. Isso se aplica independentemente de o fluxo de trabalho estar sendo conduzido por Codex, Claude Code ou outro wrapper de agente.

# Se você instalou o pacote como uma CLI:
archcompiler-preflight --app-repo /caminho/para/app-repo --mode compile

# Ou execute o helper diretamente de um caminho de repositório local estável:
python3 ~/.codex/arch-compiler/tools/archcompiler_preflight.py --app-repo /caminho/para/app-repo --mode compile
python3 ~/.claude/arch-compiler/tools/archcompiler_preflight.py --app-repo /caminho/para/app-repo --mode compile

Use --mode implement quando o fluxo de trabalho estiver prestes a escrever código a partir de uma pasta docs/architecture/ aprovada.

Claude Code

O Claude Code não usa a descoberta nativa de habilidades do Codex, mas este repositório inclui adaptadores de comando prontos para copiar em adapters/claude-code/commands/, incluindo um ponto de entrada roteador.

Mantenha o repositório completo em um caminho local estável, como ~/.claude/arch-compiler, para que os comandos possam encontrar consistentemente o compilador, os padrões e os schemas entre as sessões.

Adaptadores de comando disponíveis:

• using-arch-compiler.md
• compile-architecture.md
• implement-architecture.md

---

Formato da Especificação

A especificação de entrada é um arquivo YAML validado contra schemas/canonical-schema.yaml. Um exemplo:

# ─── ESPECIFICAÇÃO DE EXEMPLO ───
# Esta é uma especificação mínima mostrando a estrutura básica.
# Você adicionará campos progressivamente à medida que seus requisitos se tornarem mais claros.
# Consulte test-specs/ para exemplos mais completos e casos extremos.
project:
  name: Meu Serviço
  domain: ecommerce
functional:
  summary: API REST para catálogo de produtos
constraints:
  cloud: azure
  language: python
  platform: api
nfr:
  availability:
    target: 0.999
  latency:
    p95Milliseconds: 100
    p99Milliseconds: 200
  security:
    auth: jwt

Todos os campos não fornecidos são preenchidos a partir de config/defaults.yaml e registrados na seção assumptions da saída.

Para excluir explicitamente padrões que de outra forma seriam selecionados (por exemplo, muito complexos para o escopo), adicione uma lista disallowed-patterns de nível superior:

disallowed-patterns:
  - ops-low-cost-observability
  - ops-slo-error-budgets

Os padrões excluídos aparecem em rejected-patterns.yaml com phase: phase_2_5_disallowed_patterns. Um aviso é emitido para qualquer ID não encontrado no registro.

Consulte test-specs/ para um conjunto abrangente de especificações de exemplo que cobrem casos extremos, combinações de plataformas, requisitos de conformidade e muito mais.

---

Saída do Compilador

stdout

O compilador sempre imprime a especificação compilada para stdout — a especificação mesclada com todos os defaults aplicados e comentários inline de padrões (no modo verbose). Código de saída 0 em caso de sucesso, 1 em caso de erros de validação.

Arquivos escritos com -o

Arquivo	Modo	Descrição
compiled-spec.yaml	sempre	Especificação mesclada completa com suposições; pode ser re-alimentada como entrada
selected-patterns.yaml	sempre	Padrões selecionados com pontuações de correspondência e regras honradas
rejected-patterns.yaml	apenas -v	Padrões rejeitados com motivo e fase de filtro
compiled-spec-<timestamp>.yaml	-t	Mesmos arquivos com apêndice de timestamp UTC (ex.: compiled-spec-2026-03-17T19:36:31Z.yaml)

Comentários inline do modo verbose

Com -v, a especificação compilada anota cada campo com os padrões que ele acionou:

constraints:
  platform: api  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (mais 13)
  cloud: aws     # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (mais 13)
nfr:
  availability:
    target: 0.999  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (mais 14)

Isso torna a relação entre os valores da sua especificação e os padrões selecionados imediatamente visível.

---

Como Funciona a Seleção de Padrões

Fase	O que acontece
1. Analisar e Validar	Carrega a especificação, valida o schema, verifica consistência semântica
2. Mesclar Defaults	Preenche campos ausentes de config/defaults.yaml; registra em assumptions
2.5 Filtro de Desabilitados	Remove qualquer padrão listado em disallowed-patterns; avisa sobre IDs desconhecidos
3.1 Filtro de Restrições	Mantém padrões cujas regras supports_constraints correspondem todas à especificação
3.2 Filtro NFR	Mantém padrões cujas regras supports_nfr correspondem todas à especificação
3.3 Resolução de Conflitos	Remove padrões conflitantes; vencedor = maior pontuação de correspondência, depois menor custo com base na intenção
3.4 Mesclagem de Config	Mescla defaultConfig do padrão em assumptions.patterns
3.5 Filtro de Codificação	Descarta padrões de nível de codificação a menos que --include-coding-patterns seja definido
4. Viabilidade de Custo	Verifica o custo total contra cost.ceilings; emite avisos consultivos
5. Saída	Emite especificação compilada para stdout; escreve arquivos de artefato se -o for especificado

Padrões de Codificação

Por padrão, padrões com tipo coding (GoF, DI, estratégias de teste, fluxos de trabalho de desenvolvimento) são excluídos — na era dos agentes de codificação de IA, estes podem ser tratados sob demanda. Use --include-coding-patterns para incluí-los.

---

Refinamento Progressivo

O compilador é projetado para uso iterativo e incremental. Você não precisa de uma especificação completa de antemão — comece mínimo e adicione restrições progressivamente à medida que seu entendimento cresce.

Um fluxo de trabalho de exemplo

Comece mínimo → compile → revise suposições → adicione restrições → recompile → ...

Passo 1: Comece apenas com o básico

constraints:
  cloud: aws
  language: javascript
  platform: api
nfr:
  availability:
    target: 0.999

Execute o compilador. A seção assumptions na saída mostra todos os defaults que foram aplicados — estas são as decisões que o compilador tomou em seu nome. Revise-as para entender o que o compilador assumiu.

Passo 2: Adicione restrições NFR à medida que as descobre

nfr:
  availability:
    target: 0.999
  latency:           # ← adicione isto quando souber seu alvo de latência
    p95Milliseconds: 50
    p99Milliseconds: 100

Cada nova restrição restringe a seleção de padrões. Alguns padrões serão rejeitados que não eram antes — o compilador informa o motivo via o arquivo rejected-patterns.yaml (no modo -v).

Em alguns casos, a própria especificação pode ser rejeitada: se um alvo NFR difícil (por exemplo, uma latência muito apertada ou um requisito de alta disponibilidade) não puder ser satisfeito por nenhum padrão disponível, o compilador sai com código 1 e explica o que falhou. Este é um sinal útil — significa que suas restrições são contraditórias ou exigem um padrão que ainda não existe no registro.

Passo 3: Opte por funcionalidades explicitamente

constraints:
  features:
    caching: true       # ← aciona cache-aside e padrões relacionados

As flags de funcionalidades ficam sob constraints.features, não sob nfr. Elas representam capacidades de opt-in, não alvos de desempenho.

Quando um padrão é correspondido, o compilador pode emitir avisos warn_nfr — avisos de que um padrão selecionado está subutilizado dados seus valores NFR atuais. Por exemplo, ativar caching sem um NFR de throughput pode produzir:

⚠️  cache-aside: pico de QPS de leitura é 5 req/s (<10 req/s). A sobrecarga de caching
    (infraestrutura, invalidação, serialização) pode superar o benefício nesta escala.

Esta é a forma do compilador dizer que o padrão foi selecionado, mas é improvável que se pague — um prompt para fornecer dados NFR mais específicos ou reconsiderar a flag de funcionalidade.

Passo 4: Forneça dados de throughput para resolver avisos warn_nfr

Se você vir um aviso warn_nfr após ativar caching (ou outros padrões sensíveis a throughput), adicione seu pico de QPS real:

nfr:
  throughput:
    peak_query_per_second_read: 20    # ← compilador reavalia o benefício do caching
    peak_query_per_second_write: 10

Com números de throughput reais, o compilador pode fazer uma chamada definitiva — ou o aviso desaparece (caching é justificado) ou persiste com raciocínio mais específico. Qualquer resultado é mais útil do que um padrão selecionado no escuro.

Passo 5: Especifique explicitamente custo e modelo operacional quando se importar com isso

cost:
  intent:
    priority: optimize-tco   # default é minimize-opex, outra opção é minimize-capex
  ceilings:
    monthly_operational_usd: 500
    one_time_setup_usd: 1000
operating_model:
  ops_team_size: 2                    # número de engenheiros de operações dedicados
  single_resource_monthly_ops_usd: 10000  # custo mensal totalmente carregado por engenheiro
  on_call: true                       # adiciona multiplicador de 1,5× ao custo da equipe de operações
  deploy_freq: daily                  # afeta a sobrecarga de operações (diário = 1,0×, semanal = 0,8×, sob demanda = 1,2×)
  amortization_months: 24             # período sobre o qual o CapEx

…

[truncado para tradução]