README
¶
Handler template — errorx reference implementation
This file (handler_template.go) is a reference template showing correct
errorx usage in a typical service / repository pair. AI coding tools should
use it as the starting point when generating new business handlers.
How to use
Option A: AI tools (Cursor / Claude Code / Copilot)
When you ask the AI to "create a new module called agent", it should:
- Read this file (
cmd/kernel/internal/project/templates/handler_template.go) - Copy the structure
- Rename
Skill→Agent,AIHUB_SKILL_*→AIHUB_AGENT_* - Fill in the business logic
The AI tool configs (.cursor/rules/errorx.mdc, CLAUDE.md,
.github/copilot-instructions.md) point here as the canonical example.
Option B: Manual copy
cp cmd/kernel/internal/project/templates/handler_template.go \
internal/service/agent.go
# then rename Skill → Agent, AIHUB_SKILL_* → AIHUB_AGENT_*
Option C: cmd/kernel new (future)
When cmd/kernel new is extended to scaffold from local templates (currently
it pulls from a remote layout repo), this file will be the source template.
What this template demonstrates
| Concept | Where in template |
|---|---|
| Domain error codes as constants | Section 1 |
| Domain object (DO) without proto/storage tags | Section 2 |
| Repository interface | Section 3 |
| Service with validation → authz → duplicate check → persist → log | Section 4 |
errorx.BadRequest for validation |
Create step 4.1 |
errorx.Forbidden for authz |
Create step 4.2 (commented) |
errorx.Conflict for duplicate |
Create step 4.3 |
errorx.Wrap for repo failure (with retryable) |
Create step 4.4 |
errorx.NotFound for missing resource |
Get |
WithMetadata for internal context |
throughout |
WithPublicMetadata for client-safe context |
throughout |
logx.FromContext(ctx).Info(...) for logging |
Create step 4.5 |
What this template does NOT do (forbidden)
// ❌ Never in business code:
return errors.New("skill not found")
return fmt.Errorf("create failed: %w", err)
return nil, err
panic(err)
log.Printf("created skill %s", id)
fmt.Println("debug")
slog.Info("...")
os.Getenv("DATABASE_URL")
Lint enforcement
The patterns in this template are enforced by:
.golangci.yml— depguard forbidserrors/fmt/log/slog/osimports inhandler/,service/,repository/,worker/codescripts/check-errorx-usage.sh— grep-based check for forbidden patterns.github/workflows/errorx-enforcement.yml— CI runs both checks on every PR
Related docs
errorx/README.md— single entry guidedocs/ai/errorx.md— AI coding recipe (10 scenarios + complete handler)errorx/example_test.go— 18 Go Examples for all constructorsexamples/errorx-http/— full HTTP server example with 7 error scenarios
Documentation
¶
Overview ¶
Package main is a reference handler template showing correct errorx usage.
AI coding tools should use this file as a starting point when generating new business handlers. Copy this file, rename the package and types, and fill in the business logic.
Key points illustrated:
- Error codes declared as errorx.Code constants at module top
- Constructor chosen by semantic (NotFound / BadRequest / Forbidden / ...)
- Cause preserved with errorx.Wrap or WithCause
- Internal metadata via WithMetadata, public metadata via WithPublicMetadata
- NO use of errors.New / fmt.Errorf / panic in business code
- NO use of log.Printf / fmt.Println — use logx.FromContext(ctx)
See docs/ai/errorx.md for the full AI coding recipe.
Source Files