Hey Cursor & AI coding community!
I’ve built something I think could make Cursor even more powerful for production development, and I’d love both community feedback and the Cursor team’s thoughts.
The Problem:
We all love Cursor for AI-assisted coding, but maintaining consistency across a team can be challenging. Sometimes it generates Next.js code when we use Vite, or puts components in unexpected places. Every team member gets slightly different results when asking for similar features.
The Solution:
AISpec - a simple specification layer that makes AI coding assistants respect your project’s architecture and patterns. Here’s a real example from our project:
RootAISpec: root {
What:
- Frontend project called Nucleus
- Has Projects feature that allows users to create, edit and delete projects
- A project has a name, description, and a system prompt
- Projects allows users to chat using custom system prompt and uploaded files
- In the future, will have agents for automating tasks such as marketing
- The project is built with React, TypeScript, vite, TailwindCSS, and Clerk and yarn as the package manager
Boundaries:
- Frontend will be hosted on AWS in an S3 bucket, with a CloudFront distribution
- The project is built with React, TypeScript, vite, TailwindCSS, Antd and Clerk and yarn as the package manager
- hooks for calling backend are in src/api/
- UI pages go in src/pages/
- UI components go in src/components/
- Icons mostly use Antd Icons
- For Modals, Tables, Forms, etc. use Antd
- No use of shadcn/ui
- No use of Next.js
Success:
- The project is a successful project.
- Free of bugs and errors
- Uses best practices for React, TypeScript, TailwindCSS, Antd and Clerk
Technical:
- routing: "@generouted/react-router"
- styling: "antd"
- theme: "custom"
- httpClient: "axios"
- auth: "Clerk, @clerk/clerk-react"
- queryClient: "@tanstack/react-query"
- queryDevtools: "@tanstack/react-query-devtools"
- This is a frontend only project
- The project is built with React, TypeScript, TailwindCSS, Antd and Clerk.
- Project will be deployed on AWS
- Will use FastAPI for the backend in a separate project
path:
current path: src/
}
What makes AISpec different is its granular, hierarchical approach. While .cursorrules provides project-wide rules, AISpec lets you define specifications at any level - from project root down to individual complex components.
For instance, in our Nucleus project, we start with a root.aispec that defines our global React + Vite architecture. But when building a complex feature like our history page, we create a specific spec that defines exact requirements:
Create a responsive history page for the Nucleus frontend project with the following specifications:
What:
1. The history page should display a list of previous chats
2. Key components:
- Header Section:
- Title: "Your chat history"
- A prominent "Start New Chat" button on the top-right
- Search Bar:
- Search input field with placeholder "Search your chats..."
- Display total number of chats (e.g., "440 previous chats")
- Include a "Select" link for filtering options
- Chat History List:
- Each chat displays:
- Chat title (e.g., "Growth Strategy Analysis")
- Timestamp (e.g., "Last message: 2 minutes ago")
- Associated project (e.g., "Market Research") as a badge
- Hover effects to indicate clickable items
- Pagination or lazy loading for chat histories
Boundaries:
- Build using React, TypeScript, TailwindCSS, and Antd components
- Use Antd Icons for search and interactive UI elements
- Place in src/pages/(pages)/history/index.tsx
- Fetch data using hooks from src/api/
- Use @generouted/react-router for navigation
- Use @tanstack/react-query for data fetching and state management
- Ensure responsive design for all viewports
Success:
- Adheres to dark theme design of Nucleus project
- "Start New Chat" button navigates correctly
- Search functionality works smoothly
- Chat items link to corresponding chat pages
- Responsive and bug-free implementation
- Follows React and TypeScript best practices
Technical:
- Component Placement:
- Main page: src/pages/(pages)/history/index.tsx
- Reusable components: src/components/
- Mock Data: Include sample chats for development
- Theme: Custom dark theme matching project design
This hierarchical specification means the AI assistant always has the most relevant context for what it’s building, whether it’s a new feature, page, or component. The more complex the component, the more detailed the spec can be - and it all inherits from the parent specifications.
We’re currently using this with Cursor by copying our AISpec into prompts. The results have been promising - the AI sticks to our specified frameworks, file structure, and patterns more consistently.
Here’s a practical example:
Without AISpec:
Me: “Add a new Projects component”
Cursor: Generates code using Next.js and shadcn/ui
With AISpec:
Me: “Add a new Projects component with the project AISpec”
Cursor: Generates code using React + Vite, Antd, and puts it in src/components/
Native Integration Potential:
While copying specs into prompts works, native Cursor integration could make this much more seamless. The IDE could automatically understand your project’s architecture and requirements, helping maintain consistency across the team without extra steps.
Next Steps:
The project is open source and available at https://github.com/cbora/aispec . If you’re running into similar challenges with AI-assisted development, give it a try and let me know what works and what doesn’t.
For the Cursor team: Would love to discuss the possibility of native integration if this resonates with your vision for the tool.
Looking forward to your thoughts.
Chris