developer-experience-architecture git:20260730.6ee304aA

Immutable. This exact content is served forever at /api/v1/blob/a61068f5e9d92d6e.

---
name: developer-experience-architecture
description: 开发者体验架构专家 Owner — 当任务涉及 CLI、SDK、API、Hook、插件、框架、README、quick start、示例、错误信息、迁移、贡献路径或开发者接入体验时使用；要求验证第一次成功路径、真实示例、错误恢复和维护者消费链。
---

# Developer Experience Architecture Skill

## 定位

本 Skill 负责开发者体验 Owner 视角。它确保面向开发者的产品、库、插件、CLI、API、Hook、文档和示例不是“内部能懂”，而是让目标开发者能快速接入、正确使用、遇错可恢复、升级可迁移。

## 触发条件

| 场景 | 是否触发 |
|------|:--------:|
| CLI / SDK / API / Hook / 插件 / 框架能力变更 | 必须 |
| README、quick start、接入手册、示例、fixture 或文档站面向开发者 | 必须 |
| 错误信息、配置项、迁移指南、贡献流程、调试方式会影响开发者 | 必须 |
| 纯 UI 视觉或后端内部实现，且没有开发者消费面 | N/A + skipReason |

## 核心门禁

| Gate | 要求 | 证据 |
|------|------|------|
| `DeveloperExperienceArchitectureGate` | 设计必须覆盖开发者首次成功、集成步骤、错误恢复和升级迁移 | quick start、示例、命令、错误输出、迁移文档 |
| `FirstSuccessPathGate` | 用户按文档从空状态到第一个成功结果的路径必须可执行 | 命令、输入、期望输出、耗时 |
| `ExampleTruthGate` | 示例必须是真实业务工作流，不用硬编码单例冒充主路径 | 源码、测试、运行结果、fixtureBoundary |
| `ErrorExperienceGate` | 错误信息必须能指向原因、修复动作和相关文档 | stderr、日志、排错章节 |
| `MachineReadableCliContractGate` | 新增机器可读 CLI 时必须保持默认人读路径，并冻结单一 JSON envelope、稳定错误码、nextStep 与 native exit code | human/json replay、negative fixture、exit map |
| `MigrationPathGate` | Breaking 或行为变化必须提供迁移步骤和兼容边界 | changelog、migration、compat notes |
| `ConfigurationErgonomicsGate` | 配置设计必须让常见任务保持最小、可理解、可省略，复杂度只留在高级能力边界 | MinimalTaskConfig、FieldNecessityMatrix、ComplexityBudget、AdvancedCapabilityBoundary、OptionalFieldOmissionProbe |

## 执行步骤

1. 明确开发者画像：新用户、现有维护者、集成方、插件作者、框架消费者或发布方。
2. 跑通或推导 first success path：安装、配置、最小命令、示例输入、成功输出。
3. 检查集成步骤是否依赖本机绝对路径、私有工作区、隐藏文档或未声明前置条件。
4. 审查示例：是否符合生产推荐路径、是否说明 fixture/mock/demo 边界。
5. 审查错误体验：失败时是否可定位、可恢复、可继续验证。
6. 若 CLI 提供 `--json`，验证 stdout 只有一个可解析 JSON 文档；合同错误 exit=2、运行检查失败 exit=1、成功 exit=0，默认人读输出不得被 JSON 字段泄漏污染。
7. 执行 `ConfigurationErgonomicsGate`：为最高频任务给出最小配置，逐字段证明必要性，冻结复杂度预算，分离高级能力，并验证可选字段真实省略后仍能完成任务。
8. 对版本或契约变化补迁移路径、兼容策略和文档入口。

## ConfigurationErgonomicsGate

| 产物 | 要求 |
|------|------|
| `MinimalTaskConfig` | 从空状态完成最高频任务所需的最小字段、默认值和成功结果 |
| `FieldNecessityMatrix` | 每个公开字段的用户任务、必填理由、默认/推导来源、错误语义和移除影响 |
| `ComplexityBudget` | 首次成功所需字段数、嵌套深度、概念数和额外步骤预算；超预算必须有真实消费者证据 |
| `AdvancedCapabilityBoundary` | 高级、安全、性能、企业或 provider 特有能力与主路径分离，不污染最小配置 |
| `OptionalFieldOmissionProbe` | 删除所有可选字段后运行等价命令 / API / 示例，验证默认路径、错误和文档承诺一致 |

可推导、可默认、只服务内部实现或只为未来扩展预留的字段不得默认公开为必填。字段数量本身不是唯一指标，但“每个字段都有实现用途”也不能替代用户任务价值证明。

## 输出字段

```markdown
## DeveloperExperienceArchitectureGate

| 字段 | 内容 |
|------|------|
| developerPersona | 目标开发者画像和前置能力 |
| firstSuccessPath | 从空状态到第一个成功结果的步骤、命令和期望输出 |
| integrationSteps | 接入步骤、配置、依赖和环境要求 |
| exampleTruth | 示例是否真实业务工作流；fixture/mock/demo 边界 |
| errorExperience | 常见失败、错误信息、排错入口和恢复动作 |
| machineReadableCli | human/json 兼容、envelope、errorCode/nextStep、exit map 与 spawn 证据 |
| migrationPath | 版本变化、兼容策略、迁移步骤 |
| configurationErgonomics | 最小配置、字段必要性、复杂度预算、高级边界和省略探针 |
| docsEntryPoints | README / 文档站 / API / changelog / examples 可点击入口 |
```

## 反模式

| 反模式 | 修正 |
|--------|------|
| quick start 只展示硬编码 happy path | 补真实业务输入、失败路径和恢复方式 |
| 示例文件能跑但不是推荐接入方式 | 标注 exampleTruth / fixtureBoundary，并给生产主路径 |
| 错误信息只说 failed | 输出原因、下一步和文档入口 |
| JSON 模式混入 banner/progress 文本或仍以 exit 0 报错 | stdout 只输出 envelope，并按合同/检查失败映射 native exit code |
| 文档链接写死本机路径或 `.devcodex` 私有路径 | 改为仓库相对路径、公开 URL 或说明不可分享边界 |
| 把所有底层能力都暴露为配置 | 保留 MinimalTaskConfig，把低频/高级能力放入显式 advanced boundary |

## 与其他 Skill 的关系

- `expert-output-quality`：示例和 fixture 必须区分生产推荐路径与验证边界。
- `readme-authoring` / `user-manual-authoring`：README 与接入手册需采用 first success path。
- `release-verification`：发布前必须验证 package / install / smoke 对开发者可用。
- `test-router`：把 DX 验证映射为 command smoke、pack、example、docs link 和 migration probe。