Para documentar dependências entre contas em integrações de inteligência artificial, registre quem utiliza a aplicação, qual identidade autoriza cada conexão, quais recursos ela alcança e o que deixa de funcionar se essa autorização for removida. O documento deve permitir que outra pessoa investigue uma falha ou substitua um responsável sem depender da memória de quem configurou o fluxo.
A ficha precisa distinguir conta humana, organização, aplicação, credencial e recurso. Esses elementos podem pertencer a pessoas e empresas diferentes. As recomendações abaixo formam um método de documentação operacional; não representam uma função automática de inventário oferecida pelo Claude ou por qualquer outro assistente. Para entender o contexto de conexões com esse produto, consulte a página de integrações do Claude.
Resumo rápido
- Desenhe o caminho da conta que inicia o fluxo até o recurso final.
- Separe identidade humana, aplicação e credencial técnica.
- Registre permissões, proprietário, substituto e evidência de conferência.
- Documente referências a segredos, sem copiar seus valores.
- Teste revogação, troca de responsável e recuperação em ambiente controlado.
Comece pelo fluxo de trabalho
Descrever apenas “Claude conectado ao sistema de vendas” deixa muitas perguntas abertas. Quem adicionou o conector? Quem autorizou o serviço de vendas? A conexão usa o acesso individual do vendedor ou uma credencial compartilhada? Qual conta possui a pasta onde os documentos são gravados? Cada resposta revela uma dependência que pode afetar continuidade e acesso.
Escolha uma tarefa concreta, como preparar uma proposta a partir de um pedido. Acompanhe o caminho completo: usuário no assistente, conector, servidor intermediário, sistema de pedidos e armazenamento do arquivo. Se o fluxo ainda envia um aviso, acrescente o serviço de mensagens e o destinatário. Documentar a partir da tarefa evita um inventário extenso sem relação com o que realmente funciona.
Para cada etapa, descreva a ação esperada e a consequência de falha. “Ler o pedido aprovado” é mais útil do que “acessar API”. “Sem essa autorização, propostas novas ficam suspensas; propostas antigas continuam disponíveis na pasta” explica o impacto operacional. Essa descrição permite priorizar a recuperação e impede que uma falha parcial seja tratada como perda de todo o processo.
Use identificadores estáveis sempre que estiverem disponíveis. Um endereço de e-mail pode mudar; um nome de exibição pode ser repetido. Combine o identificador da organização ou recurso com uma descrição legível e a data da verificação. Registre o ambiente, pois a mesma pessoa pode autorizar uma conta de teste e outra operacional.
Separe as identidades e suas responsabilidades
Conta humana representa uma pessoa. Organização ou espaço de trabalho define uma fronteira administrativa. Aplicação identifica o software que solicita acesso. Credencial demonstra uma autorização técnica. Recurso é o objeto alcançado, como pasta, calendário ou base. Quando tudo aparece no documento como “conta da integração”, a equipe não sabe qual elemento precisa ser alterado.
A documentação de conectores personalizados do Claude distingue conexões individuais e o uso de credenciais compartilhadas. Uma credencial compartilhada exige atenção ao alcance concedido a quem usa o conector. Registre explicitamente o modelo adotado, sem deduzir o isolamento apenas porque cada funcionário entra com seu próprio usuário no assistente.
Defina três responsabilidades: quem responde pelo processo de negócio, quem administra a conexão e quem administra o recurso de destino. Uma pessoa pode acumular funções, mas elas devem continuar identificáveis. Acrescente um substituto autorizado e um canal interno para acionar o suporte. Não registre códigos de recuperação de conta no inventário distribuído à equipe.
Para fluxos que envolvem permissões em equipes, o artigo sobre permissões de conectores do Claude ajuda a orientar a conferência. A ficha de dependências deve apontar para a evidência da configuração efetiva e informar quem fez a revisão. O documento não deve prometer uma permissão que ainda não foi testada.
Monte uma ficha que permita investigar
Uma tabela simples pode funcionar para uma pequena operação. Use uma linha por relação de acesso, não necessariamente uma linha por fornecedor. O mesmo serviço pode ser acessado por uma conexão individual e por um processo técnico com permissões diferentes. Se isso ocorrer, registre as duas relações separadamente.
| Campo | O que registrar | Exemplo ilustrativo |
|---|---|---|
| Finalidade | Tarefa e limite da conexão | Preparar rascunho de proposta |
| Origem | Aplicação e espaço de trabalho | Assistente da equipe comercial |
| Identidade autorizadora | Usuário ou identidade técnica conferida | Identidade operacional do fluxo |
| Destino | Recurso e organização proprietária | Pasta de propostas aprovadas |
| Permissões | Ações necessárias e restrições | Ler pedido e criar rascunho |
| Segredo | Referência ao armazenamento protegido | Entrada do cofre administrado pela TI |
| Dependência | Elemento que precisa continuar ativo | Autorização do serviço de pedidos |
| Recuperação | Responsável e procedimento aprovado | Interromper escrita e reautorizar com revisão |
Acrescente a última data de conferência, o ambiente e o vínculo com evidências. Uma captura de tela pode ajudar a identificar a organização selecionada, desde que não exponha dados desnecessários. Para configurações técnicas, prefira registrar uma saída sanitizada que mostre recurso e permissão. Diferencie “informado pelo responsável” de “testado pela equipe”.
Desenhe relações em frases curtas: “o servidor de propostas usa a identidade operacional para criar arquivos na pasta comercial”. Essa forma revela direção e finalidade. Acrescente relações administrativas, como “somente o administrador do espaço pode cadastrar a conexão”, quando isso tiver sido conferido no produto usado. Não suponha que administrar uma aplicação concede automaticamente acesso aos arquivos de outro serviço.
Documente autorização, revogação e recuperação
OAuth é um mecanismo de autorização usado em muitas integrações. Ele permite conceder acesso sem entregar a senha da pessoa ao aplicativo. Para fins de documentação, registre quem concedeu a autorização, quais permissões foram solicitadas e onde a equipe consegue revogá-la. Não guarde os próprios tokens na ficha.
As boas práticas de OAuth do Google orientam proteger credenciais e tokens e remover os que deixaram de ser necessários. Já a documentação de chaves de contas de serviço trata riscos de administração dessas chaves. São orientações específicas para esse ecossistema; verifique o procedimento equivalente do fornecedor utilizado.
Se houver um servidor MCP entre o assistente e outro serviço, documente as duas relações de autorização. A especificação MCP consultada diferencia a autorização do servidor e o acesso que ele faz a serviços posteriores. A credencial recebida em uma fronteira não deve ser tratada como chave universal para as demais etapas.
Inclua eventos que exigem revisão: saída de funcionário, troca de administrador, transferência de recurso, mudança de permissões e substituição de aplicação. Para cada evento, defina o procedimento e a evidência esperada. “Revisar quando necessário” não informa quem deve agir. “O administrador da conexão confere o recurso e executa o roteiro depois da troca de responsável” cria uma responsabilidade verificável.
Em ambiente controlado, remova uma autorização e observe o resultado. O fluxo deve parar de maneira compreensível, sem repetir operações de escrita indefinidamente. Depois, aplique o procedimento aprovado de recuperação e confira se o destino permaneceu o mesmo. O artigo sobre credenciais temporárias para agentes complementa a organização do ciclo de acesso.
Registre também como identificar ações parcialmente concluídas. Se a proposta foi criada mas o aviso falhou, repetir a tarefa inteira pode gerar um segundo arquivo. A ficha deve apontar o identificador usado para conferir conclusão e quem decide a retomada. Essa informação conecta a dependência técnica ao trabalho que a equipe precisa terminar.
Exemplo: escritório de projetos em Belo Horizonte
Imagine um escritório fictício de projetos em Belo Horizonte que usa um assistente para preparar resumos de solicitações comerciais. O caso é ilustrativo. As solicitações chegam a um sistema de atendimento, o resumo é gravado em uma pasta e uma tarefa é aberta para revisão do coordenador. O conteúdo só segue para o cliente depois da aprovação humana.
Ao documentar o processo, a equipe descobre que a pasta pertence a uma conta individual antiga. O conector funciona, mas a continuidade depende dessa pessoa. Em vez de registrar apenas “armazenamento conectado”, a ficha identifica proprietário, organização, identidade que grava arquivos e responsável pela revisão. O escritório avalia com seu administrador o procedimento de transferência permitido pelo serviço.
Outra dependência aparece no envio da tarefa: o servidor usa uma credencial técnica administrada por um prestador. A ficha registra o vínculo contratual, o responsável interno e a referência protegida da credencial. A equipe não pede que o prestador cole a chave em uma planilha. Ela define como manter administração autorizada e como substituir o acesso quando o contrato terminar.
Na simulação de indisponibilidade, a consulta de solicitações continua disponível, mas a gravação do resumo é bloqueada. O roteiro informa que os arquivos já existentes não foram perdidos e que novos resumos aguardam recuperação da conexão. Após reautorizar, a equipe confere os identificadores antes de retomar. A documentação passa a explicar o impacto de cada dependência, em vez de tratar o fluxo como uma caixa única.
Erros comuns
- Usar só nomes de fornecedores: um fornecedor pode conter várias organizações e recursos. Identifique a instância efetivamente utilizada.
- Confundir proprietário com usuário: quem usa uma pasta pode não ter poderes para transferi-la ou recuperar seu acesso.
- Guardar segredos na ficha: registre a referência ao local protegido e as pessoas autorizadas a administrá-lo.
- Esquecer prestadores: explicite quais acessos dependem de administração externa e quem responde internamente por eles.
- Atualizar só depois de uma falha: incorpore a revisão à troca de conta, recurso, administrador ou aplicação.
- Recuperar sem conferir duplicidade: antes de repetir uma escrita, verifique quais etapas foram concluídas.
Perguntas frequentes
Preciso de uma ferramenta especializada?
Não necessariamente. Uma tabela com responsáveis, relações e evidências pode atender um fluxo pequeno. O essencial é controlar acesso ao documento, manter as informações conferidas e permitir que o substituto encontre o procedimento.
Devo incluir senhas e tokens?
Não. Inclua referências ao armazenamento protegido e instruções para solicitar acesso autorizado. O inventário precisa revelar dependências sem se transformar em uma coleção de credenciais utilizáveis.
Como representar uma conexão compartilhada?
Registre a identidade usada, quem pode utilizar a conexão e quais recursos ela alcança. Não deduza que o acesso é individual só porque os usuários possuem contas próprias no assistente.
O documento pode ser gerado por IA?
A IA pode organizar informações fornecidas e apontar campos vazios. Um responsável deve verificar contas, permissões e recursos na configuração real. Um diagrama coerente pode conter relações inventadas ou desatualizadas.
Quando considerar a documentação pronta?
Quando alguém autorizado que não montou o fluxo consegue identificar o recurso, compreender o impacto de falha e executar o roteiro de investigação. Faça esse exercício com dados controlados e registre as lacunas encontradas.
