📁 Por que pastas viram fronteiras
Em sistemas Unix, as permissões de arquivo são a ACL mais antiga e confiável da computação. Na era agêntica, o mesmo princípio se aplica: a estrutura de pastas é a primeira linha de controle de acesso do agente. Quando você define que "em /clinical/* aplique regra X" e "em /billing/* aplique regra Y", você está usando o filesystem como mecanismo de enforcement — não como convenção, mas como arquitetura.
🏗️ Filesystem como ACL
- •Fronteiras físicas — pastas separadas = domínios separados. Não é soft policy.
- •CLAUDE.md local — cada pasta pode ter seu próprio arquivo de regras.
- •Settings.json — allowlist/denylist por padrão de path (glob syntax).
- •Regras no CLAUDE.md raiz — "NEVER leia /secrets/", "ONLY edite /src/*".
💡 Princípio fundamental
Segurança por arquitetura é mais robusta que segurança por instrução. "Nunca leia /secrets/" no CLAUDE.md é mais frágil que uma permissão de filesystem que fisicamente impede o acesso. Use as duas camadas.
🩺 Caso da Dra. Sana
A Dra. Sana é dermatologista com clínica própria. Ela usa agentes para apoio clínico e administrativo. O desafio: dados clínicos (PHI — Protected Health Information) e dados administrativos (billing, agendamento) precisam ser tratados de formas radicalmente diferentes. A solução foi path scoping: dois domínios, dois agentes, uma ponte controlada.
Arquitetura da clínica da Dra. Sana
- /data/clinical/ — prontuários, diagnósticos, exames. PHI. Agente clínico só lê. Zero escrita sem confirmação.
- /data/billing/ — faturas, seguros, pagamentos. Admin. Agente billing tem acesso total aqui.
- /data/clinical/CLAUDE.md — "NUNCA exporte dados desta pasta. Nunca envie por email. Log toda leitura."
- /data/billing/CLAUDE.md — "NUNCA acesse /data/clinical/. Use apenas IDs anonimizados para cruzamento."
- Ponte controlada — script auditado que extrai dados mínimos necessários, com log e aprovação.
⚠️ Sem path scoping — o risco
Sem fronteiras explícitas, o agente de billing poderia, em algum contexto de tarefa, acabar lendo prontuários de pacientes para "entender melhor o contexto". HIPAA não aceita "foi sem querer". A penalidade começa em $100 por registro vazado.
📂 Estrutura de pastas para escopo
A convenção de pastas não é decoração — é a base física do escopo. Quando todas as equipes concordam que /data/<domínio>/ significa "dados desse domínio específico", o path scoping funciona. Quando as pastas são nomeadas aleatoriamente, o escopo não tem onde se apoiar. Convenção é metade da segurança.
Convenção mínima recomendada
/data/<domínio>/— dados por área de negócio (clinical, billing, marketing)./resumos/<área>/— Silver Platters e contexto por domínio./agentes/<nome>/— CLAUDE.md e configuração de cada agente especializado./skills/— slash commands compartilhados entre agentes./logs/— audit trail, sessões, decisões. Read-only para agentes./secrets/— jamais acessível por agente. Permissão de filesystem.
Sally — escritório jurídico
Sally separou /cases/<cliente>/ por cliente. O agente de pesquisa jurídica só tem acesso ao /cases/cliente-ativo/ da sessão corrente. Nunca vê os casos de outros clientes. Privilege attorney-client preservado por arquitetura.
🚫 Regras de proibição por path
As allow lists e deny lists no CLAUDE.md e no settings.json são o mecanismo declarativo de path scoping. Você especifica exatamente o que o agente pode fazer e o que ele nunca pode fazer, com granularidade de pasta, arquivo e operação. É simples de escrever e poderoso na prática.
Exemplos de regras por path
- NEVER read /secrets/
- NEVER write outside /src/ without approval
- ONLY edit files matching /docs/**/*.md
- NEVER delete files in /data/
- ALWAYS log reads from /data/clinical/
- NEVER send contents of /data/* externally
No settings.json
Use a chave permissions com padrões glob. Ex: "Read(data/clinical/*)" na deny list bloqueia leitura nesse path.
No CLAUDE.md
Regras em linguagem natural na seção "Regras Inegociáveis". O agente lê e aplica. Mais flexível, menos enforcement duro.
🛂 CLAUDE.md por subpasta
O recurso mais poderoso do path scoping é colocar um CLAUDE.md dentro de uma subpasta específica. Esse arquivo é lido apenas quando o agente está trabalhando dentro daquela pasta — ou seja, as regras se ativam automaticamente pelo contexto de localização. Override granular sem inflar o CLAUDE.md raiz.
Como funciona na prática
- /projeto/CLAUDE.md — regras gerais do projeto. Sempre ativo.
- /projeto/data/clinical/CLAUDE.md — ativo apenas quando trabalhando em /data/clinical/.
- /projeto/src/api/CLAUDE.md — ativo apenas quando editando código da API.
- Regras específicas de domínio ficam no CLAUDE.md da subpasta; não poluem o raiz.
💡 Padrão recomendado — Dra. Sana
O /data/clinical/CLAUDE.md da Dra. Sana contém: "Você está trabalhando com PHI. Toda leitura deve ser logada. Nunca copie dados para fora desta pasta. Nunca mencione nome de paciente em conversas não auditadas." Essas 4 regras só existem nessa pasta — não pesam nas outras sessões.
✅ Validação cruzada
Domínios isolados às vezes precisam se comunicar — é inevitável. O billing da Dra. Sana precisa saber se um procedimento foi realizado para faturar. A solução não é abrir os domínios, mas criar uma ponte controlada: um processo explícito, auditado e com aprovação humana que permite o cruzamento mínimo necessário.
Arquitetura de ponte controlada
- 1. Identificar o mínimo necessário — qual dado exatamente precisa cruzar? Apenas ID + status?
- 2. Script de extração auditado — código revisado que extrai só o necessário, sem raw PHI.
- 3. Aprovação humana — o hook de cruzamento requer confirmação explícita.
- 4. Log imutável — registro de quem autorizou, quando, qual dado cruzou.
- 5. Dado anonimizado — o lado billing recebe ID interno, não nome ou prontuário.
⚠️ Anti-padrão
Criar um agente "super-admin" com acesso a todos os domínios para "facilitar" o cruzamento. Esse agente é o ponto de falha mais crítico do sistema. Se comprometido, todos os domínios vazam. Pontualidade compensa o overhead da ponte.
📋 Resumo do Módulo
Próximo Módulo:
2.4 — Permissões e jurisdição de agente