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

┌─────────────────────────────────────────────────────────────┐
│  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  │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

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

---
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.

---
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.

~/.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)

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

# 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

# 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

# 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)

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

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

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

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

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

# ✅ Zero sobreposição

"Como configuro um agent?"

# 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

🤔 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?

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.)"

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?"

# 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

# ❌ 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/

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

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

# 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
---

# 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)

# 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)
---

# 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
---

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

#!/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