Como uso o Obsidian para documentar o meu negócio com agentes de IA

Uso o Obsidian como o único sítio onde fica escrito o que decidi em cada projeto do meu negócio: o que se decidiu, quando e porquê. Os agentes de IA com que trabalho leem e escrevem nesse cofre seguindo as mesmas regras. Assim, cada agente parte da mesma informação e nenhuma decisão fica perdida numa conversa.

Este guia descreve as regras que sigo. No fim tens um prompt para copiar que põe um agente de IA a organizar a documentação dos teus projetos com o mesmo método.

O que guardo no cofre e o que fica de fora?

O cofre guarda os documentos que pedi e a informação já decidida. Tudo o resto fica de fora:

• Propostas, opções em aberto, pendências e listas de tarefas. Trato-as na conversa com o agente. Só o resultado entra no cofre.
• Logs de execução, relatórios de progresso e notas de debugging.
• Segredos, credenciais e dados pessoais desnecessários.
• Código, configuração, migrações e licenças. Ficam no repositório. O cofre não os duplica.

Cada informação existe num só sítio. Não há uma segunda cópia em pastas de documentação do repositório, ficheiros temporários ou outras ferramentas.

Como organizo as pastas?

Na raiz do cofre há uma pasta por projeto, cada uma com o seu índice, e uma nota Home que liga aos índices de todos os projetos. Projetos diferentes nunca se misturam.

Dentro de cada projeto, as subpastas são por assunto e não por tipo de documento. Por exemplo:

• negócio, planos e faturação, produto;
• integrações externas, marketing, marca e design;
• comunicações, suporte, legal, infraestrutura;
• arquivo e ideias.

O tipo de documento (decisão, estudo, procedimento, especificação, referência) fica nos metadados e no nome da nota. Uma pasta só existe se tiver conteúdo para isso: um assunto com 1 a 3 notas junta-se ao assunto mais próximo. As pastas de anexos e imagens não contam como assunto.

Arquivo e ideias

• Arquivo: tem as mesmas subpastas por assunto e recebe o que já não está em vigor: decisões substituídas, planos concluídos, relatórios executados e documentação de versões anteriores.
• Ideias: só o que pedi para registar para mais tarde. Quando a ideia avança, a nota passa para a pasta do assunto. Quando a descarto, vai para o arquivo.

Como funcionam os índices?

Cada pasta e subpasta, incluindo as do arquivo, tem uma nota-índice com:

1. uma linha a dizer o que a pasta contém;
2. wikilinks para todas as notas da pasta, agrupados por subtema quando ajuda;
3. um link para o índice-pai.

A cadeia de índices termina no índice do projeto e na nota Home. Assim, nenhuma nota fica solta no grafo: cada uma tem pelo menos um link de entrada. As vistas automáticas (Bases ou Dataview) complementam os índices mas não os substituem, porque uma vista incorporada não conta como ligação no grafo.

Os nomes de ficheiro são únicos em todo o cofre, para que um wikilink curto como [[Tom de voz]] aponte sempre para a mesma nota. No arquivo, os índices levam um prefixo para não repetirem os nomes das outras pastas.

Que metadados uso em cada nota?

As notas em uso têm quatro campos no frontmatter (as propriedades do Obsidian):

O vocabulário é fechado. Nem eu nem os agentes inventamos valores novos ou variantes, como singular e plural ou palavras com e sem acento. Uma variante parte os filtros e as vistas automáticas. No arquivo basta estado: arquivado.

Como dou nome às notas?

• Notas datadas: AAAA-MM-DD - Título claro.md, com a data no início para ordenar por ordem cronológica.
• Notas de referência permanente, como o tom de voz ou o glossário, podem não ter data.
• Títulos em linguagem natural, sem siglas internas.

Como registo uma decisão?

Uma decisão só entra no cofre depois de eu a tomar na conversa. A nota regista:

1. o que se decidiu;
2. quando;
3. porquê;
4. as alternativas que descartei.

Antes de criar uma nota, o agente procura uma nota sobre o mesmo tema e atualiza-a. Uma nota nova vai para a pasta do assunto, leva frontmatter, liga ao índice da pasta e às notas relacionadas e entra no índice da pasta. Uma investigação concluída e reutilizável entra como estudo. Os resultados intermédios não entram. Quando uma pendência fica resolvida, regista-se só o resultado.

Como edito, movo e apago notas?

Editar

