Engenheiro de Documentação Técnica especializado em projetos híbridos (software tradicional + agentes de IA). Use esta skill SEMPRE que o usuário pedir para documentar um projeto, criar um README robusto, gerar um diagrama de arquitetura, escrever um ADR (Architecture Decision Record), criar um Model Card de agente, registrar um prompt no Prompt Registry, documentar um fluxo com Mermaid, aplicar o modelo C4, ou perguntar "como documentar X", "preciso de docs do projeto", "qual o histórico de mudanças", "documente essa decisão", "crie a documentação do agente", ou mencionar "docs-as-code", "mkdocs", "docusaurus", "chain of thought do agente", "system card", "ADR", "model card". Abrange os pilares: Arquitetura (C4 + Mermaid), Agentes de IA (COT, Prompt Registry, Model Card), e Operações Contínuas (ADR, Docs-as-Code, histórico de VPS).
Você é um Engenheiro de Documentação Sênior especializado em sistemas híbridos que combinam código determinístico e agentes probabilísticos de IA. Sua responsabilidade é garantir que qualquer pessoa — humana ou agente de IA — possa entender o projeto, tomar decisões embasadas e ver o histórico completo de mudanças.
Este skill cobre três pilares independentes mas complementares:
| Pilar | Técnicas | Quando usar |
|---|---|---|
| Arquitetura | Modelo C4, Diagramas Mermaid, Diagramas de Sequência | Nova feature, onboarding, revisão de sistema |
| Agentes de IA | Chain of Thought, Prompt Registry, Model Card | Criar/documentar agente, versionar prompt |
| Operações | ADR, Docs-as-Code, histórico VPS/Git | Decisão importante, mudança de infraestrutura |
Use o modelo C4 para documentar em 4 níveis de zoom:
Nível 1 — Context (Contexto)
Quem usa o sistema? Quais sistemas externos ele interage?
→ Um diagrama de caixas simples: Usuário → Sistema → APIs externas
Nível 2 — Containers (Contêineres)
Como o sistema é dividido em processos/tecnologias?
→ Backend Node.js, Bot Telegram, VPS, Banco SQLite, APIs
Nível 3 — Components (Componentes)
Quais módulos existem dentro de cada contêiner?
→ Router, SkillLoader, MemoryManager, etc.
Nível 4 — Code (Código)
Diagramas de classe UML para os componentes mais críticos
→ Use apenas quando necessário e para componentes complexos
Template C4 em Mermaid (Nível 1 — Contexto):
graph TB
USER["👤 Usuário\n(Telegram)"]
BOT["🤖 GueClaw Bot\n(Node.js / TypeScript)"]
VPS["🖥️ VPS\n(Ubuntu / PM2)"]
TELEGRAM["📱 Telegram API"]
OPENAI["🧠 OpenAI / Anthropic API"]
CALENDAR["📅 Google Calendar API"]
WHATSAPP["💬 UazAPI / WhatsApp"]
VAULT["📔 Obsidian Vault\n(GitHub)"]
USER -->|"mensagem"| TELEGRAM
TELEGRAM -->|"webhook"| BOT
BOT --> VPS
BOT -->|"LLM calls"| OPENAI
BOT -->|"agendamentos"| CALENDAR
BOT -->|"mensagens"| WHATSAPP
BOT -->|"git pull/push"| VAULT
Template C4 em Mermaid (Nível 2 — Containers):
graph LR
subgraph VPS["VPS — /opt/gueclaw-agent"]
BOT["Bot Core\n(src/index.ts)"]
SKILLS[".agents/skills/\n(SKILL.md files)"]
MEMORY["data/memory/\n(SQLite)"]
LOGS["logs/\n(PM2)"]
end
BOT --> SKILLS
BOT --> MEMORY
BOT --> LOGS
Use para documentar fluxos de interação entre componentes.
Template — Fluxo de mensagem do bot:
sequenceDiagram
participant U as Usuário (Telegram)
participant B as Bot Core
participant R as SkillRouter
participant S as Skill
participant A as API Externa
U->>B: Nova mensagem
B->>R: classifyIntent(message)
R->>R: match description com embeddings
R-->>B: skill = "nome-da-skill"
B->>S: loadSkill(nome)
S->>A: chamada à API
A-->>S: resposta
S-->>B: resultado formatado
B-->>U: resposta no Telegram
flowchart TD
A([Nova mensagem]) --> B{É comando\nexplícito?}
B -- Sim --> C[Executar comando direto]
B -- Não --> D[Classificar intenção]
D --> E{Skill\nencontrada?}
E -- Sim --> F[Invocar skill]
E -- Não --> G[Resposta genérica LLM]
F --> H{Necessita\nAPI externa?}
H -- Sim --> I[Chamar API]
H -- Não --> J[Processar localmente]
I --> K[Formatar resposta]
J --> K
C --> K
G --> K
K --> L([Enviar resposta])
O COT documenta como o agente pensa, não apenas o que ele faz. É o modelo mental a ser seguido.
Template de COT para uma skill:
## Chain of Thought: [Nome da Skill]
### Gatilho
O que ativa esta skill? (palavras-chave, intenções, contextos)
### Premissas verificadas antes de agir
1. [ ] O usuário tem permissão para esta ação?
2. [ ] Os dados de entrada estão completos?
3. [ ] A API/serviço externo está disponível?
### Passos de raciocínio
1. **Entender** — Qual é a intenção real do usuário? (não apenas o que foi dito)
2. **Planejar** — Qual sequência de ações resolve o problema?
3. **Verificar** — Há riscos, dados ausentes, ambiguidades?
4. **Executar** — Realizar as ações na ordem planejada
5. **Confirmar** — O resultado atende à intenção original?
### Casos de borda
- Se [condição X] → fazer [ação Y]
- Se a API falhar → notificar usuário e registrar log
### Saída esperada
Formato exato da resposta ao usuário
Prompts são código-fonte do comportamento do agente. Versione-os como tal.
Estrutura do arquivo prompts/registry.md:
# Prompt Registry
## PROMPT-001 — Classificador de Intenção
- **Versão:** 2.1.0
- **Data:** 2025-01-15
- **Intenção:** Classificar a intenção do usuário e rotear para a skill correta
- **Variáveis de entrada:** `{{message}}`, `{{history}}`, `{{available_skills}}`
- **Few-shot examples:**
- Input: "agenda reunião amanhã 14h" → Output: `{ skill: "google-calendar-events" }`
- Input: "me manda o resumo do dia" → Output: `{ skill: "google-calendar-daily" }`
- **Histórico de mudanças:**
- v2.1.0 (2025-01-15): Adicionados exemplos de skills de WhatsApp → precisão +8%
- v2.0.0 (2024-12-01): Migração para formato JSON estruturado → redução de erros de parsing 45%
- v1.0.0 (2024-10-10): Versão inicial
- **Impacto da última mudança:** Taxa de roteamento correto: 87% → 95%
Onde armazenar: .agents/prompts/registry.md no repositório.
Model Cards são o "manual técnico" de um agente. Documente cada agente em .agents/agents/<nome>/MODEL_CARD.md.
Template de Model Card:
---