Documento interno PROX · Junho 2026

O sistema operacional de engenharia com IA da PROX

O PROX AI Engineering OS (PROX AI OS) não é uma coleção de prompts. É um framework em Markdown que governa como agentes de IA leem contexto, assumem papéis, seguem workflows e escrevem código — de forma previsível, em qualquer projeto do time.

4
Pilotos ativos
3
Roles definidos
8
Capabilities
10
Princípios core

01 Para que serve?

Resolver os problemas recorrentes de engenharia assistida por IA em escala: contexto perdido, alucinações, padrões inconsistentes e onboarding lento de novos devs e novos agentes.

Sem o OS

  • Cada dev escreve prompts diferentes
  • IA lê o repo inteiro e alucina
  • Decisões ficam só no chat
  • Trocar de IDE/modelo quebra o fluxo
  • Novo agente não sabe a stack

Com o PROX AI OS

  • Boot sequence determinístico
  • Contexto carregado sob demanda
  • Conhecimento permanente em arquivos
  • Vendor agnostic (Cursor, Claude, etc.)
  • Perfil do projeto sempre disponível

Filosofia central: FileSystem as Protocol — pastas e arquivos Markdown roteiam a IA de forma determinística. O conhecimento é permanente; os modelos de IA são substituíveis.

02 Vantagens de usar em todos os projetos

Padronizar o OS em TellMyCleaner, Content Machine, Retirement, Prox Listas e futuros repos cria um mesmo “contrato” entre humanos, IAs e projetos.

🎯

Context Economy

Quick Boot para tarefas simples; Full Boot só quando necessário. A IA carrega apenas role, workflow e knowledge relevantes — economizando tokens e reduzindo alucinações.

🔒

Segurança por padrão

Regras explícitas: parar e pedir aprovação antes de ações destrutivas (schema, deletes, mudanças de arquitetura). Checklists de security e review embutidos.

🔄

Portabilidade entre projetos

Mesma estrutura .ai-os/ em todo repo. Um dev (ou agente) que aprendeu o boot no TellMyCleaner já sabe operar no Retirement.

🧠

Memória institucional

Decisões, glossário de domínio, regras permanentes e ADRs vivem em knowledge/ — não se perdem quando o chat fecha.

👥

Roles com escopo claro

Architect, Implementation Engineer e Reviewer têm fronteiras rígidas. Evita que a IA misture concerns (ex.: frontend alterando schema).

⚡

Instalação com baixo atrito

Installer PowerShell oficial: dry-run, apply, análise de repos existentes, migração de ai-dev-os/ legado. Nunca commita automaticamente.

🔌

Sem vendor lock-in

Regras universais em Markdown; adapters (ex.: Cursor rule) só apontam para o core. Funciona com Cursor hoje e evolui para outros IDEs.

📈

Base para multi-agente (v2/v3)

v0.1.2 é foundation. O roadmap prevê handoffs entre agentes, CLI de updates, ADRs automáticos e distribuição via package manager.

03 O que tem hoje (v0.1.2)

Cada projeto hospedeiro recebe uma pasta .ai-os/ com o framework copiado pelo installer. Abaixo, as camadas reais do repositório-fonte.

1

Kernel — ponto de entrada obrigatório

Regras universais, Quick Boot vs Full Boot, proibição de buscas globais, contratos antes de código.

.ai-os/core/KERNEL.md · CONTEXT-ROUTER.md
2

Project Package — identidade do projeto

Perfil (stack, domínio, paths de código) e índice de conhecimento. Específico de cada app.

.ai-os/project/PROJECT-PROFILE.md · PROJECT-KNOWLEDGE-INDEX.md
3

Roles — personas com escopo

Architect, Implementation Engineer, Reviewer — cada um carrega só suas regras.

.ai-os/roles/
4

Workflows — SOPs passo a passo

Feature development e bug fix hoje; mais workflows conforme validação.

.ai-os/workflows/
5

Knowledge — memória do projeto

Permanent, working, research, decisions, domain, glossary — conhecimento que sobrevive às sessões.

.ai-os/knowledge/
6

Capabilities · Templates · Principles · Adapters

8 tipos de trabalho, templates de SPEC/ADR/Review, 10 princípios, bridge Cursor → core.

.ai-os/capabilities/ · templates/ · principles/ · adapters/
Repo-fonte
prox-ai-engineering-os/
→
Installer
install-ai-os.ps1
→
Projeto hospedeiro
meu-app/.ai-os/
O framework não vive como submodule — é copiado para dentro do repo do app, versionado no git do projeto.

04 Boot sequence — como a IA inicia

Toda sessão no Cursor segue uma ordem fixa. A cursor rule em .cursor/rules/ai-engineering-os.mdc dispara o boot automaticamente.

  1. CONTINUE-HERE.md — estado vivo da sessão (se existir)
  2. CLAUDE.md — regras operacionais do projeto (pipeline, deploy, constraints)
  3. .ai-os/core/KERNEL.md — entry point do framework
  4. .ai-os/core/CONTEXT-ROUTER.md — roteamento de contexto sob demanda
  5. .ai-os/project/PROJECT-PROFILE.md + PROJECT-KNOWLEDGE-INDEX.md
  6. Carregar role, workflow e knowledge somente conforme a tarefa
  1. Kernel — reconhecer regras
  2. Project Profile — identidade e path do código-fonte
  3. Executar a tarefa diretamente (bug fix pequeno, pergunta rápida, edit minor)
  1. Kernel — reconhecer regras
  2. Context Router — navegar o sistema
  3. Project Profile — stack e domínio
  4. Role — ex.: roles/architect.md
  5. Workflow — ex.: workflows/feature-development.md
  6. Knowledge — arquivos específicos via índice ou busca em knowledge/
  7. Executar seguindo o workflow passo a passo

