Claude Code Integration ¶

Set up project rules that Claude Code reads automatically every session — so your AI assistant follows your conventions from the first prompt.

In plain terms

Claude Code is an AI coding assistant that runs in your terminal. When you add a CLAUDE.md file to your project root, Claude reads it at startup and follows the rules inside — coding style, architecture, do's and don'ts — without you having to repeat them every time.

How It Works¶

Claude Code looks for a CLAUDE.md file in your project root when a session starts. Everything inside that file becomes context for the entire conversation. Think of it as a persistent briefing that tells Claude:

What your project does and how it's structured
Which patterns and conventions to follow
What to avoid (e.g., modifying shared models, hardcoding secrets)
How to run tests and deploy

Because the file is read automatically, you don't need to copy-paste rules into each prompt. Write them once, and every session starts with the right context.

Works with AGENTS.md too

Claude Code also reads AGENTS.md if present. Use CLAUDE.md for rules and constraints; use AGENTS.md for architecture context and onboarding. Both are read at session start.

Quick Start¶

1. Download the Template¶

Get the starter CLAUDE.md and place it in your project root.

2. Customize the Rules¶

Replace the placeholders with your project's name, stack, patterns, and conventions.

3. Start a Session¶

Open Claude Code in your project. It reads CLAUDE.md automatically — no extra setup needed.

Download CLAUDE.md Template

Template scope

The downloadable template is for projects integrating with the Moveris API — your app captures video frames and calls the API for liveness verification. It includes endpoints, models, security rules, and code patterns. Customize the identity section with your project name and stack.

What to Include in CLAUDE.md¶

A good CLAUDE.md covers identity, critical rules, and patterns. The Moveris template emphasizes integration rules. Below are examples; the download includes Moveris-specific content ready to use.

1. Project Identity¶

Tell Claude what it's working on. This prevents wrong assumptions about your stack.

## Project Identity

**Name**: [Your Project Name]
**Type**: [Your stack, e.g. Next.js, Express, FastAPI]
**Integration**: Moveris Liveness API v2
**Base URL**: https://api.moveris.com
**Docs**: https://documentation.moveris.com

In practice

Without this section, Claude may guess your framework or language version. Replace the placeholders with your project name and stack.

2. Critical Rules¶

The non-negotiable constraints. These are the rules Claude must never break. For Moveris integration, focus on security and API usage:

## Critical Rules

### NEVER Expose API Keys in Client-Side Code
Always proxy requests through your backend. Your backend adds the X-API-Key header before forwarding to Moveris.

### ALWAYS Store API Keys in Environment Variables
Never hardcode credentials in source code.

### ALWAYS Validate the Verdict Server-Side
Never trust client-side liveness results. Verify the verdict on your server before granting access.

### Frame Count Must Match the Model
Send exactly the number of frames the model expects (e.g. 10 for mixed-10-v2, 30 for mixed-30-v2).

Best practice

Use strong verbs — NEVER, ALWAYS, MUST — for rules that have no exceptions. Claude treats these as hard constraints.

3. Code Patterns¶

Show Claude how you write code in this project. Include short, realistic examples. The Moveris template includes integration patterns (backend proxy, fast-check, fast-check-stream) and code snippets for calling the API.

Beyond the template

If your project has internal structure (routes, services, etc.), add sections 4 and 5. The Moveris template focuses on integration rules rather than internal project layout.

4. Project Structure (Optional)¶

Map out the project layout so Claude can place new code correctly.

## Project Structure

routes/    — API endpoints (one file per feature)
services/  — Business logic (no HTTP dependencies)
schemas/   — Pydantic models (requests, responses, common)
auth/      — Authentication and authorization
core/      — Base classes and utilities

5. Environment & Testing (Optional)¶

Tell Claude how to run the project and what testing standards to follow. For Moveris integration, the key variable is MOVERIS_API_KEY.

## Environment Variables

### Required
- DATABASE_URL — PostgreSQL connection string
- API_SECRET_KEY — Secret key for signing

## Testing
- Unit tests for services/ (no external dependencies)
- Integration tests for API endpoints
- Target >80% coverage
- Run: make test

6. Do / Don't Rules¶

A quick-reference checklist. Claude scans these as guardrails.

## Do
- Use async for all I/O operations
- Store secrets in environment variables
- Write tests for business logic

## Don't
- Hardcode URLs or credentials
- Use blocking I/O in async contexts
- Commit .env files

Implementation Best Practices¶

These patterns come from real production projects. They work across Python, TypeScript, and polyglot stacks.

Type Safety¶

Language	Rule
Python	Full type hints on every function. Use `X \\| None` instead of `Optional[X]`.
TypeScript	Strict mode enabled. Never use `any` — use `unknown` with type guards.

Configuration¶

All configuration must come from environment variables. Never hardcode URLs, credentials, or feature flags.

# GOOD — reads from environment
settings = get_settings()
db_url = settings.database_url

# BAD — hardcoded value
db_url = "postgresql://localhost/mydb"

Error Handling¶

Use custom exception classes. Return structured error responses with a machine-readable code and a human-readable message.

class InsufficientCreditsError(AppError):
    status_code = 402
    error_code = "insufficient_credits"

Testing Standards¶

Unit tests for business logic — no database, no network
Integration tests for API endpoints — use real or cloned databases in CI
Coverage target: 80% or higher
Test data: Use identifiable patterns (e.g., test-* prefixes) for automatic cleanup

Git Conventions¶

Branches: main (production), develop (integration), feature/*, hotfix/*
Commits: Conventional Commits format — feat:, fix:, docs:, chore:, ci:
Pre-push: Run make pre-push (lint + format + typecheck + test) before pushing

Do / Don't Reference¶

A consolidated checklist you can copy into your CLAUDE.md.

Do¶

Practice	Why
Use type hints on every function	Prevents runtime errors and improves editor support
Validate all input at the boundary	Stops bad data before it reaches business logic
Use async/await for I/O	Avoids blocking the event loop in async frameworks
Store secrets in environment variables	Keeps credentials out of source control
Write tests for business logic	Catches regressions early, enables safe refactoring
Use structured logging	Makes debugging and monitoring easier in production
Keep services free of HTTP dependencies	Business logic stays testable and reusable
Use Conventional Commits	Enables automated changelogs and clear history

Don't¶

Practice	Risk
Hardcode URLs, credentials, or config	Secrets leak; breaks across environments
Skip input validation	Injection attacks, corrupt data, crashes
Use blocking I/O in async contexts	Freezes the entire server under load
Commit `.env` files or secrets	Credentials exposed in version control
Use `any` (TS) or skip type hints (Python)	Hides bugs; loses editor autocomplete
Put business logic in route handlers	Untestable, tightly coupled to framework
Ignore linter warnings	Technical debt accumulates silently
Modify shared/external models	Breaks other services that depend on the same schema

MCP Server Configuration (Optional)¶

If your project exposes or consumes an MCP server, document it in CLAUDE.md so Claude understands the tools available.