🧠 nirvana-context-engineering

Squad de engenharia de contexto para agentes de IA — pipeline de 5 fases que transforma requisitos brutos em artefatos de contexto otimizados: CLAUDE.md, regras contextuais, AGENTS.md, configurações de memória e templates de prompt.

📋 Índice

• Visão Geral
• Instalação
• Pipeline
• Agentes
• Tasks
• Workflows
• Abordagens de Context Engineering
• Best Practices 2026
• Artefatos Gerados
• Uso
• Configuração
• Estrutura de Diretórios
• Troubleshooting
• Contribuindo
• Licença

🔭 Visão Geral

O squad nirvana-context-engineering resolve um problema crítico no desenvolvimento com agentes de IA: contexto mal estruturado destrói qualidade e eleva custos. Agentes que recebem contexto genérico, inflado ou desorganizado tomam decisões ruins, ignoram restrições do projeto e repetem erros já documentados.

Este squad aplica as melhores práticas de Context Engineering para garantir que cada agente receba exatamente o contexto certo — nem mais, nem menos.

Para quem é este squad?

• Times que adotam AIOS e precisam configurar contexto inicial de qualidade
• Projetos legados sendo onboardados para desenvolvimento com agentes
• Equipes que notam degradação progressiva na qualidade das respostas de IA
• Engenheiros que querem padronizar gestão de contexto entre múltiplos projetos

⚡ Instalação

npx squads add gutomec/squads-sh/nirvana-context-engineering

Verificar instalação:

squads list | grep nirvana-context-engineering

🔄 Pipeline

O squad executa um pipeline sequencial de 5 fases, desde a coleta de requisitos até a otimização final do contexto:

Fases do pipeline:

🤖 Agentes

📋 Tasks

.claude/rules/

🔀 Workflows

context_engineering_pipeline — Pipeline Principal

Pipeline sequencial de 5 fases que executa o fluxo completo de coleta a otimização. Cada fase depende dos artefatos da fase anterior. Indicado para novos projetos ou onboarding inicial de projetos legados.

context_optimization_cycle — Ciclo Iterativo

Loop de otimização para projetos com contexto existente que precisa de refinamento. Analisa artefatos atuais, identifica problemas e aplica melhorias incrementais. Indicado para manutenção periódica e melhoria contínua de contexto já estabelecido.

/ce optimize

🧩 Abordagens de Context Engineering

O squad implementa e combina cinco abordagens complementares de gestão de contexto:

🏆 Best Practices 2026

.claude/rules/

📦 Artefatos Gerados

O squad produz um conjunto completo de artefatos de contexto prontos para uso imediato:

• CLAUDE.md — Arquivo principal de contexto (≤ 200 linhas), com instruções gerais, stack, convenções e restrições

• .claude/rules/

  — Regras contextuais com paths: frontmatter para carregamento seletivo por escopo de arquivo
• AGENTS.md — Catálogo de agentes disponíveis com personas, capacidades e exemplos de ativação
• Memory configs — Configurações de memória de curto, médio e longo prazo para persistência de contexto
• Prompt templates — Templates reutilizáveis para tarefas comuns com placeholders tipados

💻 Uso

Comandos Principais

# Iniciar pipeline completo (fluxo padrão)
/ce start

# Executar apenas escaneamento do projeto
/ce scan

# Otimizar contexto existente
/ce optimize

# Validar qualidade dos artefatos atuais
/ce validate

# Visualizar arquitetura de contexto gerada
/ce inspect

# Ajuda e lista de comandos
/ce help

Exemplo de Fluxo Completo

# 1. Instalar o squad
npx squads add gutomec/squads-sh/nirvana-context-engineering

# 2. Iniciar o pipeline no projeto alvo
cd meu-projeto
/ce start

# 3. Responder a entrevista do Interviewer (interativo)
# O agente fará perguntas sobre: stack, time, restrições, objetivos

# 4. Aguardar o pipeline completar (automático após entrevista)

# 5. Revisar os artefatos gerados
ls .claude/
cat CLAUDE.md

