CLAUDE.md Templates

Template 1: Flask + Angular (Flangular Stack)

# Constellation Project

## About
Product factory building SaaS products with shared infrastructure.
Stack: Angular frontend, Flask backend, PostgreSQL database.

## Commands
- `cd frontend && ng serve` - Run Angular dev server (localhost:4200)
- `cd backend && flask run` - Run Flask dev server (localhost:5000)
- `cd backend && pytest` - Run Python tests
- `cd frontend && ng test` - Run Angular tests
- `alembic upgrade head` - Run database migrations

## Code Style

### Python (Backend)
- Type hints required on all functions
- Use Pydantic for request/response validation
- Follow repository pattern for data access
- Use dependency injection via Flask-Injector

### TypeScript (Frontend)
- Strict mode enabled
- Use Angular signals for state
- Standalone components preferred
- Use the HttpClient service in /src/app/core/http

## Architecture

backend/ ├── app/ │ ├── models/ # SQLAlchemy models │ ├── repositories/ # Data access layer │ ├── services/ # Business logic │ ├── controllers/ # Flask blueprints │ └── schemas/ # Pydantic schemas └── migrations/ # Alembic migrations

frontend/ └── src/app/ ├── core/ # Singletons, guards, interceptors ├── shared/ # Reusable components ├── features/ # Feature modules └── pages/ # Route components

