ilia/allmy.work

Fork 0

Files

Ilia Mashkov e2eba5ec55 docs(CLAUDE.md): add code style section aligned with glyphdiff conventions

2026-03-06 23:03:45 +03:00

12 KiB

Raw Permalink Blame History

Project Configuration

Language: TypeScript
Package Manager: Bun
Add-ons: none

CLAUDE.md

Project Overview

Name: allmywork Purpose: Portfolio web application Stack: SvelteKit + Bun + Biome + Tailwind CSS + Feature Sliced Design (FSD) Deployment: Self-hosted on VPS with Docker

Bun Usage Guidelines

Always use bun commands, never npm:

Package management: bun install, bun add, bun remove
Script execution: bun run <script-name>
Running binaries: Use bunx <package> instead of npx <package>
Test runner: bun test or bun run test (Vitest via Bun)

Examples:

# Install dependencies
bun install

# Add dependency
bun add -D tailwindcss

# Run script
bun run dev

# Run binary (instead of npx)
bunx @biomejs/biome init

# Run tests (Vitest via Bun)
bun run test

Agent Fleet

Use the following agents for different tasks:

Agent	When to Use
`technical-architect`	Design architecture, API schemas, database design
`builder`	Write code, implement features, fix bugs, manage Git
`qa-reliability-engineer`	Test strategy, performance analysis, SLOs
`design-specialist`	UI/UX design, component design, styling
`knowledge-architect`	Documentation, research, explain concepts
`ops-engineer`	Deployment, CI/CD, infrastructure
`security`	Security review, vulnerability assessment
`workflow-orchestrator`	Multi-agent task coordination

Technology Stack

Core Framework

SvelteKit: Full-stack framework with file-based routing
Svelte 5: Using runes ($state, $derived, $effect) and snippets
TypeScript: Strict mode enabled

Runtime & Build

Bun: Package manager and runtime
Vite: Build tool (included with SvelteKit)

Code Quality

Biome: Linting and formatting (ESLint/Prettier replacement)
Configuration: Includes .svelte files in files.includes

Styling

Tailwind CSS: Utility-first CSS
Integration: Via PostCSS with vitePreprocess({ style: true })
Pattern: Mixed approach - utilities for one-off, classes for repeated patterns

Architecture

Feature Sliced Design (FSD):
- pages/ - Full pages
- features/ - User interactions
- entities/ - Business entities
- widgets/ - Composed components
- shared/ - Shared code
- app/ - SvelteKit routes (configured via svelte.config.ts)

Testing

Vitest: Unit testing (Vite-native)
Playwright: E2E testing
Coverage target: 80%+ for new code

Development Workflow

1. Start Development

# Install dependencies
bun install

# Start dev server
bun run dev -- --open

# Watch for changes
bun run dev

Note: Always use bun commands, never npm. For running binaries (like npx), use bunx instead.

2. Code Quality

# Lint code
bun run lint

# Format code
bun run format

# Check format without modifying
bun run format:check

# Fix all issues
bun run lint:fix && bun run format

3. Testing

# Run unit tests
bun run test

# Run E2E tests
bun run test:e2e

# Run all tests
bun run test:all

# Watch mode
bun run test:watch

# Coverage report
bun run test:coverage

4. Build & Deploy

# Build for production
bun run build

# Preview build
bun run preview

# Build Docker image
docker build -t allmywork:latest .

# Run Docker container
docker run -d -p 3000:3000 --restart unless-stopped allmywork:latest

Code Conventions

Naming

