.cursorrules for Project Context Management

by @ kryptobaseddev

## Key Principles

- **Code Quality & Style**

  - Write concise, maintainable, and strongly typed code with accurate TypeScript implementations.
  - Embrace functional, declarative programming. Avoid OOP and classes.
  - Limit files to a maximum of 150 lines; refactor into smaller modules if exceeded.
  - Prefer iteration and modularization over duplication.
  - Use descriptive, semantic variable names with auxiliary verbs (e.g., `isLoading`, `hasError`).
  - Use lowercase with dashes for directories and files (e.g., `components/auth-wizard`).
  - Favor named exports for components.
  - Adopt RORO (Receive an Object, Return an Object) for function parameters/returns.
  - Always attain to use DRY (Don't Repeat Yourself) principles.
  - Conduct regular code reviews and frequent refactoring sessions to ensure consistency and quality.
  - Check and improve Web Vitals (LCP, CLS, FID) to maintain performance and user experience.

- **Create 'Build Notes':**

  - You must create a 'Build Notes' file for each task group to track the progress of the task group we work on.
  - **Clarity & Brevity:** Keep notes concise, direct, and focused on the task at hand.
  - **Logical Naming:** Use a consistent naming convention that ties each notes file to a specific task and date.
  - **Incremental Updates:** Update notes as plans evolve or tasks are completed. Append rather than overwrite.
  - **Traceability:** Ensure that each decision or change in approach is recorded and easy to follow.

- **Review 'Project Contexts':**

  - You must review the `projectContext.md` as we need to ensure that the project context is up to date and accurate.
  - **Stability:** Treat context files as stable references, not daily scratchpads.
  - **Selective Updates:** Update context files only when there are significant, approved changes to requirements or project scope.
  - **Accessibility:** Make context files easily understandable and organized so future developers can quickly grasp the project’s core guidance.

- **Stack and Framework Conventions**

  - Target **Next.js 15+** and leverage the App Router, React Server Components (RSC), and SSR capabilities.
  - Use Zustand for state management in client components when necessary.
  - Maintain proper Shadcn UI management using `npx shadcn@latest add` for new components.
  - Follow a mobile-first approach and responsive design patterns.
  - Emphasize server-side logic, minimizing the usage of `use client` and other client-only APIs.
  - Structure project as Progressive Web App (PWA) with offline capabilities, app-like experience, and installability across devices.

- **Monorepo & Tooling**

  - If using a monorepo structure, place shared code in a `packages/` directory and app-specific code in `app/`.
  - Use `Taskfile.yml` commands for development, testing, and deployment tasks.
  - Keep environment variables and sensitive data outside of code and access them through `.env` files or similar configuration.

Below is a structured guideline to provide to the AI development agent, incorporating key principles and detailed rules for maintaining the `/ProjectDocs/Build_Notes/` and `/ProjectDocs/contexts/` directories.

---

### Rules for Build Notes Files

1. **Location & Naming:**

   - Store all notes files in `/ProjectDocs/Build_Notes/`.
   - Use a logical, descriptive naming convention, e.g., `build-title_phase-#_task-group-name.md`.
   - Use the `` to describe the build task.
   - Use the `` to apply the Phase # to the build task.
   - Use the `` to describe the task group name.
   - Example: `supabase-schema-standardization_phase-1_preparation-and-code-analysis.md`
     - `supabase-schema-standardization` is the build title
     - `phase-1` is the phase number
     - `preparation-and-code-analysis` is the task group name

2. **Content Structure:**

   - Begin with a brief **Task Objective** that summarizes what you aim to achieve.
   - Provide **Current State Assessment**: a short description of the current state of the project pertaining to the build tasks.
   - Provide **Future State Goal**: a short description of the future state of the project pertaining to the build tasks.
   - Follow with a **Implementation Plan**: a numbered list of **steps** containing checklist **tasks** to achieve the future state.
   - Update the **Implementation Plan** as tasks are completed and line out not applicable tasks. NEVER DELETE TASKS FROM THE PLAN.
   - If the plan changes or evolves, add new **steps** or **tasks**, rather than overwriting previous content.

3. **When to Update:**

   - **At Task Start:** Create or open the task-specific notes file and record the initial plan before coding.
   - **During Task Execution:** Add updates when plans change, difficulties arise, or new insights emerge.
   - **At Task Completion:** Append a summary of what was done and verify it aligns with the original objective.

4. **Style & Tone:**

   - Keep notes succinct, on-topic, and free of unrelated commentary.
   - Maintain a logical sequence so that future readers can understand the decision-making process without confusion.

5. **Completion of Build Notes:**

   - Once the build notes are complete, move the file to the `/ProjectDocs/Build_Notes/completed/` directory.
   - If build notes are deprecated and no longer needed, move the file to the `/ProjectDocs/Build_Notes/archived/` directory.

---

### Rules for Context Files

1. **Master Project Context (`projectContext.md`):**

   - Located in `/ProjectDocs/contexts/`.
   - Provides the overarching project scope, requirements, and design principles.
   - Only update this file if there are major changes to the project’s fundamental direction or scope.

2. **Additional Context Files:**

   - Supplementary files (e.g., `uiContext.md`, `featureAContext.md`) may be created for more detailed specifications on certain functionalities, designs, or areas of the application.
   - Keep these files stable. Update them only when new, approved changes need to be documented.
   - Reference these files frequently to ensure development aligns with established guidelines.

3. **Change Management:**

   - Record any changes to context files within the corresponding build notes file for that task.
   - Maintain a clear rationale for context changes to preserve transparency and alignment with the core project goals.

---

## Project Structure

Adopt a clear, modular directory structure:

Project Management Framework

A structured approach to organizing and documenting software development projects, emphasizing clarity, consistency, and collaboration.

Core Components

ProjectDocs Structure:
Organized documentation with build notes and context files (e.g., projectContext.md, appFlow.md).
Key Features:
- Build Notes Management: Systematic tracking of development progress.
- Context Awareness: Maintains project context to reduce misunderstandings.
- Task Organization: Breaks down tasks into manageable units.
- Progress Tracking: Clear system for monitoring task completion.

Technical Standards

Code Quality & Style:
- Maximum file size of 150 lines; refactor into smaller modules if exceeded.
- Functional, declarative programming approach (avoid OOP and classes).
- Semantic variable naming with auxiliary verbs (e.g., isLoading, hasError).
Stack & Framework Conventions:
- Next.js 15+ with App Router and React Server Components (RSC).
- Zustand for state management in client components.
- Shadcn UI management using npx shadcn@latest add.
- Mobile-first approach and responsive design.
- Emphasis on server-side logic.
- Progressive Web App (PWA) structure.

Project Structure

App Directory:
- Auth-related routes/pages (auth).
- Dashboard routes/pages (dashboard).
- API routes (api).
- Root layout (layout.tsx).
Components Directory:
- Shared UI components (shared).
- Feature-specific components (features).
- Shadcn UI components (ui).
Lib Directory:
- Supabase client and utilities (supabase).
- Global constants (constants).
- Custom React hooks (hooks).
- Custom middleware (middleware).
- Shared utility functions (utils).

Usage and Best Practices

Initial Setup: Create a ProjectDocs folder with contexts and build notes.
Context Files: Start with projectContext.md and add more as needed.
Build Notes: Use a structured format for task objectives, current state, future state, and implementation plans.
Customization: Modify the .cursorrules file to fit specific project needs.

Key Technologies:

Next.js
TypeScript
Shadcn UI
Supabase
Zustand

Overview of .cursorrules prompt

This framework provides a structured approach to managing software projects by organizing documentation, maintaining consistent coding standards, and enhancing collaboration. It emphasizes clear project context, systematic task management, and adherence to best practices for Next.js development.

Updated: March 17, 2025

A project management framework for Next.js projects, focusing on documentation, coding standards, and collaboration.

Usefull for: