hns-moaiadk-best-practices

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.