CLAUDE.md

1# Development Guide
2 
3This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
4 
5<critical>
6**MANDATORY REQUIREMENTS:**
7- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
8- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
9- **NEVER** use workarounds, especially in tests - implement proper solutions
10- **MUST** follow all established project standards:
11    - Architecture patterns: `.cursor/rules/architecture.mdc`
12    - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
13    - Testing requirements: `.cursor/rules/testing-standards.mdc`
14    - API standards: `.cursor/rules/api-standards.mdc`
15    - Security & quality: `.cursor/rules/quality-security.mdc`
16- **MUST** run `make lint` and `make test` before completing ANY subtask
17- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
18**Enforcement:** Violating these standards results in immediate task rejection.
19</critical>
20 
21## Project Overview
22 
23Compozy is a **workflow orchestration engine for AI agents** that enables building AI-powered applications through declarative YAML configuration and a robust Go backend. It integrates with various LLM providers and supports the Model Context Protocol (MCP) for extending AI capabilities.
24 
25## Development Commands
26 
27### Essential Commands
28 
29```bash
30# Quick setup
31make deps && make start-docker && make migrate-up
32 
33# Start development server with hot reload
34make dev
35 
36# Run tests (excludes E2E/slow tests)
37make test
38 
39# Run all tests including E2E
40make test
41 
42# Format and lint code (ALWAYS run before committing)
43make fmt && make lint
44 
45# Run specific test
46go test -v ./engine/task -run TestExecutor_Execute
47```
48 
49### Database Commands
50 
51```bash
52make migrate-up     # Apply migrations
53make migrate-down   # Rollback last migration
54make migrate-status # Check migration status
55make reset-db       # Reset database completely
56```
57 
58## Architecture & Project Structure
59 
60**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
61 
62## 🚨 CRITICAL: Follow All Development Standards
63 
64**📋 MANDATORY: Review and follow ALL established coding standards:**
65 
66- **Code Formatting & Line Spacing**: [no_linebreaks.mdc](mdc:.cursor/rules/no_linebreaks.mdc) - NEVER add blank lines inside function bodies
67- **Go Coding Standards**: [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc) - Function limits, error handling, documentation policy
68- **Testing Standards**: [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc) - MANDATORY `t.Run("Should...")` pattern, testify usage
69- **Go Implementation Patterns**: [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc) - Canonical implementations of architecture principles
70- **Architecture Principles**: [architecture.mdc](mdc:.cursor/rules/architecture.mdc) - SOLID principles, Clean Architecture, DRY
71- **Code Quality & Security**: [quality-security.mdc](mdc:.cursor/rules/quality-security.mdc) - Linting rules, security requirements
72- **Required Libraries**: [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) - Mandatory library choices and usage patterns
73- **API Development**: [api-standards.mdc](mdc:.cursor/rules/api-standards.mdc) - RESTful design, versioning, documentation
74- **Code Review Process**: [review-checklist.mdc](mdc:.cursor/rules/review-checklist.mdc) - Pre-review requirements and checklist
75 
76## Development Workflow
77 
78### Pre-Commit Requirements
79 
80**ALWAYS run before committing:**
81 
82```bash
83make fmt && make lint && make test
84```
85 
86### Development Process
87 
881. **API changes:** Update Swagger annotations (`swag` comments)
892. **Schema changes:** Create migrations with `make migrate-create name=<name>`
903. **New features:** Include comprehensive tests following [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc)
914. **Task completion:** Follow [task-review.mdc](mdc:.cursor/rules/task-review.mdc) for mandatory code review workflow via Zen MCP tools
925. **Backwards Compatibility:** See [backwards-compatibility.mdc](mdc:.cursor/rules/backwards-compatibility.mdc) - NOT REQUIRED during development phase
93 
94### Key Development Notes
95 
96- **Logging:** Use [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) for structured logging patterns
97- **Core types:** Use `core.ID` for UUIDs, `core.Ref` for polymorphic references
98- **Dependencies:** Mock external dependencies in tests when necessary (see [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc))
99 
100## Task Management
101 
102For task-based development workflows, see these rule files:
103 
104- [prd-create.mdc](mdc:.cursor/rules/prd-create.mdc) - PRD Creation
105- [prd-tech-spec.mdc](mdc:.cursor/rules/prd-tech-spec.mdc) - Technical Specifications
106- [task-generate-list.mdc](mdc:.cursor/rules/task-generate-list.mdc) - Task List Generation
107- [task-developing.mdc](mdc:.cursor/rules/task-developing.mdc) - Task Development
108- [task-review.mdc](mdc:.cursor/rules/task-review.mdc) - Task Completion with Zen MCP code review
109 
110## Rule Management
111 
112The development rules are actively maintained and improved:
113 
114- **Rule Management**: [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) - Comprehensive guidelines for creating, maintaining, and improving rules
115 
116## Compozy Configuration Examples
117 
118For YAML configuration patterns and examples:
119 
120- **Project Configuration**: [compozy-project-config.mdc](mdc:.cursor/rules/compozy-project-config.mdc) - Project setup patterns
121- **Task Patterns**: [compozy-task-patterns.mdc](mdc:.cursor/rules/compozy-task-patterns.mdc) - Workflow task configurations
122- **Agent Configuration**: [compozy-agent-config.mdc](mdc:.cursor/rules/compozy-agent-config.mdc) - AI agent setup patterns
123- **Shared Patterns**: [compozy-shared-patterns.mdc](mdc:.cursor/rules/compozy-shared-patterns.mdc) - MCP, templates, and references
124- **Configuration Index**: [compozy-examples.mdc](mdc:.cursor/rules/compozy-examples.mdc) - Overview and cross-references
125 
126**All rule files are located in `.cursor/rules/` and use semantic XML tags for better context and AI understanding.**
127 
128The project uses Go 1.24+ features and requires external dependencies to be mocked in tests when necessary.
129