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

17 KiB

Raw Blame History

AGENT.md

Available MCP Tools

You have access to five powerful MCP tool sets for comprehensive research and analysis:

1. CodeGraphContext (CGC) - Local Code Analysis

Purpose: Analyze, understand, and navigate local codebases through graph-based relationships.

When to Use:

Working with existing code in the local repository
Understanding how code works together
Finding where functions/classes are defined or used
Analyzing the impact of code changes
Identifying dead code or complex code
Tracing execution flows across files
Refactoring or maintaining code

Key Tools:

codegraph_find_code - Find functions, classes, or code by keywords
codegraph_analyze_code_relationships - Analyze callers, callees, inheritance, dependencies
codegraph_watch_directory - Monitor active projects for real-time updates
codegraph_add_code_to_graph - Index code into the graph
codegraph_find_dead_code - Find potentially unused functions
codegraph_calculate_cyclomatic_complexity - Measure function complexity
codegraph_get_repository_stats - Understand codebase size and structure
codegraph_list_indexed_repositories - Check what code is available

Common Queries:

"Where is the process_payment function?"
"What functions call get_user_by_id?"
"If I change calculate_tax, what code will be affected?"
"Show me the call chain from main to process_data"
"Find dead or unused code in this project"
"What's the most complex function in this codebase?"

Best Practices:

Check codegraph_list_indexed_repositories first to see what code is available
Use codegraph_watch_directory for projects you're actively working on
Start with codegraph_find_code for simple searches
Use codegraph_analyze_code_relationships for deep analysis and impact assessment
Check codegraph_list_watched_paths to see what's being monitored
Background indexing jobs return a job_id - use codegraph_check_job_status to track progress

2. Context7 - Up-to-Date Library Documentation

Purpose: Get current, version-specific documentation and code examples for thousands of libraries and frameworks.

When to Use:

Needing up-to-date documentation for libraries or frameworks
Looking for code examples and best practices
Implementing new features using external libraries
Learning APIs you haven't used before
Wanting to avoid hallucinated APIs or outdated code
Working with specific versions of libraries

Key Tools:

context7_resolve-library-id - Find the correct library ID (max 3 calls/question)
context7_query-docs - Get documentation for a library (max 3 calls/question)

Usage Pattern:

Call context7_resolve-library-id with library name and your task
Review results, select best match based on description, trust score, benchmark score
Call context7_query-docs with the library ID and your specific question

If user provides library ID in /org/project format, you can skip step 1.

Common Queries:

"How do I set up authentication with Supabase?"
"Show me examples of using Next.js middleware"
"How to implement JWT auth with Express.js"
"What's the best way to handle errors in React hooks?"

Best Practices:

ALWAYS use context7_resolve-library-id first unless user provides exact library ID
Be specific in your query: "How to set up authentication with JWT" not "auth"
Max 3 calls: Do not call these tools more than 3 times per question
Check scores: Prioritize libraries with higher trust and benchmark scores
No secrets: Never include API keys, passwords, credentials, or personal data in queries
Explain choice: Briefly explain which library was selected when multiple matches exist

3. Brave - Quick Web Search

Purpose: Quick web searches for current information.

When to Use:

Needing fast, general web searches
Looking for recent news or updates
Finding current technology information
Quick research without deep crawling

Key Tools:

brave_brave_web_search - General web search
brave_brave_local_search - Local business/places search

4. Tavily - Advanced Search & Extraction

Purpose: Comprehensive web search with advanced capabilities including content extraction and crawling.

When to Use:

Needing in-depth research on technical topics
Extracting content from multiple URLs
Crawling entire websites for documentation
Finding detailed implementation examples

Key Tools:

tavily_tavily_search - Advanced search with detailed results
tavily_tavily_extract - Extract structured content from URLs
tavily_tavily_crawl - Crawl websites systematically
tavily_tavily_map - Map website structure

5. BrightData - Web Scraping & Data Extraction

Purpose: Comprehensive web scraping, structured data extraction, and browser automation.

When to Use:

Web scraping with anti-bot bypass
Structured data extraction (clean markdown, tables, embedded content)
Browser automation for complex, interactive websites
Testing web applications

Key Tools:

brightData_search_engine - Web search using Google Search API
brightData_scrape_as_markdown - Extract and convert to markdown
brightData_search_engine_batch - Multi-query searches
Playwright browser automation (11 tools)

Project Context

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

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 Roles & Responsibilities

UI/UX Agent

Responsibilities:

Design and implement UI components using Svelte 5 features (runes, snippets)
Apply Tailwind CSS classes following the mixed approach pattern:
- Use utilities directly for one-off styles
- Create component classes for repeated patterns
Ensure responsive design and accessibility (WCAG compliance)
Implement micro-interactions and animations
Work within Feature Sliced Design structure

Naming Conventions:

Components: PascalCase (e.g., UserProfile.svelte)
Utilities: camelCase (e.g., formatDate.ts)

Comment Style:

/**
 * Component description
 */
<script lang="ts">
  // Short remark for inline logic
</script>

When to Use:

"Design/create component", "Add styling", "UI implementation", "Add animations"

Feature Developer Agent

Responsibilities:

Create and manage FSD slices (pages, features, entities, widgets, shared)
Implement business logic and data flows
Integrate UI components with backend functionality
Follow FSD methodology for slice composition
Ensure proper separation of concerns across layers

FSD Structure:

src/
├── pages/        # Full pages
├── features/      # User interactions
├── entities/      # Business entities
├── widgets/       # Composed components
├── shared/        # Shared code
└── app/          # SvelteKit app layer (routes)

When to Use:

"Create feature", "Implement business logic", "Add page", "Create slice"

Test Engineer Agent

Responsibilities:

Write unit tests using Vitest
Write E2E tests using Playwright
Test critical user flows
Ensure test coverage meets quality standards
Follow test-driven approach for new features

Testing Infrastructure:

Unit tests: Vitest (Vite-native)
E2E tests: Playwright
Target coverage: 80%+ for new code
Write tests alongside implementation (TDD for new features)

When to Use:

"Write tests", "Test coverage", "Add E2E test", "Test flow"

Documentation Agent

Responsibilities:

Write inline code comments following "Less is more" principle
Create API documentation
Write README files and guides
Document FSD structure and slice usage
Explain core logic and caveats succinctly

Comment Patterns:

/**
 * Function description explaining core logic
 */
export function processPayment(data: PaymentData): Promise<Payment> {
  // Validate input data
  const validated = validateData(data);

  // Process payment with fallback
  return processWithFallback(validated);
}

When to Use:

"Write documentation", "Add comments", "Document API", "Create README"

Architecture Reviewer Agent

Responsibilities:

Review code for FSD compliance
Identify architectural violations and anti-patterns
Ensure proper layer separation
Check for circular dependencies
Verify component and slice integration patterns

Review Checklist:

FSD layer boundaries respected
No circular dependencies
Proper slice composition
Shared code appropriately extracted
Feature isolation maintained

When to Use:

"Review architecture", "Check FSD compliance", "Analyze code structure"

Key Workflows

1. Creating a New Feature

Prerequisites: None required

Steps:

Create feature branch:
```
git checkout -b feature/featureName
```
Plan FSD slice:
- Determine which layers needed (page, feature, entity, widget, shared)
- Identify dependencies between layers
- Plan data flow

Implement entities (bottom-up):

# Example: src/entities/user/ui/UserAvatar.svelte
# Example: src/entities/user/model/types.ts

Implement features:

# Example: src/features/auth/ui/LoginForm.svelte
# Example: src/features/auth/model/useAuth.ts

Compose widgets (if needed):

# Example: src/widgets/header/ui/Header.svelte

Create page:

# Example: src/pages/home/ui/HomePage.svelte
# Example: src/pages/home/index.ts

Integrate in app routes:

# src/app/routes/+page.svelte
import { HomePage } from '$lib/pages/home';

Write tests:
- Unit tests for business logic
- E2E tests for critical flows

Commit with conventional format:

git commit -m "feat(featureName): short yet capacitive description"

Output: Complete feature implementation with FSD-compliant structure

Success Criteria:

Feature works as specified
All tests pass
FSD layer boundaries respected
Code follows naming conventions
Comments explain core logic

2. Creating a New Component

Prerequisites: None required

Steps:

Identify layer:
- Entity: Reusable business entity component
- Feature: User interaction component
- Widget: Composed UI component
- Page: Full page component

Create component file:

# src/features/myFeature/ui/MyComponent.svelte

Write Svelte 5 component:

<script lang="ts">
  /**
   * Component description
   */
  let { data }: { data: DataType } = $props();

  // Reactive state with runes
  let state = $state({});
</script>

<div class="tailwind-classes">
  <!-- Component content -->
</div>

Add Tailwind styles:
- One-off styles: Use utilities directly
- Repeated patterns: Extract to shared classes

Export from index (if applicable):

// src/features/myFeature/index.ts
export { MyComponent } from './ui/MyComponent.svelte';

Write tests:

// src/features/myFeature/ui/MyComponent.test.ts

Commit:

git commit -m "feat(myFeature): add MyComponent for ..."

Output: Working component with tests

Success Criteria:

Component renders correctly
Follows naming conventions
Has appropriate tests
Styles follow Tailwind pattern

3. Running Tests

Prerequisites: Project initialized with Vitest and Playwright