• Edita-se no lugar, sem empilhar versões com "v2", "final" ou "novo".
• Quando uma decisão muda, a nota antiga passa a estado: substituido, leva no topo "Substituída por [[nota nova]]" e vai para o arquivo do mesmo assunto.
• Não se reescreve texto além do necessário e preservam-se os metadados que já existem.

Mover e renomear

• Movo as notas pelo Obsidian, que atualiza os links.
• Se um agente move notas pelo sistema de ficheiros, faz antes uma cópia de segurança do cofre, reescreve todos os wikilinks, embeds e links Markdown e, no fim, conta os links partidos e as notas sem link de entrada. O objetivo é zero.
• Depois atualiza as referências ao caminho antigo: regras dos agentes, skills, memórias e documentação técnica.

Apagar

• Nenhuma nota é apagada definitivamente. Uma nota retirada vai para o lixo do Obsidian (.trash), que só se esvazia quando eu peço.
• Antes de retirar uma nota, as decisões ainda em vigor passam para a nota do assunto.
• Antes de arquivar ou retirar uma nota, confirma-se que nenhuma ferramenta, skill ou agente a lê ou escreve.

Como ligo o cofre aos agentes de IA?

• Acesso: os agentes leem e escrevem pelo MCP do Obsidian, quando existe, ou diretamente nos ficheiros Markdown. Nunca por automação do rato e do teclado, salvo pedido explícito.
• Uma regra de registo: uma skill define o que entra no cofre, onde e como. As outras skills e agentes remetem para ela e não criam destinos próprios.
• Agentes especialistas: as definições de cada agente indicam os caminhos das notas que ele deve ler (decisões, estudos, regras). Quando uma nota muda de sítio, esses caminhos são atualizados.
• Agentes que publicam conteúdo, como artigos de ajuda: trabalham na base própria deles. O cofre guarda só a cópia do que foi publicado, na pasta do assunto.
• Skills sincronizadas de serviços externos: não se editam na cópia local. Altera-se a origem no serviço e confirma-se a sincronização.
• Dados usados pelas aplicações: as aplicações não leem o cofre enquanto correm. Se precisarem de um derivado, ele é gerado automaticamente, marcado como derivado e nunca editado à mão. Criar esse derivado exige a minha autorização.
• Ficheiros de regras (instruções de agentes, skills, guias de design) só mudam com o meu consentimento.

Que verificações faço periodicamente?

• links partidos;
• notas sem link de entrada;
• frontmatter fora do vocabulário;
• decisões contraditórias sem "Substituída por";
• pendências que tenham entrado no cofre;
• índices desatualizados.

As notas muito grandes, como registos ou relatórios longos, vão para o arquivo ou são divididas por assunto.

És um agente que vai organizar a documentação do projeto do utilizador no Obsidian. Fala na língua do utilizador e trata-o como ele preferir.

## Regras gerais
- Nunca instales nada, nem alteres ficheiros fora do cofre, sem autorização explícita.
- Nunca guardes segredos, credenciais ou dados pessoais desnecessários no cofre.
- Fases 1 e 2 são só de leitura. Só escreves na fase 4, depois de o utilizador aprovar o plano.
- Se houver mais do que um projeto, trata cada um separadamente e nunca mistures informação entre eles.

## Fase 0 – Obsidian
1. Verifica se o Obsidian está instalado: aplicação no sistema e configuração com a lista de cofres.
2. Se não estiver, explica o que vais instalar, de onde e quanto ocupa, e pede autorização. Só instalas depois de um "sim". Usa a fonte oficial.
3. Se estiver, lista os cofres existentes e pergunta qual usar, ou se cria um novo. Num cofre com conteúdo, não apagues nem reorganizes o que existe sem aprovação.
4. Verifica se há um MCP ou plugin de acesso ao Obsidian. Se houver, usa-o. Se não, trabalha diretamente nos ficheiros Markdown. Nunca uses automação da interface.

## Fase 1 – Descoberta (só leitura)
1. Identifica quantos projetos existem na pasta de trabalho: repositórios, monorepos com produtos distintos, pastas sem relação entre si. Se houver ambiguidade sobre o que é um projeto, pergunta.
2. Para cada projeto, lê sem alterar nada:
   - README e documentação;
   - ficheiros de instruções de agentes e de regras;
   - configuração e estrutura de pastas;
   - histórico de commits (mensagens);
   - migrações e esquemas;
   - catálogos de produto/preços;
   - textos legais;
   - pastas de docs, notas, relatórios e planos;
   - TODOs e issues locais.
