moteva/AGENTS.md

DO NOT send optional commentary

• Spend time on thinking: you do not need to use the commentary channel to report progress to me.
• Follow the existing code style.
• Run tests before finalizing changes when possible.
• Do not change unrelated files.

go-zero Development Instructions

You are working in a project configured with the go-zero AI context.

Context Sources

• Start with .ai-context/ai-context/00-instructions.md for workflow rules and decision trees.
• Use .ai-context/ai-context/workflows.md for task-specific flows.
• Use .ai-context/ai-context/tools.md for exact goctl commands.
• Use .ai-context/ai-context/patterns.md for quick code patterns.
• Load detailed references from .ai-context/zero-skills/ only when needed.

Core Rules

• Create or update .api specs before generating REST API code.
• Create or update .proto files before generating RPC code.
• Prefer the local mcp-zero MCP server for generation when available.
• mcp-zero runs over stdio (stdin/stdout) with JSON-RPC, not HTTP.
• Use goctl directly only as the underlying generator or fallback.
• After generation, run go mod tidy, verify imports, and run go build ./....
• Keep handlers thin. Put business logic in internal/logic/.
• Inject dependencies through internal/svc/ServiceContext.
• Pass context.Context through all layers.
• Use configuration files for ports, hosts, credentials, and secrets.
• Generate complete logic, tests, and service documentation for new services.

Detailed References

• REST API patterns: .ai-context/zero-skills/references/rest-api-patterns.md
• RPC patterns: .ai-context/zero-skills/references/rpc-patterns.md
• Database patterns: .ai-context/zero-skills/references/database-patterns.md
• Resilience patterns: .ai-context/zero-skills/references/resilience-patterns.md
• goctl command reference: .ai-context/zero-skills/references/goctl-commands.md
• Troubleshooting: .ai-context/zero-skills/troubleshooting/common-issues.md
• Production best practices: .ai-context/zero-skills/best-practices/overview.md

Generation Defaults

• Local MCP server binary: .tools/bin/mcp-zero
• MCP transport: stdio via mcp.StdioTransport{}
• Set GOCTL_PATH=/Users/liangxu/go/bin/goctl when launching mcp-zero.
• Prefer MCP tools: create_api_service, create_api_spec, generate_api_from_spec, create_rpc_service, generate_model, generate_template, analyze_project.
• Prefer --style go_zero when creating new go-zero services unless existing code uses another style.
• Validate API specs with goctl api validate -api <file>.api.
• Generate REST APIs with goctl api go -api <file>.api -dir . --style go_zero.
• Generate RPC services with goctl rpc protoc <file>.proto --go_out=. --go-grpc_out=. --zrpc_out=. --style go_zero.
• Generate database models with goctl model mysql/pg/mongo rather than hand-written models.

Avoid

• Business logic in handlers.
• Manual edits to generated routing and boilerplate when a spec change plus regeneration is appropriate.
• Hard-coded configuration or credentials.
• Stub-only implementations for requested features.
• Skipping validation, tests, docs, go mod tidy, or build verification after generation.