🤖 Agent OS Starter

O sistema operacional para agentes de IA no seu projeto.

Um boilerplate completo para configurar projetos com Claude Code (ou outros LLMs) de forma estruturada, com memória coletiva, spec-driven development e regras de arquitetura.

📋 Índice

O que é isso?
Arquitetura "A Quadra"
Quick Start
Estrutura de Arquivos
Componentes
Comandos Disponíveis
Configuração de MCP
Customização
Roadmap
Contribuindo
Créditos e Inspiração
Licença

🎯 O que é isso?

Agent OS Starter é um template que transforma qualquer projeto em um ambiente estruturado para trabalhar com agentes de IA (Claude Code, Cursor, etc.).

Problemas que resolve:

Problema	Solução
Claude não lembra das regras do projeto	`CLAUDE.md` carregado automaticamente
Padrões de código inconsistentes	`.agent-rules.md` e `.design-system.md`
Código antes de spec	OpenSpec força spec-before-code
Erros repetidos entre sessões	Skills = memória coletiva
Descobertas perdidas	`/retrospective` documenta automaticamente

Benefícios:

✅ Consistência: Mesmas regras em todas as sessões
✅ Memória: Lições aprendidas persistem
✅ Qualidade: Spec-driven development reduz retrabalho
✅ Onboarding: Novos devs/IAs já sabem as regras
✅ Evolução: Sistema aprende com cada sessão

🏗️ Arquitetura "A Quadra"

┌─────────────────────────────────────────────────────────────────────┐
│                    ARQUITETURA AGENT OS                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   OpenSpec   │  │  Agent OS    │  │  Design OS   │              │
│  │  O FUTURO    │  │  O PRESENTE  │  │  O PRESENTE  │              │
│  │  Contratos   │  │  Backend     │  │  Frontend    │              │
│  │  .openspec/  │  │.agent-rules  │  │.design-system│              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│                           │                                         │
│                           ▼                                         │
│              ┌────────────────────────┐                            │
│              │       CLAUDE.md        │                            │
│              │   🧠 System Prompt     │                            │
│              │   + Auto-Learning      │                            │
│              └────────────────────────┘                            │
│                           │                                         │
│                           ▼                                         │
│              ┌────────────────────────┐                            │
│              │   .claude/skills/      │                            │
│              │   📚 Memória Coletiva  │                            │
│              │   O PASSADO            │                            │
│              └────────────────────────┘                            │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Componente	Tempo	Função
OpenSpec	Futuro	O que VAMOS fazer (contratos)
Agent Rules	Presente	Como fazer BACKEND
Design System	Presente	Como fazer FRONTEND
CLAUDE.md	Sempre	Orquestrador + comportamento
Skills	Passado	O que APRENDEMOS

🚀 Quick Start

Opção 1: Usar como Template (Recomendado)

Clique em "Use this template" no GitHub
Clone seu novo repositório
Customize os arquivos para seu projeto

Opção 2: Clone Manual

# Clonar
git clone https://github.com/marcelokarval/agent-os-starter.git meu-projeto
cd meu-projeto

# Limpar git e reiniciar
rm -rf .git
git init

# Customizar arquivos (ver seção Customização)

Opção 3: Copiar para Projeto Existente

# De dentro do seu projeto existente
curl -L https://github.com/marcelokarval/agent-os-starter/archive/main.tar.gz | tar xz --strip-components=1

Pré-requisitos

# Instalar CLIs necessárias
npm install -g @fission-ai/openspec openspec-mcp

# Verificar Claude Code
claude --version

📁 Estrutura de Arquivos

agent-os-starter/
│
├── CLAUDE.md                    # 🧠 System Prompt principal
├── .agent-rules.md              # 📜 Regras de backend
├── .design-system.md            # 🎨 Regras de frontend
│
├── .openspec/                   # 📋 Spec-Driven Development
│   ├── README.md                # Guia do OpenSpec
│   ├── specs/                   # Specs aprovadas (source of truth)
│   │   └── README.md
│   └── changes/                 # Proposals em andamento
│       └── README.md
│
├── .claude/                     # 🤖 Configurações do Claude
│   ├── commands/                # Comandos customizados
│   │   ├── advise.md            # /advise - consultar skills
│   │   └── retrospective.md     # /retrospective - salvar lições
│   ├── skills/                  # 📚 Memória coletiva
│   │   ├── README.md            # Documentação do sistema
│   │   ├── backend/             # Skills de backend
│   │   ├── frontend/            # Skills de frontend
│   │   ├── devops/              # Skills de devops
│   │   └── integrations/        # Skills de integrações
│   ├── hooks/                   # Hooks (futuro)
│   └── ROADMAP.md               # Evolução do sistema
│
└── README.md                    # Este arquivo

📦 Componentes

1. CLAUDE.md - System Prompt

Localização: ./CLAUDE.md Função: Cérebro do sistema - define comportamento do agente

O que contém:

