Clarity AI
Back to Blog
Configuration

Tech Stack Sync: Making AI Project-Aware with .clarityrules

Ahmed Attafi
February 13, 2026
29 min read
Tech Stack Sync: Making AI Project-Aware with .clarityrules
Development

The most common reason developers reject AI suggestions is because the code is "legacy" or "doesn't fit our pattern." The AI might suggest React class components when your team uses functional components with Hooks. It might suggest a library you're trying to migrate away from. ClarityAI eliminates this friction by syncing your tech stack context automatically.

The Concept of "Project-Awareness"

To AI models, the world is a flat list of possibilities. They don't know that your project is currently in the middle of a migration from Axios to TanStack Query. They don't know that you've forbidden the use of any in TypeScript. Without local context, the AI's suggestions are a gamble. ClarityAI removes the gambling from the process by performing a local scan of your workspace.

The Automatic Scan Engine

Every time you use @clarity, the extension does a sub-second scan of your project root. It looks for several key "Signal Files":

📦 dependencies.json / package.json

We extract version numbers for all key libraries. If you are on Next.js 14, we tell the AI to use Server Actions. If you are on React 17, we prevent it from suggesting useTransition.

📜 .clarityrules (Custom Rules)

This is your project's "Technical Constitution." Defined by you, enforced by us. "Use Tailwind utility classes only," "No external state managers," "Follow SOLID principles".

Deep Dive: .clarityrules Architecture

The .clarityrules file can be as simple or as complex as you need. It supports a hierarchical structure that allows you to set global rules and folder-specific overrides. For example:

- Global: "Always use TypeScript strict mode." - src/components: "Always use Shadcn/UI for base components." - src/api: "Enforce JWT-based authentication for all routes."

Context Lifecycle

sequenceDiagram
    participant VS as VS Code Workspace
    participant C as ClarityAI Engine
    participant AI as AI Agent (GitHub Copilot)
    
    VS->>C: Background Scan (package.json, .clarityrules)
    C->>C: Compile Constraint Map
    User->>C: "@clarity Create a contact form"
    C->>AI: "Create a contact form using React 18, Tailwind, and our specific project style rules"
    AI->>User: Correct, Project-Aligned Code Snippet

Result: The "Zero-Revision" Workflow

By making the AI "Project-Aware," you reduce the need for manual "correction prompts" by up to 80%. You no longer have to tell the AI 3 times to "not use classes." It knows from the first prompt. This results in what we call the "Zero-Revision" workflow—where the first suggestion is actually the one you ship to production.