Claude Code: Separação Meta vs Domínio

⚠️ META-CONFIGURAÇÃO CRÍTICA Este skill trata da SEPARAÇÃO entre configurações DO Claude Code (meta) e configurações DE PROJETOS (domínio). Essencial para evitar conflitos.

---

🎯 Problema a Resolver

Cenário de Conflito

Quando você tem:

1. Meta-repositório (/workspace/claude-code):

   • Base de conhecimento SOBRE Claude Code
   • Skills para CONFIGURAR Claude Code
   • Templates para APLICAR em projetos

2. Projeto-alvo (/workspace/meu-projeto):

   • Implementação de funcionalidades
   • Skills DE DOMÍNIO (ex: authentication, API)
   • Pode usar SDKs agênticos (Google ADK, LangChain)

Problema: Ambos usam terminologia similar:

• "agent", "skill", "command", "hook"
• Mas significados DIFERENTES

Resultado sem separação:

• 🔴 Claude confunde "agent do Claude Code" com "agent do projeto"
• 🔴 Skills de meta ativam quando devia ativar skills de domínio
• 🔴 Commands conflitam (ex: /setup - setup de quê?)
• 🔴 Hooks executam no contexto errado

---

🏗️ Arquitetura de Separação

Princípio Fundamental

META-CONFIGURAÇÃO          ≠          CONFIGURAÇÃO DE DOMÍNIO
(Sobre a ferramenta)                  (Sobre o projeto)

Target: Claude Code                   Target: Funcionalidades
Prefixo: cc-                          Prefixo: <projeto>-
Escopo: meta-configuration            Escopo: domain-implementation
Keywords: claude-code, tool, meta     Keywords: application, feature, app

Visualização da Separação

┌─────────────────────────────────────────────────────────────┐
│  Meta-Repositório: /workspace/claude-code                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ .claude/                                               │ │
│  │ ├── skills/                                            │ │
│  │ │   ├── cc-overview/           ← Sobre Claude Code   │ │
│  │ │   ├── cc-hooks-guide/        ← Sobre Claude Code   │ │
│  │ │   └── cc-separation-guide/   ← Sobre Claude Code   │ │
│  │ ├── commands/                                          │ │
│  │ │   ├── cc-setup.md            ← Setup do Claude Code │ │
│  │ │   └── cc-diagnose.md                                │ │
│  │ └── CLAUDE.md                  ← Diretrizes META      │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

                              ≠

┌─────────────────────────────────────────────────────────────┐
│  Projeto: /workspace/meu-app                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ .claude/                                               │ │
│  │ ├── skills/                                            │ │
│  │ │   ├── app-auth-agent/        ← Autenticação da app │ │
│  │ │   ├── app-api-setup/         ← API da app          │ │
│  │ │   └── app-deploy/            ← Deploy da app       │ │
│  │ ├── commands/                                          │ │
│  │ │   ├── app-setup.md           ← Setup da APP        │ │
│  │ │   └── app-test.md            ← Testes da app       │ │
│  │ └── CLAUDE.md                  ← Diretrizes PROJETO  │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

---

📐 Convenções de Nomenclatura

Regra de Ouro

SE artefato é SOBRE Claude Code → prefixo cc-
SE artefato é SOBRE projeto → prefixo do projeto
NUNCA usar nomes genéricos sem prefixo

Tabela de Prefixos

Contexto	Prefixo	Exemplo Skill	Exemplo Command
Meta (Claude Code)	cc-	cc-hooks-guide	cc-setup.md
Projeto Web	app-	app-auth-setup	app-deploy.md
Backend API	api-	api-endpoints	api-test.md
Microserviço	svc-	svc-payments	svc-deploy.md
SDK Agêntico	<sdk>-	cva-agent-types	cva-new-agent.md

Exemplos Corretos vs Incorretos

Skills

✅ Correto	❌ Incorreto	Problema
cc-hooks-setup	hooks-setup	Ambíguo (hooks de quê?)
app-auth-flow	auth-flow	Conflita com auth do Claude Code
cva-healthcare-pipeline	healthcare-pipeline	Sem namespace, genérico

Commands

✅ Correto	❌ Incorreto	Problema
/cc:setup	/setup	Conflita com setup de projeto
/app:deploy	/deploy	Ambíguo (deploy de quê?)
/api:test	/test	Genérico demais

Hooks

✅ Correto	❌ Incorreto	Problema
cc-posttool-format.sh	format.sh	Não indica contexto
app-posttool-lint.sh	lint.sh	Pode conflitar

---

📝 Declaração Explícita de Escopo

YAML Frontmatter Obrigatório

Toda skill DEVE declarar seu escopo no frontmatter:

Meta-Skill (Claude Code)

---
name: cc-hooks-guide
scope: meta-configuration              # ← OBRIGATÓRIO
target: claude-code-itself             # ← O QUE configura
description: Complete guide to Claude Code hooks. This is about CONFIGURING the Claude Code TOOL itself, not project code.
keywords: claude-code, cc-hooks, meta-configuration, tool-configuration, automation
allowed-tools: Read,Edit,Write
---

# Claude Code Hooks Guide

> **⚠️ META-CONFIGURAÇÃO**
> Este skill configura o PRÓPRIO Claude Code, não código de projeto.

Domain-Skill (Projeto)

---
name: app-auth-setup
scope: domain-implementation           # ← OBRIGATÓRIO
target: application-feature            # ← O QUE implementa
description: Authentication setup for the application using OAuth2 and JWT. This is about APPLICATION functionality, not Claude Code configuration.
keywords: application, app-auth, authentication, oauth2, jwt, security
allowed-tools: Read,Edit,Write,Bash
---

# Application Authentication Setup

> **🎯 FUNCIONALIDADE DO PROJETO**
> Este skill implementa autenticação na aplicação, não configura Claude Code.

Campos Obrigatórios

Campo	Meta	Domínio	Propósito
scope	meta-configuration	domain-implementation	Identifica escopo
target	claude-code-itself	application-feature	Identifica alvo
description	Deve incluir "Claude Code" e "tool"	Deve incluir nome do projeto/feature	Auto-discovery
keywords	Incluir claude-code, cc-*, meta	Incluir nome do projeto, features	Evitar sobreposição

---

🧭 Hierarquia CLAUDE.md

Estrutura de Precedência

~/.claude/CLAUDE.md                    # Nível 1: Global
    ↓  (princípios universais de desenvolvimento)

/workspace/claude-code/CLAUDE.md       # Nível 2: Meta
    ↓  (diretrizes de configuração do Claude Code)

/workspace/meu-projeto/CLAUDE.md       # Nível 3: Projeto
    ↓  (diretrizes específicas do projeto)

Regra de Precedência:

Projeto (mais específico) > Meta > Global (mais genérico)

Conteúdo de Cada CLAUDE.md

Global (~/.claude/CLAUDE.md)

# CLAUDE.md - Diretrizes Globais

> **Escopo:** Todos os projetos
> **Foco:** Princípios universais de desenvolvimento

## Conteúdo

- Princípios de execução autônoma
- Gestão de dependências
- Versionamento (SemVer)
- CI/CD patterns
- Quality gates
- Observabilidade

**Aplicável a:** Qualquer projeto, qualquer linguagem

Meta (/workspace/claude-code/CLAUDE.md)

# CLAUDE.md - Meta-Configuração Claude Code

> **Escopo:** Configuração do Claude Code
> **Foco:** Como configurar a ferramenta

## Conteúdo

- Separação meta vs domínio
- Prefixos obrigatórios (cc-)
- Estrutura de skills/commands/hooks
- Convenções de nomenclatura
- Templates para projetos

**Aplicável a:** Configuração do Claude Code em qualquer projeto

Projeto (/workspace/meu-projeto/CLAUDE.md)

# CLAUDE.md - Projeto [Nome]

> **Escopo:** Desenvolvimento do projeto [Nome]
> **Prefixo:** `app-`

## Conteúdo

- Arquitetura do projeto
- Convenções específicas (app- prefix)
- Workflows de desenvolvimento
- Testing strategies
- Deployment procedures

**Herda de:** `/workspace/claude-code/CLAUDE.md` (meta-config)
**Sobrescreve:** Diretrizes conflitantes (precedência)

---

🔍 Detecção de Contexto

Checklist de Verificação

Claude deve SEMPRE verificar antes de executar tarefas:

1. Qual diretório estou?

pwd
# /workspace/claude-code        → Contexto META
# /workspace/meu-projeto        → Contexto PROJETO

2. Qual CLAUDE.md tem precedência?

if exists("/workspace/meu-projeto/CLAUDE.md"):
    context = "project"
    prefix = extract_prefix_from_claudemd()  # ex: "app-"
elif exists("/workspace/claude-code/CLAUDE.md"):
    context = "meta"
    prefix = "cc-"
else:
    context = "global"
    prefix = None  # use generic

3. Prefixo esperado?

Contexto META → cc-
Contexto PROJETO → <projeto>- (extrair de CLAUDE.md)