Seção	Descrição
Comportamento	Regras de como o agente deve agir (conciso, sem desculpas, etc.)
Auto-Learning	Comportamento proativo (auto-advise, auto-retrospective)
Ordem de Leitura	Quais arquivos ler antes de codificar
OpenSpec Workflow	Como usar spec-driven development
Vigilância	Reportar desvios de padrão
Anti-Patterns	O que NUNCA fazer
Stack	Tecnologias do projeto
Wireframes	Templates obrigatórios

Comportamento Proativo:

ANTES de tarefas:
- Detecta tipo (config, bug, integração)
- Consulta .claude/skills/ automaticamente
- Avisa armadilhas conhecidas

DEPOIS de tarefas:
- Detecta padrões de descoberta
- Sugere criar skill se relevante

Customização:

Atualize a seção "Stack Real" com suas tecnologias
Ajuste os anti-patterns para seu contexto
Modifique wireframes se necessário

2. .agent-rules.md - Backend OS

Localização: ./.agent-rules.md Função: Regras e padrões para desenvolvimento backend

O que contém:

Seção	Descrição
Stack Técnico	Python, Django, GraphQL, Celery, Redis, etc.
Herança de Models	BaseModel vs Mixins
Arquitetura	Models → Services → Tasks → Consumers
Regra 200 Linhas	Quando e como quebrar arquivos
TODOs	Formato com timestamps BRT
Validação	Comandos obrigatórios antes de PR
Segurança	IDOR, Race Conditions, etc.
Wireframes	Template de workflow tree

Exemplo de Regra:

# ❌ ERRADO: Business logic em Model
class Deal(BaseModel):
    def calculate_profit(self):
        # lógica aqui
        pass

# ✅ CORRETO: Business logic em Service
class DealService:
    @staticmethod
    def calculate_profit(deal: Deal) -> Decimal:
        # lógica aqui
        pass

Customização:

Ajuste a stack para suas tecnologias
Modifique regras de arquitetura conforme necessário
Atualize comandos de validação

3. .design-system.md - Frontend OS

Localização: ./.design-system.md Função: Regras e padrões para desenvolvimento frontend

O que contém:

Seção	Descrição
Stack Técnico	React, Vite, Apollo, Tailwind, etc.
Regra de Ouro	PROCURAR antes de criar componentes
Hierarquia	Atomic Design (ui → ui-enhanced → shared → features)
i18n	NUNCA hard-coded text
Sistema de Cores	Variáveis CSS do design system
Wireframes	Template visual + componentes

Hierarquia de Componentes:

Level 5: features/     (Páginas)
         ↑
Level 4: layout/       (Shell)
         ↑
Level 3: shared/       (Organismos)
         ↑
Level 2: ui-enhanced/  (Moléculas)
         ↑
Level 1: ui/           (Átomos)

Customização:

Ajuste a stack para suas tecnologias
Atualize o sistema de cores
Modifique a hierarquia se necessário

4. .openspec/ - Spec-Driven Development

Localização: ./.openspec/ Função: Workflow de especificação antes de código

Conceito:

"Corrigir texto (spec) é mais barato que corrigir código."

Workflow:

1. /openspec:proposal  → Criar spec ANTES de codificar
2. Revisar e aprovar   → Ajustar texto se necessário
3. /openspec:apply     → Implementar seguindo a spec
4. /openspec:archive   → Mover para specs/ (source of truth)

Estrutura:

.openspec/
├── README.md          # Guia de uso
├── specs/             # Specs aprovadas e implementadas
│   └── README.md      # Template de spec
└── changes/           # Proposals em andamento
    └── README.md      # Template de proposal

Configurar MCP:

# Instalar
npm install -g @fission-ai/openspec openspec-mcp

# Adicionar ao ~/.mcp.json
{
  "mcpServers": {
    "openspec": {
      "command": "openspec-mcp",
      "args": ["/caminho/do/seu/projeto"]
    }
  }
}

5. .claude/skills/ - Memória Coletiva

Localização: ./.claude/skills/ Função: Base de conhecimento persistente entre sessões

Conceito:

Baseado no artigo da Sionic AI sobre "Team Memory".

"Claude é inteligente, mas amnésico. Skills dão memória."

Estrutura de um Skill:

.claude/skills/backend/celery-gotchas/
├── SKILL.md          # Conhecimento documentado
└── plugin.json       # Triggers para ativação

SKILL.md Template:

---
name: celery-gotchas
description: |
  Problemas comuns com Celery. Use quando:
  (1) Tasks não executam
  (2) Erros de conexão
author: Seu Nome
date: 2026-01-08
tags: [celery, backend]
---

# Celery - Lições Aprendidas

## ✅ O Que Funcionou
...

## ❌ Tentativas que Falharam
| Tentativa | Por que Falhou | Lição |
|-----------|----------------|-------|
| ... | ... | ... |

## 🔧 Troubleshooting
...

plugin.json:

{
  "name": "celery-gotchas",
  "version": "1.0.0",
  "description": "Problemas comuns com Celery...",
  "triggers": ["celery", "task queue", "broker", "Connection reset"],
  "skills": "./SKILL.md"
}

