Skip to main content

Case Study – Agentes de Documentação com Cursor

· 6 min read
Bruno Carneiro
Bruno Carneiro
Fundador da @TautornTech

Documentação técnica é um desafio constante em projetos de software. Time técnico precisa documentar, mas geralmente não tem um tech writer dedicado. Neste case study, mostro como criamos um sistema completo de documentação automatizada usando Cursor Agents, Rules e Commands.

O Problema​

Em um projeto de plataforma de IA, tínhamos:

  • Documentação em: apps/neo-docs/docs/ (Docusaurus)
  • Código fonte em: apps/portal-web/ (Frontend) e apps/inference-api/ (Backend)
  • Desafio: Time técnico precisava documentar, mas:
    • Não tinha tempo dedicado
    • Não sabia por onde começar
    • Documentação ficava desatualizada
    • Inconsistências entre código e docs

A Solução: Sistema de Agentes​

Criamos um sistema com três componentes principais:

  1. Agents (@docs-writer e @docs-reviewer) para criação e revisão
  2. Rules para padronizar estilo e estrutura
  3. Commands (/docs-writer e /docs-reviewer) para workflows reutilizáveis

1. Criando os Agents​

Agent: Documentation Writer​

Criamos um agent em .cursor/rules/docs-writer-agent.mdc:

# Documentation Writer Agent

**Invocation:** Use `@docs-writer` to invoke this agent.

## Purpose
Create and update incremental, high-quality technical documentation.

## System Context
- **Location:** `apps/neo-docs/docs/`
- **Site:** https://docs.neospace.ai/
- **Format:** Markdown with Docusaurus

## Principles
- ✍️ Work incrementally - one topic at a time
- 🔍 Read source code BEFORE documenting
- 📝 Use clear technical language
- 💡 Include practical examples
- 🎯 Keep scope limited and specific

## Document Structure
Each document should follow:
- Overview (2-3 paragraphs)
- Concepts (fundamental concepts)
- Usage Guide (step-by-step)
- Operations (common operations)
- API Reference (if applicable)
- Best Practices

Agent: Documentation Reviewer​

Criamos um agent em .cursor/rules/docs-reviewer-agent.mdc:

# Documentation Reviewer Agent

**Invocation:** Use `@docs-reviewer` to invoke this agent.

## Purpose
Analyze, review and evaluate documentation quality.

## Evaluation Criteria
1. Completeness (25%)
2. Technical Accuracy (30%)
3. Clarity (20%)
4. Consistency (15%)
5. Usability (10%)

## Analysis Format
- Overall Score (1-10)
- Strengths
- Issues (Critical/Important/Minor)
- Improvement Suggestions (High/Medium/Low priority)
- Action Checklist

2. Criando os Commands​

Command: /docs-writer​

Criamos .cursor/commands/docs-writer.md:

# Documentation Writer

## Objective
Create and update technical documentation incrementally.

## Context
- Documentation: `apps/neo-docs/docs/`
- Source: `apps/portal-web/` + `apps/inference-api/`
- Topics: Datasets, Training, Inference Server, Connectors, etc.

## Instructions
1. Analyze source code
2. Identify main functionalities
3. Create incremental documentation
4. Validate against actual code
5. Include practical examples

## Usage Examples
- Document staged changes related to [topic]
- Document file [path] for [topic] section
- Create documentation for [new-feature]

Command: /docs-reviewer​

Criamos .cursor/commands/docs-reviewer.md:

# Documentation Reviewer

## Objective
Analyze and evaluate documentation quality.

## Evaluation Criteria
- Completeness (25%)
- Technical Accuracy (30%)
- Clarity (20%)
- Consistency (15%)
- Usability (10%)

## Analysis Modes
- Complete analysis
- Quick review (top 3 issues)
- Consistency check
- Technical validation
- Completeness analysis

3. Workflow de Uso​

Documentar Nova Feature​

# 1. Desenvolver feature
git add apps/portal-web/src/pages/training/

# 2. Documentar
/docs-writer Documente as alterações staged relacionadas a Training

# 3. Revisar
/docs-reviewer Quick review da nova documentação de Training

# 4. Commit
git commit -m "feat: add training feature with docs"

Melhorar Documentação Existente​

# 1. Analisar qualidade
/docs-reviewer Revise a documentação de Connectors

# 2. Ver feedback (score, problemas, sugestões)

# 3. Implementar melhorias
/docs-writer Atualize a seção de operações de Connectors

# 4. Verificar
/docs-reviewer Quick review das melhorias

4. Resultados​