Steps:

Run unit tests:
```
bun run test
# or
bun run test:watch
```
Run E2E tests:
```
bun run test:e2e
```
Run all tests:
```
bun run test:all
```
Check coverage:
```
bun run test:coverage
```

Output: Test results with pass/fail status

Success Criteria:

All tests pass
Coverage meets 80%+ for new code
No flaky tests

4. Building for Production

Prerequisites: Development complete, tests passing

Steps:

Run linting and formatting:
```
bun run lint
bun run format:check
```
Build application:
```
bun run build
```
Test build locally:
```
bun run preview
```
Build Docker image:
```
docker build -t allmywork:latest .
```

Test Docker container:

docker run -p 3000:3000 allmywork:latest

Output: Production-ready build and Docker image

Success Criteria:

Build completes without errors
Linting passes
Docker image runs successfully
Application accessible at expected port

5. Deploying to VPS

Prerequisites: Docker image built, VPS accessible

Steps:

Transfer image to VPS:

docker save allmywork:latest | gzip | ssh user@vps "docker load"

Or build directly on VPS:

ssh user@vps "cd /path/to/project && bun run build && docker build -t allmywork:latest ."

Stop old container (if exists):

ssh user@vps "docker stop allmywork && docker rm allmywork"

Run new container:

ssh user@vps "docker run -d --name allmywork -p 3000:3000 --restart unless-stopped allmywork:latest"

Verify deployment:
```
curl https://your-domain.com
```

Output: Running application on VPS

Success Criteria:

Container running
Application accessible
No errors in logs
HTTPS configured (if applicable)

Code Conventions

Naming

Components: PascalCase (e.g., UserProfile.svelte)
Files/Functions: camelCase (e.g., formatDate.ts, getUserData)
Types: PascalCase (e.g., UserData, PaymentResult)

Comments

Multiline comments (for documentation and types):

/**
 * Function description explaining core logic and caveats
 */

One-line comments (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
fix - Bug fix
chore - Maintenance tasks
refactor - Code refactoring
docs - Documentation changes
style - Code style changes
test - Test changes
perf - Performance improvements
ci - CI/CD changes
build - Build system changes
revert - Revert previous commit

Examples:

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

Tool Selection Decision Tree

Need help with code or libraries?
│
├─ LOCAL codebase analysis?
│  └─ YES → CodeGraphContext
│     ├─ Find something → codegraph_find_code
│     ├─ Understand relationships → codegraph_analyze_code_relationships
│     ├─ Check impact → find_callers, find_all_callers
│     └─ Code quality → find_dead_code, find_most_complex_functions
│
└─ EXTERNAL library/framework?
   └─ YES → Context7
      ├─ Have exact ID? → context7_query-docs
      └─ Need to find ID? → resolve-library-id → query-docs

Need web research?
│
├─ Quick search?
│  └─ YES → Brave
│     └─ brave_brave_web_search
│
├─ Advanced research/extraction?
│  └─ YES → Tavily
│     ├─ tavily_tavily_search
│     ├─ tavily_tavily_extract
│     └─ tavily_tavily_crawl
│
└─ Scraping/testing?
   └─ YES → BrightData
      ├─ brightData_search_engine
      ├─ brightData_scrape_as_markdown
      └─ Playwright tools

Deployment Strategy

Self-Hosted Docker Deployment:

Build: bun run build
Docker image: docker build -t allmywork:latest .
Run: docker run -d -p 3000:3000 --restart unless-stopped allmywork:latest
Update: docker stop && docker rm && docker run ...

Git Workflow

Branching Strategy:

Feature branches: feature/featureName
Bugfix branches: fix/issueName
Main branches: main, develop

Commit Process:

Write code
Run tests: bun run test:all
Run lint: bun run lint
Stage files: git add
Commit: git commit -m "prefix(feature): description"
Push: git push
Create PR

Use skip orchestrator when committing to avoid extra agent overhead.

17 KiB Raw Blame History

AGENT.md

Available MCP Tools

1. CodeGraphContext (CGC) - Local Code Analysis

2. Context7 - Up-to-Date Library Documentation

3. Brave - Quick Web Search

4. Tavily - Advanced Search & Extraction

5. BrightData - Web Scraping & Data Extraction

Project Context

Bun Usage Guidelines

Agent Roles & Responsibilities

UI/UX Agent

Feature Developer Agent

Test Engineer Agent

Documentation Agent

Architecture Reviewer Agent

Key Workflows

1. Creating a New Feature

2. Creating a New Component

3. Running Tests

4. Building for Production

5. Deploying to VPS

Code Conventions

Naming

Comments

Commit Messages

Tool Selection Decision Tree

Deployment Strategy

Git Workflow

17 KiB

Raw Blame History