Keith WilliamsandDevin AI
d4ea931bf8
* feat(agents): add modular engineering rules from 2026 standards Add a rules directory with individual rule files derived from the Cal.com Engineering in 2026 and Beyond blog post. Rules are organized by section (architecture, quality, data, api, performance, testing, patterns, culture) following the Vercel agent-skills structure. Includes: - _sections.md defining rule categories and impact levels - _template.md for creating new rules - 14 individual rule files covering key engineering standards - README documenting the rules structure and usage Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * feat(agents): consolidate DI and Repository+DTO docs into rules - Move di-pattern.md content to rules/patterns-di-pattern.md - Extract Repository + DTO section from knowledge-base.md into: - rules/data-repository-methods.md (method naming conventions) - rules/data-dto-boundaries.md (DTO location and naming) - Update knowledge-base.md to reference the new rule files - Delete old di-pattern.md file Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * chore(agents): remove stub reference sections from knowledge-base.md The rules directory is self-contained with its own README, so these redirect sections are unnecessary clutter. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * refactor(agents): combine DI pattern rules into single file Merged patterns-di-pattern.md into patterns-dependency-injection.md to eliminate overlap and create one comprehensive DI guide. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
84 lines
2.4 KiB
Markdown
84 lines
2.4 KiB
Markdown
# Cal.com Development Guide for AI Agents
|
|
|
|
This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.
|
|
|
|
## Quick Navigation
|
|
|
|
- **[Rules](rules/)** - Modular engineering rules derived from our 2026 standards
|
|
- **[Commands](commands.md)** - Build, test, and development commands
|
|
- **[Knowledge Base](knowledge-base.md)** - Knowledge base & best practices
|
|
- **[Architecture Overview](#architecture-overview)** - System structure and patterns
|
|
|
|
## Getting Started
|
|
|
|
Cal.com is a monorepo using Yarn workspaces and Turbo for build orchestration. The main application is in `apps/web/` with shared packages in `packages/`.
|
|
|
|
### Key Directories
|
|
|
|
- `apps/web/` - Main Next.js application
|
|
- `packages/prisma/` - Database schema and migrations
|
|
- `packages/trpc/` - API layer using tRPC
|
|
- `packages/ui/` - Shared UI components
|
|
- `packages/features/` - Feature-specific code
|
|
- `packages/app-store/` - Third-party app integrations
|
|
|
|
## Architecture Overview
|
|
|
|
### Database Layer
|
|
|
|
- **Prisma ORM** with PostgreSQL
|
|
- Schema in `packages/prisma/schema.prisma`
|
|
- Always use `select` instead of `include` for better performance
|
|
- Never expose `credential.key` field in API responses
|
|
|
|
### API Layer
|
|
|
|
- **tRPC** for type-safe APIs
|
|
- Routers in `packages/trpc/server/routers/`
|
|
- Authentication handled via NextAuth.js
|
|
|
|
### Frontend
|
|
|
|
- **Next.js 13+** with App Router in some areas
|
|
- **React 18** with TypeScript
|
|
- **Tailwind CSS** for styling
|
|
- Internationalization with `next-i18next`
|
|
|
|
## Common Patterns
|
|
|
|
### Error Handling
|
|
|
|
- Use early returns to reduce nesting
|
|
- Throw descriptive errors with proper error codes
|
|
- Prefer composition over prop drilling
|
|
|
|
### Performance
|
|
|
|
- Avoid O(n²) logic in backend code
|
|
- Minimize Day.js usage in performance-critical paths
|
|
- Use `select` queries to only fetch needed data
|
|
- Consider using `.utc()` for Day.js operations
|
|
|
|
### Security
|
|
|
|
- Never commit secrets or API keys
|
|
- Always validate input data
|
|
- Use proper authentication checks
|
|
- Never expose sensitive credential fields
|
|
|
|
## Testing Strategy
|
|
|
|
- **Unit tests** with Vitest
|
|
- **Integration tests** for complex workflows
|
|
- **E2E tests** with Playwright
|
|
- Test files use `.test.ts` or `.spec.ts` extensions
|
|
|
|
## Pull Request Guidelines
|
|
|
|
For large PRs (>500 lines or >10 files):
|
|
|
|
- Split by feature boundaries
|
|
- Separate database migrations, backend logic, frontend components
|
|
- Create dependency chains that can be merged sequentially
|
|
- Pattern: Database → Backend → Frontend → Tests
|