Zekai Docs

Sistema de documentacao viva para desenvolvimento assistido por IA.

Resolve um problema concreto: toda vez que voce abre uma sessao nova com IA (Cursor, Claude, Copilot, ChatGPT), perde contexto. O que foi feito, quais decisoes foram tomadas, o que ficou pendente — tudo precisa ser re-explicado do zero.

Com esse sistema, a IA le os docs e ja sabe tudo antes de voce digitar qualquer coisa.

---

Como funciona

Tres camadas de documentacao que se complementam:

┌──────────────────────────────────────────────┐
│  CAMADA 1: docs/ dentro do projeto (no git)  │
│                                              │
│  docs/STATUS.md    → estado atual            │
│  docs/DECISIONS.md → decisoes tecnicas       │
│  README.md         → doc publica             │
│                                              │
│  Qualquer IA le. Portavel. Vai no commit.    │
├──────────────────────────────────────────────┤
│  CAMADA 2: Vault Obsidian (hub central)      │
│                                              │
│  sessoes/    → historico por dia             │
│  decisoes/   → ADRs linkados                │
│  bugs/       → bugs rastreados              │
│                                              │
│  Grafo navegavel. Busca global. Wiki-links.  │
├──────────────────────────────────────────────┤
│  CAMADA 3: Rules do editor (auto-injetado)   │
│                                              │
│  .cursor/rules/ → contexto automatico        │
│                                              │
│  A IA recebe contexto sem voce pedir.        │
└──────────────────────────────────────────────┘

Principio: Obsidian e a fonte de verdade, docs/ e o snapshot portavel, rules sao a ponte.

Se voce trocar de maquina, de editor ou de IA — docs/ ja esta no git e o vault copia em 1 minuto.

---

O que tem no template

zekai-docs-template/
│
├── cursor-rules/                      ← Copiar para .cursor/rules/
│   ├── contexto-ecossistema.mdc       ← alwaysApply: true (editar com seus dados)
│   ├── atualizar-docs.mdc             ← fluxo /atualizar-docs
│   └── finalizar-sessao.mdc           ← encerramento de sessao
│
├── obsidian-templates/                ← Copiar para _templates/ no vault
│   ├── sessao.md                      ← template de registro diario
│   ├── adr.md                         ← template de decisao tecnica
│   ├── bug.md                         ← template de bug rastreado
│   ├── projeto.md                     ← template de ficha de projeto
│   └── ecossistema.md                 ← template de hub de ecossistema
│
├── obsidian-snippets/                 ← Copiar para .obsidian/snippets/
│   └── zekai-docs-theme.css           ← cores por tipo de nota no grafo
│
├── projeto-template/                  ← Copiar docs/ para cada projeto
│   ├── docs/
│   │   ├── STATUS.md                  ← estado, pendencias, PAROU EM, PROXIMO PASSO
│   │   └── DECISIONS.md               ← decisoes tecnicas acumulativas
│   └── README.md                      ← template de README
│
├── CONCEITO.md                        ← Arquitetura completa, fluxo, cenarios
└── GUIA-SETUP.md                      ← Passo a passo (15-20 min)

---

Quick start (5 passos)

1. Copie as rules para o workspace

.cursor/rules/
├── contexto-ecossistema.mdc    ← editar com seus projetos
├── atualizar-docs.mdc
└── finalizar-sessao.mdc

2. Edite contexto-ecossistema.mdc

Substitua os placeholders com:

• Nome do ecossistema/equipe
• Tabela de projetos (nome, path, stack, status)
• Path do vault Obsidian
• Convencoes da equipe

3. Adicione docs/ em cada projeto

projeto/
├── docs/
│   ├── STATUS.md
│   └── DECISIONS.md
└── README.md

Preencha pelo menos o STATUS.md com estado atual e stack.

4. Monte o vault Obsidian

vault/
├── .obsidian/snippets/zekai-docs-theme.css
├── _templates/        ← templates daqui
└── 01-projetos/
    ├── ecossistema.md
    └── projeto/
        ├── projeto.md
        ├── sessoes/
        ├── decisoes/
        └── bugs/

5. Trabalhe normalmente

Ao final da sessao, rode /atualizar-docs. A IA atualiza docs/STATUS.md, cria nota no Obsidian, e mostra o resumo. Na proxima sessao, a IA le tudo automaticamente.

---

O fluxo /atualizar-docs

Comando unico que a IA executa para persistir o conhecimento:

/atualizar-docs
      │
      ├──► docs/STATUS.md        (estado, pendencias, PAROU EM)
      ├──► docs/DECISIONS.md     (se houve decisao nova)
      ├──► README.md             (se mudou stack/setup)
      ├──► Obsidian sessao       (snapshot do dia)
      ├──► Obsidian ADR/bug      (se relevante)
      └──► Resumo ao usuario

---

Cores no Obsidian

O CSS snippet aplica cores no grafo e nos links por tipo de nota:

Tipo	Cor	Uso
sessao	Azul #3B82F6	Registro de trabalho diario
decisao	Roxo #8B5CF6	ADRs — decisoes tecnicas
bug	Vermelho #EF4444	Bugs rastreados
projeto	Verde #22C55E	Ficha do projeto
ecossistema	Amarelo #F59E0B	Hub do ecossistema
referencia	Cinza #6B7280	Docs estaticos
pendencia	Laranja #F97316	Itens abertos
status	Ciano #06B6D4	Estado vivo

Requer plugin Supercharged Links para cores nos links. Grafo funciona nativamente com grupos por tag.

---

Cenarios de uso

Solo (1 pessoa, N projetos)

Voce e seus projetos pessoais ou freelance. 1 workspace, 1 vault, rules globais.

Equipe (2-10 pessoas, 1 setor)

Equipe compartilha o workspace e o vault. Rule contexto-ecossistema.mdc carrega contexto do setor. Qualquer membro roda /atualizar-docs.

Empresa (N setores)

Cada setor tem seu workspace e suas rules. Vault pode ser unico (subpastas por setor) ou separado. Padroes globais em rule de empresa herdada por todos.

empresa/
├── _empresa/              ← padroes globais
├── setor-cobranca/        ← rules + projetos do setor
├── setor-produto/
└── obsidian-vault/
    ├── 00-empresa/
    ├── 01-cobranca/
    └── 02-produto/

---

Por que nao basta um README?

O README e doc publica — como rodar, stack, estrutura. Ele nao responde:

• Onde paramos na ultima sessao?
• Que bug foi resolvido semana passada?
• Por que escolhemos X em vez de Y?
• O que esta pendente para o proximo sprint?

docs/STATUS.md responde as duas primeiras. docs/DECISIONS.md responde a terceira. Obsidian responde todas, com historico e links.

---

Documentacao adicional

• CONCEITO.md — Arquitetura detalhada, diagramas, principios, beneficios
• GUIA-SETUP.md — Passo a passo completo com checklist

---

Licenca

MIT — use, adapte, distribua livremente.