Skip to content

Getting Started with Claude Code

This guide walks you through the complete setup for AI-assisted development at Sartiq. By the end, you'll have Claude Code configured with team standards, MCP servers, quality hooks, and plugins.

Prerequisites

  • Claude Code installed (curl -fsSL https://claude.ai/install.sh | bash)
  • Repository cloned and working locally
  • Node.js 18+ (for MCP servers)
  • Python 3.12+ with uv (for backend work)
  • npm (for frontend work)
  • GitHub CLI (gh) authenticated

Step 1: Create CLAUDE.md

The CLAUDE.md file is loaded automatically at every session start. It's the single most important file for team consistency.

Create CLAUDE.md in your repository root:

# Project: Sartiq

## Quick Reference
- **Frontend**: Next.js 15 (App Router), TypeScript, Tailwind, shadcn/ui
- **Backend**: Python 3.12+, FastAPI, Celery, PostgreSQL, Redis
- **Package Managers**: npm (frontend), uv (backend)
- **Linting**: ESLint + Prettier (frontend), ruff (backend)

## Commands
```bash
# Frontend
bun dev          # Start dev server
bun run lint     # Lint and fix
bun run type-check   # TypeScript check
bun test         # Run tests

# Backend
uv sync                              # Install dependencies
uv run uvicorn src.main:app --reload # Dev server
uv run ruff check --fix .            # Lint and fix
uv run pytest                        # Run tests

Code Style (IMPORTANT)

Frontend (TypeScript/React)

  • Prefer Server Components by default; only use 'use client' when state/effects needed
  • No any type — use unknown or proper generics
  • Use shadcn/ui components for all standard UI elements
  • Import order: react → next → external libs → local (@/ aliases)
  • Destructure props; annotate return types explicitly

Backend (Python)

  • MUST include type hints for ALL function signatures
  • MUST include docstrings (Google style) for public functions
  • Use async/await for all I/O operations
  • NEVER use time.sleep() in async routes — use await asyncio.sleep()
  • CPU-intensive tasks go to Celery, not async routes
  • Use Pydantic v2 models for all request/response validation

Architecture

Frontend Structure

app/                    # App Router pages and API routes
components/             # shadcn/ui and custom components
  ui/                   # shadcn primitives
  features/             # Feature-specific components
lib/                    # Utilities and API clients
hooks/                  # Custom React hooks

Backend Structure (Domain-Based)

src/
├── [domain]/           # Feature modules (auth/, users/, etc.)
│   ├── router.py       # FastAPI endpoints
│   ├── schemas.py      # Pydantic models
│   ├── models.py       # SQLAlchemy models
│   ├── service.py      # Business logic
│   └── dependencies.py # DI functions
├── config.py           # Settings
├── database.py         # DB connection
└── main.py             # App entry

Before Committing (CRITICAL)

  1. Frontend: bun run lint && bun run type-check && bun test
  2. Backend: uv run ruff check --fix . && uv run pytest
  3. Verify no console.logs or debug statements remain
  4. Check that changes follow existing patterns in the codebase

Git Workflow

  • Branch naming: feature/TICKET-description or fix/TICKET-description
  • Commit messages: feat(scope): description or fix(scope): description
  • Always create PR, never push directly to main

Domain Terminology

  • Sartiq: The main product platform
  • Compute Server: GPU-backed image processing service 
    !!! tip "Bootstrap alternative"
    Run `/init` in Claude Code to auto-generate a CLAUDE.md based on your repo structure, then customize it with the template above.

For detailed CLAUDE.md guidance, see the [official docs](https://code.claude.com/docs/en/memory).

---

## Step 2: Install Marketplace & Plugins

The [Sartiq Marketplace](./skills-and-plugins/marketplace.md) provides shared plugins for task management, code review, issue tracking, and more.

### Register the marketplace (user-level, one-time)

```bash
/plugin marketplace add shootify-io/claude-marketplace

Install the core developer plugin

/plugin install sq-dev@sartiq-marketplace

Run setup

/sq-dev:setup

This runs the full onboarding checklist:

  1. Prerequisites — verifies Node.js, npm, Python, uv, and the gh CLI are available
  2. LSP binaries — checks for typescript-language-server and pyright-langserver and installs them globally via npm if missing
  3. Environment variables — checks SARTIQ_YOUTRACK_USER_TOKEN and SARTIQ_DOCS_TOKEN; guides you to get and store them without ever asking you to paste them in chat
  4. MCP servers — configures YouTrack, Sartiq Docs, and Context7 connections automatically
  5. Shell auto-loading — detects your shell and suggests the one-liner to source the env file on every new terminal

Restart required

After setup completes, restart Claude Code for MCP servers and LSP servers to activate. They are initialized at startup from your shell environment.

Install additional plugins (optional)

/plugin install sq-scrum@sartiq-marketplace      # Issue management
/plugin install sq-research@sartiq-marketplace    # ML research tools
/plugin install plugin-dev@sartiq-marketplace     # Contributor tools

See the Marketplace Overview for the full catalog and role-based recommendations.

Step 3: Configure MCP Servers

Auto-configured by sq-dev:setup

If you ran /sq-dev:setup in Step 2, YouTrack, Sartiq Docs, and Context7 MCP servers are already configured. This step is for adding additional MCP servers or verifying your configuration.

Create or update .mcp.json in your repository root:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./src",
        "./tests",
        "./docs"
      ]
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--transport", "stdio"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Security

Use read-only database connections for the PostgreSQL MCP. Never hardcode credentials — always use environment variables.

Commit .mcp.json to git so the entire team shares the same tool configuration.

For details on MCP servers, see the official docs.

Step 4: Set Up Settings and Hooks

Create .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -I {} sh -c 'case {} in *.ts|*.tsx|*.js|*.jsx) npx prettier --write {} && npx eslint --fix {} ;; *.py) uv run ruff check --fix {} && uv run ruff format {} ;; esac'"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(uv *)",
      "Bash(pytest *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

This auto-runs linting after every file edit and pre-approves safe operations.

For the full hooks reference, see Settings & Hooks.

Step 5: Verify Setup

Check MCP connections

/mcp

All configured servers should show as connected.

Check available skills

/skills

You should see both built-in and installed skills.

Test a simple task

Read the files in src/auth/ and summarize the authentication patterns used.
Don't write any code.

Claude should use the Explore subagent to read files, respect your CLAUDE.md standards, and provide a clear summary.

Verify hooks

Edit any .py or .ts file — ruff/prettier should auto-run after the edit completes.

Step 6: First Real Task

Try the full workflow with a task from YouTrack:

/sq-dev:start-task

This fetches the YouTrack issue, creates a feature branch from dev, and assigns the issue to you. Then work on it and when done:

/sq-dev:close-task

This squash-merges your branch back to dev, cleans up, and updates the YouTrack issue status.

What's Next