guia

Construa uma camada de contexto e verifique se ela está conforme.

Tradução assistida por agentes de IA. Em caso de divergência, prevalece a página em inglês. Se você encontrar algum problema no texto, abra uma issue ou envie um pull request.

Cinco comandos levam você da instalação à conformidade. Tudo o que o leji faz está incluído no pacote e roda offline; você mesmo inicia qualquer operação que acesse a rede. A etapa de dependência em leji init e leji adopt executa o seu próprio gerenciador de pacotes após a sua confirmação, e as buscas de federação entram em contato com o repositório que você nomeou: leji mounts hydrate --fetch, leji mounts update-pin --fetch e leji conformance --federation=verify.

Runtimes suportados Node.js 22+ Python 3.10+ Go 1.26.6+

01Instale as ferramentas

As três implementações passam pelo mesmo conjunto de fixtures. Por isso, as flags, a saída JSON e os códigos de saída são idênticos, independentemente daquela que o seu CI instalar.

Declarar a CLI como dependência de desenvolvimento garante que o CI, o hook de pre-commit e todas as pessoas que contribuem executem a mesma versão fixada. Você não precisa descobrir qual comando usar: leji init e leji adopt detectam o gerenciador de pacotes que este repositório realmente usa e se oferecem para executar o comando de adição correspondente, sempre com a sua confirmação explícita: npm, pnpm, yarn e bun; uv, poetry, pdm e pipenv; e go get -tool, que precisa de Go 1.24 ou mais novo, enquanto construir a própria CLI Go precisa de Go 1.26.6 ou mais novo. Com pip, leji exibe a linha que deve ser acrescentada, sem executar nada. Uma instalação global não interfere: dentro de um repositório que fixa a própria cópia, as CLIs Node e Python usam essa cópia em todas as invocações (a CLI que um repositório fixa).

$ npm install -g @leji-org/leji

02Crie uma camada de contexto nova, ou adote um repositório existente

Você recebe um manifesto leji.json na raiz do repositório, um perfil de boot, documentos iniciais de categoria, um primeiro registro de decisão e um roteiro de integração. Também são criados dois arquivos fora da raiz do contexto: um AGENTS.md contendo apenas o ponteiro, quando o repositório ainda não tiver esse arquivo (--no-agents ignora essa criação), e uma entrada no .gitignore da raiz para .leji/, o espaço de trabalho onde fica o roteiro. Nada disso exige um agente.

A estrutura inicial começa com textos de espaço reservado. Se você aceitar a oferta, o agente lê o repositório, propõe um mapeamento para sua aprovação e depois apaga o roteiro. Se recusar, você recebe o comando para executar mais tarde; --yes pula essa etapa para que o CI prossiga sem supervisão.

Trabalhando sozinho? --mode solo semeia pontos de partida de identidade e de estilo de escrita e direciona o roteiro para uma entrevista com o dono; as respostas podem ser digitadas, anexadas ou colocadas em uma pasta. Somente a síntese aprovada por você se torna contexto, e o material bruto fica no espaço de trabalho ignorado pelo git em .leji/, na raiz do repositório: init e adopt criam essa entrada no .gitignore, e ambos se recusam a rodar enquanto qualquer coisa sob ele estiver rastreada. O agente apaga os artefatos assim que a camada de contexto estiver preenchida.

Já tem uma árvore docs/? adopt gera a estrutura ao lado dela, sem mover nada. O ponto de entrada existente permanece intacto. Portanto, até executar --wire-adapters, você terá um rascunho de adoção, não uma camada conforme.

leji adopt --dry-run    # o plano exato de escrita; nada é gravado
leji adopt              # adota um repositório existente (leji init para um novo)
                        # depois, oferece-se para abrir o Claude Code ou o Codex

leji adopt --wire-adapters  # adota sobre um CLAUDE.md / AGENTS.md existente

npm create leji         # ou faz tudo isso em uma etapa, sem instalar nada:
                        # lê o diretório e escolhe adopt ou init

03Valide

