Skip to content
HM
← Back to blog

Spec-driven agentic development with Cursor

How I use Cursor, markdown artifacts, ADRs, and multi-agent workflows to ship quality at scale — from small features to large brownfield platforms.

cursoragentic-engineeringspec-drivenarchitectureadr

AI coding agents are powerful. Without structure, they are also chaotic.

I treat agentic engineering as a pipeline with guardrails: clarify intent in markdown, freeze a behavioural spec, record architectural decisions, decompose work, then let Cursor implement against project rules that encode how we build software.

The pipeline

Loading diagram…
  1. REQUIREMENTS — user stories, acceptance criteria, MoSCoW priorities
  2. STACK — language, runtime, repo layout, testing strategy
  3. SPEC — API contracts, data models, state transitions, edge cases
  4. PLAN — modules, integration points, failure modes
  5. TASKS — atomic, independently testable units
  6. Implement — Cursor agents execute; humans review architecture and blast radius

The critical move is the spec freeze. Agents should not invent product behaviour mid-implementation.

The normal MD flow

Markdown files are the interface between humans and agents. Each file has a purpose, an owner, and a human gate before the next phase starts.

Loading diagram…
File Purpose Gate
REQUIREMENTS.md Stories, acceptance criteria, scope Refine signed off — no code yet
STACK.md Language, runtime, layout, testing Stack locked before design
SPEC.md Frozen behavioural contracts Spec freeze — source of truth
PLAN.md Modules, integrations, risks Plan signed off
TASKS.md Atomic, ordered work units Tasks ready for build
REVIEW.md Pass/fail vs spec and standards Review before merge

Agents read and write these artifacts. Product behaviour is decided in REQUIREMENTS and SPEC — not in a chat thread that disappears.

Bigger projects

A single Cursor session is enough for a small feature. Platforms need a different shape.

Brownfield first

Detect greenfield vs brownfield. On existing systems, build or update a code review graph before planning so impact radius is visible. PLAN.md should name packages and modules that change — not hand-wave “touch the backend.”

Bounded tasks

One TASKS.md item = one focused agent session. Never ask an agent to “implement the whole platform.” Split by milestone: foundation → features → polish.

Multi-agent roles

Specialized roles with human gates beat one mega-prompt:

Loading diagram…
  1. Requirements analyst
  2. Tech-stack advisor
  3. Spec writer
  4. Architect
  5. Task planner
  6. Implementer
  7. Reviewer

The reviewer checks blast radius: affected callers, tests, and integration points against SPEC and Cursor rules.

Shared rules and MCP

Global Cursor rules (API design, DB design, system design, production-grade code, UX) plus repo-specific rules give every agent the same bar. MCP servers connect docs, CI, and trackers — agents discover tool schemas before calling them.

Loading diagram…

Agents call GetMcpTools to discover schemas before CallMcpTool. Custom MCP servers — often scaffolded by the agent itself — extend the toolchain beyond what ships in the IDE. Extensions can register their own MCP servers so agents get domain tools (Git, PRs, issues) without manual wiring.

Server vector repository (100+ repos)

At enterprise scale, local IDE context is not enough. A server-hosted vector repository continuously indexes code, docs, ADRs, and runbooks across many repos — with service ownership and domain metadata on every chunk.

Loading diagram…

Pair that with a feature → service → repo → API map. Semantic search plus the map answers “where is this handled?”, surfaces dependency gaps, and narrows blast radius when hunting issues.

Engineers and Cursor agents then ask natural-language questions over the same store (RAG). The LLM answers with grounded citations instead of guessing across 100+ repositories. Plan, implement, and review steps should query that store via MCP — not rely on what fits in a single prompt window.

Keeping ADRs

Significant trade-offs belong in Architecture Decision Records, not buried in Slack or agent transcripts.

Location: docs/adr/ADR-NNN-title.md

When to write one: database choice, service boundaries, framework selection, security architecture, significant infra changes.

Lifecycle: Proposed → Accepted → Deprecated | Superseded by ADR-XXX

Template

# ADR-NNN: [Title]
Status: Proposed | Accepted | Deprecated | Superseded
Date: YYYY-MM-DD

## Context
## Decision
## Consequences (Positive / Negative / Risks)
## Alternatives Considered
## Implementation Notes

How ADRs connect to the MD flow

  • PLAN.md references ADRs for module boundaries and integration choices
  • SPEC.md implements accepted ADRs — agents do not reopen frozen decisions
  • New trade-offs mid-build → write a new ADR before changing direction
  • Superseded ADRs link forward so history stays navigable

Cursor rules as quality infrastructure

Project rules are how you scale taste:

  • API design standards
  • Database and migration practices
  • System design impact analysis
  • Production-grade principles (KISS, DRY, SOLID, security)
  • UX and accessibility expectations

Every agent session inherits the same bar. That is how you get consistency across squads and products — not by hoping the model “just knows.”

What this is not

This is not “AI writes the architecture.” Architecture judgment stays human — in REQUIREMENTS, SPEC, PLAN, and ADRs. Agents amplify execution once contracts are clear.

Where I apply it

I use this workflow on enterprise platform work and on products like Arena360 — multi-app systems where API contracts, client surfaces, and operational constraints must stay aligned.

If you want to talk about adopting this in your org, reach out.