Go Microservice Dev

Go Microservice Dev

Use this for implementation of new backend products and services. It should adapt to the repo in front of you, but the workflow is independent of any prior codebase.

Skill Routing

• Use this skill for implementation, scaffolding, code generation, handlers, RPC methods, DAL, Redis, MQ, jobs, external clients, DI, and tests.
• Use product-rd-workflow first when the request is an end-to-end product delivery workflow, product idea to implementation plan, release workflow, cross-skill coordination, bug postmortem, or durable process improvement.
• Use defect-diagnosis first when the task is to reproduce, isolate, instrument, fix, verify, or root-cause a backend defect, regression, repeated failure, review finding, or failing test.
• Use go-microservice-architecture when the user asks for system design, service boundaries, contract strategy, storage ownership, reliability design, or architecture review without code changes.
• Use testing-strategy when the main question is which unit, integration, contract, or E2E layer should prove behavior; then return here for Go-specific implementation.
• Use test-artifact-management when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
• Use codebase-specific skills only when the task is explicitly about an existing legacy/workspace repository.
• Development references should turn already-chosen architecture into code, tests, and generated artifacts. If a change requires choosing ownership, security model, source of truth, or release governance, first apply go-microservice-architecture.
• For money, billing, quota, permission, tenant/user data isolation, high-impact AI, repeated writes, async finality, or incident-explanation risk, apply product-rd-workflow high-risk resilience gates and route test-layer design through testing-strategy.
• When a change edits strings, templates, or config values that are returned to, persisted for, emitted to, served to, synchronized with, or configured for client consumption (error copy, labels, notification text, localization payloads, content/CMS/seed rows, message or notification templates, flag-delivered content), classify the consumers with a recorded bounded check (client repo / contract / locale search) before closing on API/log evidence; if any client surface renders the value user-facing, or consumers are unknown, load product-ui-ux-design and record its implementation-owner checkpoint — including the consuming client stack owner(s) and testing-strategy per that checkpoint's field list — with client-side rendered-evidence routing. Backend-only closure without that recorded consumer check is invalid.

Generalization Discipline

• Implement the repo in front of you, but do not import product nouns, service names, package paths, provider names, IDs, dashboards, or organization-specific habits from prior codebases.
• Convert domain-specific source patterns into reusable mechanics: handler shape, contract evolution, repository pattern, transaction boundary, cache key strategy, idempotency, job lease, config, observability, or test style.
• If an observed pattern only works for one product domain, discard it instead of turning it into a rule.
• Resolve conflicts by choosing the safer generic default: explicit contracts over hidden conventions, DB constraints over cache-only correctness, typed config over ad hoc strings, idempotent consumers over retry-only consumers, focused unit tests over live-infra tests by default, and fail-closed for auth/permission/data-integrity paths.
• Fuse patterns only when both are product-agnostic and reduce implementation ambiguity; otherwise keep the simpler rule.
• When adding or revising durable Go implementation guidance, check whether the lesson is generic backend service practice that should also update python-service-dev, or belongs in a shared workflow skill instead. If the rule depends on Go tooling, protobuf/Kitex/Hertz, Go concurrency, or Go package layout, keep it here and do not force a Python mirror.
• Example: if an existing project uses inline Redis keys but another wraps keys in typed builders, implement typed builders and discard inline string formatting as a reusable pattern.

Development Workflow

Before editing code, generated files, migrations, configs, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-package change can use a short inline plan; multi-file, contract-visible, data/schema, async, release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to architecture, testing, or diagnosis skills before edits.

Repo-local agent contracts (AGENTS.md at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per product-rd-workflow's spec / repo-contract sync gate (tooling: references/developer-tooling-patterns.md).

1. Establish the target service shape.

• Is this an HTTP API, internal RPC, worker/consumer, scheduled task, command-line tool, or shared library?
• For internal service-to-service calls, use RPC/gRPC by default and HTTP when the service contract chooses it. Do not treat HTTP as a local shortcut: use the repository/platform HTTP client wrappers for discovery, auth, deadlines, retries, logging, metrics, tracing, and contract tests.
• Also classify SDK/tooling, generated-contract packages, and demo/test modules; do not treat every go.mod, cmd/*, or unfamiliar directory-naming/build-target convention as a deployable RPC service.
• Identify the nearest go.mod, service entrypoint, config files, IDL, generated code, DI setup, and test commands.
• When mining a local/internal reference tree for Go implementation patterns, first detect nested git repositories, submodules, and implementation-bearing non-default branches or tags before judging the tree empty. Prefer read-only tree inspection over switching branches, and record the reusable mechanism rather than the source branch, module, or path.
• Check whether tests are split into fast unit tests and infrastructure-dependent integration tests.

1. Start from contracts and data.

• Update protobuf IDL before changing request/response shape.
• For new or contract-visible services, confirm the globally unique service name, IDL source location, generation command, and generated artifact version before implementing handlers or service logic. Prefer consuming generated contract packages from the contract/generation boundary. When shared IDL and IDLGen repositories exist, Go implementation must use the generated Go artifacts from that shared boundary and keep compatibility with Python and client-side consumers; do not create service-local private IDL copies that drift from the shared contract.
• For protobuf-backed HTTP, confirm whether protobuf is only the contract source or also the binary wire format. For a new protobuf-backed HTTP surface, record the source/config/test location for the generator, route annotations, JSON/binary content-type policy, protobuf-generated clients, middleware order, error/envelope mapping, and compatibility tests before writing handlers. For modifications, confirm only the touched items; an additive non-wire claim must cite the out-of-scope evidence required by ../platform-service-connectivity/references/protobuf-http-contract-signals.md. Without that cited evidence, the touched item is a blocker, not an additive pass.
• Implement JSON-wire business API responses through the contract-recorded envelope per ../platform-service-connectivity/references/http-response-envelope-contract.md; when the canonical envelope applies, map domain errors to the canonical code/message model at the transport boundary and do not return ad hoc top-level business fields from handlers.
• Select the transport contract first — the carrier is scenario-driven per the Carrier decision in ../platform-service-connectivity/references/rpc-framework-recipe.md: on a platform that has standardized the in-message base carrier (or a contract that declares/publishes base), apply the recipe's ordered base-field gate as the single source of truth; on a metadata-carrier service (the default for ordinary gRPC), apply the R7 owner-recorded header-set gate (../platform-service-connectivity/SKILL.md R7) instead. Boundary-exposure classification (canonical trigger set, rerun conditions, dispositions) and the implementation population check are canonical in the same recipe; when any canonical boundary trigger fires, run boundary-exposure classification before release per that recipe — missing or contradictory classification evidence is an open release gap, and authz on unauthenticated caller-supplied identity is an immediate blocking implementation finding. Go service diffs cite the recipe evidence for the touched edit kind; service-authored proto snippets, service-local copied descriptors, uncited provenance claims, stale/wrong-version descriptors, or broad tag claims cannot self-certify the shared contract.
• Handler, adapter, or DTO diffs that manually construct generated request/response DTOs outside the middleware-filled path, or write/mutate/overwrite base, LogId, caller, From, To, Tags, or equivalent identity fields on generated DTOs, apply the implementation population check in ../platform-service-connectivity/references/rpc-framework-recipe.md (carrier-neutral — it runs even when the base-field gate is not applicable); missing evidence is an open implementation gap.
• Use generated request/response/common-field types where they exist. If domain or persistence models differ from transport DTOs, map them explicitly at the transport/application boundary; do not let generated API DTOs leak into domain code unless the architecture record makes them the public application contract.
• Define DB schema/model changes before DAL code. New Go MySQL services use GORM behind DAL/repository boundaries by default unless the repo already standardizes or conventionally uses another query layer, or the architecture records a deliberate alternative.
• Define Redis keys, TTLs, and idempotency/lock semantics before cache code.
• Define MQ topics/events, retry behavior, and idempotency before consumers.
• Define runtime config, health/readiness behavior, deploy metadata, traffic/canary switches, and rollback controls before release-facing code.

1. Keep layers clean.

• Transport layer: protocol mapping, validation, auth context, response mapping.
• Application/service layer: use-case orchestration and transactions.
• Domain layer: domain rules and invariants.
• Infrastructure layer: DB, Redis, MQ, RPC/HTTP clients, object storage, third-party APIs.
• Generated code: never hand-edit unless explicitly repairing generated output.

1. Wire dependencies explicitly.

• Constructors should declare what they need.
• Prefer small interfaces at boundaries where tests or adapters matter.
• Update DI provider sets and regenerate generated DI output if the repo uses it.
• Keep production and test dependency graphs separate when infrastructure clients need fakes.
• Reuse the repository's runtime wrappers for RPC/HTTP servers, clients, DB, Redis, MQ, logs, metrics, tracing, config, and service discovery before adding local one-off clients.
• If a mature internal reference has stronger wrappers than the target repo, reuse existing target-repo wrappers first. When no wrapper exists, add the smallest local adapter that the current task justifies, or route platform-wide wrapper extraction to architecture/platform skills before implementation. Do not paste reference business code or private package layout; preserve only the generic contract, such as Tx(ctx, fn), typed config client, MQ producer/consumer wrapper, context injector, error mapper, or query-safety hook. Safety-critical fragments — recover wrappers, timeout enforcement, untrusted-input decoding — must be a single shared implementation even at a dozen lines; a per-adapter copy that drifts fails as a process crash or a silent no-op, not as slowness.
• If the implementation task directly mines an internal checkout, private repository, local path, or organization project, apply the same sanitization gate before landing any artifact: keep only mechanisms and generic contracts; remove source-identifying domains, paths, repository/module names, people, tickets, and business nouns.

1. Verify at the right scope.

• Run focused unit tests for changed packages.
• Run integration-ish tests for DB/Redis/MQ wrappers only when environment is available.
• TC traceability: link tests via tc.Mark(t, "TC-XX-NNN") (helper from test-artifact-management/references/tc_helpers/tc.go, installed under internal/testkit/tc/).
• tc.Mark MUST be the first non-comment line in the test body, BEFORE any t.Skip / t.Skipf / setup that may call t.Fatal — otherwise the sidecar entry won't be written for skipped tests.
• See test-artifact-management/references/tc-marker-conventions.md.
• Before adding tests, grep -rn 'tc\.Mark.*"TC-[A-Z]' . plus the sidecar test/results/tc-map.jsonl to check for existing coverage — extend rather than duplicate.
• When a TC is marked 废弃, grep both source and sidecar for that TC ID; follow deprecation cascade and orphan rules in testing-strategy.
• Tests without tc.Mark calls: prompt user only when the underlying code is also removed.
• 废弃级联：业务代码是否仍在用 — Go 用 go list 拿真实导入图，不依赖手 grep：

1. 看测试文件导入的产品包：go list -f '{{join .TestImports "\n"}}{{"\n"}}{{join .XTestImports "\n"}}' ./internal/foo/
2. 对每个产品包，查谁还在 import：go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./... | grep ""
3. 只剩本测试 import → 同 commit 删 pkg + 测试；其他产品代码仍 import → 测试目标在用，不删
4. 边界：go:build tag 受限的 import 默认看不到，用对应 tag 跑 go list；反射 / interface 实现注册（init() 注册到全局 map）grep 抓不到，得运行时验证或人工确认

• Run codegen and formatting when generated inputs changed.
• Keep fast tests deterministic; isolate tests that need live infrastructure, long sleeps, generated files, or external credentials.

Implementation Rules

• Pass context.Context through all external calls. The carve-out is narrow and behavioral: only a function that is and stays side-effect-free — no external calls, goroutines, filesystem/env, clock/random, or logging/trace/tenant/feature lookup across its body and callees — may omit ctx. A mapper or helper that does, or later gains, any such call takes ctx. "ctx on external calls" is not "ctx on every function", but the test is behavior, not the name.
• Set timeouts for RPC/HTTP/DB/Redis/MQ operations.
• Honor an existing context deadline when it is shorter than the local default timeout.
• Separate short serving-path request timeouts from longer admin, migration, bootstrap, and repair-operation timeouts. Do not reuse a sub-second request timeout for synchronous dependency setup, index builds, resource activation, schema creation, or other startup administration.
• Use one canonical error model and convert errors at transport boundaries.
• Add or preserve trace/log id in inbound, outbound, and async execution paths.
• MQ producers and consumers should preserve request context where possible, define retry/drop/dead-letter/alert behavior explicitly, and not return success after business failure unless the drop policy is deliberate and observable.
• MQ producer/consumer wrappers should centralize metadata propagation, topic/tag/filter config, worker sizing, retry/drop behavior, panic re

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ccoalm
• Source: ccoalm/ccl-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.