> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receita: Debug Cross-Layer com 3 Bases de Conhecimento

> Indexe app, Terraform e GitOps em bases de conhecimento separadas e deixe a IA conectar as camadas para diagnosticar um problema que nenhuma camada explica sozinha.

Um incidente raramente mora numa camada só. O pod não sobe — é o **manifesto do Argo**? o **node group do Terraform**? o **health check no código**? Esta receita indexa as três camadas como [knowledge bases](/pt/features/knowledge-base) separadas com [`@docs-flatten kind=code`](/pt/features/knowledge-base) e deixa o agente **cruzar** as bases para achar a causa raiz.

## O Problema

O `Rollout` `checkout-api` fica preso em `Progressing` e nunca vira `Healthy`. Olhar uma camada por vez não resolve: o manifesto parece certo, o Terraform aplicou sem erro, e o código compila. A resposta está **na junção** — e está espalhada por três repositórios.

## Ingredientes

* O repositório da aplicação (código do serviço).
* O módulo Terraform da infra (cluster, node groups).
* O repositório GitOps (manifestos Argo/Kubernetes).
* ChatCLI com o tool builtin `@docs-flatten` (já vem incluso).

<Note>
  Nenhuma API key é necessária: o knowledge mode usa BM25 puro-Go por padrão. Embeddings ([Voyage/OpenAI/Bedrock](/pt/features/quality/rag-hyde)) são um boost opcional.
</Note>

***

## Passo a Passo

<Steps>
  <Step title="Indexe cada camada como uma base">
    `kind=code` fatia cada repo por estrutura — funções, recursos Terraform, manifestos — com títulos de símbolo/recurso, em vez de um blob de texto:

    ```bash theme={"system"}
    @docs-flatten root=./checkout-api  kind=code format=jsonl output=app.jsonl
    @docs-flatten root=./infra-eks     kind=code format=jsonl output=infra.jsonl
    @docs-flatten root=./gitops-argo   kind=code format=jsonl output=argo.jsonl
    ```

    Ruído (`vendor/`, `.terraform/`, lockfiles, binários) é pulado automaticamente, e arquivos acima de 1 MiB são ignorados.
  </Step>

  <Step title="Crie e anexe as três bases">
    ```bash theme={"system"}
    /context create app   app.jsonl   --mode knowledge
    /context create infra infra.jsonl --mode knowledge
    /context create argo  argo.jsonl  --mode knowledge

    /context attach app && /context attach infra && /context attach argo
    ```

    Cada attach custa só um **index card** (\~900 tokens, fixo) no prompt — as três juntas continuam baratas, mesmo com repos grandes.
  </Step>

  <Step title="Pergunte cruzando as camadas">
    No `/agent` (ou `/coder`), descreva o sintoma e deixe a IA conectar. O `@knowledge search` faz **fan-out sobre as três bases**, marcando cada trecho pela base de origem:

    ```
    /agent o Rollout checkout-api fica em Progressing e nunca vira Healthy.
           conecte o manifesto do Argo, o node group do Terraform e o
           readiness/health check no código do serviço.
    ```

    Por baixo, o agente investiga iterativamente:

    ```
    → @knowledge search "checkout-api Rollout readiness"      (base: argo)
    → @knowledge search "node group taints capacity"          (base: infra)
    → @knowledge search "health readiness endpoint port"      (base: app)
    → @knowledge get "argo/rollout-checkout.yaml"
    ```
  </Step>

  <Step title="Receba o diagnóstico cross-layer">
    Com trechos das três camadas no mesmo raciocínio, a IA conecta os pontos — por exemplo:

    > O `Rollout/checkout-api` (argo) define `readinessProbe` na porta **8080**, mas o serviço (`app`, `server.go`) escuta em **8081**; e o `aws_eks_node_group.workers` (infra) tem um `taint` `dedicated=checkout` que o `Rollout` não tolera. **Dois fatores compondo**: o probe nunca passa e os pods nem agendam nos nós certos.

    A base é **read-only** — ela dá o entendimento. Para **aplicar a correção** e rodar os testes, use o `/coder` no repo vivo com `@read`/`@search`/`@coder`.
  </Step>
</Steps>

***

## Por que funciona

<CardGroup cols={2}>
  <Card title="Fan-out automático" icon="arrows-split-up-and-left">
    `@knowledge search` consulta **todas** as bases anexadas de uma vez; cada hit vem marcado pela base de origem, então o modelo sabe de qual camada veio.
  </Card>

  <Card title="Fatiamento por estrutura" icon="cubes">
    Recursos Terraform, manifestos K8s e funções viram chunks próprios com títulos (`aws_eks_node_group.workers`, `Rollout/checkout-api`) — a busca aterrissa no ponto certo.
  </Card>

  <Card title="Custo fixo" icon="feather">
    Index card de \~900 tokens por base, não importa o tamanho do repo. Três camadas continuam cabendo no prompt.
  </Card>

  <Card title="Keyless" icon="key">
    BM25 puro-Go cobre tudo sem API key; identificadores (`getReadiness`, `checkout_api`) são achados por suas partes graças ao split camelCase/snake.
  </Card>
</CardGroup>

<Tip>
  Não precisa dizer "isto é código" para cada repo: o agente escolhe `kind=code` sozinho pela intenção e por um hint auto-corretivo. Veja [Knowledge Base](/pt/features/knowledge-base).
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Knowledge Base" icon="book-open" href="/pt/features/knowledge-base" />

  <Card title="Contextos Persistentes" icon="box-archive" href="/pt/features/persistent-context" />

  <Card title="Coder Mode" icon="code" href="/pt/features/coder-plugin" />

  <Card title="Monitoramento K8s" icon="dharmachakra" href="/pt/cookbook/k8s-monitoring" />
</CardGroup>