140 Claude 0e101976

# Development Philosophy

## Core Principle: **Less is more**
Keep every implementation as small and obvious as possible.

## Guidelines
- **Simplicity first** – Prefer the simplest data structures and APIs that work
- **Avoid needless abstractions** – Refactor only when duplication hurts
- **Remove dead code early** – `pnpm tidy` scans for unused files/deps and lets you delete them in one command
- **Minimize dependencies** – Before adding a dependency, ask "Can we do this with what we already have?"
- **Consistency wins** – Follow existing naming and file-layout patterns; if you must diverge, document why
- **Explicit over implicit** – Favor clear, descriptive names and type annotations over clever tricks
- **Fail fast** – Validate inputs, throw early, and surface actionable errors
- **Let the code speak** – If you need a multi-paragraph comment, refactor until intent is obvious

# REQUIRED COMMANDS AFTER CODE CHANGES
**IMMEDIATE ACTION REQUIRED: After using `edit_file` tool:**

1. Run `pnpm format`
2. Run `pnpm build-sdk`
3. Run `pnpm check-types`
4. Run `pnpm tidy`
5. Run `pnpm test`

**These commands are part of the `edit_file` operation itself.**

(CI also runs these steps; your PR will fail if any step fails.)


# Pull Request Guidelines

## When to Create a Pull Request
- **Create PRs in meaningful minimum units** - even 1 commit or ~20 lines of diff is fine
- Feature Flags protect unreleased features, so submit PRs for any meaningful unit of work
- After PR submission, create a new branch from the current branch and continue development

## What Constitutes a "Meaningful Unit"
- Any UI change (border color, text color, size, etc.)
- Function renames or folder structure changes
- Any self-contained improvement or fix

## Size Guidelines
- **~500 lines**: Consider wrapping up current work for a PR
- **1000 lines**: Maximum threshold - avoid exceeding this
- Large diffs are acceptable when API + UI changes are coupled, but still aim to break down when possible


# Bash commands
- pnpm build-sdk: build the SDK packages
- pnpm -F playground build: build the playground app
- pnpm -F studio.giselles.ai build: build Giselle Cloud
- pnpm check-types: type‑check the project
- pnpm format: format code
- pnpm tidy --fix: delete unused files/dependencies
- pnpm tidy: diagnose unused files/dependencies
- pnpm test: run tests


# Language Support
- Some core members are non‑native English speakers.
- Please correct grammar in commit messages, code comments, and PR discussions.
- Rewrite unclear user input when necessary to ensure smooth communication.