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 |
执行步骤
- 明确开发者画像：新用户、现有维护者、集成方、插件作者、框架消费者或发布方。
- 跑通或推导 first success path：安装、配置、最小命令、示例输入、成功输出。
- 检查集成步骤是否依赖本机绝对路径、私有工作区、隐藏文档或未声明前置条件。
- 审查示例：是否符合生产推荐路径、是否说明 fixture/mock/demo 边界。
- 审查错误体验：失败时是否可定位、可恢复、可继续验证。
- 若 CLI 提供
--json，验证 stdout 只有一个可解析 JSON 文档；合同错误 exit=2、运行检查失败 exit=1、成功 exit=0，默认人读输出不得被 JSON 字段泄漏污染。
- 执行
ConfigurationErgonomicsGate：为最高频任务给出最小配置，逐字段证明必要性，冻结复杂度预算，分离高级能力，并验证可选字段真实省略后仍能完成任务。
- 对版本或契约变化补迁移路径、兼容策略和文档入口。
ConfigurationErgonomicsGate
| 产物 | 要求 |
|---|
MinimalTaskConfig | 从空状态完成最高频任务所需的最小字段、默认值和成功结果 |
FieldNecessityMatrix | 每个公开字段的用户任务、必填理由、默认/推导来源、错误语义和移除影响 |
ComplexityBudget | 首次成功所需字段数、嵌套深度、概念数和额外步骤预算；超预算必须有真实消费者证据 |
AdvancedCapabilityBoundary | 高级、安全、性能、企业或 provider 特有能力与主路径分离，不污染最小配置 |
OptionalFieldOmissionProbe | 删除所有可选字段后运行等价命令 / API / 示例，验证默认路径、错误和文档承诺一致 |
可推导、可默认、只服务内部实现或只为未来扩展预留的字段不得默认公开为必填。字段数量本身不是唯一指标，但“每个字段都有实现用途”也不能替代用户任务价值证明。
字段含义只引用 api-contract-architecture 的 contractInventory.fieldSemantics：按实际字段路径复核条件必填、允许值、省略/null/空值/0/false、默认来源、依赖互斥、恢复和兼容。FieldNecessityMatrix为同一记录补用户任务价值与移除影响，不重定义含义。若最小示例依赖未声明默认值或把false/0当未提供，应回Owner修正并复测。无公开字段时说明N/A原因，不为完成表格增加配置。
输出字段
## 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。
