ai-collaboration

AI Collaboration Guidelines

The 3-Stage Agentic Loop

Every code generation task MUST follow this loop:

Stage 1: PLAN (gather context first)

Before writing ANY code, the AI MUST:

1. Read the relevant source files to verify current state — do NOT rely on memory
2. Identify which .cursor/rules/ files apply to this task
3. List the files to modify and explain why
4. Do NOT write code yet

Prompt template:

Analyze the current codebase and plan how to implement [feature]. 
List the files you'll modify and why. Don't write code yet.

Stage 2: IMPLEMENT (follow constraints)

When generating code:

• Follow ALL active .cursor/rules/ constraints
• If unsure about auth patterns, re-read supabase-auth-security.mdc
• If unsure about params/layouts, re-read nextjs15-params.mdc
• Use unknown + Zod validation instead of any for external data
• Return ActionResponse<T> from all Server Actions (see below)

Stage 3: VERIFY (confirm before declaring done)

After generating code, the AI MUST self-check:

• No getSession() on the server (MUST be getUser())
• No synchronous params or searchParams access
• No @supabase/auth-helpers-nextjs imports
• No any types — use unknown + type narrowing
• Every API route has Zod validation
• Every error is caught and returns { error: string }
• New tables have RLS enabled
• loading.tsx and error.tsx exist for data-fetching pages

Report issues BEFORE the developer runs the code.

Skeptical Retrieval Rule

NEVER trust stored knowledge about the codebase. Before modifying a file:

1. Re-read the file to verify its current contents
2. Check imports and exports to ensure they match expectations
3. Verify that function signatures haven't changed

This prevents generating code that references stale function signatures, deleted files, or renamed exports.

Standard Patterns

ActionResponse Type (use for all Server Actions)

type ActionResponse<T = void> = 
  | { success: true; data: T }
  | { success: false; error: string }