Add Function

CRITICAL: Do NOT explore or analyze other microservices unless explicitly instructed to do so. The instructions in this skill are self-contained to this microservice.

CRITICAL: A functional endpoint is declared as a define.Function var in myserviceapi/definition.go and implemented as a handler in service.go. Add the declaration and run cmd/genservice.

CRITICAL: Keep the // MARKER: MyFunction comment on the define.Function var and on its In/Out structs. They are waypoints for future edits.

Workflow

Copy this checklist and track your progress:

Creating or modifying a functional endpoint:
- [ ] Step 1: Read local CLAUDE.md file
- [ ] Step 2: Determine the signature
- [ ] Step 3: Determine the method and route
- [ ] Step 4: Determine a description
- [ ] Step 5: Determine the required claims
- [ ] Step 6: Define complex types
- [ ] Step 7: Declare the endpoint in definition.go
- [ ] Step 8: Generate the boilerplate
- [ ] Step 9: Implement the logic in service.go
- [ ] Step 10: Test the function
- [ ] Step 11: Housekeeping

Step 1: Read Local CLAUDE.md File

Read the local CLAUDE.md file in the microservice's directory. It contains microservice-specific instructions that should take precedence over global instructions.

Step 2: Determine the Signature

Determine the Go signature of the functional endpoint.

func MyFunction(ctx context.Context, input1 string, input2 ThirdPartyStruct) (output1 map[string]MyStruct, err error)

Constraints:

• The first input argument must be ctx context.Context
• The function must return an err error
• Maps must be keyed by string, e.g. map[string]any
• Complex types (structs) are allowed by value or by reference, e.g. MyStruct or *MyStruct
• All input or output arguments must be serializable into JSON, including complex types
• Arguments must not be named t or svc
• Argument names must start with a lowercase letter
• The function name must start with an uppercase letter
• A return argument named httpStatusCode must be of type int
• If the return argument httpResponseBody is present, no other return argument other than httpStatusCode and error can be present
• The magic HTTP argument names httpRequestBody, httpResponseBody and httpStatusCode are documented in the rules file under "Magic HTTP Arguments"

Step 3: Determine the Method and Route

The method of the endpoint determines the HTTP method with which it will be addressable. Unless there's a reason to use a specific method, like for a REST API, use ANY to accept requests with any method.

The route of the endpoint is resolved relative to the hostname of the microservice to determine how it is addressed. The common approach is to use the name of the endpoint in kebab-case as its route, e.g. /my-function.

To set a port other than the default 443, prefix the route with the port, e.g. :1234/my-function.

Encase path arguments with {} , e.g. /section/{section}/page/{page...}.

Prefix the route with // to set a hostname other than that of this microservice, e.g. //another.host.name:1234/on-something

Step 4: Determine a Description

Describe the endpoint starting with its name, in Go doc style: MyFunction does X. This becomes the godoc comment on the define.Function var.

Describe what the endpoint does and the effect it produces, not who is expected to call it. "Charges the card and returns a receipt id" is good; "called by the LLM as a tool" or "used by the checkout page" is not.

Do not write per-argument descriptions in the godoc. Put them in jsonschema_description:"..." tags on the In/Out struct fields (Step 7).

Step 5: Determine the Required Claims

Determine if the endpoint should be restricted to authorized actors only. Compose a boolean expression over the JWT claims associated with the request that if not met will cause the request to be denied. For example: roles.manager && level>2. Default to closed: in a standard ingress configuration an empty requiredClaims on a :443 endpoint (or any port the operator added to AllowedInternalPorts) is reachable by the entire internet. Leave it empty only for an intentionally public endpoint; if the endpoint wields a stored secret or a privileged side effect, it must be gated by requiredClaims and/or an internal port. See the Ports and Authentication sections of .claude/rules/microbus.md.

Step 6: Define Complex Types

Identify the struct types in the signature and define each in the myserviceapi directory following the add-type skill: one file per type, camelCase json tags with omitzero, jsonschema_description tags, optional dv8 validation tags, and an optional pure Validate method for cross-field invariants. A type owned by another microservice is aliased rather than redefined. Skip this step if there are no complex types.