Início rápido

Este é o caminho rápido do zero até uma configuração de harness verificada: instalar, escrever o perfil compartilhado, materializar a configuração nativa de uma ferramenta, confirmá-la e fazer sua primeira edição. Todo comando é real e pode ser copiado, colado e executado, e cada etapa mostra o que uma execução limpa imprime. A instalação em si termina em menos de dois minutos; editar o perfil é a única parte que leva o tempo que você quiser.

Ao final, você terá uma configuração de harness funcional gerada a partir de um perfil que você escreveu — e conhecerá o único comando que propaga uma alteração do perfil de volta para uma ferramenta ou para todas elas.

Você usará o Claude Code como harness de exemplo — ele é o padrão do instalador. Troque o nome do adaptador em qualquer etapa para mirar outra ferramenta; a lista de harnesses traz todos os nomes suportados.

1. Instalar o ApothemCopy Anchor Link

O Apothem é distribuído como um runtime autocontido — o motor é executado diretamente a partir da sua árvore de código-fonte, com as dependências incorporadas. Um único comando baixa o código-fonte, posiciona o motor e materializa seu primeiro harness. Como ele verifica primeiro o lançamento assinado, importe a chave de assinatura do mantenedor uma vez, antes da primeira instalação, e confira se a impressão digital é 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163:

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

Em seguida, execute o instalador:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

irm https://apothem.ahmedgad.com/install.ps1 | iex

O instalador exige um Python 3.10+ do sistema, além de git e gpg para a forma via rede. Ele verifica os pré-requisitos e posiciona o motor em ~/.apothem. Quando click ou rich está ausente, ele instala o pacote com a sua confirmação, com --yes (-Yes no PowerShell) ou com APOTHEM_AUTO_INSTALL_DEPS=1, e, caso contrário, para e informa o comando pip a executar (consulte Pré-requisitos de relance). Ao concluir, ele imprime um banner de próximos passos; em POSIX, quando o diretório do shim já está no PATH, o banner tem esta aparência:

Installation complete.

The 'apothem' command is on your PATH.

Recommended first step — the guided setup (profile -> preview -> install):

  apothem quickstart

O guia de instalação cobre as outras rotas de instalação — o plugin do Claude Code (/plugin marketplace add ahmed-g-gad/apothem e depois /plugin install apothem@apothem); as extensões da família VS Code e as demais extensões nativas das ferramentas; e a forma sob demanda com npx (npx @ahmed-g-gad/apothem <command>) — junto com as opções de variáveis de ambiente.

2. Criar o perfil compartilhadoCopy Anchor Link

apothem profile init grava o menor perfil válido segundo o schema em ~/.config/apothem/profile.yaml. Se já houver um perfil ali, como quando o instalador da Etapa 1 copiou o exemplo, init para com um erro e deixa o arquivo inalterado; passe --force para sobrescrevê-lo, ou mantenha o arquivo e edite-o como mostrado abaixo. Passe --profile PATH quando você mantiver em outro lugar um perfil específico de um projeto ou de CI.

apothem profile init
apothem profile show --json

O esqueleto usa dados de identidade fictícios, como marcadores de posição, e pode ser editado com segurança antes de você instalar qualquer saída de harness. show --json o lê de volta e relata o perfil validado com todos os padrões preenchidos, começando por schema_version. O comando o imprime em uma única linha; aqui ele aparece expandido:

{
  "schema_version": 1,
  "identity": {
    "name": "Example User",
    "role": "senior software engineer",
    "email": "[email protected]",
    "github": "example-user"
  },
  "preferences": {
    "language": "python",
    "style": "concise"
  },
  "rules": [],
  "seriousness": "PERSONAL_USE",
  "enforcement": {
    "sprints": false,
    "agent_teams": false,
    "multitasking": false,
    "continuous_execution": false,
    "learning_loop": false
  },
  "mcp_servers": {},
  "agent_mcp_servers": {},
  "harnesses": {},
  "exclude_harnesses": [],
  "workspace": {
    "directory_name": ".apothem",
    "scope": "project-local"
  }
}

