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.