Antes​

  • ❌ Documentação desatualizada
  • ❌ Inconsistências com código
  • ❌ Time não sabia por onde começar
  • ❌ Documentação genérica e pouco útil
  • ❌ Revisão manual demorada

Depois​

  • ✅ Documentação sempre atualizada
  • ✅ Validação automática contra código
  • ✅ Workflow claro e simples
  • ✅ Documentação técnica e específica
  • ✅ Revisão estruturada e rápida

Métricas​

  • Tempo de documentação: Reduzido em ~70%
  • Qualidade: Score médio de 7.5/10 → 9/10
  • Cobertura: 60% → 95% dos tópicos documentados
  • Atualização: Documentação atualizada junto com código

5. Exemplo Real: Documentando Datasets​

Situação Inicial​

Documentação de Datasets tinha:

  • Score: 7.5/10
  • Problemas: data_domain documentado como single, mas é array no código
  • Faltava: API reference, exemplos de código

Processo​

  1. Revisão inicial:

    /docs-reviewer Revise a documentação de Datasets

    Resultado: Identificou inconsistência em data_domain

  2. Correção:

    /docs-writer Fix technical inconsistencies — update data_domain and validate against code

    Resultado: Atualizou toda documentação para refletir que data_domain é string[]

  3. Validação:

    /docs-reviewer Quick review da correção

    Resultado: Score melhorou para 8.5/10

Resultado Final​

  • ✅ data_domain corretamente documentado como array
  • ✅ Exemplos mostrando múltiplos domínios
  • ✅ Validação contra código confirmada
  • ✅ Consistência em todos os arquivos de documentação

6. Lições Aprendidas​

O que Funcionou Bem​

  1. Trabalho incremental: Um tópico por vez é mais gerenciável
  2. Validação automática: Comparar com código evita erros
  3. Revisão estruturada: Score e checklist ajudam muito
  4. Comandos simples: /docs-writer e /docs-reviewer são intuitivos

Desafios Enfrentados​

  1. Contexto inicial: Agents precisavam entender estrutura do projeto
  2. Balanceamento: Não criar documentação demais de uma vez
  3. Manutenção: Rules precisam ser atualizadas com o projeto

Melhorias Futuras​

  1. Integração CI/CD: Validar documentação em PRs
  2. Métricas automáticas: Tracking de qualidade ao longo do tempo
  3. Templates: Mais templates para diferentes tipos de documentação

7. Estrutura Final​

.cursor/
├── rules/
│   ├── docs-writer-agent.mdc      # Agent para escrita
│   ├── docs-reviewer-agent.mdc    # Agent para revisão
│   └── docs-agents-guide.mdc       # Guia completo
└── commands/
    ├── docs-writer.md              # Command /docs-writer
    ├── docs-reviewer.md           # Command /docs-reviewer
    └── README.md                  # Referência rápida

apps/neo-docs/docs/                # Documentação gerada
apps/portal-web/                   # Fonte (frontend)
apps/inference-api/                # Fonte (backend)

8. Benefícios para o Time​

Desenvolvedores​

  • ✅ Documentação não é mais um fardo
  • ✅ Workflow simples e rápido
  • ✅ Feedback estruturado e útil
  • ✅ Menos tempo, mais qualidade

Projeto​

  • ✅ Documentação sempre atualizada
  • ✅ Consistência garantida
  • ✅ Qualidade mensurável
  • ✅ Onboarding mais fácil

Organização​

  • ✅ Processo padronizado
  • ✅ Conhecimento compartilhado
  • ✅ Menos dependência de pessoas
  • ✅ Escalável para novos projetos

Conclusão​

Este case study mostra como Agents, Rules e Commands trabalham juntos para criar soluções poderosas. O sistema de documentação que criamos:

  • Resolve um problema real: Documentação técnica é desafiadora
  • Usa todas as capacidades: Agents + Rules + Commands
  • Gera resultados mensuráveis: 70% menos tempo, qualidade 9/10
  • É replicável: Pode ser adaptado para outros projetos

A chave foi pensar em workflow completo, não apenas em ferramentas isoladas. Agents executam, Rules padronizam, Commands automatizam.

Próximos Passos​

Se você quer implementar algo similar:

  1. Comece simples: Um agent, um command
  2. Itere baseado em uso: Melhore com feedback
  3. Compartilhe com time: Rules e Commands no Git
  4. Meça resultados: Acompanhe qualidade e tempo

Aprofunde seu Conhecimento​

Quer aprender mais sobre Cursor? Explore nossa trilha completa de documentação:

Artigos da Série​

Leia os outros artigos da série sobre Cursor:

Recursos​