Guardrails

Guardrails

Guardrails are organization-wide standards that apply as defaults to all projects. They tell the AI what your organization uses for design, technology, and security — so generated PRDs, agent instructions, and implementation guidance reflect your actual environment rather than generic best practices.

Why Guardrails Matter

Without guardrails, SpecGraph's AI has no way to know that your organization uses React and not Vue, or that your design system is built on shadcn/ui and not Tailwind alone, or that you operate under HIPAA and not just general security best practices. Every organization is different, and guardrails capture those differences.

When guardrails are set:

• Generated PRDs include technology-appropriate requirements.
• AI coding agents receive project context that matches your stack and standards.
• The MCP server's get_control_manifest tool returns guardrails to Claude Code, keeping implementations within your organization's approved patterns.

The Three Guardrail Types

Navigate to Settings → Guardrails to see the three sub-sections:

Design System

Defines your organization's visual and UI standards. This should cover:

• Component library — what UI framework you use (shadcn/ui, Material UI, Ant Design, etc.)
• Color system — your brand colors, semantic tokens, and dark mode approach.
• Typography — font families, type scale, and heading hierarchy.
• Spacing and layout — grid system, container widths, breakpoints.
• Components — button variants, form patterns, card styles, modal conventions.
• Accessibility — your compliance targets (WCAG 2.1 AA, etc.) and focus management standards.

Tech Stack

Defines your organization's technical standards. This should cover:

• Frontend — frameworks, build tools, state management, routing.
• Backend — runtime, framework, API patterns (REST, GraphQL, tRPC).
• Database — database type and ORM/query patterns.
• Infrastructure — cloud provider, deployment platform, CDN.
• CI/CD — pipeline tools, testing requirements, deployment gates.
• Monitoring — logging, error tracking, performance monitoring.
• Approved libraries — specific packages your organization uses and recommends.

Security & Compliance

Defines your organization's security and compliance requirements. This should cover:

• Compliance frameworks — SOC 2, GDPR, HIPAA, PCI-DSS, ISO 27001, or others.
• Authentication requirements — password policy, MFA requirements, SSO standards.
• Authorization model — role-based access control, least privilege principles.
• Data handling — encryption standards, data residency, retention policies.
• Audit logging — what events must be logged and for how long.
• Dependency management — vulnerability scanning, approved package registries.

Setting Guardrails

Each guardrail page offers three ways to create content:

Quick Start Presets

Pre-built templates for common setups. For example, the Design System section has presets for shadcn/ui, Material UI, and Ant Design. Click a preset to load it into the editor. This is the fastest way to get started if your stack matches one of the presets.

Manual Editing

Click Edit to open a text editor and write or paste your guardrail content directly. Guardrails are formatted as markdown. Use headings to organize sections and bullet points for specifics.

Generate with AI

Click Generate with AI to have the AI create a guardrail draft based on your organization's name and any content already in the editor. The AI produces a comprehensive starting point that you then review and edit to match your actual standards.

Tip: Generate with AI works best when you already have some content in the editor. A few seed lines like "We use Next.js 16, React 19, and Tailwind CSS 4" give the AI much more to work with than an empty editor.

Saving Guardrails

After editing, click Save to persist the guardrail to your organization. It takes effect immediately — new projects created after saving will use the updated guardrails, and existing projects that haven't yet generated agents can benefit from the updated standards.

Project-Level Overrides

Guardrails set here are organization-level defaults. Individual projects can have their own project-level context that overrides the organization defaults. This is useful for projects that use a different tech stack than the organization's standard — for example, a legacy project that still runs on an older framework.

Project-level context is managed from the project detail page under the Context sections (Design System, Tech Stack, Security).