🎮 Comandos Disponíveis

/advise

Função: Consultar memória coletiva ANTES de começar uma tarefa

/advise configurar celery com rabbitmq
/advise criar componente de tabela paginada
/advise integrar stripe webhooks

O que faz:

Busca skills relevantes em .claude/skills/
Apresenta lições aprendidas
Avisa sobre armadilhas conhecidas

/retrospective

Função: Salvar lições aprendidas DEPOIS de uma sessão

/retrospective
/retrospective backend celery-connection-fix

O que faz:

Analisa a sessão atual
Identifica descobertas importantes
Cria skill com SKILL.md + plugin.json
Sugere commit

/openspec:proposal

Função: Criar especificação antes de codificar

/openspec:proposal Adicionar autenticação Google

/openspec:apply

Função: Implementar spec aprovada

/openspec:apply auth-google

/openspec:archive

Função: Arquivar spec implementada

/openspec:archive auth-google

⚙️ Configuração de MCP

Pré-requisitos

npm install -g @fission-ai/openspec openspec-mcp

Configurar ~/.mcp.json

{
  "mcpServers": {
    "openspec": {
      "command": "openspec-mcp",
      "args": ["/caminho/absoluto/do/seu/projeto"]
    }
  }
}

Verificar Conexão

claude mcp list
# Deve mostrar: openspec: ... - ✓ Connected

🔧 Customização

Para Seu Projeto

CLAUDE.md
- Atualize a seção "Stack Real"
- Ajuste anti-patterns
- Modifique comportamento proativo se necessário
.agent-rules.md
- Troque stack técnico (Python/Django → Node/Express, etc.)
- Ajuste regras de arquitetura
- Atualize comandos de validação
.design-system.md
- Troque stack (React/Vite → Vue/Nuxt, etc.)
- Atualize sistema de cores
- Ajuste hierarquia de componentes
Skills
- Comece vazio, vá criando conforme descobre coisas
- Use /retrospective para criar automaticamente

Remover Componentes

Se não usar frontend:

rm .design-system.md
# Remova referências no CLAUDE.md

Se não usar spec-driven:

rm -rf .openspec
# Remova referências no CLAUDE.md

🗺️ Roadmap

O sistema de Auto-Learning evolui em fases:

Fase	Status	Descrição
Fase 1	✅ Implementado	CLAUDE.md proativo
Fase 2	🔜 Q1 2026	Hooks nativos do Claude Code
Fase 3	🔮 Q2 2026	MCP Server dedicado

Detalhes em .claude/ROADMAP.md.

🤝 Contribuindo

Contribuições são bem-vindas!

Fork o repositório
Crie uma branch (git checkout -b feature/minha-feature)
Commit suas mudanças (git commit -m 'Add: minha feature')
Push para a branch (git push origin feature/minha-feature)
Abra um Pull Request

Ideias de Contribuição

Templates para outras stacks (Node, Go, Rust)
Mais skills de exemplo
Integração com outros LLMs
Scripts de setup automatizado
Testes de validação

🙏 Créditos e Inspiração

Sionic AI - Claude Code Skills - Conceito de Team Memory
Piebald AI - System Prompts - Referência de prompts
OpenSpec - Fission AI - Spec-Driven Development
Anthropic - Claude Code - A ferramenta base

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.

📞 Contato

Autor: Marcelo Karval
GitHub: @marcelokarval

Feito com 🧠 para agentes de IA serem mais inteligentes.

Name		Name	Last commit message	Last commit date
.claude		.claude
.openspec		.openspec
.agent-rules.md		.agent-rules.md
.design-system.md		.design-system.md
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

🤖 Agent OS Starter

📋 Índice

🎯 O que é isso?

Problemas que resolve:

Benefícios:

🏗️ Arquitetura "A Quadra"

🚀 Quick Start

Opção 1: Usar como Template (Recomendado)

Opção 2: Clone Manual

Opção 3: Copiar para Projeto Existente

Pré-requisitos

📁 Estrutura de Arquivos

📦 Componentes

1. CLAUDE.md - System Prompt

O que contém:

Comportamento Proativo:

Customização:

2. .agent-rules.md - Backend OS

O que contém:

Exemplo de Regra:

Customização:

3. .design-system.md - Frontend OS

O que contém:

Hierarquia de Componentes:

Customização:

4. .openspec/ - Spec-Driven Development

Conceito:

Workflow:

Estrutura:

Configurar MCP:

5. .claude/skills/ - Memória Coletiva

Conceito:

Estrutura de um Skill:

SKILL.md Template:

plugin.json:

🎮 Comandos Disponíveis

/advise

/retrospective

/openspec:proposal

/openspec:apply

/openspec:archive

⚙️ Configuração de MCP

Pré-requisitos

Configurar ~/.mcp.json

Verificar Conexão

🔧 Customização

Para Seu Projeto

Remover Componentes

🗺️ Roadmap

🤝 Contribuindo

Ideias de Contribuição

🙏 Créditos e Inspiração

📄 Licença

📞 Contato

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors