Skip to content

Samsen Internal Framework

This is Samsen's internal framework content for Claude Code & Agentic Coding. It is read-only reference material.

Claude Code — Project Setup

The CLAUDE.md File

Every project that uses Claude Code should have a CLAUDE.md file at the repository root. This file is Claude Code's persistent context — it reads this file automatically at the start of every session, giving the AI baseline knowledge about the project.

What to Include

A good CLAUDE.md contains:

Project Overview

What the project is, what stack it uses, what it does. Two to three sentences.

# CLAUDE.md

This is a React 19 application built with Vite, deployed on Cloudflare Pages.
It uses Supabase for auth and database, and our custom design system for UI.

Key Commands

The commands Claude Code will need to run most often:

## Commands
- `npm run dev` — Start dev server
- `npm run build` — Production build
- `npm run test` — Run tests
- `npm run lint` — Lint check
- `npm run lint:fix` — Auto-fix lint issues

Architecture Decisions

The conventions that aren't obvious from the code:

## Architecture
- Components in `src/components/`, grouped by feature
- Shared UI components in `src/components/ui/`
- All data fetching through `src/services/`
- CSS modules for component styling, design system tokens via CSS custom properties
- Server components by default, client components only when interactivity required

Design System Reference

If the project uses a design system, include token naming and usage rules:

## Design System
- Tokens defined in `src/styles/tokens.css`
- Naming: `--{category}-{property}-{variant}` (e.g., `--color-action-primary`)
- Never use hardcoded color/spacing values — always reference tokens
- Component tokens override semantic tokens for component-specific values

Things to Avoid

Explicit constraints prevent common AI mistakes:

## Avoid
- Don't use inline styles — use CSS modules
- Don't add new dependencies without asking
- Don't use React class components — hooks only
- Don't create new token values — use existing tokens or ask
- Don't modify files in `src/generated/` — these are auto-generated

What Not to Include

  • Entire codebases — CLAUDE.md is a guide, not a dump. Link to files, don't copy them.
  • Frequently changing data — Put stable conventions here. Volatile information goes in task-specific prompts.
  • Obvious information — Claude Code can read package.json. You don't need to list every dependency.

Context Files Beyond CLAUDE.md

For larger projects, a single CLAUDE.md can become unwieldy. Use a structured context approach:

.claude/
├── CLAUDE.md              # Main context (always read)
├── design-system.md       # Token reference, component patterns
├── architecture.md        # Detailed architecture decisions
└── conventions.md         # Naming, file structure, patterns

Claude Code reads CLAUDE.md automatically. Reference additional files when relevant: "Read .claude/design-system.md and use those tokens for this component."

Repository Structure for AI

AI tools work best with predictable, well-organized repositories:

Consistent File Naming

Pick a convention and stick to it:

  • kebab-case.tsx for component files
  • ComponentName/index.tsx for component directories
  • use-hook-name.ts for hooks
  • component-name.module.css for styles

Colocation

Keep related files together:

components/
├── Button/
│   ├── index.tsx          # Component
│   ├── button.module.css  # Styles
│   ├── button.test.tsx    # Tests
│   └── button.stories.tsx # Storybook story

AI can read a component's entire directory to understand it completely.

Clear Boundaries

Separate concerns into directories with obvious purposes:

  • components/ — UI components
  • services/ — Data and API logic
  • hooks/ — Shared React hooks
  • styles/ — Global styles and tokens
  • utils/ — Pure utility functions
  • types/ — Shared TypeScript types

Initial Setup Checklist

When adding Claude Code to an existing project:

  • [ ] Create CLAUDE.md with project overview, commands, architecture, and constraints
  • [ ] Verify design system tokens are documented (or add a token reference file)
  • [ ] Ensure the project builds and tests pass (AI can't work in a broken environment)
  • [ ] Set up a development branch strategy (AI should never commit to main)
  • [ ] Test one simple task end-to-end: prompt → generate → review → commit → PR