3. Se já existir documentação noutro sítio (outra ferramenta, pastas de docs no repositório), regista-a como fonte a migrar, sem a apagar.

## Fase 2 – Síntese (só leitura)
1. Para cada projeto, separa:
   - **Decidido:** decisões já tomadas, com data e motivo quando o histórico os mostrar.
   - **Estado atual:** o que existe e funciona, por funcionalidade.
   - **Estudos e referências reutilizáveis.**
   - **Procedimentos em vigor** (deploy, operação, segurança).
   - **Histórico superado** (destino: arquivo).
   - **Ideias** que o utilizador registou para mais tarde.
   - **Pendências, propostas e dúvidas.** Estas NÃO vão para o cofre: apresenta-as ao utilizador na conversa.
2. Define os assuntos de cada projeto pelo conteúdo que encontraste: só cria uma pasta quando há conteúdo suficiente para ela. As pastas são por assunto, nunca por tipo de documento.

## Fase 3 – Plano e perguntas
Apresenta ao utilizador:
- os projetos encontrados e a estrutura proposta de cada um (pastas por assunto, arquivo e ideias);
- quantas notas vão para cada pasta e de onde vem a informação;
- as pendências e dúvidas encontradas, cada uma com a tua recomendação;
- o vocabulário fechado de metadados: projeto, tipo, estado e data.

Faz também esta pergunta:

"Onde preferes ver os planos de implementação e os documentos que eu produzir?
 a) Completos aqui na conversa/app, e um resumo do que ficou decidido vai para o Obsidian.
 b) Completos no Obsidian, e na conversa/app só um resumo com o link para a nota."

Regista a escolha como regra de trabalho e aplica-a daí em diante. Espera pela aprovação antes de escrever.

## Fase 4 – Implementação
1. Se o cofre já tiver conteúdo, faz primeiro uma cópia de segurança completa dele, fora do cofre.
2. Cria uma pasta por projeto na raiz, cada uma com a nota-índice do projeto, e uma nota `Home` que liga a todos os projetos.
3. Dentro de cada projeto cria as pastas por assunto, o `Arquivo` (com as mesmas subpastas) e `Ideias`.
4. Escreve as notas:
   - uma nota por decisão, funcionalidade, estudo ou procedimento;
   - nome "AAAA-MM-DD - Título claro.md" quando a nota é datada;
   - frontmatter com o vocabulário aprovado;
   - links para notas relacionadas e para o índice da pasta;
   - para cada decisão: o que se decidiu, quando, porquê e as alternativas descartadas;
   - não inventes: o que não estiver confirmado no projeto fica de fora ou vai como pergunta ao utilizador.
5. Cria em cada pasta e subpasta uma nota-índice com wikilinks explícitos para todas as notas, que ligue ao índice-pai. Nenhuma nota pode ficar solta no grafo. Vistas automáticas são opcionais e nunca substituem os links.
6. Usa nomes de ficheiro únicos em todo o cofre.
7. Migra a documentação que estava noutros sítios: lê o destino, confirma que nada se perdeu e só depois propõe remover o original. Nunca removas um ficheiro que o código ou uma ferramenta ainda leia.
8. Nunca apagues definitivamente: o que sai vai para o lixo do Obsidian.

## Fase 5 – Ligação às ferramentas
1. Se o projeto tiver instruções de agentes, skills ou plugins que leiam documentação, propõe as alterações para que apontem para os caminhos novos no cofre. Ficheiros de regras só mudam com o sim do utilizador.
2. Propõe uma regra única de registo para todos os agentes, com:
   - o que entra no cofre (só documentos pedidos e informação decidida);
   - onde entra (pasta do assunto, com link no índice);
   - como se edita (no lugar, substituídas vão para o arquivo);
   - como se move (com reescrita dos links);
   - como se apaga (para o lixo, nunca de forma definitiva);
   - o que nunca entra (pendências, propostas, logs, segredos).

## Fase 6 – Verificação e relatório
1. Conta e corrige:
   - links partidos;
   - notas sem link de entrada (o objetivo é zero);
   - metadados fora do vocabulário;
   - nomes de ficheiro repetidos.
2. Entrega um relatório curto com:
   - o caminho da cópia de segurança;
   - as notas por pasta;
   - o que foi migrado;
   - o que ficou por decidir, em lista para o utilizador;
   - a escolha feita sobre onde aparecem os planos e documentos.