docs: rewrite CLAUDE.md with project architecture and commands
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Naiyuan Qing
parent
1a1c3ec086
commit
456d9c5429
1 changed files with 94 additions and 55 deletions
149
CLAUDE.md
149
CLAUDE.md
|
|
@ -1,63 +1,102 @@
|
||||||
# Project Instructions for AI Agents
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
Super Multica is a distributed AI agent framework with a monorepo architecture. It includes an agent engine with multi-provider LLM support, a WebSocket gateway, a console hub for multi-agent coordination, and frontend apps (Next.js web, Electron desktop).
|
||||||
|
|
||||||
|
## Monorepo Structure
|
||||||
|
|
||||||
|
- **`src/`** — Core modules (agent engine, gateway, console, client, shared types)
|
||||||
|
- **`apps/web`** — Next.js 16 web app (`@multica/web`, port 3001)
|
||||||
|
- **`apps/desktop`** — Electron + Vite + React desktop app (`@multica/desktop`)
|
||||||
|
- **`packages/ui`** — Shared UI component library (`@multica/ui`, Shadcn/Tailwind CSS v4)
|
||||||
|
- **`packages/sdk`** — Gateway client SDK (`@multica/sdk`, Socket.io)
|
||||||
|
- **`packages/store`** — Zustand state management (`@multica/store`)
|
||||||
|
- **`skills/`** — Bundled agent skills (commit, code-review, skill-creator)
|
||||||
|
|
||||||
|
## Common Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Development (all services concurrently: gateway:3000, console, web:3001)
|
||||||
|
pnpm dev
|
||||||
|
|
||||||
|
# Individual services
|
||||||
|
pnpm dev:gateway # WebSocket gateway only
|
||||||
|
pnpm dev:console # NestJS console with agent
|
||||||
|
pnpm dev:web # Next.js web app
|
||||||
|
pnpm dev:desktop # Electron desktop app
|
||||||
|
|
||||||
|
# Agent CLI
|
||||||
|
pnpm agent:cli # Non-interactive agent
|
||||||
|
pnpm agent:interactive # Interactive REPL mode
|
||||||
|
|
||||||
|
# Build (turbo-orchestrated)
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# Type checking
|
||||||
|
pnpm typecheck
|
||||||
|
|
||||||
|
# Testing (vitest, tests live in src/**/*.test.ts)
|
||||||
|
pnpm test # Single run
|
||||||
|
pnpm test:watch # Watch mode
|
||||||
|
pnpm test:coverage # With v8 coverage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
Frontend (web:3001 / desktop)
|
||||||
|
→ @multica/sdk (GatewayClient, Socket.io)
|
||||||
|
→ Gateway (NestJS, WebSocket, port 3000)
|
||||||
|
→ Console Hub (multi-agent coordination)
|
||||||
|
→ Agent Engine (LLM runner, sessions, skills, tools)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Agent Engine** (`src/agent/`): Orchestrates LLM interactions with multi-provider support (OpenAI, Anthropic, DeepSeek, Kimi, Groq, Mistral, Google, Together). Features session management (JSONL-based, UUIDv7 IDs), profile system (`~/.super-multica/agent-profiles/`), modular skills with hot-reload, and token-aware context window guards (compaction modes: tokens, count, summary).
|
||||||
|
|
||||||
|
**Gateway** (`src/gateway/`): NestJS WebSocket server with Socket.io for real-time message passing, RPC request/response, and streaming.
|
||||||
|
|
||||||
|
**Console** (`src/console/`): NestJS hub for multi-agent coordination with a web dashboard.
|
||||||
|
|
||||||
|
## Tech Stack & Config
|
||||||
|
|
||||||
|
- **Package manager**: pnpm 10 with workspaces (`pnpm-workspace.yaml`)
|
||||||
|
- **Build orchestration**: Turborepo (`turbo.json`)
|
||||||
|
- **TypeScript**: ESNext target, NodeNext modules, strict mode, `verbatimModuleSyntax`, `experimentalDecorators` (NestJS)
|
||||||
|
- **Testing**: Vitest with globals enabled, node environment
|
||||||
|
- **Frontend**: React 19, Next.js 16, Tailwind CSS v4, Shadcn/UI (zinc base, hugeicons)
|
||||||
|
- **Backend**: NestJS 11, Socket.io, Pino logging
|
||||||
|
- **CLI bundling**: esbuild → `bin/` directory
|
||||||
|
|
||||||
|
## Environment Setup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
# Set LLM_PROVIDER and corresponding API keys
|
||||||
|
# Supported: openai, anthropic, deepseek, kimi-coding, groq, mistral, together, google
|
||||||
|
# .env is loaded automatically via --env-file in all dev/agent scripts
|
||||||
|
```
|
||||||
|
|
||||||
## Atomic Commits
|
## Atomic Commits
|
||||||
|
|
||||||
After completing any task that modifies code, you MUST create atomic commits before ending the conversation. Do not ask for permission - just do it.
|
After completing any task that modifies code, create atomic commits without asking for permission.
|
||||||
|
|
||||||
### Workflow
|
1. Run `git status` and `git diff` to see all modifications
|
||||||
|
2. Skip if no changes exist
|
||||||
|
3. Group changes by logical purpose (feature, fix, refactor, docs, test, chore)
|
||||||
|
4. Stage and commit each group separately
|
||||||
|
|
||||||
1. **Check for changes**: Run `git status` and `git diff` to see all modifications
|
**Format**: Conventional commits — `<type>(<scope>): <description>`
|
||||||
2. **Skip if clean**: If there are no changes, skip the commit process
|
|
||||||
3. **Analyze changes**: Group changes by their logical purpose:
|
|
||||||
- Feature additions
|
|
||||||
- Bug fixes
|
|
||||||
- Refactoring
|
|
||||||
- Documentation
|
|
||||||
- Tests
|
|
||||||
- Configuration/dependencies
|
|
||||||
4. **Create atomic commits**: For each logical group, stage only the relevant files and create a separate commit
|
|
||||||
|
|
||||||
### Commit Process
|
Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
|
||||||
|
|
||||||
For each logical group of changes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Stage specific files for this logical change
|
|
||||||
git add <file1> <file2>
|
|
||||||
|
|
||||||
# Commit with conventional commit message
|
|
||||||
git commit -m "<type>(<scope>): <description>"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Commit Message Format
|
|
||||||
|
|
||||||
Use conventional commits:
|
|
||||||
- `feat`: New feature
|
|
||||||
- `fix`: Bug fix
|
|
||||||
- `refactor`: Code refactoring (no functional change)
|
|
||||||
- `docs`: Documentation changes
|
|
||||||
- `test`: Adding or updating tests
|
|
||||||
- `chore`: Build, config, dependencies
|
|
||||||
|
|
||||||
### Examples
|
|
||||||
|
|
||||||
If you modified:
|
|
||||||
- `src/api/user.ts` (added new endpoint)
|
|
||||||
- `src/api/user.test.ts` (tests for new endpoint)
|
|
||||||
- `src/utils/format.ts` (refactored helper)
|
|
||||||
- `README.md` (updated docs)
|
|
||||||
|
|
||||||
Create three commits:
|
|
||||||
1. `git add src/api/user.ts src/api/user.test.ts && git commit -m "feat(api): add user profile endpoint"`
|
|
||||||
2. `git add src/utils/format.ts && git commit -m "refactor(utils): simplify date formatting logic"`
|
|
||||||
3. `git add README.md && git commit -m "docs: update API documentation"`
|
|
||||||
|
|
||||||
### Rules
|
|
||||||
|
|
||||||
|
**Rules**:
|
||||||
- Each commit should be independently meaningful and buildable
|
- Each commit should be independently meaningful and buildable
|
||||||
- Related test files should be committed with their implementation
|
- Related test files go with their implementation
|
||||||
- Never create empty commits
|
- Never create empty commits or combine unrelated changes
|
||||||
- Never combine unrelated changes in one commit
|
- `git commit --amend` only for immediate small fixes to the last commit
|
||||||
- Keep commit messages concise but descriptive
|
|
||||||
- If all changes are related to one logical unit, a single commit is fine
|
|
||||||
- `git commit --amend` can be used for immediate small fixes to the last commit, but not for unrelated changes
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue