Golden Path

从开发者关键旅程设计路径

先观察代表性团队如何完成工作，记录等待、手工复制、权限工单、环境差异和排障跳转。关键旅程从本地创建与调试开始，经过模型、Tool、Context、身份、Trace、Eval、发布与运营，直到升级和退役；只优化脚手架会把摩擦推到后半程。

每条旅程定义用户、起点、成功终态、所需时间、依赖、失败反馈和支持升级路径。优先解决高频且高认知负担的交集，不为少数极端需求设计万能平台。DORA 的平台工程能力说明建议从常见工作流构建最小可行平台，并把开发者视为内部客户。

默认路径由可组合能力组成

参考架构和最小服务骨架负责端到端示范；SDK 与 CLI 承接重复操作；模型、Tool 与 Skill 目录提供受治理发现；Eval 与 Release Pipeline 把质量证据接入发布；SLO、Runbook 和成本模板让生产责任从第一天可见。

组件通过稳定协议组合，而不是由一个平台 UI 隐藏全部语义。领域团队可以替换模型 Adapter、检索或 UI，但身份、Trace 关联、策略结果和业务终态的契约仍可验证。Backstage Software Templates 等脚手架能创建骨架，却不能替代上线后的所有权与运营。

好的默认值降低决策负担

默认配置应可运行且安全：最小权限、开发测试生产隔离、敏感内容默认不进日志、预算与循环上限、标准错误和 Trace Schema、超时与重试边界。业务必须填写的权限、成功定义和风险等级要在创建时显式阻断，不能用虚假默认值让示例“看起来能跑”。

默认值必须公开理由、适用条件和覆盖方式。不可绕过的底线应少而明确，例如租户身份、审计和高风险审批；偏好性选择允许替换。每项默认值有 Owner、版本、兼容策略和失效信号，避免历史最佳实践沉积成永久复杂度。

# 教学用路径契约，不代表特定平台配置
riskTier: low
permissions: read-only
traceContent: redacted
maxSteps: 12
releaseGate: [contract, eval, security, rollback]
businessOutcome: required

路径要解释机制与边界

Quickstart 只负责第一次成功；How-to 解决一个具体任务；Reference 精确定义接口与配置；Concept 和 Decision Guide 解释机制、适用条件与 Why Not；Troubleshooting 从错误码、Trace 和 Runbook 进入恢复。把所有内容塞进一页长文会让新手找不到入口，资深工程师也无法核对契约。

文档必须与版本绑定，并在流水线中运行示例、检查链接和验证 Schema。失败反馈直接给原因、证据位置与下一步，而不是只显示“策略不通过”。DORA 页面引用的 2025 年数据指出，清晰反馈与平台用户体验高度相关；这里应理解为改进方向，而非对任何组织的因果保证。

例外是产品信号，不是治理失败

逃生舱先区分底线和偏好。租户隔离、审计、法定数据边界和高风险授权通常不可绕过；模型选择、编排方式或部署形态可以在风险可控时例外。申请记录业务理由、替代控制、Owner、支持边界、到期日和回归路径。

私叉会承担漏洞修复、升级与退出责任，平台不应默认为其提供无限兼容。高频逃逸是重要反馈：若来自同一旅程，应修改抽象或开放扩展点；若来自文档不清，应改善反馈；若只是规避底线，则由风险 Owner 决定是否拒绝。

度量真实采用和开发体验

采用率必须配合留存、任务成功和逃逸原因解释。强制接入能制造高采用，却不能证明路径有效。度量 Time to First Production Run、关键旅程成功率、发布门禁时间、支持工单、故障恢复、升级覆盖和迁移成本，并按团队类型与风险切片。

平台价值还需连接业务交付：应用团队是否更快交付合规 Agent，质量与 SLO 是否改善，重复建设和事故是否减少。使用前后对比应控制任务复杂度与组织变化，不把相关性包装成平台带来的确定收益。

Golden Path 按证据迭代

与两到三个差异明显的代表性团队共创，小范围发布并收集旅程遥测、访谈、支持与逃逸证据。新版本给兼容窗口、自动迁移、废弃通知和回滚，先影子检查再升级强制门禁。升级成功率本身就是路径质量指标。

当一个默认值不再降低风险或认知负担，应删除而不是继续包装。路径的退出条件同样重要：若维护成本长期高于使用价值、标准产品已更成熟或平台团队无法承担支持，发布迁移计划并退役，避免 Golden Path 变成组织级锁定。