docs(CLAUDE.md): add code style section aligned with glyphdiff conventions
This commit is contained in:
Ilia Mashkov
666
AGENT.md
Normal file
666
AGENT.md
Normal file
@@ -0,0 +1,666 @@
|
||||
# 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**:
|
||||
1. Call `context7_resolve-library-id` with library name and your task
|
||||
2. Review results, select best match based on description, trust score, benchmark score
|
||||
3. 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```svelte
|
||||
/**
|
||||
* 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**:
|
||||
```typescript
|
||||
/**
|
||||
* 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**:
|
||||
|
||||
1. **Create feature branch**:
|
||||
```bash
|
||||
git checkout -b feature/featureName
|
||||
```
|
||||
|
||||
2. **Plan FSD slice**:
|
||||
- Determine which layers needed (page, feature, entity, widget, shared)
|
||||
- Identify dependencies between layers
|
||||
- Plan data flow
|
||||
|
||||
3. **Implement entities** (bottom-up):
|
||||
```bash
|
||||
# Example: src/entities/user/ui/UserAvatar.svelte
|
||||
# Example: src/entities/user/model/types.ts
|
||||
```
|
||||
|
||||
4. **Implement features**:
|
||||
```bash
|
||||
# Example: src/features/auth/ui/LoginForm.svelte
|
||||
# Example: src/features/auth/model/useAuth.ts
|
||||
```
|
||||
|
||||
5. **Compose widgets** (if needed):
|
||||
```bash
|
||||
# Example: src/widgets/header/ui/Header.svelte
|
||||
```
|
||||
|
||||
6. **Create page**:
|
||||
```bash
|
||||
# Example: src/pages/home/ui/HomePage.svelte
|
||||
# Example: src/pages/home/index.ts
|
||||
```
|
||||
|
||||
7. **Integrate in app routes**:
|
||||
```bash
|
||||
# src/app/routes/+page.svelte
|
||||
import { HomePage } from '$lib/pages/home';
|
||||
```
|
||||
|
||||
8. **Write tests**:
|
||||
- Unit tests for business logic
|
||||
- E2E tests for critical flows
|
||||
|
||||
9. **Commit with conventional format**:
|
||||
```bash
|
||||
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**:
|
||||
|
||||
1. **Identify layer**:
|
||||
- Entity: Reusable business entity component
|
||||
- Feature: User interaction component
|
||||
- Widget: Composed UI component
|
||||
- Page: Full page component
|
||||
|
||||
2. **Create component file**:
|
||||
```bash
|
||||
# src/features/myFeature/ui/MyComponent.svelte
|
||||
```
|
||||
|
||||
3. **Write Svelte 5 component**:
|
||||
```svelte
|
||||
<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>
|
||||
```
|
||||
|
||||
4. **Add Tailwind styles**:
|
||||
- One-off styles: Use utilities directly
|
||||
- Repeated patterns: Extract to shared classes
|
||||
|
||||
5. **Export from index** (if applicable):
|
||||
```typescript
|
||||
// src/features/myFeature/index.ts
|
||||
export { MyComponent } from './ui/MyComponent.svelte';
|
||||
```
|
||||
|
||||
6. **Write tests**:
|
||||
```typescript
|
||||
// src/features/myFeature/ui/MyComponent.test.ts
|
||||
```
|
||||
|
||||
7. **Commit**:
|
||||
```bash
|
||||
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**:
|
||||
|
||||
1. **Run unit tests**:
|
||||
```bash
|
||||
bun run test
|
||||
# or
|
||||
bun run test:watch
|
||||
```
|
||||
|
||||
2. **Run E2E tests**:
|
||||
```bash
|
||||
bun run test:e2e
|
||||
```
|
||||
|
||||
3. **Run all tests**:
|
||||
```bash
|
||||
bun run test:all
|
||||
```
|
||||
|
||||
4. **Check coverage**:
|
||||
```bash
|
||||
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**:
|
||||
|
||||
1. **Run linting and formatting**:
|
||||
```bash
|
||||
bun run lint
|
||||
bun run format:check
|
||||
```
|
||||
|
||||
2. **Build application**:
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
3. **Test build locally**:
|
||||
```bash
|
||||
bun run preview
|
||||
```
|
||||
|
||||
4. **Build Docker image**:
|
||||
```bash
|
||||
docker build -t allmywork:latest .
|
||||
```
|
||||
|
||||
5. **Test Docker container**:
|
||||
```bash
|
||||
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**:
|
||||
|
||||
1. **Transfer image to VPS**:
|
||||
```bash
|
||||
docker save allmywork:latest | gzip | ssh user@vps "docker load"
|
||||
```
|
||||
|
||||
2. **Or build directly on VPS**:
|
||||
```bash
|
||||
ssh user@vps "cd /path/to/project && bun run build && docker build -t allmywork:latest ."
|
||||
```
|
||||
|
||||
3. **Stop old container** (if exists):
|
||||
```bash
|
||||
ssh user@vps "docker stop allmywork && docker rm allmywork"
|
||||
```
|
||||
|
||||
4. **Run new container**:
|
||||
```bash
|
||||
ssh user@vps "docker run -d --name allmywork -p 3000:3000 --restart unless-stopped allmywork:latest"
|
||||
```
|
||||
|
||||
5. **Verify deployment**:
|
||||
```bash
|
||||
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):
|
||||
```typescript
|
||||
/**
|
||||
* Function description explaining core logic and caveats
|
||||
*/
|
||||
```
|
||||
|
||||
**One-line comments** (for short remarks):
|
||||
```typescript
|
||||
// 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**:
|
||||
1. Write code
|
||||
2. Run tests: `bun run test:all`
|
||||
3. Run lint: `bun run lint`
|
||||
4. Stage files: `git add`
|
||||
5. Commit: `git commit -m "prefix(feature): description"`
|
||||
6. Push: `git push`
|
||||
7. Create PR
|
||||
|
||||
**Use `skip orchestrator` when committing** to avoid extra agent overhead.
|
||||
Reference in New Issue
Block a user