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

cc-

cc-hooks-guide

cc-setup.md

app-

app-auth-setup

app-deploy.md

api-

api-endpoints

api-test.md

svc-

svc-payments

svc-deploy.md

<sdk>-

cva-agent-types

cva-new-agent.md

Exemplos Corretos vs Incorretos

Skills

cc-hooks-setup

hooks-setup

app-auth-flow

auth-flow

cva-healthcare-pipeline

healthcare-pipeline

Commands

/cc:setup

/setup

/app:deploy

/deploy

/api:test

/test

Hooks

cc-posttool-format.sh

format.sh

app-posttool-lint.sh

lint.sh

📝 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

scope

meta-configuration

domain-implementation

target

claude-code-itself

application-feature

description

keywords

claude-code

cc-*

meta

🧭 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

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