The Problem

Documentation debt piles up as features ship faster than pages get updated. Our docs at docs.airops.com needed coverage for everything we'd shipped in the past four months.

The old approach: manually gathering context from Linear, Slack and Notion, then manually updating each page. A multi-day project full of context-switching.

The Solution

We used Cursor with MCP (Model Context Protocol) integrations to pull context from Linear, AirOps and Notion directly into the IDE. The agent queries shipped features and reads specs without us leaving the editor. For Slack context, we used Claude.ai, which has MCP integrations rolling out to select partners.

The second piece was an AGENTS.md file in the repo root. This file contains our style guide and detailed rules for eliminating AI writing patterns, informed by our Brand Kit from AirOps. Cursor reads it automatically and applies the rules to every edit.

How It Works

• Pull context via MCPs. The Linear MCP lets you query issues and project updates. Notion MCP provides access to specs and internal docs. "What features shipped in the Grids project since September?" returns Linear issues with descriptions and linked Notion pages. Claude.ai's Slack integration lets us search channel history for additional context on feature discussions and decisions.
• Review existing docs. With the feature context loaded, the agent reads current doc pages and identifies gaps: outdated screenshots, missing parameters.
• Generate updates. The agent drafts updates following AGENTS.md rules. It knows our structure and terminology.
• Review diffs in Gitbook. Our docs sync to Gitbook via Git. Every change appears as a diff. We review proposed changes, approve or adjust, then merge.

What Made This Fast

• Single repo access. All docs live in one repository. The agent can read any page, understand cross-references, and maintain consistency across the entire docs site.
• MCP context injection. Instead of copy-pasting from Linear into prompts, the agent queries directly. A feature that shipped three months ago is just as accessible as one from last week.
• Iterative rule refinement. When output quality drifted, we added a rule. The fix applied to all future edits without re-prompting.
• Git-based review. Diffs showed exactly what changed. Accept or modify each change with full visibility into what the agent touched.

AGENTS.md is Key

Most AI writing sounds like AI writing. Same throat-clearing openers, same formulaic structures. We addressed this by encoding anti-patterns directly into our rules file. We started with our AirOps Brand Kit, which already contained our voice guidelines and terminology, then expanded it with specific rules for the docs repo.

The file includes:

• Structure rules. Every page follows the same hierarchy: YAML frontmatter, single H1, introduction, then H2/H3 sections in a predictable order.
• Terminology enforcement. We use "Workflow" not "app," "Step" not "component," "Grid" not "spreadsheet." The agent follows these consistently.
• Anti-slop rules. A detailed section on phrases to remove ("Here's the thing:", "Let that sink in") and structures to avoid (binary contrasts, repetitive rhythms).

When we spotted a pattern we wanted to fix during the project, we added it to AGENTS.md. The next edit incorporated the new rule.

Usage Example

A typical session:

1. Ask Cursor what Grids features shipped since last docs update
2. Agent queries Linear MCP, returns list of issues with descriptions
3. Open the relevant docs page
4. Ask agent to update the page with new features, following AGENTS.md
5. Review diff, adjust any phrasing, commit
6. Move to next page

For pages needing screenshots, we experimented with the BrowserBase MCP, which uses computer use to navigate the product and capture screens. It handled most user flows surprisingly well. Complex interfaces like our Studio still needed manual screenshots.

Constraints

• Screenshot automation is early. BrowserBase worked for simple flows. Anything requiring drag-and-drop or complex interactions needed manual capture.
• Review is still necessary. The agent gets terminology and structure right. It occasionally misses nuance or adds details that need verification. Git diffs make review fast, but you still need to read them.

Why This Matters

• Rules files scale. One person adds a rule, everyone benefits. The agent doesn't forget or have a bad day where it ignores the style guide. Consistency improves over time as the rules file grows.
• Context access is the bottleneck. Gathering what shipped and understanding the feature took most of the time. MCPs collapse the gathering phase, leaving more time for actual writing and review.

A semi-technical person with domain knowledge and access to these tools has significant leverage. This project took an afternoon. The old approach took multiple days.

What's Next

We're bringing AirOps context everywhere. Your Brand Kit and Knowledge Bases should be accessible to any tool you use, whether that's Cursor or your CMS. The patterns we tested here (rules files and context integrations) point toward that future. The AGENTS.md approach works because rules live where the work happens. We're exploring how to make this portable: your AirOps brain available in any environment where you create content.