hns-moaiadk-dev-reference

moai-adk-go 로컬 dev 레퍼런스 — CLAUDE.local.md §5/§7/§10 의 작업 특화 상세를 이곳으로 이관 (lazy-load). 세션마다 필요 없는 참고 자료. 항상-로드 컨텍스트 절감용. 소유: hns-* 네임스페이스 (user-owned, moai update 보존 — CLAUDE.local.md §24). 템플릿 미러 금지.

---

Version Management (from CLAUDE.local.md §5)

Single Source of Truth

• [HARD] go.mod module version + git tags are the authoritative sources
• [HARD] pkg/version/version.go reads from git tags at build time

Version Reference:

• Authoritative Source: Git tags (e.g., v1.0.0)
• Runtime Access: pkg/version/version.go via git describe
• Config Display: .moai/config/sections/system.yaml (updated by release process)

Build Version Injection

Version is injected at build time using ldflags:

# Build with version injection
go build -ldflags="-X github.com/modu-ai/moai-adk/pkg/version.Version=v1.0.0"

# Makefile handles this automatically
make build VERSION=1.0.0

Files Requiring Version Sync

When releasing new version, update:

Documentation Files:

• README.md (Version line)
• README.ko.md (Version line)
• CHANGELOG.md (New version entry)

Configuration Files:

• .moai/config/sections/system.yaml (moai.version)
• internal/template/templates/.moai/config/sections/system.yaml.tmpl (moai.version)

Release Process

1. Update CHANGELOG.md with new version entry
2. Create git tag: git tag v1.0.0
3. Push tag: git push origin v1.0.0
4. Build release binaries: make release VERSION=1.0.0

---

Hook Development (from CLAUDE.local.md §7)

[HARD] Shell Script Hooks Only

moai-adk-go uses shell scripts for hooks, NOT Python:

Hook Wrapper Pattern:

#!/bin/bash
# .claude/hooks/moai/handle-session-start.sh

# Read stdin JSON from Claude Code
INPUT=$(cat)

# Call moai binary with hook subcommand
moai hook session-start <<< "$INPUT"

Why Shell Scripts:

• Faster execution (no Python startup overhead)
• Always available (no dependency on uv/python)
• Cross-platform (bash, /bin/sh)

Hook Command Format

settings.json hook configuration:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-session-start.sh\"",
        "timeout": 5
      }]
    }]
  }
}

Key Rules:

• [HARD] Always quote $CLAUDE_PROJECT_DIR: "$CLAUDE_PROJECT_DIR"
• [HARD] Use full path to hook wrapper script
• [HARD] Set appropriate timeout. MoAI policy default is 5 seconds (the Claude Code platform default is 10 minutes; MoAI tightens this to 5 seconds to avoid stalling the session).

Platform Differences

macOS/Linux:

"command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/hook.sh\""

Windows:

"command": "\"%CLAUDE_PROJECT_DIR%\\.claude\\hooks\\moai\\hook.sh\""

---

Build & Dev Commands (from CLAUDE.local.md §10)

Common Commands

# Build the project
make build

# Run tests
make test

# Run with race detection
make test-race

# Run linter
make lint

# Format code
make fmt

# Install locally
make install

# Clean build artifacts
make clean

# Run go fix modernizers
make fix

Development Workflow

# 1. Edit templates
vim internal/template/templates/.claude/skills/moai/SKILL.md

# 2. Regenerate embedded files
make build

# 3. Run tests
go test ./internal/template/...

# 4. Test locally
./moai init test-project

# 5. Commit
git add internal/template/templates/
git commit -m "feat(template): update SKILL.md"