Verificado por schema: o manifesto, o índice, o changelog e o frontmatter de perfil de agente e de registro de decisão.
Estrutura e lint: perfis de boot, arquivos de índice e documentos comuns não usam schema. Os arquivos declarados precisam existir, e o changelog é somente acréscimo em relação ao HEAD. A partir de indexed, um índice desatualizado causa uma falha.

Depois de um adopt simples sobre um CLAUDE.md ou AGENTS.md existente, espere uma falha vendor-adapter-redirect para cada um deles até que --wire-adapters rode.

leji validate           # schemas + regras de lint
leji validate --content # + avisos de texto de espaço reservado / conteúdo raso
leji index              # gera o índice

04Declare um nível e depois verifique-o

A adoção parcial é intencional: comece em core, e cada nível contém o anterior. O manifesto declara o nível; leji conformance avalia a camada de contexto de acordo com esse nível.

core → indexed → governed → federated

O que cada nível exige de você

leji conformance        # pontua a declaração

05Veja a sua camada de contexto

A mesma camada que os seus agentes leem, apresentada para pessoas.

leji view               # abre o visualizador legível por humanos no navegador
leji viewer build       # exporta uma pasta estática para hospedagem com autenticação interna

Mantenha tudo honesto no CI

O provedor é identificado pelo remote origin. Se o remote não indicar nenhum, o GitHub é usado como alternativa.

leji ci                 # gera o workflow
leji ci --hooks         # as mesmas verificações em um hook local de pre-commit

# o que o job gerado executa:
leji validate           # schemas + regras de lint
leji index --check      # falha se o índice estiver desatualizado

# adicione em indexed e acima:
leji changelog check    # somente acréscimo

Os códigos de saída são nativos de CI: 0 limpo, com avisos permitidos; 1 uma verificação que não passou, tendo ela reportado um achado ou não; 2 um erro de uso ou uma falha interna, como a recusa em sobrescrever.

Entre na camada de contexto

A camada se torna o primeiro contexto do agente, sem a intermediação de arquivos de fornecedor.

leji start              # ou --agent claude-code | codex para fixar um deles

Se houver vários hosts detectados, ele pergunta qual usar. Se não houver nenhum, ou se a execução ocorrer por script ou no CI, ele exibe o comando a ser executado em vez de tentar adivinhar. O guia de adoção cobre as flags de repasse para o host e a tabela de alternativas de arquivo de fornecedor.

Dê ao seu agente as ferramentas, não só o contexto

Entrar na camada de contexto fornece o contexto ao seu agente. O servidor MCP fornece as ferramentas: um servidor local, somente leitura, que executa validação e conformidade na camada de contexto em disco, para que o agente não precise de um shell. Ele lê e relata, mas nunca escreve.

# Claude Code (este projeto)
claude mcp add leji --scope project -- npx -y @leji-org/mcp

# Codex
codex mcp add leji -- npx -y @leji-org/mcp

init e adopt se oferecem para registrá-lo: com escopo de projeto no Claude Code, com escopo de usuário no Codex. Os comandos acima são para quem pulou aquele prompt, e trocar --scope project por --scope user faz um registro único para o seu usuário, em vez de limitá-lo a este repositório. Qualquer cliente MCP funciona; a página do servidor MCP tem a lista completa de ferramentas.

Depois, escolha a forma de adoção adequada à sua situação

Monorepo	Um repositório, uma camada de contexto, inicializada uma vez na raiz do repositório.
Muitos repositórios, uma camada	Um repositório de contexto dedicado, montado como somente documentação em cada repositório consumidor, fixado por repositório.
Várias camadas com donos	Equipes que já possuem uma camada de contexto cada. Monte cada uma como irmã; a propriedade e o fluxo de trabalho ficam como estão.

A partir de um script

A maioria dos comandos também está disponível como chamada de biblioteca para hooks, bots e etapas de build. O código-fonte está em leji-org/leji, Apache-2.0.

import { validateLayer, writeIndex, conformanceReport } from '@leji-org/leji';

const { findings } = validateLayer('.');

Próximo: o guia de adoção para um repositório existente, ou federação quando várias equipes são donas de uma camada de contexto cada.