ARK

Best Practices

A collection of habits, learned the hard way, for getting reliable output from AI tools when modifying ARK products. None of these are strictly required. All of them will save you time.

Prompting

1. Be specific

Generic prompts produce generic code. Specific prompts produce specific code.

Too vague:

Add user permissions to the app.

Better:

Add a role column (enum: owner, admin, member, viewer) to the team_members table via a migration. Update the RLS policies on boards, contacts, and deals so that viewer can select only, member can insert/update their own rows, and admin/owner can do anything. Don't change the existing policies on platform tables (profiles, audit_log).

Specificity forces you to make the design decisions yourself before the AI does. That's the whole point — you want the design, the AI wants to type.

2. Share CLAUDE.md first

Every session, every chat, every new AI conversation starts with CLAUDE.md in context. Agent tools read it automatically from the repo root. Chat tools need you to paste it.

Without CLAUDE.md, you get suggestions that:

  • Use client-side secret references that should be server-only
  • Disable RLS to "simplify" a query
  • Rename or remove columns instead of adding migrations
  • Touch the license validator "while we're in there"

With CLAUDE.md, most of this just doesn't happen.

3. Ask for a plan before code

For any change touching more than two files, request a plan first:

Before you code anything, give me a plan:

  • Which files you'll create or modify
  • What changes in each
  • Any migrations or config changes
  • Anything you're unsure about

Wait for me to approve before writing code.

Reviewing a plan takes 30 seconds. Undoing 400 lines of wrong-direction code takes much longer. Plans are cheap insurance.

4. Tell the AI what not to do

Explicit negatives work better than you'd expect:

Don't:

  • Touch src/lib/license.js
  • Remove or rename existing columns
  • Disable RLS
  • Introduce new dependencies
  • "Helpfully" refactor code I didn't ask about

Add these to any prompt that's touching adjacent code.

5. Break large changes into sub-tasks

If you're about to ask for "a complete overhaul of X," stop. Break it into:

  1. The schema change
  2. The backend logic change
  3. The UI change
  4. The notification/integration change

Do each one as a separate session. Commit between each. If session 3 produces bad output, you don't lose sessions 1 and 2.

Testing

6. Run the dev server between every change

npm run dev is your smoke test. It takes 10 seconds. It catches:

  • Syntax errors
  • Import errors
  • Missing dependencies
  • TypeScript strict violations
  • Obvious runtime errors

If the dev server doesn't start clean, the change isn't done.

7. Click through the feature you changed

TypeScript passing is necessary but not sufficient. AI tools frequently produce code that compiles but doesn't work:

  • A button that's wired to the wrong handler
  • A list that renders but never fetches data
  • A form that saves but doesn't validate

Open the browser, click the thing, confirm it does what you asked for. Every time.

8. Test in Supabase's dashboard, not just the UI

For database changes (migrations, new columns, policy changes):

  1. Run the migration in the Supabase SQL editor
  2. Look at the table in Supabase Table Editor and confirm the schema matches what you expect
  3. Test the RLS policy by running select queries as different users via set request.jwt.claim.sub = '...'

Catching a bad migration in dev is a nuisance. Catching it in prod is a recovery operation.

9. Keep a separate dev Supabase project

Running migrations and policy changes against production is dangerous. Create a free Supabase project, copy your schema to it, use it for AI-assisted experimentation:

# Point VITE_SUPABASE_URL at the dev project during local dev
VITE_SUPABASE_URL=https://dev-project.supabase.co npm run dev

When the change works in dev, run it against production with eyes-open intent.

Version control and rollback

10. Commit often

One commit per working change. Commit messages should describe what the user sees, not what the code does:

  • Good: "Add CSV export to contacts list"
  • Bad: "Add handleExport function to ContactList component"

Small, descriptive commits let you git revert cleanly if an AI session produces something wrong.

11. Branch for experimental changes

For anything you're not sure about:

git checkout -b try-discord-integration
# ... ask the AI, test, iterate ...
# If it works, merge. If not:
git checkout main
git branch -D try-discord-integration

Branches are free. Use them for anything bigger than a typo fix.

12. Back up your database before migrations

Supabase → Database → Backups. Take a manual backup before any migration that's changing more than one table or touching production data. If something goes wrong, a 15-second backup saves you an all-nighter.

Keeping a modification log

13. Maintain a CUSTOMIZATIONS.md

Once you've made more than a handful of changes, your future self and future AI sessions will thank you for a running log. Create CUSTOMIZATIONS.md in your repo root:

# Customizations
 
Running log of modifications we've made to the base ARK product.
 
---
 
## 2026-04-16 — Discord integration
- Added `workspace_settings.discord_webhook_url` column
- Added `notifyDiscord` helper in `src/lib/notify.ts`
- Wired into deal-won path in `supabase/functions/track-automation-runner/`
 
## 2026-04-14 — Renamed "Deal" to "Opportunity"
- Only changed display labels (`src/i18n/strings.ts`)
- Database columns unchanged (`deals` table, `deal_id` FK)
 
## 2026-04-10 — Executive Summary dashboard
- New route `/dashboard/executive`
- Admin-only (gated on `profile.role === 'admin'`)
- File: `src/pages/ExecutiveDashboard.tsx`

This serves two purposes:

  • For you — six months from now, you'll wonder why a specific piece of code looks different. The log tells you.
  • For AI — Claude Code reads CUSTOMIZATIONS.md on session start and knows not to "helpfully" undo changes you made on purpose.

What never to change

14. Don't modify license validation

The license validator lives at src/lib/license.js (or src/lib/license.ts). It:

  • Confirms your license is active
  • Binds the license to your domain
  • Lets us push security updates to you

Removing or bypassing it:

  • Violates the Terms of Service
  • Stops updates from reaching you
  • Breaks our ability to help you if something goes wrong in the future

If you have a genuine technical problem with license validation (e.g., you need to self-host offline), email support@arkteams.io and we'll work it out.

15. Don't tamper with fingerprint markers

Every ARK repo includes around eight invisible markers that let us identify the source buyer if a copy leaks. They're:

  • Build hash comments in 4 file headers
  • Two or three CSS value micro-variations
  • One SVG path coordinate shifted slightly

The Terms of Service prohibit tampering with these. They don't affect functionality. Leave them alone.

See Platform Reference → Security for the full list.

Pre-deployment checklist

Before pushing any AI-generated change to production:

  • npm run build succeeds with no errors
  • npm run dev loads without console errors
  • You clicked through the feature and it works
  • Any migrations have been run on dev first, not directly on prod
  • git diff shows only the changes you expected
  • The commit message describes the user-visible change
  • You've recorded the change in CUSTOMIZATIONS.md
  • You've taken a Supabase backup if the change touched the schema

When AI gets it wrong

Sooner or later an AI tool will produce code that breaks something. The recovery pattern:

  1. Don't panic-push a fix. Stay on whatever commit you're on.
  2. Read the error. Full stack trace, not just the first line.
  3. Paste the error back into the same session. The AI has context from earlier messages and can usually spot the issue.
  4. If it can't fix it in 2–3 tries, back out. git reset --hard HEAD (if uncommitted) or git revert <commit> (if committed), start a fresh session, try again with a more specific prompt.
  5. If you're stuck, email support@arkteams.io with: the prompt, the generated code, the error, and what you've tried.

Where to go next