AI Workflow

AI workflow issues stem from missing context files, incorrect prompts, or AI generating code that doesn't match codebase patterns. Verify context files are accessible and prompts reference them explicitly.

AI Generates Incorrect Code

Symptoms: AI produces code that doesn't compile or doesn't match codebase patterns.

Diagnosis: AI lacks context about codebase conventions.

Solution:

Reference context files in prompts:

"Read llms/CORE.md and llms/AUTH_PATTERNS.md, then implement sign-in page"

Key context files:

• llms/CORE.md - Development rules and conventions
• llms/CODEBASE.md - Architecture and navigation
• llms/AUTH_PATTERNS.md - Authentication patterns
• llms/BILLING.md - Billing integration
• llms/SECURITY.md - Security requirements
• llms/TESTING.md - Testing standards

AI Uses Wrong Import Paths

Symptoms: AI generates imports like import { auth } from "~/lib/auth" instead of workspace imports.

Diagnosis: AI not aware of workspace package structure.

Solution:

Point AI to correct pattern:

"Use @workspace/* packages for imports. Import from @workspace/auth/server,
not ~/lib/auth"

Correct pattern:

// ✅ Correct
import { getCurrentSession } from "@workspace/app-shell/lib/auth/server";

// ❌ Wrong
import { getCurrentSession } from "~/lib/auth/server";

AI Forgets Security Helpers

Symptoms: AI generates Response.json() instead of secureUserJson().

Diagnosis: AI not aware of security helper requirements.

Solution:

Prompt AI explicitly:

"Read llms/SECURITY.md and use secureUserJson from @workspace/security
for all API responses"

AI Uses Non-Existent APIs

Symptoms: AI references api.autumn.getSubscription or other non-existent Convex queries.

Diagnosis: AI hallucinating based on common patterns rather than actual codebase.

Solution:

Ask AI to verify before generating:

"Check what Convex queries exist in convex/autumn.ts before using them.
Use ctx.check() for feature access, not getSubscription()"

AI Adds Rate Limiting to Mutations

Symptoms: AI adds assertLimitAction() to userMutation which fails at runtime.

Diagnosis: AI doesn't understand action vs mutation distinction.

Solution:

Correct the pattern:

"Move rate limiting to a userAction. Use ctx.runMutation() to call the mutation
from the action. Read llms/CONVEX.md for the pattern."

Correct pattern:

// Action with rate limiting
export const createTicket = userAction({
  handler: async (ctx, { title, description }) => {
    await assertLimitAction(ctx, {
      scope: "support:create",
      viewerId: ctx.viewerId,
      max: 5,
      windowMs: 3600_000,
    });

    return await ctx.runMutation(api.support._insert, { title, description });
  },
});

// Internal mutation (no rate limiting)
export const _insert = userMutation({
  handler: async (ctx, { title, description }) => {
    await ctx.db.insert("supportTickets", {
      userId: ctx.viewerId,
      title,
      description,
      status: "Open",
      updatedAt: Date.now(),
    });
  },
});

AI Context Files Not Found

Symptoms: AI says it cannot find llms/CORE.md or other context files.

Diagnosis: AI doesn't have access to repository files or path is wrong.

Solution:

Provide full path:

"Read the file at /llms/CORE.md"

Or ask AI to list files first:

"List files in the llms/ directory, then read CORE.md"

AI Generates Code Without Tests

Symptoms: AI implements features but doesn't generate tests.

Diagnosis: Tests not explicitly requested.

Solution:

Always request tests:

"Read llms/TESTING.md and implement the UserMenu component with unit tests.
Use TestServicesProvider for the test setup."

Related Documentation

• AI Workflow Overview - AI-first development patterns
• Templates - Code templates for AI
• Commands - AI command reference