Project context & CLAUDE.md

How Claude reads your codebase and how to help it understand your project

How Claude Code understands your project

When you launch Claude Code in a directory, it can read any file you point it to. But it doesn’t automatically know your project’s purpose, conventions, or constraints. You have two ways to give it that context: show it files explicitly, or use CLAUDE.md.

CLAUDE.md — your project’s orientation document

CLAUDE.md is a markdown file you create at the root of your project. Claude Code automatically reads it at the start of every session. Think of it as the briefing document for a new contractor who just joined your project.

What to put in CLAUDE.md

# Project: Treal Performance — Catalog Sync Middleware

## What this is
Middleware service that syncs product catalog from Slingshot ERP to Shopify. Runs on Node.js 18, deployed on DigitalOcean.

## Architecture
- /sync — main sync service
- /transforms — data transformation logic
- /api — Shopify API wrapper
- /logs — sync logs and error tracking

## Key constraints
- Never modify the Shopify product IDs — these are source of truth
- All prices are in USD, never apply conversion
- Slingshot API rate limit: 100 req/min — respect it

## Development conventions
- Use async/await, not .then() chains
- All errors must be caught and logged to /logs/errors.log
- Write tests for all transform functions

## Common commands
- To run sync manually: npm run sync:manual
- To run tests: npm test

## Things NOT to change without asking
- The database schema in /db/schema.sql
- The Shopify webhook endpoints
- The cron schedule in ecosystem.config.js