How It Works

What Are AI Conventions

Every ShipUI theme ships with a set of battle-tested rules files and an architecture guide for AI coding tools. These give Cursor and Claude Code specific, opinionated instructions about how to structure your code, which patterns to use, and what to never do.

Free cursor rules are generic. They tell AI to "use TypeScript" or "follow best practices." The conventions included with ShipUI themes tell AI exactly how to organize files, exactly how to handle errors, and exactly what architectural boundaries must never be crossed. Every rule explains why it exists and what breaks without it.

The result: AI that makes implementation decisions but stays within the architectural constraints you define.

Getting Started

Setup takes about two minutes. The conventions work with any existing project or a new one.

• 1
  Locate the conventions

  Every ShipUI theme includes .cursorrules and CLAUDE.md in the project root, along with the architecture guide. These are ready to use out of the box.
• 2
  Copy your stack folder into your project root

  Pick the folder that matches your stack (for example, nextjs-typescript). Copy .cursorrules and CLAUDE.md into the root of your repository.
• 3
  Customize for your project

  Open both files and fill in your project-specific details: the stack section, your dev and build commands, and any project-specific conventions. The architecture rules come pre-filled and should not need changes for most projects.
• 4
  Start coding

  Cursor reads .cursorrules automatically. Claude Code reads CLAUDE.md automatically. Both tools will follow the guardrails from this point forward without any additional setup.

File placement

Using the Universal config

If your stack is not one of the three named stacks, or if you want a language-agnostic baseline, start with the universal folder. It contains the architecture principles and the "Don't" rules that apply to any project. You can layer stack-specific rules on top.

A Note on Rule Compliance

These conventions reduce the frequency and severity of rule violations, but they cannot eliminate them entirely. AI models can drift during long conversations, complex tasks, or ambiguous prompts.

Treat the rules as strong architectural guidance rather than guarantees.

Recommended complementary tools

For the best results, pair these conventions with at least one automated code review layer that catches what the AI misses:

Included Stacks

Each stack includes a .cursorrules file for Cursor, a CLAUDE.md file for Claude Code, and all rules tailored to that framework's conventions.

Rule Categories

The rules are organized into four categories. Each stack covers all four.

How Rules Are Written

Every rule follows the same four-part format. This is what makes it more effective than a list of bullet points: AI tools understand context and examples, not just directives.

When an AI tool sees a rule written this way, it understands not just what to do but what to avoid and why. This reduces the back-and-forth where AI produces code that technically works but violates the conventions your project requires.

Architecture Guide

Every ShipUI theme includes a plain-English architecture guide covering the five structural mistakes that AI makes most often. It is designed for developers who learned to code with AI assistance and want to understand the reasoning behind the rules.

What the guide covers

• 1
  The God File problem

  Why AI puts everything in one file, how it breaks, and how to structure by responsibility instead.
• 2
  Database calls in the wrong place

  Why direct database imports in route handlers and components cause maintenance debt, and how a service layer fixes it.
• 3
  Silent error handling

  Why empty catch blocks and generic error messages make debugging impossible, and the pattern that gives you context when things break.
• 4
  Missing pagination

  Why unbounded list queries work fine in development and fail in production, with the minimum implementation required on every list endpoint.
• 5
  Secrets in source code

  Why hardcoded credentials are a production risk regardless of repository visibility, and the environment variable pattern that prevents it.

Pre-Shipment Checklist

Each theme includes a checklist that maps directly to the rules. Before marking any task complete, verify each item. The checklist is embedded in the CLAUDE.md and .cursorrules files so AI tools can reference it during code review.

Security

• No secrets or credentials in source code
• All user input validated on the server before use
• Auth checked on every protected endpoint
• .env files in .gitignore
• CORS configured with specific origins, not wildcard

Structure

• Business logic separated from route handlers and components
• Database access goes through a service or repository layer
• One responsibility per file
• Consistent naming conventions throughout

Data

• All list endpoints paginated with limit and offset
• No database calls inside loops
• Transactions used for multi-step operations
• Schema changes handled through migrations

Error Handling

• No empty catch blocks
• Structured error responses returned to clients
• Errors logged with enough context to debug
• No stack traces exposed to end users