# 6. Commit dos artefatos de contexto
git add CLAUDE.md .claude/ AGENTS.md
git commit -m "feat: context engineering artifacts [ce-pipeline]"

Setup Inicial — Checklist

• Squad Protocol v5 instalado e configurado
• Claude Code ativo no projeto
• Squad instalado via npx squads add
• Diretório do projeto com git inicializado
• Permissão de escrita em

  .claude/

  e raiz do projeto
• Pipeline executado com

  /ce start

• Artefatos revisados e commitados

⚙️ Configuração

name: nirvana-context-engineering
version: 1.0.0
slashPrefix: ce
protocol: "5.0"

settings:
  maxClaudeMdLines: 200
  compactionTarget: 0.5        # 50% de redução de tokens
  language: pt-BR
  encoding: utf-8
  generateAgentsMd: true
  generateMemoryConfigs: true
  generatePromptTemplates: true

pipeline:
  workflow: context_engineering_pipeline
  phases:
    - agent: interviewer
      task: gatherRequirements
    - agent: scanner
      task: scanProject
    - agent: architect
      task: designContextArchitecture
    - agent: generator
      task: generateContextArtifacts
    - agent: optimizer
      task: optimizeContext

config/agents/

# config/agents/interviewer.yaml
interviewer:
  maxQuestions: 20
  requiredTopics:
    - stack
    - teamSize
    - codeConventions
    - ciCdPlatform
    - testingStrategy
  skipIfExists:
    - requirements.yaml

# Habilitar modo verbose no pipeline
CE_VERBOSE=true

# Sobrescrever idioma dos artefatos
CE_LANGUAGE=en-US

# Desabilitar geração de prompt templates
CE_SKIP_TEMPLATES=true

# Caminho customizado para artefatos
CE_OUTPUT_DIR=.context/

📁 Estrutura de Diretórios

squads/nirvana-context-engineering/
├── README.md                    # Este arquivo
├── README.en.md                 # Versão em inglês
├── squad.yaml                   # Configuração principal
├── component-registry.md        # Registro de componentes
├── analysis.md                  # Análise de design
│
├── agents/
│   ├── interviewer.yaml         # 🎯 Agente Interviewer
│   ├── scanner.yaml             # 🔬 Agente Scanner
│   ├── architect.yaml           # 🏗️ Agente Architect
│   ├── generator.yaml           # ⚡ Agente Generator
│   └── optimizer.yaml           # 🔧 Agente Optimizer
│
├── tasks/
│   ├── gather-requirements.yaml
│   ├── scan-project.yaml
│   ├── design-context-architecture.yaml
│   ├── generate-context-artifacts.yaml
│   ├── optimize-context.yaml
│   └── validate-context-quality.yaml
│
├── workflows/
│   ├── nirvana-context-engineering-pipeline.yaml
│   └── context-optimization-cycle.yaml
│
├── templates/
│   ├── claude-md.md             # Template base para CLAUDE.md
│   ├── agents-md.md             # Template base para AGENTS.md
│   ├── rule-template.md         # Template para regras contextuais
│   └── memory-config.yaml       # Template de configuração de memória
│
├── checklists/
│   ├── quality-gate.md          # Checklist de qualidade final
│   └── review-checklist.md      # Checklist de revisão manual
│
├── config/
│   └── defaults.yaml            # Configurações padrão do squad
│
├── references/
│   ├── nirvana-context-engineering-guide.md
│   └── best-practices-2026.md
│
└── scripts/
    ├── validate.sh              # Script de validação local
    └── metrics.sh               # Coleta de métricas de contexto

🔧 Troubleshooting

.claude/rules/

.claude/rules/

ls -la .claude/

chmod 755 .claude/

/ce optimize

npx squads add --force gutomec/squads-sh/nirvana-context-engineering

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, siga o fluxo padrão do AIOS:

1. Crie uma story em

   docs/stories/

   descrevendo a melhoria
2. Implemente seguindo o Story Development Cycle (SDC)
3. Execute o QA Gate com @qa
4. Submeta via @devops com PR descritivo

Para discussões sobre arquitetura do squad, abra uma issue com a label nirvana-context-engineering.

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para detalhes completos.