ARK

Using Claude Code

Claude Code is Anthropic's official CLI for Claude. It's our recommended tool for modifying ARK products because every ARK repo ships with a CLAUDE.md that configures it for the codebase out of the box.

You don't have to use Claude Code — see Using ChatGPT & Others if you prefer another tool — but this is the path with the least friction.

Why Claude Code for ARK products

Claude Code reads files, edits files, runs commands, and iterates on failures without you copy-pasting anything. When it starts a session, it automatically reads:

  • The repo's CLAUDE.md (project conventions, guardrails)
  • Any linked docs the CLAUDE.md references
  • The files it decides are relevant to your request

That means for an ARK product, Claude Code starts every session already knowing:

  • The project structure (where features live, what naming conventions are)
  • Which files are off-limits (license validation, fingerprint markers)
  • How to run the dev server, tests, and migrations
  • When to pause and ask before making non-trivial schema or architecture changes

You get AI-assisted development that respects the codebase's rules.

Setting up Claude Code

1. Install Claude Code

Follow the install instructions at claude.com/claude-code. At time of writing, the install is one command on macOS and Linux:

curl -fsSL https://claude.ai/install.sh | sh

Verify the install:

claude --version

2. Sign in

claude /login

You'll be prompted for an Anthropic account. A Claude subscription (Pro, Max, or Team) includes Claude Code usage. You can also use an Anthropic API key directly if you prefer pay-as-you-go.

3. Clone your ARK repo

After you complete a purchase, you receive a GitHub invitation to your fingerprinted repo. Accept it, then clone:

git clone git@github.com:arkteams/track-a1b2c3.git
cd track-a1b2c3

4. Start a session

From inside the repo directory:

claude

Claude Code reads CLAUDE.md automatically on first prompt. You'll see it reference the conventions in its responses — that's the signal that the project context loaded correctly.

The CLAUDE.md file and why it matters

Every ARK product ships with a CLAUDE.md at the repo root. It's roughly 200–400 lines and covers:

  • Product identity — what this codebase is, what it does, what it explicitly isn't
  • Behavioral principles — how to make decisions in this repo ("read the docs first," "don't touch the license validator," etc.)
  • Decision autonomy — what Claude can do without asking, and what requires a pause-and-confirm
  • Hard guardrails — security, coding, and process rules with no exceptions
  • Satellite doc triggers — which deeper docs to open for which kinds of task ("touching the schema? read docs/database.md")

This file is why AI-assisted changes to ARK products work on the first try instead of the fifth. It front-loads the context Claude needs so every session doesn't start from zero.

Don't delete or "clean up" CLAUDE.md

If you've customized the product heavily and think the guardrails don't apply anymore, don't remove them. Instead, add your own section at the bottom with your buyer-specific conventions:

---
 
## Buyer Customizations
 
### Our conventions
- We use `@/features/` import alias, never relative paths
- All new tables get a `company_id` column for our multi-tenant setup
- Slack notifications go through `lib/notify.ts`, not `lib/slack.ts`
 
### What we've already changed
- Renamed "Deal" to "Opportunity" throughout the UI (Dec 2025)
- Added custom dashboard at `/dashboard/exec` (Jan 2026)
- Forked Pulse's Slack integration to use Teams instead

Your additions layer on top of the ARK-provided guardrails. Claude reads both and honors both.

Example workflow: "I want to add a feature"

Let's walk through a full Claude Code session end to end. The goal: add a "health score" field to companies in Track that updates nightly based on recent activity.

Step 1: Describe the change clearly

From inside your Track repo:

claude

Then paste a prompt like this:

I want to add a health score to companies in Track.

What it should do:

  • Integer 0–100 stored on each company row
  • Computed nightly by an Edge Function based on: days since last activity (lower score for older), count of open tasks (lower for more), total deal value (higher for more)
  • Displayed as a colored badge on the company list view: green ≥ 70, yellow 40–69, red < 40

Before you start, read CLAUDE.md, then look at src/features/companies/ and supabase/functions/ to understand how similar things are built. Then propose a plan and wait for me to confirm before writing code.

Step 2: Review the plan

Claude will respond with something like:

Here's my plan:

  1. Add a migration supabase/migrations/20260416_health_score.sql that adds a health_score integer default 0 column to companies.
  2. Create an Edge Function at supabase/functions/compute-company-health/ that reads companies, recent activities, and open tasks, computes the score, and bulk-updates.
  3. Add a pg_cron schedule to run it nightly at 3am.
  4. Add a HealthBadge component at src/features/companies/HealthBadge.tsx.
  5. Wire the badge into the company list at src/features/companies/CompanyList.tsx.

Files I'll touch:

  • supabase/migrations/20260416_health_score.sql (new)
  • supabase/functions/compute-company-health/index.ts (new)
  • src/features/companies/HealthBadge.tsx (new)
  • src/features/companies/CompanyList.tsx (edit — one row in render)

Let me know if you want changes before I implement.

This is the review point. Read the plan. If anything's off — wrong file, wrong column type, missing an index — say so now. Fixing a plan costs one sentence; fixing finished code costs a refactor.

Step 3: Let it implement

Once you approve, Claude writes the files, runs npm run build to confirm TypeScript is clean, and summarizes what it did.

Step 4: Test locally

npm run dev

Click through the UI. Does the badge render? Does the color match the score? Open localhost:3000/companies and check.

For the Edge Function, deploy it to a dev branch Supabase project first:

npx supabase functions deploy compute-company-health

Then manually invoke it and verify rows update:

npx supabase functions invoke compute-company-health

Step 5: Apply the migration to production

If everything looks good locally, open your production Supabase project and run the migration SQL in the SQL editor. Migrations are intentionally not auto-applied — you decide when schema changes hit production.

Step 6: Commit and push

Claude can do this for you:

Commit the changes with a clear message and push to main.

Or do it yourself:

git add .
git commit -m "Add nightly health score to companies"
git push

Vercel rebuilds automatically on push. Within a minute or two, the badge is live.

Step 7: (Optional) Record the change

If you want to keep a changelog of your modifications — which is a good idea once you have more than two or three — add a line to your repo's CUSTOMIZATIONS.md (create it if it doesn't exist):

## 2026-04-16 — Company health score
- Added `companies.health_score` column
- Added `compute-company-health` Edge Function (nightly at 3am UTC)
- Added `HealthBadge` to the company list view

This helps both you (six months from now, when you wonder what you changed) and Claude (in future sessions, it reads this too).

Tips for productive Claude Code sessions

  • Scope each session. One feature per session produces clean commits and is easy to roll back.
  • Let Claude read first. "Before you code, read X, Y, Z" is almost always worth the tokens. Context-free code is hit-or-miss.
  • Stop-gate risky changes. For anything schema- or security-adjacent, ask for a plan first, not code.
  • Use git status as a lie detector. If Claude says "I've added a health score column" and git status shows no migration file, prompt again: "I don't see a migration. Show me git status."
  • Commit often. After each working change, commit. If the next prompt breaks something, git reset --hard HEAD is your undo.

Where to go next