如何为 MoAI-ADK 贡献代码：Go 1.26 + Template-First + TDD/DDD 贡献指南（含测试与 Lint 规范）

MoAI-ADK 是一个面向 Claude Code 的智能体开发框架（Agentic development harness），支持 SPEC 驱动的 plan/run/sync 三阶段工作流、TRUST 5 质量门、模型+effort 路由，以及 Claude×GLM 多 LLM 成本控制。它用单个 Go 二进制实现，支持 16 种语言，零运行时依赖。本文带你完整走一遍 MoAI-ADK 贡献代码的标准流程：从 Go 1.26 开发环境搭建，到 Template-First 模板镜像纪律，再到 TDD/DDD 测试规范、Lint 规则和提交规范。

1. 快速了解：MoAI-ADK 是怎么开发的？

MoAI-ADK 自身就是用一套严格流程开发出来的——这也是你贡献代码时必须遵循的流程：

• SPEC 三阶段工作流：规划（plan）→ 执行（run）→ 同步（sync），每个功能先写 SPEC 契约，再实现，最后同步审计。
• TRUST 5 质量门：Tested（已测试）、Readable（可读）、Unified（一致）、Secured（安全）、Trackable（可追踪），五项标准是质量底线。
• Template-First 纪律：仓库里的.claude/、.moai/等文件，在internal/template/templates/下都有"孪生模板"，本地漂移会直接导致 CI 失败。
• 16 语言中立：go、python、typescript、rust、java 等 16 种语言是模板一等公民。

这套设计思想详见 docs/design/major-v3-master.md，社区贡献入口在 CONTRIBUTING.md 和 docs-site/content/en/contributing/_index.md。

2. 开发环境一键搭建：Go 1.26 + 工具链

2.1 必需工具清单

2.2 克隆仓库并启动

git clone https://gitcode.com/gh_mirrors/mo/moai-adk.git cd moai-adk go mod download # 安装依赖

2.3 Make 命令速查表 🚀

Makefile 是所有日常操作的统一入口，最常用的命令：

make build # 构建 bin/moai 二进制 make test # 全量测试：go test -race -coverprofile=coverage.out ./... make lint # golangci-lint run ./... make fmt # gofumpt 格式化全部 .go 文件 make preflight # pre-push 门禁：lint-fast + test-race-short + build make coverage # 生成 coverage.html 覆盖率报告

💡新手建议：提交前先跑make preflight，它等价于 CI 的 pre-push 检查，能避免大量返工。

3. Template-First：修改配置文件前必知的镜像纪律 ⚠️

这是 MoAI-ADK 最容易"踩坑"的贡献规范：每一个.claude/、.moai/、.codex/下的文件，在 internal/template/templates/ 下都有一个孪生模板。

正确的贡献姿势：

1. 改模板源头：先修改internal/template/templates/下的对应文件（模板树就是源）。
2. 保持中立性：镜像副本中不允许出现 SPEC ID、commit SHA、本机绝对路径、日期等内部痕迹——TestTemplateNeutrality和TestInternalContentLeak两个测试会守住这条线。
3. 重新生成 catalog：make build会重新生成内嵌的 internal/template/catalog.yaml，同一次变更必须包含。
4. 跑漂移检查：CI 用diff -rq比对本地树与模板树，任何漂移都是 CI 错误。

相关机制可在 internal/config/loader_archive.go 的 Template-First 注释和 internal/template/embed_catalog_test.go 中找到实证测试。

4. TDD vs DDD：测试规范怎么选？

MoAI-ADK 贡献代码时，新代码走 TDD，存量代码走 DDD，完整方法论在 docs-site/content/en/core-concepts/ddd.md：

4.1 TDD 三步循环 🧪

1. RED：先写一个必然失败的测试，用 Given-When-Then 描述行为。
2. GREEN：写最少的代码让测试通过，不提前抽象。
3. REFACTOR：在测试持续通过的前提下整理命名、消除重复。

CHANGELOG.md 中有大量真实 TDD 证据记录，例如RED failing-test output captured before GREEN——先捕获失败输出，再让测试变绿。

4.2 表驱动测试（Table-Driven Tests）

项目推荐 Go 惯用的表驱动测试风格：

tests := []struct { name string input string want string }{ {"default", "", wantDefault}, {"custom bin", "/custom/bin", wantCustom}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { ... }) }

4.3 硬性质量红线 📊

TRUST 5 的Tested /Trackable 标准对贡献代码原样生效（见 docs-site/content/en/core-concepts/trust-5.md）：

跑覆盖率报告：make coverage后打开coverage.html检查。

5. Lint 与格式化规范：零警告文化

5.1 Lint 配置在哪里

Lint 规则集中在 .golangci.yml：启用errcheck、govet、ineffassign、staticcheck、unused五个检查器，本地与 CI 使用完全相同的 linter 集合，配置注释明确解释了为何要 pin 住这一交集——避免版本升级静默扩大检查范围。

错误处理遵循统一约定：包装错误必须带上下文：

return fmt.Errorf("deploy templates: %w", err) // ✅ 好 return fmt.Errorf("read " + path + ": " + err.Error()) // ❌ 坏

5.2 Git Hooks：lefthook 自动把关

仓库通过 lefthook.yml 安装 git hooks，把门禁前置到本地：

• pre-commit：只对暂存的*.go文件跑golangci-lint run --fast，快速反馈。
• pre-push：跑完整make preflight（lint-fast + race-short 测试 + build）。

也就是说，测试和 Lint 不是"提交前记得跑一下"，而是 hook 强制的。

6. 提交与 PR 规范：Conventional Commits 一步到位

6.1 分支命名

6.2 提交信息格式

<type>(<scope>): <description> [可选正文] Closes #123

类型包括feat/fix/docs/style/refactor/perf/test/chore，真实示例：

feat(cli): add interactive wizard for project initialization fix(update): correct version comparison for go-v prefix

6.3 PR 前检查清单 ✅

• 所有测试通过（make test）
• 零 Lint 错误（make lint）
• 代码已格式化（make fmt）
• 覆盖率 85%+
• Race 检测通过
• 提交信息符合 Conventional Commits
• PR 描述包含变更摘要与测试说明

7. 总结：新手贡献路径清单

记住三句话：Go 1.26 起步、Template-First 镜像不漂移、85% 覆盖率 + 0 Lint 是底线。MoAI-ADK 项目遵循 Apache License 2.0（见 LICENSE），欢迎每一份遵守规范的好代码。🎉