Type	Convention	Example
Components	PascalCase	`UserProfile.svelte`
Functions/Files	camelCase	`formatDate.ts`, `getUserData`
Types/Interfaces	PascalCase	`UserData`, `PaymentResult`
Constants	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`

Comment Style

Multiline (for documentation and types):

/**
 * Process payment with retry logic
 * Handles transient failures with exponential backoff
 */

One-line (for short remarks):

// Validate input before processing

Rule: "Less is more" - short yet capacitive, explaining core logic and caveats

Commit Messages

Format: prefix(featureName/fileName): short yet capacitive one-line description

Prefixes:

feat - New feature introduced
fix - Bug fix
chore - Maintenance tasks (no code changes)
refactor - Code refactoring (no functional change)
docs - Documentation changes
style - Code style changes
test - Test additions/corrections
perf - Performance improvements
ci - CI/CD changes
build - Build system changes
revert - Revert previous commit

Examples:

feat(auth): add OAuth2 token refresh flow
fix(payment): resolve memory leak in service
docs(readme): update deployment instructions

FSD Structure

src/
├── pages/          # Full pages (top-level FSD layer)
│   ├── home/
│   │   ├── ui/
│   │   │   └── HomePage.svelte
│   │   └── index.ts
│   └── about/
├── features/        # User interactions
│   ├── auth/
│   │   ├── ui/
│   │   │   ├── LoginForm.svelte
│   │   │   └── RegisterForm.svelte
│   │   ├── model/
│   │   │   ├── useAuth.ts
│   │   │   └── types.ts
│   │   └── index.ts
│   └── contact/
├── entities/        # Business entities
│   ├── user/
│   │   ├── ui/
│   │   │   └── UserAvatar.svelte
│   │   ├── model/
│   │   │   └── types.ts
│   │   └── index.ts
│   └── project/
├── widgets/         # Composed UI components
│   ├── header/
│   │   ├── ui/
│   │   │   └── Header.svelte
│   │   └── index.ts
│   └── footer/
├── shared/          # Shared code
│   ├── ui/
│   │   ├── Button.svelte
│   │   └── Input.svelte
│   ├── config/
│   │   └── site.ts
│   └── lib/
│       └── api.ts
└── app/            # SvelteKit app layer
    └── routes/
        ├── +layout.svelte
        ├── +page.svelte
        └── about/
            └── +page.svelte

FSD Rules

Bottom-up composition: entities → features → widgets → pages → app
Public API: Each slice exports via index.ts
No upward dependencies: Lower layers cannot import from higher layers
Shared: Only use shared/ for truly cross-cutting concerns

Key Workflows

Creating a Feature

Create feature branch: git checkout -b feature/featureName
Plan FSD slice structure (pages → features → entities)
Implement entities (bottom layer)
Implement features with business logic
Compose widgets (if needed)
Create page
Integrate in app/routes/+page.svelte
Write tests (unit + E2E)
Commit: git commit -m "feat(feature): description"
Create PR

Running Tests Before Commit

# Always run before committing
bun run lint          # Check code quality
bun run test:all      # Run all tests
bun run format:check   # Check formatting

# Fix issues
bun run lint:fix
bun run format

Building for Deployment

Run tests: bun run test:all
Lint code: bun run lint
Build: bun run build
Build Docker image: docker build -t allmywork:latest .
Test Docker container: docker run -p 3000:3000 allmywork:latest
Deploy to VPS (see docs/deployment.md)

Important Notes

Svelte 5 Features

Use runes for reactivity: $state, $derived, $effect
Use snippets for reusable logic
TypeScript strict mode enabled

Biome Configuration

Lints and formats .svelte files
Initialize with bunx @biomejs/biome init
Run bun run lint and bun run format before commits
Configuration in biome.json

Tailwind Usage

Direct utilities: class="p-4 bg-blue-500 text-white" (one-off)
Component classes: Repeated patterns extracted to shared components
Design tokens in tailwind.config.ts

Deployment

Self-hosted on VPS with Docker
No Vercel/Netlify integration
Docker image contains full application
Use docker restart allmywork for updates

Git Workflow

Feature branches with PRs
Use skip orchestrator when committing
Conventional commit format enforced
Self-review before merging

Documentation

Project Docs: /docs/ folder contains detailed guides

docs/development.md - Development workflow
docs/testing.md - Testing strategy
docs/deployment.md - Deployment procedures
docs/fsd.md - FSD architecture guide

External Resources:

Troubleshooting

Build Issues

# Clear build cache
rm -rf .svelte-kit
rm -rf node_modules/.vite

# Rebuild
bun install
bun run build

Biome Not Formatting Svelte Files

Check biome.json includes .svelte in files.includes
Ensure Biome extension is installed in VS Code

Tailwind Classes Not Applying

Check src/app.css includes Tailwind directives
Verify tailwind.config.ts content paths include src/**/*.{svelte,ts,js}
Ensure PostCSS is enabled in svelte.config.ts

FSD Import Errors

Check slice index.ts exports
Verify no upward dependencies
Ensure proper path aliases configured

Getting Help

For code implementation: Use builder agent For architecture decisions: Use technical-architect agent For testing issues: Use qa-reliability-engineer agent For UI/UX design: Use design-specialist agent For documentation: Use knowledge-architect agent For deployment: Use ops-engineer agent For security review: Use security agent

Multi-agent tasks: Use workflow-orchestrator agent

Code Style

Formatting (Biome)

Indent: tabs
Quote style: double quotes for JS/TS, double quotes for Svelte attributes
Line width: 120 characters
Semicolons: always
Trailing commas: all

TypeScript

Strict mode: on
Prefer interface over type for object shapes
Always type component props via an interface Props { ... } block
Use $props() rune — never export let
Use $derived() and $effect() — never Svelte 4 $: syntax
Use $state() for all reactive primitives

Component Conventions

File name: PascalCase (Button.svelte, ProjectCard.svelte)
Store files: camelCase with .svelte.ts suffix (sidebarStore.svelte.ts)
Story files: .stories.svelte suffix (Storybook CSF with Svelte addon)
Test files: .test.ts for unit, .svelte.test.ts for component tests
Each slice exports a public API via index.ts

Svelte 5 Patterns

<script lang="ts">
import { cn } from '$shared/lib/cn';
import type { Snippet } from 'svelte';
import type { HTMLButtonAttributes } from 'svelte/elements';

interface Props extends HTMLButtonAttributes {
    variant?: 'primary' | 'secondary';
    children: Snippet;
    class?: string;
}

let { variant = 'primary', children, class: className, ...rest }: Props = $props();

const classes = $derived(cn(baseStyles, variantStyles[variant], className));
</script>

<button class={classes} {...rest}>
    {@render children()}
</button>

Comments

Multiline JSDoc (/** ... */) for exported functions and component description headers
Single-line (//) for inline logic remarks
Principle: "less is more" — explain the why, not the what

Import Order (Biome organizeImports)

Svelte/SvelteKit built-ins (svelte, $app/...)
FSD layer aliases ($shared/..., $entities/..., etc.)
Relative imports (./, ../)

Commit Messages

Format: prefix(scope): short description Prefixes: feat, fix, chore, refactor, docs, style, test, perf, ci, build, revert Example: feat(shared/ui): add Button component with brutalist variants

12 KiB Raw Permalink Blame History

Project Configuration

CLAUDE.md

Project Overview

Bun Usage Guidelines

Agent Fleet

Technology Stack

Core Framework

Runtime & Build

Code Quality

Styling

Architecture

Testing

Development Workflow

1. Start Development

2. Code Quality

3. Testing

4. Build & Deploy

Code Conventions

Naming

Comment Style

Commit Messages

FSD Structure

FSD Rules

Key Workflows

Creating a Feature

Running Tests Before Commit

Building for Deployment

Important Notes

Svelte 5 Features

Biome Configuration

Tailwind Usage

Deployment

Git Workflow

Documentation

Troubleshooting

Build Issues

Biome Not Formatting Svelte Files

Tailwind Classes Not Applying

FSD Import Errors

Getting Help

Code Style

Formatting (Biome)

TypeScript

Component Conventions

Svelte 5 Patterns

Comments

Import Order (Biome organizeImports)

Commit Messages

12 KiB

Raw Permalink Blame History