菜单
Use when adding or modifying any HTTP handler in a GO project using GIN framework — every handler MUST carry swaggo annotations and a `make swagger` run must accompany the commit. Drift is enforced by `make swagger-check` in `make check`.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Guidelines for building Flutter/Dart UI, theming, and reusable components. Use this skill whenever working on Flutter UI — creating or styling widgets, components, screens, buttons, pills, badges, inputs, navigation bars, drawers, dialogs; setting up or editing colors, ColorScheme, ThemeData, ThemeExtension, TextTheme, fonts, gradients, shadows; or any task that produces or modifies Flutter visual code. Apply it even when the user just says "build a screen", "make a button", "style this", or "add a component", not only when they mention theming explicitly. It enforces a strict palette/theme architecture, prefers native Material widgets over hand-built ones, and prevents unnecessary widget nesting.
Use this skill whenever Go code interacts with a database via GORM — including model definitions, querying, inserts/updates/deletes, transactions, preloading relations, joins, migrations, or repository implementations. Triggers include any mention of `gorm.DB`, `gorm:"..."` tags, `db.Find`, `db.Where`, `db.Create`, `db.Preload`, `db.Joins`, `db.Exec`, `db.Raw`, "use GORM", "load related records", "N+1", "master/detail", or any Go file that imports `gorm.io/gorm`. Apply this skill even when the user doesn't explicitly ask for GORM guidance — if they're touching GORM code, these rules apply.
Use this skill whenever a Flutter app needs to call a backend API — including initial API client setup, adding new endpoints, handling auth tokens, error mapping, retries, request/response logging, multipart uploads, or regenerating the client from an updated OpenAPI spec. Triggers include "add an endpoint", "call the backend", "Dio interceptor", "OpenAPI", "swagger", "regenerate the API client", "auth token", "401 refresh", or any HTTP work in a Flutter project. Apply even when the user doesn't mention OpenAPI by name — generated clients from the backend spec are the default pattern here.
Use this skill whenever a new Flutter/Dart project is being scaffolded, an existing Flutter project is being reorganized, or a new feature is being added to an existing Flutter app. Triggers include "new Flutter app", "start a Flutter project", "where should this file go in Flutter", "add a feature to my Flutter app", "refactor Flutter folder structure", or any mention of `lib/`, `pubspec.yaml`, or feature module organization in Dart code. Use this even when the user doesn't explicitly ask for structure advice — if they're starting a Flutter project or adding a feature, apply this layout by default.
Use this skill whenever state management decisions arise in Flutter code — including creating providers, choosing between Notifier/AsyncNotifier/FutureProvider/StreamProvider, handling async data, side effects in widgets, dependency injection, or testing stateful logic. Triggers include "add a provider", "manage state in Flutter", "Riverpod", "ref.watch", "ref.read", "AsyncValue", "how do I share state across screens", or any Flutter code change that involves reactive state. Apply this skill even when the user doesn't say "Riverpod" — it's the default for all Flutter state work in this codebase.
Use this skill whenever tests are being written, modified, or debugged in a Flutter project — including unit tests for providers/repositories, widget tests for screens, golden tests for visual regression, and integration tests for end-to-end flows. Triggers include "write a test for this", "test this Flutter code", "widget test", "golden test", "mock the API", "test a Riverpod provider", "pumpAndSettle", or any failing test discussion. Apply even when the user doesn't ask explicitly — when modifying production Flutter code, propose the matching tests.
| name | swagger-annotations |
| description | Use when adding or modifying any HTTP handler in a GO project using GIN framework — every handler MUST carry swaggo annotations and a `make swagger` run must accompany the commit. Drift is enforced by `make swagger-check` in `make check`. |
Whenever you create, modify, or remove an HTTP handler in cmd/api, internal/<aggregate>/handler.go, or pkg/ginx/endpoint/<name>/handler.go. Drift between annotations and internal/swaggerdocs/ fails CI.
func.Patch[T] (dual-decode), update the parallel *Doc mirror struct.make swagger.internal/swaggerdocs/ along with your handler change.make check will run make swagger-check and fail if anything was missed.Place annotations as the last comment block before func. Keep any existing WHY paragraph; separate the two with a blank comment line.
// FunctionWHY ... (existing intent paragraph stays)
//
// @Summary Short imperative title
// @Description One-paragraph description; use multiple @Description lines for paragraphs.
// @Tags users // group label in the UI; reuse existing tags where possible
// @Accept json // omit for GET
// @Produce json
// @Security BearerAuth // omit for public routes
// @Param id path string true "User ULID" example(01HZX5K7ZQ8M0J9C2YR4VWEXAM)
// @Param body body user.PatchUserRequestDoc true "Partial user fields"
// @Success 200 {object} user.MeUserResponse
// @Failure 400 {object} errorx.ErrorResponse "validation error"
// @Failure 401 {object} errorx.ErrorResponse
// @Failure 404 {object} errorx.ErrorResponse
// @Failure 500 {object} errorx.ErrorResponse
// @Router /api/v1/users/{id} [get]
func (h *Handler) GetByID(c *gin.Context) { ... }
Reuse existing tags before inventing new ones:
users — /api/v1/users/*health — /health, /readyauth, providers, bookings, discoveryAlways reference errorx.ErrorResponse (envelope: { "error": { "code", "message", "details" } }). Never reference errorx.AppError directly — that's the in-process value, not the wire shape.
Standard @Failure set per route:
400 — request validation, including unknown fields on PATCH (USER_INVALID_*, VALIDATION_UNKNOWN_FIELDS).401 — missing or invalid Bearer token. Required on every @Security BearerAuth route.403 — caller authenticated but not authorized for this resource (omit if no such case).404 — resource not found. Omit if not applicable.409 — conflict (duplicate email on register, version mismatch).500 — generic server error. Always include.Patch[T]) endpointsPatch[T] is an internal generic with a custom UnmarshalJSON. swag introspects struct fields, so it would render the meaningless internal shape (Set/Null/Value).
Convention: add a *Doc mirror struct with plain pointer types and annotate against the mirror.
Example: internal/user/patch.go defines PatchUserRequest; internal/user/patch_doc.go defines PatchUserRequestDoc with *string, *int, *AddressInput fields. Annotate as:
// @Param body body user.PatchUserRequestDoc true "Partial user fields"
When you add a field to PatchUserRequest, mirror it into the *Doc struct in the same commit. make swagger-check indirectly catches drift: any PatchUserRequest change produces a different rendered spec; if the mirror lags, the diff is visibly missing the new field.
The package-level doc comment of cmd/api/main.go carries @title, @version, @host, @BasePath, and @securityDefinitions.apikey BearerAuth. Edit there if API metadata changes (version bumps, base path moves).
pkg/ginx/endpoint/swagger/handler.go — Register(*gin.Engine) mounts /swagger/*any. Wired in cmd/api/main.go before AuthMiddleware so the UI is public.internal/swaggerdocs/ — generator output, committed.Makefile — swagger, swagger-check, tools targets.Patch[T] request types have updated *Doc mirrors.make swagger ran cleanly; internal/swaggerdocs/ is staged.make check passes locally (includes swagger-check).internal/swaggerdocs/ regeneration.docs/decisions/2026-05-05-api-docs-swaggo.mdpkg/ginx/middleware/error.godocs/decisions/2026-05-04-patch-dual-decode.md