| name | go-microservice-guardrails |
| description | 将 Go 微服务架构规范应用到代码生成、重构整改和规范评审中。适用于涉及 gRPC、proto、contracts、services/、pkg/、服务边界、接口所有权、配置边界、数据最小权限、服务间鉴权、可观测性、部署与测试的任务。 |
Go 微服务架构规范
概览
在处理 Go 微服务任务时，先用这份 Skill 约束架构边界，再进入具体实现。目标不是教 Go 语法，而是确保生成、整改、评审都遵守同一套服务边界、契约所有权、配置边界、最小权限和可观测性规则。
任务归类
先判断当前任务属于哪一类，再决定读哪些 reference：
生成：新建服务、补 proto、补共享基础设施、补部署或测试骨架整改：目录重构、收敛配置、拆边界、修正通信或权限模型评审：检查设计、目录、契约、代码或部署测试是否违反规范
如果任务同时涉及多个主题，优先按“边界与所有权 -> 契约 -> 通信鉴权 -> 配置与共享包 -> 数据权限与部署测试 -> 可观测性”的顺序处理。
Reference 导航
按任务主题读取对应 reference，不要一次性加载全部文件：
- 涉及工作区结构、模块落位、根目录职责时，读
references/repository-layout.md
- 涉及 proto、Buf、生成代码、接口归属时，读
references/contracts-and-codegen.md
- 涉及 gRPC metadata、服务身份、用户上下文透传和逐跳授权时，读
references/service-communication-auth.md
- 涉及
internal/config、pkg/ 边界和共享基础设施抽取时，读 references/config-and-shared-pkg-boundaries.md
- 涉及服务自治、接口所有权和跨服务依赖时，读
references/service-boundaries.md
- 涉及数据拥有权、运行时账号、跨服务数据访问时，读
references/data-min-privilege.md
- 涉及数据库约束、联调资源、Docker 构建和测试分层时，读
references/database-deploy-test.md
- 涉及日志、Trace、缓存刷新、配置或密钥热更新时，读
references/observability-hot-reload.md
固定执行顺序
所有任务都先做边界判断，再做实现判断：
- 确认服务边界和接口所有权是否正确
- 确认契约真源、生成路径和字段归属是否正确
- 确认服务间通信、服务认证和用户上下文透传是否正确
- 确认配置是否留在服务内、共享包是否只承载无业务语义能力
- 确认数据访问、运行时权限、部署资源和测试落位是否正确
- 最后才讨论具体代码、目录、部署细节和测试实现
如果前面的边界判断不成立，不要直接开始写代码补丁。
三类任务的输出方式
生成
- 先给出符合规范的目录与职责划分
- 再给契约位置、生成路径、服务间依赖和测试落位
- 最后才给最小实现骨架
整改
- 先明确违反了哪条规范
- 说明风险来自哪里
- 按最小改动原则给出修正方案
评审
- 以问题清单优先
- 每个问题明确对应的规范主题
- 明确风险、影响范围和建议整改方向
输出要求
输出中始终说明：
- 本次用了哪些 reference
- 哪些结论是从已有代码或文档直接得出的
- 哪些结论属于基于规范的推断
如果上下文不足以判断某个边界，应明确列为待确认项，不要把猜测写成既成事实。
硬性禁止项
- 不允许把共享 proto 真源放进服务目录
- 不允许把服务私有配置、领域模型或服务私有鉴权流程抽到
pkg/
- 不允许服务依赖其他服务的内部实现、内部数据结构或仓储实现
- 不允许服务通过运行时 DSN 直接修改其他服务拥有的数据边界
- 不允许把
x-service-token、x-user-id、x-user-authenticated 混进业务 request
- 不允许在业务 handler 中直接读取原始 metadata 作为可信身份
- 不允许把上游服务签发的服务令牌原样转发给下游
- 不允许热更新、缓存刷新、配置切换失败时没有日志、Trace 或回退策略
默认工作方式
当用户要求“按规范生成”“按规范整改”“检查是否符合微服务规范”时：
- 先给出当前任务对应的规范主题
- 明确哪些目录、接口、配置或权限边界必须先收敛
- 再输出实现建议、代码结构或评审结论
如果只是普通 Go 语法、算法题、CLI 小工具或与微服务架构无关的任务，不要使用这份 Skill。
