developer-experience-architecture

# 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，默认人读输出不得被...