kodit: Instructions file for Claude Code

Helix Development Rules

Current year: 2026 — include "2026" in web searches for documentation and browser APIs.

Setup

Install required development tools before doing anything else:

make tools    # Install golangci-lint, goimports, swag, oapi-codegen, openapi-spec-converter

Build, Test, and Check

Always use make commands — never run go test, go vet, or golangci-lint directly. The Makefile sets required build tags, CGO flags, and environment variables that raw go commands miss.

make build                       # Build the binary
make test                        # Run all tests
make test PKG=./internal/foo/... # Test a specific package
make check                       # Format, vet, lint, and test
make check PKG=./internal/foo/... # Check a specific package
make test-smoke                  # Run smoke tests (needs running Docker env)

Shipping Code

Before committing:

1. Run make check and confirm it passes (or at minimum make test for affected packages). Do not commit code that has not been validated.
2. Fix any failures before committing — do not skip or work around them.

Commits and PRs use Conventional Commits:

• Prefix: feat:, fix:, docs:, refactor:, chore:, test:, etc.
• Example commit: feat: add webhook retry logic
• PR titles follow the same format: feat: add webhook retry logic

When pushing additional commits to an existing PR, update the PR title and description to reflect the full set of changes in the branch.

Go

• Fail fast: return fmt.Errorf("failed: %w", err) — never log and continue
• Error on missing configuration — fail with an error, don't log a warning and continue
• Use structs, not map[string]interface{}
• GORM AutoMigrate only — no SQL migration files
• Use gomock, not testify/mock
• No fallbacks — one approach, no fallback code paths
• No type aliases — update all references when moving or renaming types
• No panics — return errors; rewrite methods to support error returns if needed
• Log errors once at the top level — domain code returns errors, only handlers/workers log them