| name | hns-moaiadk-best-practices |
| description | moai-adk-go best-practices reference for the 4 harness specialists (cli-template-specialist, quality-specialist, workflow-specialist, hook-ci-specialist). Covers TRUST 5 gates, Go test isolation (t.TempDir, no OTEL env in parallel tests), hardcoding-prevention rules (env constants in envkeys.go, thresholds in defaults.go), the AskUserQuestion orchestrator-only boundary, the deferred-tool preload rule, the archived-agent rejection contract, and verification-claim integrity. Loaded by the specialists when authoring or reviewing moai-adk-go code.
|
| allowed-tools | Read, Grep, Glob, Bash |
| user-invocable | false |
| metadata | {"version":"1.0.0","category":"harness/best-practices","status":"active","updated":"2026-06-17","tags":"moai-adk-go,best-practices,trust5,testing,hardcoding"} |
| progressive_disclosure | {"level_1_tokens":120,"level_2_tokens":4000,"level_3_optional":true} |
| triggers | {"agents":["cli-template-specialist","quality-specialist","workflow-specialist","hook-ci-specialist"],"keywords":"TRUST 5, t.TempDir, envkeys.go, defaults.go, AskUserQuestion, archived-agent, verification-claim, deferred tool"} |
| paths | internal/**/*.go,**/*_test.go,.claude/rules/** |
moai-adk-go Best Practices
TRUST 5 Quality Gates
Every change must pass all five dimensions before completion:
| Pillar | Gate | Failure action |
|---|
| Tested | go test ./... with coverage | Block merge; generate missing tests |
| Readable | golangci-lint run | Warn; suggest refactoring |
| Unified | go fmt + goimports | Auto-format or warn |
| Secured | OWASP-aligned review (per-spawn opus agent) | Block; require review |
| Trackable | Conventional Commits regex | Suggest format |
Coverage targets: 85% package minimum; 90%+ for critical packages
(internal/cli, internal/template, internal/hook).
Test Isolation
- Always
t.TempDir() for temp dirs — auto-cleanup, under os.TempDir().
- macOS path pitfall:
t.TempDir() returns /var/folders/.... Go's
filepath.Join(cwd, absPath) does NOT strip the leading /:
filepath.Join("/a/b", "/var/folders/x") → "/a/b/var/folders/x" (WRONG).
Use filepath.Abs() when resolving user-supplied paths in CLI commands.
- No OTEL env in parallel tests (CLAUDE.local.md §WARN): never
t.Setenv("OTEL_EXPORTER_*", ...) in parallel tests — the OTEL SDK
initializes global state from env vars on first use, causing data races. Use
a fake/no-op exporter instead; or make the parent test non-parallel.
- No
t.Setenv("HOME", tmpDir) in GLM integration tests — parallel-test
pollution. Use t.TempDir() + explicit path construction.
- After fixing any test, run the FULL suite (
go test ./...) to catch
cascading failures. Use -count=1 to disable caching when debugging flaky
tests; use -race for concurrency-safety checks.