## Gotchas
- Always run `alembic upgrade head` after pulling
- Backend uses JWT in HttpOnly cookies, not localStorage
- Angular proxy config forwards /api/* to Flask

## Testing
- Backend: pytest with fixtures in conftest.py
- Frontend: Jest for unit, Cypress for e2e
- Always write tests for new features (TDD preferred)

---

Template 2: Next.js Full-Stack

# [Project Name]

## About
Next.js 14 application with App Router, Prisma ORM, and Tailwind CSS.

## Commands
- `npm run dev` - Development server
- `npm run build` - Production build
- `npm run test` - Run Jest tests
- `npm run lint` - ESLint check
- `npx prisma migrate dev` - Run migrations
- `npx prisma studio` - Database GUI

## Code Style
- Use Server Components by default
- Client Components only when needed (interactivity, hooks)
- Colocation: keep related files together
- Use Zod for validation
- Prefer named exports

## Architecture

src/ ├── app/ # App Router pages │ ├── (auth)/ # Auth route group │ ├── (dashboard)/ # Dashboard route group │ └── api/ # API routes ├── components/ │ ├── ui/ # Shadcn/ui components │ └── features/ # Feature-specific components ├── lib/ │ ├── db.ts # Prisma client │ ├── auth.ts # Auth utilities │ └── utils.ts # Helpers └── types/ # TypeScript types

## Gotchas
- Use `"use client"` directive sparingly
- Server Actions for mutations (not API routes)
- Environment variables: NEXT_PUBLIC_ prefix for client

---

Template 3: Python CLI Tool

# [Tool Name]

## About
Python CLI tool built with Click and Rich for terminal UI.

## Commands
- `poetry install` - Install dependencies
- `poetry run pytest` - Run tests
- `poetry run mypy src` - Type checking
- `poetry run black src tests` - Format code
- `poetry run [tool-name]` - Run the CLI

## Code Style
- Type hints required everywhere
- Use dataclasses or Pydantic for data structures
- Click for CLI interface
- Rich for terminal output
- 100% test coverage goal

## Architecture

src/[tool_name]/ ├── main.py # Entry point ├── cli.py # Click commands ├── core/ # Business logic ├── utils/ # Helpers └── config.py # Configuration

tests/ ├── conftest.py # Fixtures ├── test_cli.py # CLI tests └── test_core/ # Core logic tests

## Testing
- Use pytest with Click's CliRunner
- Mock external services
- Test both success and error paths

---

Template 4: React Native / Expo

# [App Name]

## About
Cross-platform mobile app built with Expo and React Native.

## Commands
- `npx expo start` - Start dev server
- `npx expo start --ios` - iOS simulator
- `npx expo start --android` - Android emulator
- `npm run test` - Run Jest tests
- `npx expo prebuild` - Generate native projects

## Code Style
- Functional components with hooks only
- Use Expo SDK where possible
- Zustand for global state
- React Query for server state
- StyleSheet.create for styles (no inline)

## Architecture

src/ ├── app/ # Expo Router screens ├── components/ │ ├── ui/ # Design system │ └── features/ # Feature components ├── hooks/ # Custom hooks ├── stores/ # Zustand stores ├── services/ # API clients └── utils/ # Helpers

## Gotchas
- Test on both iOS and Android
- Use SafeAreaView for notches
- Handle keyboard avoiding views
- Deep linking config in app.json

---

Template 5: Minimal Starter

# [Project Name]

## About
[One line description]

## Commands
- `[build command]`
- `[test command]`
- `[lint command]`

## Code Style
- [Key convention 1]
- [Key convention 2]

## Important Files
- `[path/to/important/file]` - [what it does]

## Gotchas
- [Thing that might trip you up]

---

Custom Slash Commands Collection

.claude/commands/commit.md

---
description: Smart git commit with validation
allowed-tools: Bash(git:*)
---

1. Run `git diff --staged` to see staged changes
2. Check for issues:
   - TODO/FIXME comments
   - console.log/print statements
   - Commented out code
   - Hardcoded secrets or test values
3. If issues found, warn me and ask to proceed
4. Write commit message following conventional commits:
   - feat: new feature
   - fix: bug fix
   - docs: documentation
   - refactor: code refactor
   - test: adding tests
   - chore: maintenance
5. Include scope if clear: feat(auth): add OAuth support

Message hint: $ARGUMENTS

.claude/commands/review.md

---
description: Code review current changes
allowed-tools: Bash(git diff:*)
---

Review the current uncommitted changes:

!`git diff`

Check for:
1. **Logic errors** - Bugs, edge cases, race conditions
2. **Security issues** - Injection, auth bypass, data exposure
3. **Performance** - N+1 queries, unnecessary loops, missing indexes
4. **Code quality** - Naming, duplication, complexity
5. **Tests** - Are new features tested?

Provide specific, actionable feedback with line numbers.

.claude/commands/test.md

---
description: Write tests for a file or feature
allowed-tools: Bash, Read, Edit
argument-hint: [file-or-feature]
---

Write comprehensive tests for: $ARGUMENTS

1. Detect the test framework (Jest, pytest, etc.)
2. Find existing test patterns in the codebase
3. Write tests covering:
   - Happy path
   - Edge cases
   - Error conditions
   - Boundary values
4. Follow existing test file naming conventions
5. Run the tests to verify they pass

.claude/commands/explain.md

---
description: Explain code with diagrams
---

Explain: $ARGUMENTS

1. **Analogy**: Compare to something from everyday life
2. **Diagram**: ASCII art showing flow/structure
3. **Walkthrough**: Step-by-step what happens
4. **Gotcha**: Common mistake or misconception

Keep it clear and educational.

.claude/commands/pr.md

---
description: Create a pull request
allowed-tools: Bash(git:*), Bash(gh:*)
---

Create a pull request:

1. Ensure all changes are committed
2. Push branch: `git push -u origin HEAD`
3. Create PR with `gh pr create`:
   - Title: conventional commit style
   - Body: 
     - ## Summary
     - ## Changes
     - ## Testing
     - ## Screenshots (if UI)
4. Add appropriate labels if possible

.claude/commands/catchup.md

---
description: Load work-in-progress into context
allowed-tools: Bash(git:*)
---

Load current work state:

## Uncommitted Changes
!`git diff`

## Staged Changes  
!`git diff --staged`

## Recent Commits (last 5)
!`git log --oneline -5`

## Current Branch
!`git branch --show-current`

Summarize what's in progress and what might need attention.

.claude/commands/deploy-check.md

---
description: Pre-deployment checklist
allowed-tools: Bash
---

Run pre-deployment checks:

1. **Lint**: !`npm run lint` or equivalent
2. **Type Check**: !`npm run typecheck` or equivalent  
3. **Tests**: !`npm run test`
4. **Build**: !`npm run build`

Report any failures. If all pass, confirm ready for deployment.