Temporal Go Development with Cursor
A comprehensive set of development rules for building Temporal workflows in Go using Cursor IDE. Emphasizes deterministic workflow patterns, incremental development, test-driven workflows, and maintainable code architecture.
Instructions
Follow these development principles and patterns when working on Temporal Go projects in Cursor:
1. Development Philosophy
**Incremental Progress**: Prefer small, incremental, compiling commits over large "big bang" changes**Learn Before Building**: Study and learn from existing code before writing new functionality**Pragmatic Code**: Choose pragmatic, clear, and maintainable code over clever abstractions**Single Responsibility**: Each function or struct should have one clear responsibility**Avoid Premature Abstraction**: Don't add complexity until it's needed**Simplicity First**: When in doubt, choose the simplest solution that clearly conveys intent2. Implementation Workflow
Follow a disciplined, test-driven approach:
**TDD Flow**: Follow red → green → refactor when practical**Document Stages**: Break complex work into documented stages in `IMPLEMENTATION_PLAN.md`**Every Commit Must**: - Compile successfully
- Pass all tests
- Include new tests for new functionality
- Conform to project formatting/linting standards
**Meaningful Commits**: Commit messages should explain _why_ changes are made, not just what3. Problem-Solving Guidelines
When stuck or encountering issues:
**Three-Attempt Rule**: Maximum 3 failed attempts before reassessing approach**Document Failures**: Record what failed, why, and alternatives explored**Prioritize Solutions** by: 1. Testability
2. Readability
3. Consistency
4. Simplicity
5. Reversibility
4. Go Code Organization
Structure Go files from general → specific:
1. Package declaration
2. Imports
3. File-level constants (domain-related)
4. Type declarations (interfaces before structs)
5. Constructor functions (immediately after their type)
6. Methods on types (grouped logically, not alphabetically)
7. Standalone helper functions at bottom
**Key Principles**:
Keep all methods for a struct grouped togetherOrder methods by conceptual flow: constructor → configuration → execute → cleanupSplit files by domain when they become "junk drawers" (e.g., `model.go`, `service.go`, `handlers.go`)Place constants near top only if used broadly; otherwise keep close to relevant types5. Architecture & Code Quality
**Composition Over Inheritance**: Use composition and interfaces, not singletons**Explicit Dependencies**: Keep dependencies explicit; avoid hidden coupling**Fail Fast**: Return descriptive errors that include context**Never Disable Tests**: Fix or adapt them instead**Idiomatic Go**: Write clear, idiomatic Go with descriptive naming and comments when necessary6. Temporal Workflow Determinism Rules
When working with code that imports `go.temporal.io/sdk/workflow`:
**Avoid Non-Deterministic Operations**:
❌ Do NOT use `math/rand` for workflow logic❌ Do NOT call external systems (HTTP, DB, file I/O) directly❌ Do NOT use `time.Now()` or `time.Sleep()`❌ Do NOT use native goroutines, channels, or `select`❌ Do NOT iterate over maps with `range` where ordering matters❌ Do NOT branch on Workflow run IDs**Use Temporal-Provided Alternatives**:
✅ Use `workflow.Now()` and `workflow.Sleep()` for time✅ Use `workflow.Go()` for concurrency✅ Use `workflow.Channel()` and `workflow.Selector()` for coordination✅ Move all side effects (I/O, randomness, external calls) to Activities✅ Keep workflow logic focused on orchestration**Versioning & Replay**:
Add replay tests using `worker.NewWorkflowReplayer()` with Event History JSONStore Event History artifacts in `tests/` directoryTreat failing replay tests as blocking issuesUse `workflow.GetVersion()` or patch APIs for long-running workflow changesNever make breaking changes to workflows with active executions7. Testing & Quality Gates
**Test Behavior**: Test behavior, not implementation details**Isolated Tests**: Keep tests deterministic and isolated**Clear Assertions**: One clear assertion per test where possible**Follow Conventions**: Use existing testing utilities and patterns**Definition of Done**:
✅ All tests passing✅ Code linted and formatted✅ No TODOs without issue references✅ Implementation matches documented plan8. Documentation Standards
**Mermaid Diagrams**: Use Mermaid to visualize complex flows, architecture, or relationships**Prefer Visual**: Use diagrams over lengthy text when they add clarity**Common Diagram Types**: flowcharts, sequence diagrams, class diagrams, state diagrams**Keep Simple**: One concept per diagram**Accompany with Text**: Always add brief explanatory text9. Development Safety Rules
❌ Never use `--no-verify` to bypass hooks❌ Never commit broken or uncompiled code✅ Always document implementation stages as you progress✅ Avoid introducing new tools unless justified✅ Continuously learn from similar patterns in the codebase10. Pull Request Workflow
When generating PR descriptions:
**Do NOT** create pull requests or interact with remote hosting services**Do NOT** modify `PR_DESCRIPTION_GUIDE.md` or `PULL_REQUEST_TEMPLATE.md`**Read** `PR_DESCRIPTION_GUIDE.md` at workspace root for guidelines**Use** template from `PULL_REQUEST_TEMPLATE.md` at workspace root**Output Only**: Completed PR description in a single Markdown code block**Format**: Suitable for saving as `PR_DESCRIPTION.md` in current workspace**No Commentary**: No explanations or extra text outside the code block11. Atlassian Integration
When working with Jira or Confluence links:
✅ Always use available Atlassian MCP tools to access content✅ Treat resources as read-only (never create, edit, or delete)✅ Use Jira MCP tool for Jira URLs (issues, epics, projects, sprints, filters)✅ Use Confluence MCP tool for Confluence URLs (pages, spaces, attachments)❌ Never use web scraping or generic searches for Atlassian URLsℹ️ State unavailability if MCP tools cannot access the resourceExample: Temporal Workflow Pattern
```go
package workflows
import (
"time"
"go.temporal.io/sdk/workflow"
)
// OrderWorkflow orchestrates order processing
func OrderWorkflow(ctx workflow.Context, orderID string) error {
// ✅ Use workflow.Now() for deterministic time
startTime := workflow.Now(ctx)
// ✅ Use workflow.Sleep() for delays
if err := workflow.Sleep(ctx, 5*time.Second); err != nil {
return err
}
// ✅ Call Activities for side effects
var result string
err := workflow.ExecuteActivity(ctx, ProcessOrderActivity, orderID).Get(ctx, &result)
if err != nil {
return err
}
// ✅ Use workflow.Go() for concurrency
workflow.Go(ctx, func(ctx workflow.Context) {
// Concurrent workflow logic
})
return nil
}
```
Constraints
All workflow code must be deterministic and replay-safeCommits must compile and pass tests before pushingMaximum 3 problem-solving attempts before reassessmentDocumentation (diagrams, implementation plans) is mandatory for complex workNever bypass Git hooks or linting checks