AI-Assisted Development

Mosayic is built on the assumption that you’ll use an AI coding assistant — Claude Code, Cursor, GitHub Copilot, Aider, or similar — to write most of your features. The Blueprint cards even ship with ready-to-paste prompts.

This page covers how to get good results, and how to avoid the predictable ways AI-assisted projects go off the rails.

What works well

• Implementing a feature card from the Blueprint. The prompt is curated, the patterns are known, the AI has plenty of context to draw on. Success rate is very high.
• Writing new SQL migrations with RLS policies. The starter has examples; the AI can pattern-match.
• Wiring up a new screen that follows existing UI conventions.
• Refactoring small functions when you can describe the goal precisely.
• Writing tests for code that already exists and works.
• Debugging error messages when you paste in the full error and the relevant file.

What works poorly

• “Build me an app”-scale prompts. Even great AI gets lost. Break work into small, testable steps.
• Architectural decisions. AI will happily justify any architecture you ask it to compare. It doesn’t have your specific constraints. Make these calls yourself.
• Adding a giant new dependency because the AI saw it once. Always question new deps. Mosayic’s stack is already opinionated; sticking to it keeps your codebase coherent.
• Anything that requires running and verifying the actual app on a phone. The AI can’t see what your app looks like. Hand off to yourself for visual review and device testing.

Don’t ship code you can’t read

The single rule that keeps AI-assisted projects shippable: you should be able to read every file in your codebase and explain what it does. Not write it from scratch — read it.

If the AI generates code you don’t understand:

• Ask it to explain
• Ask it to simplify
• Reject it and write a smaller chunk yourself

The cost of “I’ll figure it out later” code is paid in production, at 3 AM, when something breaks and you can’t debug it.

Don’t give the AI your secrets

Standard caveat for any AI tooling, but worth repeating:

• ❌ Never paste a .env file into a prompt
• ❌ Never paste a private key, API key, or service account JSON
• ❌ Never paste real user data
• ✅ Use placeholders: <API_KEY>, <USER_ID>, etc.
• ✅ Use redacted versions of error messages

If you accidentally paste a secret, rotate it immediately. Assume any secret that touched an LLM provider is compromised.

Recommended setup: Claude Code

Claude Code is the assistant Mosayic was designed around. It’s a terminal-based AI that can:

• Read and edit files in your project
• Run shell commands and read their output
• Verify its own work (run tests, check things compile, etc.)

To set up:

npm install -g @anthropic-ai/claude-code
cd <project>
claude

The first run walks you through Anthropic API key setup. From then on, just cd into your project and run claude to start a session.

Why Claude Code over a chat interface

Three reasons:

1. It edits files directly. No copy-paste cycle. You ask for a change; it makes the change; you git diff to review.
2. It can run things. Tests, type checks, linters. You say “make it work”; it iterates until things pass.
3. It has the whole codebase as context without you having to paste files in. It can read files on demand.

You can also use Cursor (a VS Code fork with similar capabilities) or Aider (terminal-based, model-agnostic). The Blueprint prompts are model-agnostic.

Working effectively

A few patterns that consistently produce better results:

Be specific

Bad: “Add notifications”

Good: “Add a hook called useUnreadCount in mobile/hooks/useUnreadCount.ts that subscribes to the notifications table in Supabase, filtered by user_id = auth.uid() AND read_at IS NULL, and returns the count. Use it in mobile/components/TabBar.tsx to show a red dot on the inbox tab.”

One concern at a time

Don’t ask for a feature, a refactor, and a test in one shot. Ship the feature, then refactor, then test — three separate AI sessions if needed. Each focused, each reviewable.

Verify, don’t trust

After every AI change:

• git diff to see what actually changed
• Run the app and try the change end-to-end
• Run the tests if you have them

Trust-but-verify breaks down with AI — the AI’s confidence in its own output is uncalibrated. Treat the output as a draft.

Capture what worked

When the AI gets a feature right, capture the approach. Save the prompt, the resulting commit, and any debugging you had to do. Future-you can reuse the pattern.

Tip

The Blueprint cards are exactly this idea — capturing the prompt + the files-to-touch for common features so you don’t have to figure them out yourself each time.

When AI gets stuck

Sometimes the AI flails — burning attempts on the same broken approach. Common fixes:

• Restart the session. A fresh conversation often gets unstuck where a long one is bogged down.
• Add constraints. “Don’t add new dependencies.” “Use React hooks, not class components.” “This file is the source of truth — don’t change it.”
• Hand-write the hard part. If the AI can’t grok the data structure, write the type definitions yourself, then ask the AI to fill in functions.
• Ask it what it’s confused about. “Before writing code, tell me what you understand about the goal.” Forces the AI to surface assumptions you can correct.

What about hallucinated APIs?

AI sometimes invents library functions that don’t exist. Two safeguards:

• TypeScript catches most of it. A non-existent function won’t compile.
• Run the code. “It looks right” isn’t shipping; “it ran” is.

If you get a confident reference to a method that doesn’t exist, point this out: “There is no supabase.auth.refreshUser() function. Check the Supabase JS docs and use the correct method.” This usually gets the AI to course-correct.