4. Keywords evitam conflito?

# META
keywords: claude-code, cc-*, tool-*, meta-configuration

# PROJETO
keywords: application, app-*, feature-*, business-logic

# ✅ Zero sobreposição

---

🎭 Resolução de Ambiguidades

Cenário 1: Pergunta Sobre "Agent"

Pergunta ambígua:

"Como configuro um agent?"

Claude detecta ambiguidade:

# Verificar contexto
pwd = get_current_directory()

if "claude-code" in pwd:
    # Contexto meta
    likely_meaning = "Claude Code agent (autonomous AI)"
    relevant_skill = "cc-agent-config"
else:
    # Contexto projeto
    likely_meaning = "Domain agent (LLM agent, workflow agent)"
    relevant_skill = "app-agent-setup"  # ou similar

# Se não houver certeza (keywords ambíguas), PERGUNTAR

Claude pergunta ao usuário:

🤔 Preciso clarificar o contexto da sua pergunta:

Você quer:

A) **Configurar Claude Code** (o agente autônomo da Anthropic)?
   → Contexto: Meta-configuração
   → Skill relevante: cc-agent-config
   → Exemplo: Configurar comportamento, permissões, output style

B) **Criar/configurar um agente de domínio** no seu projeto?
   → Contexto: Implementação de projeto
   → Skill relevante: app-agent-setup
   → Exemplo: Agente LLM, workflow agent, microserviço

Qual dos dois?

Cenário 2: Auto-Discovery Correto

Usuário em /workspace/claude-code

Pergunta: "Como adiciono hooks?"

Claude detecta:
  - pwd: /workspace/claude-code
  - CLAUDE.md: Meta-configuração
  - Prefixo esperado: cc-

Claude busca skills:
  - Match: cc-hooks-guide
  - Keywords: claude-code, hooks, tool-configuration, meta

Claude ativa: cc-hooks-guide
Claude responde: "Hooks do Claude Code (SessionStart, PostToolUse, etc.)"

Usuário em /workspace/meu-app

Pergunta: "Como adiciono hooks?"

Claude detecta:
  - pwd: /workspace/meu-app
  - CLAUDE.md: Projeto (prefixo app-)
  - Prefixo esperado: app-

Claude busca skills:
  - Match: app-hooks-workflow (se existir)
  - Keywords: application, webhooks, event-handlers

Se skill existe:
  Claude ativa: app-hooks-workflow
  Claude responde: "Hooks da aplicação (webhooks, lifecycle events)"

Se skill NÃO existe:
  Claude pergunta: "Você quer configurar hooks do Claude Code ou implementar hooks na aplicação?"

Cenário 3: Command Conflitante

Comando: /setup

# Verificar contexto
pwd = get_current_directory()

if "claude-code" in pwd:
    # Buscar /cc:setup ou cc-setup.md
    execute_command("cc-setup")
else:
    # Buscar /<projeto>:setup ou <projeto>-setup.md
    project_prefix = extract_prefix()
    execute_command(f"{project_prefix}-setup")

# Se comando não existe, sugerir criar com prefixo

---

📊 Matriz de Conflitos Comuns

Termo Ambíguo	Contexto Meta	Contexto Projeto
agent	Claude Code (IA autônoma)	Agente de domínio (LLM, workflow)
skill	Claude Code skill (SKILL.md)	Agent skill (capability, function)
hook	Claude Code lifecycle hook	Webhook, event handler
command	Slash command do Claude Code	CLI command, API endpoint
tool	Claude Code tool (Read, Write)	External tool (API client, lib)
setup	Setup do Claude Code	Setup do projeto/ambiente
config	Claude Code config (settings.json)	App config (env vars, config files)

Como Disambiguar

1. Usar qualificadores:

   "Claude Code hook" vs "application hook"
   "Claude Code agent" vs "domain agent"
   "Claude Code skill" vs "agent skill"
   

2. Verificar prefixo:

   cc-hook-setup     → META (Claude Code)
   app-hook-handler  → DOMÍNIO (Application)
   

3. Verificar keywords:

   # Meta
   keywords: claude-code, tool, meta, cc-*
   
   # Domínio
   keywords: application, feature, app-*, business
   

4. Perguntar quando incerto:

   Claude: "Para clarificar: você está perguntando sobre
           configuração do Claude Code ou implementação do projeto?"
   

---

🛠️ Aplicação em Novos Projetos

Template: Novo Projeto

Passo 1: NÃO Copiar Meta-Repo Inteiro

