hns-moaiadk-dev-reference Skill

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

Update CHANGELOG.md with new version entry
Create git tag: git tag v1.0.0
Push tag: git push origin v1.0.0
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"

Agent Skills: hns-moaiadk-dev-reference

Install this agent skill to your local

Skill Files