Specstory and Cursor Rules: Derivation and Usage¶

This document explains how Specstory (conversation history) feeds into derived Cursor rules, and how Cursor uses those rules to guide AI behavior in the IDE.

1. Overview: Two Sides of the Same Loop¶

Specstory captures what was said and decided in Cursor conversations; derived rules turn that into persistent instructions for future Cursor sessions. Cursor then applies those rules when answering or editing code.

2. What Is Specstory?¶

Specstory is a tool that exports Cursor (or similar AI-IDE) conversation history into markdown files. Each conversation becomes a timestamped file (e.g. in .specstory/history/), preserving:

• User messages and AI replies
• Tool calls and results (when included in the export)
• Decisions and context that were discussed

Why it matters for rules: Those transcripts contain repeated patterns (e.g. “always use repository pattern for DB access”, “never put Prisma in controllers”), tech stack choices, and project-specific conventions. Deriving rules from history turns that implicit knowledge into explicit, reusable instructions.

3. How Specstory Derives Cursor Rules¶

Derivation is the process of turning conversation history (and optionally other docs) into Cursor rule files. It can be manual (someone reads history and edits .mdc files) or assisted (e.g. an AI or script that proposes rule text from history).

What gets derived (examples):

• Project overview and stack: e.g. “Full-stack Nx monorepo: React 19, NestJS, Prisma…” from many conversations that assume this stack.
• Import and layering rules: e.g. “libs MUST NOT import from apps” from repeated corrections or discussions.
• Observability and env: e.g. “Sentry sampling via env vars” from conversations about production safety.
• Conventions: e.g. “no Prisma outside repositories”, “DTOs required for all I/O”.

In this repo, derived-cursor-rules.mdc is the main rule file that holds project overview, tech stack summary, import rules, and observability notes—all of which can be inferred or confirmed from Specstory history and project docs.

4. How Cursor Uses Rules¶

Cursor uses rule files (.mdc or similar) to inject instructions into the AI’s context so that answers and edits follow project conventions without the user repeating them every time.

Rule file structure (frontmatter + body):

• description: Short summary; can be used for relevance when the user’s request matches.
• globs: Pattern(s) for when the rule applies (e.g. * for all files, **/*.ts for TypeScript only).
• Body: Markdown content that is injected into the AI context when the rule is selected.

Selection behavior (conceptual): Cursor typically includes rules that match the current file (via globs) and/or the current conversation (via description or “always apply” rules). So when you’re in a backend file, backend rules and project-wide rules (e.g. globs: *) are more likely to be included.

5. End-to-End: From Conversation to Applied Rule¶

Putting it all together: a conversation is captured by Specstory, then (through derivation) its lessons are written into Cursor rules; in a later session, Cursor loads those rules and injects them into the AI context so the same conventions are followed.

6. Summary Diagram¶

Takeaways:

• Specstory = conversation history (what was discussed and decided).
• Derived Cursor rules = persistent instructions distilled from that history (and other docs).
• Cursor = uses those rules (by glob and context) to inject project conventions into the AI so that code and answers stay aligned with the project’s vision and patterns.

This creates a feedback loop: more conversations → richer history → better or updated rules → more consistent behavior in future Cursor sessions.