05 Como instalar em um projeto novo

Fluxo para qualquer pessoa do time (ex.: Oscar). Requisitos: Windows, PowerShell, Git, Cursor.

Passo 1 — Clonar o repo-fonte (uma vez)

PowerShell 
cd C:\Projetos
git clone https://github.com/renato-proxtech/prox-ai-engineering-os.git

Passo 2 — Dry-run (sem alterar nada)

PowerShell 
powershell -ExecutionPolicy Bypass -File C:\Projetos\prox-ai-engineering-os\tools\install-ai-os.ps1 `
  -TargetPath "C:\Projetos\meu-projeto" `
  -Mode dry-run

Passo 3 — Apply (instala de verdade)

PowerShell 
powershell -ExecutionPolicy Bypass -File C:\Projetos\prox-ai-engineering-os\tools\install-ai-os.ps1 `
  -TargetPath "C:\Projetos\meu-projeto" `
  -Mode apply `
  -CreateContinueHere

O installer cria branch feature/install-ai-engineering-os, copia o framework para .ai-os/, gera a cursor rule e um relatório em .ai-os/INSTALL-REPORT.md. Review + commit manual — o installer nunca commita.

Repo legado com ai-dev-os/

Migração 
powershell -ExecutionPolicy Bypass -File C:\Projetos\prox-ai-engineering-os\tools\install-ai-os.ps1 `
  -TargetPath "C:\Projetos\meu-projeto" `
  -Mode apply -MigrateLegacy -ArchiveLegacy

06 Como usamos no dia a dia

O OS não substitui CLAUDE.md nem o código — ele organiza como a IA interage com ambos.

🚀

Início de sessão

Abrir o projeto no Cursor. A rule boota automaticamente. Ler CONTINUE-HERE.md para retomar de onde parou.

✏️

Feature nova

Pedir a feature. Agente faz Full Boot → Architect → workflow feature-development → SPEC antes de código.

🐛

Bug fix

Quick Boot ou workflow bug-fix. Carregar só arquivos tocados + regras de domínio se necessário.

📝

Fim de sessão

Atualizar CONTINUE-HERE.md com estado git + próximo passo. Decisões importantes → knowledge/decisions/.

O que dizer ao agente

Não basta dizer “usa o Prox AI OS”. Aponte o caminho: .ai-os/core/KERNEL.md, ou abra o projeto que já tem a cursor rule instalada.

07 Pilotos ativos

Projeto Path OS Status Notas
TellMyCleaner .ai-os/ Validado Boot check OK; legacy migrado e arquivado
PROX Content Machine .ai-os/ Instalado Profile preenchido via análise do installer
Retirement .ai-os/ Em uso Piloto ativo
Prox Listas .ai-os/ Em uso Piloto ativo
PROX (platform) — Planejado Validação ADR / arquitetura profunda
Orbita — Planejado Quick Boot / velocidade MVP

08 Inventário completo (repo-fonte)

Pasta / artefato Conteúdo
core/KERNEL.md, CONTEXT-ROUTER.md
roles/architect, implementation-engineer, reviewer
workflows/feature-development, bug-fix
capabilities/planning, architecture, research, implementation, review, testing, documentation, security
knowledge/permanent, working, research, decisions, domain, glossary
templates/SPEC, ADR, REVIEW templates
self-review/Checklists architecture, security, usability, performance
principles/10 princípios (context economy, human-first, safe-by-default…)
project/Templates de profile e knowledge index
adapters/cursor/Cursor rule template (ai-engineering-os.mdc)
tools/install-ai-os.ps1 (não copiado para host)
examples/TellMyCleaner reference-only (não copiado)

09 Roadmap resumido

v1 — Foundation & Context Economy Atual · 0.1.2

Installer PowerShell, pilotos, migração legado, validação antes do 1.0.0.

v2 — Workflows avançados & memória

ADRs automáticos, handoff multi-agente, CLI de updates, installer bash/Linux.

v3 — Automação & ecossistema

Git/PR autônomo, resolução de conflitos multi-agente, package manager.

10 Perguntas frequentes

Não. Clone o repo-fonte uma vez na máquina para rodar o installer. Depois, cada app tem .ai-os/ dentro do seu próprio git. Se o projeto já veio com .ai-os/ instalado, basta clonar o app.
Não. CLAUDE.md continua sendo as regras operacionais do projeto (deploy, pipeline, constraints). O OS é a camada de engenharia padronizada: boot, roles, workflows e knowledge index.
Sim, em princípio. O core é Markdown vendor-agnostic. Hoje o adapter pronto é Cursor; outros IDEs precisam de um adapter que aponte para .ai-os/core/KERNEL.md.
Hoje: re-run do installer com -ForceReinstall (preserva profile e arquivos protegidos). v2 trará CLI dedicada (issue #4 no backlog).