mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:41:09 +02:00
1f589c474c
The flow was only documented in code comments scattered across the catalog, executor, and runner. This guide collects the three-file contract (catalog / executor / init.ts), the auto-vs-propose policy matrix, and the drift-guard semantics into one place so future sessions adding a new module's tools have a single entry point. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
130 lines
4.8 KiB
Markdown
130 lines
4.8 KiB
Markdown
# Claude Code Guidelines
|
|
|
|
This directory contains comprehensive guidelines for working in the Mana Universe monorepo. These documents are designed to help Claude Code (and developers) maintain consistency across all projects.
|
|
|
|
## Quick Reference
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| [Code Style](./guidelines/code-style.md) | Formatting, naming conventions, linting rules |
|
|
| [Database](./guidelines/database.md) | Drizzle ORM patterns, schema design, migrations |
|
|
| [Testing](./guidelines/testing.md) | Jest/Vitest patterns, mock factories, coverage |
|
|
| [Hono Server](./guidelines/hono-server.md) | Compute servers (Hono + Bun) |
|
|
| [Error Handling](./guidelines/error-handling.md) | Go-style errors, error codes, Result types |
|
|
| [SvelteKit Web](./guidelines/sveltekit-web.md) | Svelte 5 runes, stores, routing |
|
|
| [Expo Mobile](./guidelines/expo-mobile.md) | React Native, NativeWind, navigation |
|
|
| [Authentication](./guidelines/authentication.md) | Mana Core Auth integration |
|
|
| [Design & UX](./guidelines/design-ux.md) | UI patterns, animations, accessibility |
|
|
| [AI Tools](./guidelines/ai-tools.md) | Adding AI tools to a module (catalog + executor + registration) |
|
|
|
|
## Core Principles
|
|
|
|
### 1. Explicit Over Implicit
|
|
- Use Go-style error handling with explicit `Result<T>` returns
|
|
- Prefer named exports over default exports
|
|
- Use explicit types instead of `any`
|
|
|
|
### 2. Consistency Over Preference
|
|
- Follow existing patterns in the codebase
|
|
- Use shared packages for common functionality
|
|
- Maintain consistent naming across all projects
|
|
|
|
### 3. Simplicity Over Cleverness
|
|
- Don't over-engineer solutions
|
|
- Avoid premature abstractions
|
|
- Keep files focused and small
|
|
|
|
### 4. Safety First
|
|
- Always validate user input
|
|
- Use parameterized queries (Drizzle handles this)
|
|
- Never expose sensitive data in responses
|
|
|
|
## Technology Stack Summary
|
|
|
|
| Layer | Technology | Notes |
|
|
|-------|------------|-------|
|
|
| **Package Manager** | pnpm 9.15+ | Workspace monorepo |
|
|
| **Build System** | Turborepo | Parallel task execution |
|
|
| **Server** | Hono + Bun | TypeScript, Drizzle ORM |
|
|
| **Web** | SvelteKit 2 + Svelte 5 | Runes mode only |
|
|
| **Mobile** | Expo SDK 52-54 | React Native, NativeWind |
|
|
| **Database** | PostgreSQL | Via Drizzle ORM |
|
|
| **Auth** | Mana Core Auth | Better Auth, EdDSA JWT |
|
|
| **Storage** | S3-compatible | MinIO |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
manacore-monorepo/
|
|
├── .claude/
|
|
│ ├── GUIDELINES.md # This file
|
|
│ ├── guidelines/ # Detailed guidelines
|
|
│ └── templates/ # Code templates
|
|
├── apps/ # Product applications
|
|
│ └── {project}/
|
|
│ ├── apps/
|
|
│ │ ├── server/ # Hono/Bun compute server
|
|
│ │ ├── web/ # SvelteKit web
|
|
│ │ ├── mobile/ # Expo app
|
|
│ │ └── landing/ # Astro landing
|
|
│ └── packages/ # Project-specific shared
|
|
├── packages/ # Monorepo-wide shared
|
|
│ ├── shared-errors/ # Error codes & Result types
|
|
│ ├── shared-auth/ # Client auth service
|
|
│ ├── local-store/ # Local-first data layer (Dexie.js + sync)
|
|
│ └── ...
|
|
├── services/ # Standalone microservices
|
|
│ └── mana-core-auth/ # Central auth service
|
|
└── CLAUDE.md # Root project overview
|
|
```
|
|
|
|
## Before Making Changes
|
|
|
|
1. **Read the relevant guideline** for the area you're working in
|
|
2. **Check existing patterns** in similar files
|
|
3. **Use shared packages** when available
|
|
4. **Follow the error handling pattern** with Result types
|
|
5. **Write tests** for new functionality
|
|
|
|
## Error Handling Philosophy
|
|
|
|
We use **Go-style error handling** across the entire stack:
|
|
|
|
```typescript
|
|
// Backend services return Result<T>
|
|
const result = await userService.findById(id);
|
|
if (!result.ok) {
|
|
// Handle error with error code
|
|
throw new AppException(result.error);
|
|
}
|
|
return result.data;
|
|
|
|
// Frontend handles errors explicitly
|
|
const { data, error } = await api.getUser(id);
|
|
if (error) {
|
|
showToast(error.message);
|
|
return;
|
|
}
|
|
```
|
|
|
|
See [Error Handling](./guidelines/error-handling.md) for complete details.
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
# Development
|
|
pnpm install # Install dependencies
|
|
pnpm {project}:dev # Start project (all apps)
|
|
pnpm dev:{project}:server # Start just Hono server
|
|
pnpm dev:{project}:local # Start sync + server + web (no auth)
|
|
pnpm dev:{project}:web # Start just web
|
|
|
|
# Quality
|
|
pnpm type-check # TypeScript validation
|
|
pnpm format # Format code
|
|
pnpm test # Run tests
|
|
|
|
# Database (for apps with Drizzle in server)
|
|
pnpm --filter @{project}/server db:push # Push schema changes
|
|
pnpm --filter @{project}/server db:studio # Open Drizzle Studio
|
|
```
|