メニュー
MUST load when writing or reviewing any backend HTTP handler in EASI. Load when adding a new endpoint, writing response logic, generating HATEOAS links, checking DTO structure, or writing Swagger annotations.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | easi-api-standards |
| description | MUST load when writing or reviewing any backend HTTP handler in EASI. Load when adding a new endpoint, writing response logic, generating HATEOAS links, checking DTO structure, or writing Swagger annotations. |
| compatibility | opencode |
REST Level 3 (HATEOAS) throughout. Every response carries _links — clients check link presence, never hardcode permission logic. API spec is auto-generated from handler annotations via swaggo/swag; backend/docs/ is generated output, never hand-edited.
| Code | Use Case |
|---|---|
| 200 | Successful GET, PUT, PATCH |
| 201 | POST that creates a resource |
| 204 | DELETE or PATCH with no response body |
| 400 | Validation errors, invalid input |
| 401 | Authentication required |
| 403 | Authenticated but lacks permission |
| 404 | Resource does not exist |
| 409 | Business rule violation, duplicate |
| 500 | Unhandled server error |
Every exported handler must have a godoc block — no annotations means no spec entry.
// CreateCapability godoc
// @Summary Create a new business capability
// @Description Creates a new business capability in the capability map
// @Tags capabilities
// @Accept json
// @Produce json
// @Param capability body CreateCapabilityRequest true "Capability data"
// @Success 201 {object} readmodels.CapabilityDTO
// @Failure 400 {object} sharedAPI.ErrorResponse
// @Failure 401 {object} sharedAPI.ErrorResponse
// @Failure 403 {object} sharedAPI.ErrorResponse
// @Failure 500 {object} sharedAPI.ErrorResponse
// @Security CookieAuth
// @Router /capabilities [post]
| Tag | When |
|---|---|
@Summary, @Description, @Tags, @Produce json, @Router | Always |
@Accept json | POST / PUT / PATCH with a request body |
@Failure 401, @Failure 403, @Failure 500 | Every protected endpoint |
@Security CookieAuth | Every endpoint behind auth middleware |
@Router paths are relative to @BasePath (/api/v1) — write /capabilities, not /api/v1/capabilities.
@Param format: // @Param {name} {in: path|query|body|formData} {type} {required} "{description}"
cd backend && make swagger
Generates backend/docs/docs.go + backend/docs/swagger.json, then copies to frontend/openapi.json. Commit all three. Never edit them by hand — fix annotations in the handler source instead.
Use sharedAPI — never raw json.Marshal + w.Write:
| Situation | Call |
|---|---|
| Single resource | sharedAPI.RespondJSON(w, code, resource) |
| Collection (non-paginated) | sharedAPI.RespondCollection(w, code, data, links) |
| Collection (paginated) | sharedAPI.RespondPaginated(w, code, data, hasMore, cursor, limit, self, base) |
| 201 Created | Set Location header, then sharedAPI.RespondJSON(w, 201, resource) |
| 204 No Content | w.WriteHeader(http.StatusNoContent) |
| Error | sharedAPI.RespondError(w, code, err, message) |
| Error + recovery links | sharedAPI.RespondErrorWithLinks(w, ErrorWithLinksParams{...}) |
Use the link builder — never construct URL strings by hand:
links := sharedAPI.NewResourceLinks().
SelfWithID(sharedAPI.ResourcePath("/capabilities"), sharedAPI.ResourceID(id)).
Edit(sharedAPI.ResourcePath("/capabilities"), sharedAPI.ResourceID(id)).
Collection(sharedAPI.ResourcePath("/capabilities")).
Build()
Gate every edit and delete link on the actor's permissions — never include them unconditionally.
| Relation | When |
|---|---|
self | Always |
collection | Always for items in a list |
edit | Actor can modify |
delete | Actor can delete |
up | Resource has a parent |
Custom relations use the x- prefix (x-children, x-remove, x-create-link, etc.).
Every DTO needs Links types.Links json:"_links,omitempty"```. Every handler test must assert the self link's Href and Method, and verify conditional links (edit, delete) are present or absent based on the test actor's permissions.
| Anti-Pattern | Fix |
|---|---|
Exported handler without godoc block | Add full annotation block |
@Router path starts with /api/v1 | Remove the prefix — it duplicates @BasePath |
Missing @Failure 401/403 on protected endpoint | Always document auth failures |
Editing backend/docs/ by hand | Fix annotations in source, run make swagger |
Committing handler changes without make swagger | Run it; commit the generated files |
Plain string for _links value | Use types.Link{Href, Method} |
| Hardcoded URL path in link | Use sharedAPI.ResourcePath / sharedAPI.ResourceID |
_links absent on custom response | Add types.Links field to every response struct |
| Links included regardless of permission | Gate on actor permission check |
godoc annotation block — minimum: @Summary, @Description, @Tags, @Produce, @Router@Security CookieAuth on every protected endpoint; @Failure 401/403/500 always documentedmake swagger after any annotation change; commit docs.go and frontend/openapi.jsonbackend/docs/ — fix source annotations and regeneratesharedAPI.Respond* helpers — no raw JSON writes_links; every handler test asserts link presence, href, and methodedit/delete links on actor permissions — never include unconditionallyx- prefixMUST load when building a feature contract-first or frontend-before-backend in EASI — designing an API contract before code, mocking that contract, building a runnable frontend against the mock, then implementing the backend to the same contract. Load whenever you hear "frontend first", "stub/mock the API", "contract first".
MUST load when UI/frontend changes are completed, to verify functionality by running the app in a browser.
MUST load when writing or reviewing any UI component, dialog, form, button, layout, or styling in the EASI frontend. Load when picking a UI primitive, deciding how to lay out a component, when you would otherwise reach for `style={{}}` or a bare HTML element, or when adding any visual chrome. The single UI vocabulary in EASI is Mantine v8 — this skill enforces it.
MUST load when creating, updating, or reviewing any documentation in EASI — docs/, architecture canvases, READMEs, INDEX files, or pattern guides. Load when adding a new bounded context canvas, writing a pattern guide, restructuring docs, or reviewing existing documentation for bloat.
MUST load after completing a feature, bug fix, or any behavior-changing implementation, before declaring the work done. A deliberate cleanup pass over the affected area — files you modified AND files you read while doing the work — so the code is measurably better than you found it. Distinct from `easi-codehealth`: codehealth scores the change set; boyscouting decides what additional structural cleanups belong in this branch.
Load when implementing new features. Model software around the business domain. Use when designing bounded contexts, defining aggregates and value objects, mapping context relationships, or working with complex business logic. Apply before implementation to prevent model drift.