template-monorepo/AGENTS.md

AGENTS.md

template-monorepo 是基於 go-zero 的 API Gateway，採用「模組化 Clean Architecture」。

完整的 AI agent 工作準則請見 docs/AGENTS.md（Cursor / Claude / Codex / 其他 agent 皆適用）。

一分鐘快速理解

• 業務模組 一律放 internal/model/<module>/，內部分 domain / repository / usecase / config。
• 跨模組編排（多 usecase 串接）放 internal/logic/<module>/；usecase 不可呼叫其他 usecase。
• API 由 generate/api/*.api 定義，make gen-api 產生 handler / types，make gen-doc 產生 OpenAPI。
• 錯誤碼 8 碼 SSCCCDDD，全專案唯一在 internal/library/errors。
• 回應永遠用繁體中文。

常用入口

文件	用途
docs/AGENTS.md	Agent 工作準則總覽（必讀）
README.md	專案總覽、開發約定、HTTP / 錯誤格式
docs/model.md	internal/model/{module} 分層規範
generate/api/README.md	.api 寫法、@respdoc、middleware 宣告
internal/library/errors/README.md	8 碼錯誤碼設計與 HTTP 對照
docs/identity-member-design.md	Identity / Member / Permission 跨模組架構
docs/auth-unified-registration.md	統一註冊／登入完整時序
docs/e2e-testing.md	E2E 測試流程

指令速查

make gen-api        # .api → handler / logic(skip exists) / types
make gen-doc        # .api → docs/openapi/gateway.yaml
make fix            # gofmt + goimports + lint --fix + lint
make check          # fix + test（提交前必跑）
make run-dev        # 本機啟動（需 make deps-up）
make deps-up        # docker compose Mongo + Redis

完整列表：make help。