100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Philosophy
|
|
|
|
- **Incremental progress over big bangs**: Break complex tasks into manageable stages
|
|
- **Learn from existing code**: Understand patterns before implementing new features
|
|
- **Clear intent over clever code**: Prioritize readability and maintainability
|
|
- **Simple over complex**: Keep all implementations simple and straightforward - prioritize solving problems and ease of maintenance over complex solutions
|
|
|
|
## Claude Code Eight Honors and Eight Shames
|
|
|
|
- **Shame** in guessing APIs, **Honor** in careful research
|
|
- **Shame** in vague execution, **Honor** in seeking confirmation
|
|
- **Shame** in assuming business logic, **Honor** in human verification
|
|
- **Shame** in creating interfaces, **Honor** in reusing existing ones
|
|
- **Shame** in skipping validation, **Honor** in proactive testing
|
|
- **Shame** in breaking architecture, **Honor** in following specifications
|
|
- **Shame** in pretending to understand, **Honor** in honest ignorance
|
|
- **Shame** in blind modification, **Honor** in careful refactoring
|
|
|
|
## Project Overview
|
|
|
|
Pake transforms any webpage into a lightweight desktop app using Rust and Tauri. It's significantly lighter than Electron (~5M vs ~100M+) with better performance.
|
|
|
|
**Core Architecture:**
|
|
|
|
- **CLI Tool** (`bin/`): TypeScript-based command interface
|
|
- **Tauri App** (`src-tauri/`): Rust desktop framework
|
|
- **Injection System**: Custom CSS/JS injection for webpages
|
|
|
|
## Development Workflow
|
|
|
|
1. **Understand**: Study existing patterns in codebase
|
|
2. **Plan**: Break complex work into 3-5 stages
|
|
3. **Test**: Write tests first (when applicable)
|
|
4. **Implement**: Minimal working solution
|
|
5. **Refactor**: Optimize and clean up
|
|
|
|
**Key Commands:**
|
|
|
|
```bash
|
|
pnpm test # Run comprehensive test suite
|
|
pnpm run cli:build # Build CLI for testing
|
|
pnpm run dev # Development with hot reload
|
|
```
|
|
|
|
**Testing:**
|
|
- Always run `pnpm test` before committing
|
|
- For CLI testing: `node dist/cli.js https://example.com --name TestApp --debug`
|
|
- For app functionality testing: Use `pnpm run dev` for hot reload
|
|
|
|
## Core Components
|
|
|
|
- **CLI Tool** (`bin/`): Main entry point, builders, options processing
|
|
- **Tauri App** (`src-tauri/`): Rust application, window/tray management, injection logic
|
|
- **Config Files**: `pake.json`, `tauri.conf.json`, platform-specific configs
|
|
|
|
## Documentation Guidelines
|
|
|
|
- **Main README**: Common parameters only
|
|
- **CLI Documentation** (`docs/cli-usage.md`): ALL parameters with examples
|
|
- **Rare parameters**: Full docs in CLI usage, minimal in main README
|
|
|
|
## Platform Specifics
|
|
|
|
- **macOS**: `.icns` icons, universal builds with `--multi-arch`
|
|
- **Windows**: `.ico` icons, requires Visual Studio Build Tools
|
|
- **Linux**: `.png` icons, multiple formats (deb, AppImage, rpm)
|
|
|
|
## Quality Standards
|
|
|
|
**Code Standards:**
|
|
|
|
- Prefer composition over inheritance
|
|
- Use explicit types over implicit
|
|
- Write self-documenting code
|
|
- Follow existing patterns consistently
|
|
- **NO Chinese comments** - Use English only
|
|
- **NO unnecessary comments** - For simple, obvious code, let the code speak for itself
|
|
|
|
**Git Guidelines:**
|
|
|
|
- **NEVER commit automatically** - User handles all git operations
|
|
- **NEVER generate commit messages** - User writes their own
|
|
- Only make code changes, user decides when/how to commit
|
|
- Always test before user commits
|
|
|
|
## Branch Strategy
|
|
|
|
- `dev` - Active development, target for PRs
|
|
- `main` - Release branch for stable versions
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js ≥22.0.0 (≥18.0.0 may work)
|
|
- Rust ≥1.89.0 (≥1.78.0 may work)
|
|
- Platform build tools (see CONTRIBUTING.md)
|