# ❌ ERRADO
cp -r /workspace/claude-code/.claude /workspace/novo-projeto/

# ✅ CORRETO (copiar apenas templates)
mkdir -p /workspace/novo-projeto/.claude
cp -r /workspace/claude-code/.claude/templates/* \
      /workspace/novo-projeto/.claude/

Por quê?

• Meta-repo tem skills SOBRE Claude Code
• Projeto precisa de skills SOBRE funcionalidades
• Copiar tudo = conflito garantido

Passo 2: Adaptar Prefixos

cd /workspace/novo-projeto/.claude

# Substituir todos os cc- pelo prefixo do projeto
PROJECT_PREFIX="myapp"

# Skills
find skills/ -type f -name "*.md" -exec sed -i "s/cc-/${PROJECT_PREFIX}-/g" {} +

# Commands
find commands/ -type f -name "*.md" -exec sed -i "s/cc-/${PROJECT_PREFIX}-/g" {} +

# Hooks
find hooks/ -type f -exec sed -i "s/cc-/${PROJECT_PREFIX}-/g" {} +

# Renomear arquivos/diretórios
for dir in skills/cc-*; do
  mv "$dir" "${dir/cc-/${PROJECT_PREFIX}-}"
done

Passo 3: Criar CLAUDE.md do Projeto

cat > /workspace/novo-projeto/CLAUDE.md <<'EOF'
# CLAUDE.md - Projeto [Nome]

> **📍 ESCOPO:** Desenvolvimento do projeto [Nome]
> **🎯 PREFIXO:** `myapp-` (para skills, commands, hooks)
> **📅 Criado:** $(date +%Y-%m-%d)

---

## 🎯 Visão Geral

Este projeto implementa [descrição].

## 📐 Convenções

### Nomenclatura
- **Prefixo obrigatório:** `myapp-`
- **Escopo:** domain-implementation
- **Target:** application-feature

### Skills
- `myapp-overview` - Visão geral do projeto
- `myapp-auth` - Autenticação
- `myapp-api` - Endpoints da API
- `myapp-deploy` - Deploy

### Commands
- `/myapp:setup` - Setup do ambiente
- `/myapp:test` - Executar testes
- `/myapp:deploy` - Deploy para produção

---

**Meta-configuração herdada de:**
`/home/notebook/workspace/claude-code/CLAUDE.md`

**Documentação de referência:**
`/home/notebook/workspace/claude-code/ARCHITECTURE_ANALYSIS.md`
EOF

Passo 4: Atualizar Frontmatter das Skills

# Template do meta-repo (claude-code)
---
name: cc-exemplo
scope: meta-configuration
target: claude-code-itself
description: Configure Claude Code hooks
keywords: claude-code, cc-exemplo, meta, tool-configuration
---

↓ TRANSFORMAR EM ↓

# Skill do projeto (novo-projeto)
---
name: myapp-exemplo
scope: domain-implementation         # ← Mudou
target: application-feature          # ← Mudou
description: Configure application webhooks for real-time notifications
keywords: application, myapp-exemplo, webhooks, notifications, app-feature  # ← Mudou
---

Passo 5: Validar Separação

# Checklist de validação
./scripts/validate-separation.sh

# Saída esperada:
# ✅ Todos os skills têm prefixo myapp-
# ✅ Todos os commands têm prefixo myapp-
# ✅ CLAUDE.md declara escopo: domain-implementation
# ✅ Keywords não sobrepõem com meta-keywords
# ✅ Nenhum cc- permaneceu (exceto em referências)

---

✅ Checklist de Validação

Antes de Commitar no Meta-Repo

• Todos os skills têm prefixo cc-
• Todos os commands têm prefixo cc-
• Todos os hooks têm prefixo cc-
• CLAUDE.md declara scope: meta-configuration
• Skills têm scope: meta-configuration em YAML
• Skills têm target: claude-code-itself em YAML
• Keywords incluem claude-code, cc-*, meta-configuration
• Nenhuma keyword genérica que possa conflitar
• Documentação inline indica "META-CONFIGURAÇÃO"

Antes de Aplicar em Projeto

• Copiei apenas templates, NÃO estrutura completa
• Substituí TODOS os cc- pelo prefixo do projeto
• Criei CLAUDE.md específico do projeto
• Atualizei frontmatter: scope: domain-implementation
• Atualizei frontmatter: target: application-feature
• Substituí keywords meta por keywords de domínio
• Validei que nenhum cc- permaneceu
• Executei script de validação de separação
• Documentei link para meta-repo no CLAUDE.md

---

🎓 Exemplos Práticos

Exemplo 1: Projeto com Google ADK

Problema: Google ADK usa "agents" → conflito com "agent" do Claude Code

Solução:

# Meta-skill (claude-code)
---
name: cc-agent-config
keywords: claude-code, autonomous-ai, claude-agent, tool-agent
description: Configure Claude Code autonomous agent behavior
---

# Project-skill (google-adk-project)
---
name: cva-agent-types
keywords: google-adk, llm-agents, sequential-agents, parallel-agents
description: Google ADK agent types (LLM, Sequential, Parallel)
---

Resultado: Zero sobreposição de keywords = zero conflito

Exemplo 2: Projeto com LangChain

Problema: LangChain usa "tools" → conflito com "tools" do Claude Code

Solução:

# Meta-skill
---
name: cc-tools-reference
keywords: claude-code-tools, read-tool, write-tool, bash-tool
description: Claude Code built-in tools (Read, Write, Edit, Bash)
---

# Project-skill
---
name: lc-tools-integration
keywords: langchain-tools, external-apis, tool-calling, function-calling
description: LangChain tool integration with external APIs
---

Exemplo 3: Microserviços com Múltiplos Repos

Estrutura:

workspace/
├── claude-code/              # Meta-repo (cc-)
├── payment-service/          # Serviço 1 (pay-)
├── auth-service/             # Serviço 2 (auth-)
└── notification-service/     # Serviço 3 (notif-)

Prefixos únicos:

• Meta: cc-
• Payment: pay-
• Auth: auth-
• Notification: notif-

Resultado: Cada repo tem namespace isolado

---

🔧 Ferramentas de Validação

Script: validate-separation.sh

#!/bin/bash
# Valida separação de escopo

# Detectar contexto
if [[ "$PWD" == *"claude-code"* ]]; then
  CONTEXT="meta"
  EXPECTED_PREFIX="cc-"
else
  CONTEXT="domain"
  EXPECTED_PREFIX=$(grep "PREFIXO:" CLAUDE.md 2>/dev/null | grep -oP '`\K[^`]+' || echo "UNKNOWN")
fi

echo "🔍 Validando separação de escopo..."
echo "📍 Contexto: $CONTEXT"
echo "🏷️  Prefixo esperado: $EXPECTED_PREFIX"

# Validar skills
echo ""
echo "📦 Validando skills..."
ERRORS=0

for skill in .claude/skills/*/SKILL.md; do
  SKILL_NAME=$(basename "$(dirname "$skill")")

  # Verificar prefixo
  if [[ "$SKILL_NAME" != $EXPECTED_PREFIX* ]]; then
    echo "❌ $SKILL_NAME (deveria começar com $EXPECTED_PREFIX)"
    ((ERRORS++))
  else
    # Verificar frontmatter
    SCOPE=$(grep "^scope:" "$skill" | cut -d':' -f2 | xargs)
    TARGET=$(grep "^target:" "$skill" | cut -d':' -f2 | xargs)

    if [[ "$CONTEXT" == "meta" ]]; then
      if [[ "$SCOPE" != "meta-configuration" ]]; then
        echo "⚠️  $SKILL_NAME: scope deveria ser 'meta-configuration', não '$SCOPE'"
      fi
      if [[ "$TARGET" != "claude-code-itself" ]]; then
        echo "⚠️  $SKILL_NAME: target deveria ser 'claude-code-itself', não '$TARGET'"
      fi
    fi

    echo "✅ $SKILL_NAME"
  fi
done

if [[ $ERRORS -gt 0 ]]; then
  echo ""
  echo "❌ $ERRORS erro(s) encontrado(s)"
  exit 1
else
  echo ""
  echo "✅ Validação concluída com sucesso!"
  exit 0
fi

---

📚 Recursos Adicionais

Documentação Relacionada

• ARCHITECTURE_ANALYSIS.md - Análise detalhada de riscos
• CLAUDE.md - Diretrizes completas do meta-repo
• cc-overview - Overview do Claude Code
• cc-hooks-guide - Guia de hooks
• cc-skills-guide - Guia de skills

Links Externos

• Claude Code Documentation
• Skills Best Practices
• Naming Conventions

---

🎯 Próximo Passo:

Aplicar estas diretrizes ao criar qualquer configuração nova:

1. Identificar contexto (meta ou domínio)
2. Usar prefixo correto
3. Declarar escopo no frontmatter
4. Validar separação com script
5. Documentar no CLAUDE.md

---

Última atualização: 2025-10-30 Versão: 1.0.0