É também aqui que uma edição malformada aparece — se o YAML for inválido, show o relata neste ponto, antes que qualquer configuração de harness seja gravada. Torne o perfil seu com apothem profile edit (que o abre no seu editor) ou defina diretamente uma única chave:

apothem profile set identity.name "Your Name"

3. Instalar adaptadores de harnessCopy Anchor Link

Materialize o adaptador do seu harness principal. Isso lê o seu perfil e grava a configuração nativa dessa ferramenta:

apothem install --harness claude-code

✓ Installed claude-code -> /home/you/.claude/settings.json

Os adaptadores de escopo de projeto gravam seu arquivo de regras dentro de um projeto, então precisam de um --project PATH; sete deles também gravam skills e regras compartilhadas em pastas do seu diretório pessoal, e --project não muda para onde elas vão. Pré-visualize qualquer instalação sem gravar arquivos usando --dry-run:

apothem install --harness cursor --project . --dry-run
apothem install --harness cursor --project .

Instale de uma vez todo o conjunto respaldado pelo registro com --harness all. Como essa seleção grava arquivos tanto de escopo de projeto quanto de escopo de usuário, o comando imprime os destinos concretos agrupados por local. Em um terminal interativo, ele pede confirmação antes de gravar fora da raiz do projeto. Uma execução sem terminal, uma execução com --yes ou uma execução com --format json grava sem perguntar; --dry-run não grava nada. Execute o conjunto completo com:

apothem install --harness all --project .

Consulte a lista completa de harnesses para todos os nomes suportados e a referência de install para o conjunto completo de opções.

4. VerificarCopy Anchor Link

Materializar é só metade do trabalho: verify confirma que os arquivos de configuração esperados do harness foram gravados e são válidos:

apothem verify --harness claude-code

✓ claude-code is verified at /home/you/.claude/settings.json

verify sai com código diferente de zero se um destino gerenciado estiver ausente, se um arquivo gerenciado estiver vazio ou se uma configuração JSON ou YAML não puder ser analisada. Adicione --profile PATH para também falhar quando um arquivo instalado diferir desse perfil, o que faz do verify uma verificação de desvio; sem ele, uma configuração desatualizada ainda passa na verificação. A saída diferente de zero permite usar verify como portão em um script de configuração. Para uma verificação de saúde da máquina inteira, abrangendo todos os adaptadores registrados, execute:

apothem doctor

doctor verifica cada harness instalado: ele deve passar na verificação, e cada comando de hook que a sua instalação registrou deve iniciar. Um harness que você não instalou é listado, mas não conta como falha, de modo que doctor sai com 0 quando nenhuma verificação falha, mesmo que apenas um harness esteja instalado.

5. Sua primeira execuçãoCopy Anchor Link

Abra o harness que você acabou de configurar — o Claude Code, neste exemplo — e inicie uma sessão em qualquer projeto. O perfil que você configurou na Etapa 2 agora faz parte do comportamento dessa ferramenta. Essa é a primeira execução funcional: um perfil moldando uma sessão real.

Quando você alterar o perfil mais tarde, reaplique-o sem reinstalar:

apothem update --harness claude-code

Informe outro adaptador para reaplicar o perfil a essa ferramenta (adicione --project PATH para um adaptador de escopo de projeto) ou passe --harness all --project . para reaplicá-lo a todos os harnesses suportados.

Próximos passosCopy Anchor Link

• Adicionar mais harnesses — repita a Etapa 3 para cada ferramenta.
• Escrever sua primeira regra — a unidade que todo harness herda.
• Criar um plano — conduza uma missão inteira pelo pipeline de planos determinístico.
• Referência da CLI — todo comando, sinalizador e código de saída.