Skip to content

CLAUDE.md

Latest commit

 

History

History
65 lines (47 loc) · 2.06 KB

CLAUDE.md

File metadata and controls

65 lines (47 loc) · 2.06 KB

Claude Code Rules for Common Module

Code Style

  • Early returns, no nested ifs
  • Extract logic into small, focused functions
  • Flat structure over deep nesting
  • Idiomatic Go - if err != nil { return } pattern

CRITICAL: Handler Response Propagation

NEVER ignore the return value of handler() calls. ALWAYS return it.

// WRONG - breaks blocking I/O, causes timeouts
_ = handler(ctx, ErrorPort, Error{...})
return nil

// CORRECT - propagates response back through call chain
return handler(ctx, ErrorPort, Error{...})

Exception: _reconcile port calls can ignore returns (internal system port).

Component Design

  • Handle() switch cases should be minimal - delegate to functions
  • No JSON parsing in components - SDK handles deserialization
  • No knowledge of other modules' metadata keys

CRITICAL: System Port Delivery Order

System ports (_settings, _control, _reconcile) have NO guaranteed delivery order. On pod restart, _reconcile may fire before _settings. Components that persist state to metadata must use a guard flag to prevent reconcile from overwriting fresh values with stale metadata. See SDK CLAUDE.md for the full pattern.

Context Pattern for Schema Generation

Define a type alias for Context and use it in structs:

// Context type alias for schema generation
type Context any

// Request input
type Request struct {
    Context Context `json:"context" configurable:"true" title:"Context"`
    // ... other fields
}

// Output struct
type Output struct {
    Context Context `json:"context" configurable:"true" title:"Context"`
    // ... other fields
}

// Error output - only Context and Error, no Request duplication
type Error struct {
    Context Context `json:"context" configurable:"true" title:"Context"`
    Error   string  `json:"error" title:"Error"`
}

Key points:

  • Use type Context any not just any directly - this enables proper schema generation
  • Add configurable:"true" to Context fields on both input AND output ports
  • Error structs should only have Context and Error message, not duplicate the entire Request