Skip to main content

Case Study – Documentation Agents with Cursor

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

Technical documentation is a constant challenge in software projects. The technical team needs to document, but there's generally no dedicated tech writer. In this case study, I show how we created a complete automated documentation system using Cursor Agents, Rules, and Commands.

The Problem​

In an AI platform project, we had:

  • Documentation in: apps/landing/docs/ (Docusaurus)
  • Source code in: apps/web/ (Frontend) and apps/api/ (Backend)
  • Challenge: The technical team needed to document, but:
    • Had no dedicated time
    • Didn't know where to start (we already had many features built)
    • Documentation kept falling out of date
    • Inconsistencies between code and docs

The Solution: Agent System​

We created a system with three main components:

  1. Agents (@docs-writer and @docs-reviewer) for creation and review
  2. Rules to standardize style and structure
  3. Commands (/docs-writer and /docs-reviewer) for reusable workflows

1. Creating the Agents​

Agent: Documentation Writer​

We created an agent at .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/landing/docs/`
- **Site:** https://<docs-company-site>/
- **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​

We created an agent at .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. Creating the Commands​

Command: /docs-writer​

We created .cursor/commands/docs-writer.md:

# Documentation Writer

## Objective
Create and update technical documentation incrementally.

## Context
- Documentation: `apps/landing/docs/`
- Source: `apps/web/` + `apps/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​

We created .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. Usage Workflow​

Documenting a New Feature​

# 1. Develop feature
git add apps/web/src/pages/training/

# 2. Document
/docs-writer Document the staged changes related to Training

# 3. Review
/docs-reviewer Quick review of the new Training documentation

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

Improving Existing Documentation​

# 1. Analyze quality
/docs-reviewer Review the Connectors documentation

# 2. See feedback (score, issues, suggestions)

# 3. Implement improvements
/docs-writer Update the Connectors operations section

# 4. Verify
/docs-reviewer Quick review of the improvements

4. Results​

Before​

  • ❌ Outdated documentation
  • ❌ Inconsistencies with code
  • ❌ Team didn't know where to start
  • ❌ Generic and not very useful documentation
  • ❌ Slow manual review

After​

  • ✅ Always up-to-date documentation
  • ✅ Automatic validation against code
  • ✅ Clear and simple workflow
  • ✅ Technical and specific documentation
  • ✅ Structured and fast review

Metrics​

  • Documentation time: Reduced by ~70%
  • Quality: Average score from 7.5/10 → 9/10
  • Coverage: 60% → 95% of documented topics
  • Update: Documentation updated alongside code

5. Real Example: Documenting Datasets​

Initial Situation​

Datasets documentation had:

  • Score: 7.5/10
  • Issues: data_domain documented as single, but is an array in the code
  • Missing: API reference, code examples

Process​

  1. Initial review:

    /docs-reviewer Review the Datasets documentation

    Result: Identified inconsistency in data_domain

  2. Correction:

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

    Result: Updated all documentation to reflect that data_domain is string[]

  3. Validation:

    /docs-reviewer Quick review of the correction

    Result: Score improved to 8.5/10

Final Result​

  • ✅ data_domain correctly documented as array
  • ✅ Examples showing multiple domains
  • ✅ Validation against code confirmed
  • ✅ Consistency across all documentation files

6. Lessons Learned​

What Worked Well​

  1. Incremental work: One topic at a time is more manageable
  2. Automatic validation: Comparing with code prevents errors
  3. Structured review: Score and checklist help a lot
  4. Simple commands: /docs-writer and /docs-reviewer are intuitive

Challenges Faced​

  1. Initial context: Agents needed to understand the project structure
  2. Balancing: Not creating too much documentation at once
  3. Maintenance: Rules need to be updated with the project

Future Improvements​

  1. CI/CD integration: Validate documentation in PRs
  2. Automatic metrics: Quality tracking over time
  3. Templates: More templates for different types of documentation

7. Final Structure​

.cursor/
├── rules/
│   ├── docs-writer-agent.mdc      # Agent for writing
│   ├── docs-reviewer-agent.mdc    # Agent for reviewing
│   └── docs-agents-guide.mdc       # Complete guide
└── commands/
    ├── docs-writer.md              # Command /docs-writer
    ├── docs-reviewer.md           # Command /docs-reviewer
    └── README.md                  # Quick reference

apps/landing/docs/                # Generated documentation
apps/web/                   # Source (frontend)
apps/api/                # Source (backend)

8. Benefits for the Team​

Developers​

  • ✅ Documentation is no longer a burden
  • ✅ Simple and fast workflow
  • ✅ Structured and useful feedback
  • ✅ Less time, more quality

Project​

  • ✅ Always up-to-date documentation
  • ✅ Consistency guaranteed
  • ✅ Measurable quality
  • ✅ Easier onboarding

Organization​

  • ✅ Standardized process
  • ✅ Shared knowledge
  • ✅ Less dependency on individuals
  • ✅ Scalable to new projects

Conclusion​

This case study shows how Agents, Rules, and Commands work together to create powerful solutions. The documentation system we created:

  • Solves a real problem: Technical documentation is challenging
  • Uses all capabilities: Agents + Rules + Commands
  • Generates measurable results: 70% less time, quality 9/10
  • Is replicable: Can be adapted for other projects

The key was thinking about a complete workflow, not just isolated tools. Agents execute, Rules standardize, Commands automate.

Next Steps​

If you want to implement something similar:

  1. Start simple: One agent, one command
  2. Iterate based on usage: Improve with feedback
  3. Share with team: Rules and Commands in Git
  4. Measure results: Track quality and time
tip

Deepen Your Knowledge​

Want to learn more about Cursor? Explore our complete documentation trail:

Series Articles​

Read the other articles in the series about Cursor:

Resources​