shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

cc-separation-guide

Complete guide for separating meta-configurations (Claude Code tool configuration) from domain configurations (project implementation). Learn how to avoid conflicts when working with multiple projects, especially those using agent SDKs/ADKs like Google ADK, LangChain, or Anthropic SDK. Covers namespace isolation, prefixing conventions, CLAUDE.md hierarchy, scope declaration, and conflict detection strategies.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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

🎯 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