# Contribuindo para o Everything Claude Code Obrigado por querer contribuir! Este repositório é um recurso comunitário para usuários do Claude Code. ## Índice - [O Que Estamos Buscando](#o-que-estamos-buscando) - [Início Rápido](#início-rápido) - [Contribuindo com Skills](#contribuindo-com-skills) - [Contribuindo com Agentes](#contribuindo-com-agentes) - [Contribuindo com Hooks](#contribuindo-com-hooks) - [Contribuindo com Comandos](#contribuindo-com-comandos) - [MCP e Documentação (ex: Context7)](#mcp-e-documentação-ex-context7) - [Multiplataforma e Traduções](#multiplataforma-e-traduções) - [Processo de Pull Request](#processo-de-pull-request) --- ## O Que Estamos Buscando ### Agentes Novos agentes que lidam bem com tarefas específicas: - Revisores específicos de linguagem (Python, Go, Rust) - Especialistas em frameworks (Django, Rails, Laravel, Spring) - Especialistas em DevOps (Kubernetes, Terraform, CI/CD) - Especialistas de domínio (pipelines de ML, engenharia de dados, mobile) ### Skills Definições de fluxo de trabalho e conhecimento de domínio: - Melhores práticas de linguagem - Padrões de frameworks - Estratégias de testes - Guias de arquitetura ### Hooks Automações úteis: - Hooks de lint/formatação - Verificações de segurança - Hooks de validação - Hooks de notificação ### Comandos Comandos slash que invocam fluxos de trabalho úteis: - Comandos de implantação - Comandos de teste - Comandos de geração de código --- ## Início Rápido ```bash # 1. Fork e clone gh repo fork affaan-m/everything-claude-code --clone cd everything-claude-code # 2. Criar uma branch git checkout -b feat/minha-contribuicao # 3. Adicionar sua contribuição (veja as seções abaixo) # 4. Testar localmente cp -r skills/minha-skill ~/.claude/skills/ # para skills # Em seguida teste com o Claude Code # 5. Enviar PR git add . && git commit -m "feat: adicionar minha-skill" && git push -u origin feat/minha-contribuicao ``` --- ## Contribuindo com Skills Skills são módulos de conhecimento que o Claude Code carrega baseado no contexto. ### Estrutura de Diretório ``` skills/ └── nome-da-sua-skill/ └── SKILL.md ``` ### Template SKILL.md ```markdown --- name: nome-da-sua-skill description: Breve descrição mostrada na lista de skills origin: ECC --- # Título da Sua Skill Breve visão geral do que esta skill cobre. ## Conceitos Principais Explique padrões e diretrizes chave. ## Exemplos de Código \`\`\`typescript // Inclua exemplos práticos e testados function exemplo() { // Código bem comentado } \`\`\` ## Melhores Práticas - Diretrizes acionáveis - O que fazer e o que não fazer - Armadilhas comuns a evitar ## Quando Usar Descreva cenários onde esta skill se aplica. ``` ### Checklist de Skill - [ ] Focada em um domínio/tecnologia - [ ] Inclui exemplos práticos de código - [ ] Abaixo de 500 linhas - [ ] Usa cabeçalhos de seção claros - [ ] Testada com o Claude Code ### Exemplos de Skills | Skill | Propósito | |-------|-----------| | `coding-standards/` | Padrões TypeScript/JavaScript | | `frontend-patterns/` | Melhores práticas React e Next.js | | `backend-patterns/` | Padrões de API e banco de dados | | `security-review/` | Checklist de segurança | --- ## Contribuindo com Agentes Agentes são assistentes especializados invocados via a ferramenta Task. ### Localização do Arquivo ``` agents/nome-do-seu-agente.md ``` ### Template de Agente ```markdown --- name: nome-do-seu-agente description: O que este agente faz e quando o Claude deve invocá-lo. Seja específico! tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"] model: sonnet --- Você é um especialista em [função]. ## Seu Papel - Responsabilidade principal - Responsabilidade secundária - O que você NÃO faz (limites) ## Fluxo de Trabalho ### Passo 1: Entender Como você aborda a tarefa. ### Passo 2: Executar Como você realiza o trabalho. ### Passo 3: Verificar Como você valida os resultados. ## Formato de Saída O que você retorna ao usuário. ## Exemplos ### Exemplo: [Cenário] Entrada: [o que o usuário fornece] Ação: [o que você faz] Saída: [o que você retorna] ``` ### Campos do Agente | Campo | Descrição | Opções | |-------|-----------|--------| | `name` | Minúsculas, com hifens | `code-reviewer` | | `description` | Usado para decidir quando invocar | Seja específico! | | `tools` | Apenas o que é necessário | `Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task` | | `model` | Nível de complexidade | `haiku` (simples), `sonnet` (codificação), `opus` (complexo) | ### Agentes de Exemplo | Agente | Propósito | |--------|-----------| | `tdd-guide.md` | Desenvolvimento orientado a testes | | `code-reviewer.md` | Revisão de código | | `security-reviewer.md` | Varredura de segurança | | `build-error-resolver.md` | Correção de erros de build | --- ## Contribuindo com Hooks Hooks são comportamentos automáticos disparados por eventos do Claude Code. ### Localização do Arquivo ``` hooks/hooks.json ``` ### Tipos de Hooks | Tipo | Gatilho | Caso de Uso | |------|---------|-------------| | `PreToolUse` | Antes da execução da ferramenta | Validar, avisar, bloquear | | `PostToolUse` | Após a execução da ferramenta | Formatar, verificar, notificar | | `SessionStart` | Sessão começa | Carregar contexto | | `Stop` | Sessão termina | Limpeza, auditoria | ### Formato de Hook ```json { "hooks": { "PreToolUse": [ { "matcher": "tool == \"Bash\" && tool_input.command matches \"rm -rf /\"", "hooks": [ { "type": "command", "command": "echo '[Hook] BLOQUEADO: Comando perigoso' && exit 1" } ], "description": "Bloquear comandos rm perigosos" } ] } } ``` ### Sintaxe de Matcher ```javascript // Corresponder ferramentas específicas tool == "Bash" tool == "Edit" tool == "Write" // Corresponder padrões de entrada tool_input.command matches "npm install" tool_input.file_path matches "\\.tsx?$" // Combinar condições tool == "Bash" && tool_input.command matches "git push" ``` ### Checklist de Hook - [ ] O matcher é específico (não excessivamente abrangente) - [ ] Inclui mensagens de erro/informação claras - [ ] Usa códigos de saída corretos (`exit 1` bloqueia, `exit 0` permite) - [ ] Testado exaustivamente - [ ] Tem descrição --- ## Contribuindo com Comandos Comandos são ações invocadas pelo usuário com `/nome-do-comando`. ### Localização do Arquivo ``` commands/seu-comando.md ``` ### Template de Comando ```markdown --- description: Breve descrição mostrada em /help --- # Nome do Comando ## Propósito O que este comando faz. ## Uso \`\`\` /seu-comando [args] \`\`\` ## Fluxo de Trabalho 1. Primeiro passo 2. Segundo passo 3. Passo final ## Saída O que o usuário recebe. ``` --- ## MCP e Documentação (ex: Context7) Skills e agentes podem usar ferramentas **MCP (Model Context Protocol)** para obter dados atualizados em vez de depender apenas de dados de treinamento. Isso é especialmente útil para documentação. - **Context7** é um servidor MCP que expõe `resolve-library-id` e `query-docs`. Use quando o usuário perguntar sobre bibliotecas, frameworks ou APIs para que as respostas reflitam a documentação atual. - Ao contribuir com **skills** que dependem de docs em tempo real, descreva como usar as ferramentas MCP relevantes. - Ao contribuir com **agentes** que respondem perguntas sobre docs/API, inclua os nomes das ferramentas MCP do Context7 nas ferramentas do agente. --- ## Multiplataforma e Traduções ### Subconjuntos de Skills (Codex e Cursor) O ECC vem com subconjuntos de skills para outros harnesses: - **Codex:** `.agents/skills/` — skills listadas em `agents/openai.yaml` são carregadas pelo Codex. - **Cursor:** `.cursor/skills/` — um subconjunto de skills é incluído para Cursor. Ao **adicionar uma nova skill** que deve estar disponível no Codex ou Cursor: 1. Adicione a skill em `skills/nome-da-sua-skill/` como de costume. 2. Se deve estar disponível no **Codex**, adicione-a em `.agents/skills/` e garanta que seja referenciada em `agents/openai.yaml` se necessário. 3. Se deve estar disponível no **Cursor**, adicione-a em `.cursor/skills/`. ### Traduções Traduções ficam em `docs/` (ex: `docs/zh-CN`, `docs/zh-TW`, `docs/ja-JP`, `docs/ko-KR`, `docs/pt-BR`). Se você alterar agentes, comandos ou skills que são traduzidos, considere atualizar os arquivos de tradução correspondentes ou abrir uma issue. --- ## Processo de Pull Request ### 1. Formato do Título do PR ``` feat(skills): adicionar skill rust-patterns feat(agents): adicionar agente api-designer feat(hooks): adicionar hook auto-format fix(skills): atualizar padrões React docs: melhorar guia de contribuição docs(pt-BR): adicionar tradução para português brasileiro ``` ### 2. Descrição do PR ```markdown ## Resumo O que você está adicionando e por quê. ## Tipo - [ ] Skill - [ ] Agente - [ ] Hook - [ ] Comando - [ ] Docs / Tradução ## Testes Como você testou isso. ## Checklist - [ ] Segue as diretrizes de formato - [ ] Testado com o Claude Code - [ ] Sem informações sensíveis (chaves de API, caminhos) - [ ] Descrições claras ``` ### 3. Processo de Revisão 1. Mantenedores revisam em até 48 horas 2. Abordar o feedback se solicitado 3. Uma vez aprovado, mesclado na main --- ## Diretrizes ### Faça - Mantenha as contribuições focadas e modulares - Inclua descrições claras - Teste antes de enviar - Siga os padrões existentes - Documente dependências ### Não Faça - Incluir dados sensíveis (chaves de API, tokens, caminhos) - Adicionar configurações excessivamente complexas ou de nicho - Enviar contribuições não testadas - Criar duplicatas de funcionalidade existente --- ## Nomenclatura de Arquivos - Use minúsculas com hifens: `python-reviewer.md` - Seja descritivo: `tdd-workflow.md` não `workflow.md` - Combine nome com nome do arquivo --- ## Dúvidas? - **Issues:** [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues) - **X/Twitter:** [@affaanmustafa](https://x.com/affaanmustafa) --- Obrigado por contribuir! Vamos construir um ótimo recurso juntos.