# Ship Solution

> 当用户使用「实现、执行方案、按方案做、开始实现、ship、implement solution」等词触发，或在 real-solution-plan 产出方案后用户确认时触发。严格按照 real-solution-plan 产出的方案执行实现，用真实案例验证，不接受补丁式修改和硬编码。小问题允许一次性修复，未达指标的问题需重新规划。用户确认方案后可选自动验证。前置硬要求：必须已有一份确认过的书面方案；如果没有方案、只是要把一件已授权的事推到有证据的终态（需要风险分级、重试预算、有界监控、终态判定），改用 ship-it-for-real。

- Skill: `ruosong320/ship-solution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ruosong320/ship-solution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruosong320/ship-solution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ruosong320 (https://skillmd.com/u/ruosong320)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ruosong320/ship-solution

---


# Ship Solution

严格按照已确认的实现方案（通常来自 real-solution-plan）执行实现，并用真实案例验证结果。

## 核心原则

1. **方案优先**：严格按照已确认方案实现，不得随意偏离架构、技术选型、数据结构设计。
2. **真实验证**：必须使用真实案例验证，不接受仅通过代码审查或理论推导得出的"应该能工作"。
3. **禁止补丁**：未达到用户要求/指标的问题不允许补丁式修改，必须回到方案层重新分析。
4. **禁止硬编码**：不允许针对验证案例硬编码通过，必须具备泛化能力。
5. **小问题豁免**：仅一次性可修复的小问题（逻辑写漏、网络沙箱、语法错误、导入路径）允许直接修复。

## 前置条件

调用此 skill 前必须满足：
- 已有详细的实现方案（来自 real-solution-plan 或用户提供）
- 方案已经用户确认
- 验收标准明确
- 有真实测试案例可用

如果缺少方案，必须先调用 real-solution-plan。

## 工作流程

### 1. 方案确认与加载

#### 1.1 检查方案完整性

确认方案包含：
- [ ] 架构设计（模块划分、数据流）
- [ ] 实现步骤（可执行的操作序列）
- [ ] 关键代码结构（文件组织、接口定义）
- [ ] 数据结构定义（输入/输出格式）
- [ ] 错误处理策略
- [ ] 测试验证方案（包含真实案例）
- [ ] 验收标准

如果任一项缺失且影响实现，要求用户补充或回到 real-solution-plan。

#### 1.2 询问自动验证意愿

**🔴 CHECKPOINT — 方案未确认、或验收标准不明确时，不得进入实现。** 逐条对照「前置条件」四问，缺哪条补哪条：缺方案 → 回到 real-solution-plan；缺用户确认或验收标准不明确 → 用 AskUserQuestion 与用户补齐；缺真实案例 → 取「方案执行不下去时的兜底」表中以 *方案给出的测试案例不可用* 开头的那一行处理。补不齐不得进第 2 步。

向用户确认：
```
方案已确认。是否需要我在实现后自动使用真实案例验证？

- 自动验证：实现完成后立即运行测试案例，失败时按规则修复或报告
- 手动验证：实现完成后由你手动验证
```

使用 AskUserQuestion 工具询问，记录选择。

### 2. 按方案执行实现

#### 2.1 严格遵循方案

按方案中的实现步骤顺序执行：
- 使用方案指定的技术栈、库、模式
- 创建方案规划的文件结构
- 实现方案定义的接口和数据结构
- 采用方案建议的错误处理策略

#### 2.2 允许的局部调整

仅以下情况允许偏离方案：
- 发现方案中的明显错误（API 已废弃、版本不兼容等），且有明确证据
- 项目环境变化（依赖版本、文件路径等）
- 用户在实现过程中明确要求调整（若新需求与已确认方案冲突，取「方案执行不下去时的兜底」表中以 *用户确认过的方案与用户中途提出的新需求冲突* 开头的那一行处理，不要直接照改）

任何偏离都必须：
1. 在代码注释中说明原因
2. 在最终报告中列出
3. 不改变方案的核心架构和技术选型

#### 2.3 实现质量标准

代码必须满足：
- 符合项目现有代码风格（缩进、命名、导入顺序等）——与项目现有约定冲突时不要静默混用两套，取「方案执行不下去时的兜底」表中以 *方案要求的做法与项目现有约定冲突* 开头的那一行处理
- 无冗余打印/日志（除非方案明确要求）
- 无未使用的函数、变量、导入
- 错误处理覆盖方案识别的边界情况
- 注释简洁，仅在复杂逻辑处添加

### 3. 真实案例验证

#### 3.1 准备测试案例

使用方案中定义的测试案例，或：
- 如果用户提供了真实案例，使用用户案例
- 如果方案未给出具体案例，从项目现有数据中选取代表性案例
- 至少包含：正常情况 1 例、边界情况 1 例

禁止：
- 使用过于简单的 toy example（除非需求本身就是简单场景）
- 针对案例内容硬编码（如 `if input == "特定值": return "特定结果"`）

#### 3.2 执行验证

运行测试案例，记录：
- 输入数据
- 预期输出（根据验收标准）
- 实际输出
- 执行日志（错误信息、警告）
- 性能数据（如果方案有性能要求）

#### 3.3 判定结果类型

**案例拿不到、环境跑不起来、或标准全 PASS 但输出明显不对，不要在这一步自行降级。三种情形各走各的行：案例拿不到 → 取以 *方案给出的测试案例不可用* 开头的那一行；环境跑不起来 → 取以 *验证跑不起来* 开头的那一行；标准全 PASS 但输出不对 → 取以 *全部验收标准 PASS，但输出明显不对* 开头的那一行。**

根据验证结果分类：

**A 类：完全通过**
- 所有验收标准满足
- 无错误、无警告
- 输出符合预期格式和内容
- 行动：完成，进入报告阶段

**B 类：小问题**
- 核心逻辑正确，但有小错误
- 典型示例：
  - 语法错误、类型错误
  - 逻辑分支写漏（如忘记 `else` 处理）
  - 导入路径错误
  - 文件权限、网络沙箱等环境问题（仅限一次性能修好的；修不好就不是 B 类，取「方案执行不下去时的兜底」表中以 *验证跑不起来* 开头的那一行处理，不得反复重试）
  - 格式化小瑕疵（多余空行、少一个换行符）
- 判断标准：**一次性修改就能解决，不涉及架构或算法调整**
- 行动：直接修复，重新验证一次，如果再次失败则升级为 C 类

**C 类：未达指标**
- 输出结果不符合验收标准
- 性能未达到要求
- 核心功能缺失或错误
- 边界情况处理失败且影响主要场景
- 行动：**禁止补丁式修改**，必须分析根因并决定是否需要回到方案层

**D 类：硬编码嫌疑**
- 代码中出现测试案例的特定值
- 针对特定输入有特殊分支
- 行动：标记为失败，要求重构为通用实现

### 4. 问题修复策略

#### 4.1 B 类小问题修复

允许直接修改，但：
- 仅允许修复一次（避免反复试错）
- 修改后必须重新运行完整测试案例
- 修改内容记录到最终报告
- 如果一次修改未解决，升级为 C 类处理

示例：
```python
# 修复前
def process(data):
    result = data['value'] * 2  # KeyError if 'value' missing

# 修复后（B类：补充边界检查）
def process(data):
    if 'value' not in data:
        raise ValueError("Missing required field: value")
    result = data['value'] * 2
```

#### 4.2 C 类未达指标处理

**禁止行为：**
- 反复调整参数试图"碰运气"通过
- 添加针对测试案例的特殊处理
- 简化需求以适应当前实现
- 不经分析就开始重写

**正确流程：**

1. **根因分析**（使用 analyze-only 思维）
   - 预期行为是什么？
   - 实际行为是什么？
   - 差异出现在哪个环节？（数据流哪一步）
   - 根本原因是什么？（算法错误 / 方案设计缺陷 / 需求理解偏差）

2. **分类根因**
   - **实现偏差**：代码未忠实实现方案 → 回到方案，严格重新实现
   - **方案缺陷**：方案设计本身无法满足需求 → 停止实现，报告方案缺陷，建议重新调用 real-solution-plan
   - **需求误解**：验收标准理解错误 → 与用户确认真实需求，重新对齐

3. **决策**
   ```
   if 根因 == "实现偏差":
       回到第2步，严格按方案重新实现有问题的部分
   elif 根因 == "方案缺陷":
       停止实现
       报告：方案在X方面无法满足需求Y，建议重新规划
       询问用户是否需要回到 real-solution-plan 重新设计
   elif 根因 == "需求误解":
       暂停实现
       与用户确认验收标准
       如果标准变化，评估是否需要调整方案
   ```

   **🛑 STOP — 决策树里「方案缺陷」与「需求误解」两支都必须先停，按各自那一支自己的动作执行，不得合并成一句「先修修看」。未确认前继续实现，就是被本 skill 明确禁止的补丁驱动开发。**

#### 4.3 D 类硬编码处理

**🛑 STOP — 发现硬编码立即停止：**
```
检测到针对测试案例的硬编码实现：
- 位置：[文件:行号]
- 内容：[代码片段]
- 问题：该实现仅对当前测试案例有效，缺乏泛化能力

正在重构为通用实现...
```

重构为通用实现后重新验证。硬编码嫌疑是系统性而非局部时（整个模块靠特例分支堆起来），停止逐个重构，取「方案执行不下去时的兜底」表中以 *硬编码嫌疑不是局部而是系统性* 开头的那一行处理。

### 5. 质量关卡

实现完成并验证通过后，执行最终检查：

#### 5.1 代码质量检查

- [ ] 无未使用的导入、函数、变量
- [ ] 无调试用的 print/log（除非方案要求）
- [ ] 无硬编码的测试数据
- [ ] 错误处理覆盖主要边界情况
- [ ] 代码风格符合项目现有规范
- [ ] 关键逻辑有简洁注释

#### 5.2 方案一致性检查

- [ ] 文件结构与方案一致
- [ ] 数据结构定义与方案一致
- [ ] 技术选型与方案一致
- [ ] 接口签名与方案一致
- [ ] 任何偏离都已记录并有合理原因

#### 5.3 验收标准检查

逐条对照验收标准：
- [ ] 标准 1：[描述] - [PASS/FAIL/PARTIAL]
- [ ] 标准 2：[描述] - [PASS/FAIL/PARTIAL]
- ...

**🔴 CHECKPOINT — 写报告前逐条过这张表。** 所有标准必须 PASS 才能报告为完成。按「方案执行不下去时的兜底」表处理过的每一处例外，在此逐条列出：哪条标准、什么例外、报告里在哪一段写明。

### 6. 输出报告

#### 6.1 完全成功（A 类）

```markdown
## 实现完成

### 实现内容
- 文件：[列出新增/修改的文件]
- 关键变更：[简述核心实现]

### 验证结果
- 测试案例：[案例数量/类型]
- 验证状态：全部通过 ✓
- 验收标准：[逐条列出，标记 PASS]

### 方案遵循情况
- 架构一致性：✓
- 技术选型：✓
- 偏离项：无

### 后续建议
[如果有性能优化、功能扩展等建议，简要列出]
```

#### 6.2 部分成功（B 类修复后通过）

```markdown
## 实现完成（经小幅修复）

### 实现内容
[同上]

### 验证过程
- 初次验证：发现 [X] 类小问题
  - 问题描述：[具体错误]
  - 修复方式：[一句话说明]
- 二次验证：全部通过 ✓

### 验收标准
[同上]

### 修复记录
- 修复次数：1 次
- 修复类型：B 类（小问题）
- 修复内容：[简述]
```

#### 6.3 失败（C 类或 D 类）

```markdown
## 实现受阻

### 已完成部分
- 实现进度：[百分比或模块列表]
- 已验证通过：[部分功能]

### 问题分类
[C 类：未达指标 / D 类：硬编码嫌疑]

### 根因分析
- 预期行为：[描述]
- 实际行为：[描述]
- 差异环节：[数据流中的具体位置]
- 根本原因：[实现偏差 / 方案缺陷 / 需求误解]

### 失败的验收标准
- 标准 [N]：[描述] - FAIL
  - 预期：[具体值/行为]
  - 实际：[具体值/行为]
  - 差距：[量化/定性说明]

### 建议行动
[根据根因给出建议：重新实现 / 重新规划 / 确认需求]

### 禁止的补丁式修复
[列出已识别但不应采用的"捷径"方案，说明为何不可行]
```

## 方案执行不下去时的兜底

以上流程假设方案可执行、案例可获取、验证环境可用。下列情况按表处理。

**本节是上述流程的例外条款：与正文规则冲突时——例如核心原则 1「方案优先」、核心原则 2「必须真实验证」、核心原则 3「禁止补丁」、核心原则 4「禁止硬编码」、核心原则 5「小问题豁免」、「前置条件」四项、2.2 允许偏离的清单、4.1 的一次修复预算、5.3「所有标准必须 PASS」——以本表为准——但仅在该表某行的一线修复与正文规则确实冲突时生效。同一情形命中多行时，取一线修复最保守的那一行——停下、询问、不写入，一律优先于继续推进。但每一处例外都必须在报告中显式标出，不得静默降级。**

| 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|
| 方案给出的测试案例不可用，或项目里根本没有代表性数据可作真实案例 | 用方案里最接近的场景构造一个最小真实输入，并把构造过程与「这是构造案例」的说明写进报告 | 连构造都做不出（无数据、无入口、依赖外部系统）→ 明说「无法真实验证」，把对应验收标准标 PARTIAL，不得标 PASS；报告中单列「未验证项」并写明缺什么才能验证 |
| 验证跑不起来——环境缺依赖、沙箱禁网、权限不足、服务未启动 | 先修环境本身（装依赖、切本地替身、申请权限、起服务），把环境修复动作与结果写进报告 | 环境仍不可修复 → 不得用「代码审查通过」顶替真实验证；报告标「未验证」，并把该环境阻塞列为独立风险项交用户决定 |
| 全部验收标准 PASS，但输出明显不对（标准本身没覆盖到真实要求） | 停下来，具体列出「哪些真实行为没被标准覆盖」，回到用户确认标准是否要补 | 用户坚持按原标准判通过 → 照判，但报告首段显式写明「标准未覆盖 <X>，实际输出存在 <Y>」，不得只塞在附注里 |
| 用户确认过的方案与用户中途提出的新需求冲突 | 指名冲突的是哪一条方案约束与哪一条新需求，让用户选：改方案还是压需求 | 用户不选且要求继续 → 停在第 2 步，不得带着这个未决冲突继续实现；已实现部分在报告中标出与哪条约束相抵 |
| 硬编码嫌疑不是局部而是系统性——整个模块靠特例分支堆起来 | 停止逐个重构，指出这是方案层问题（缺可泛化的算法或数据结构设计），按 4.2 的「方案缺陷」路径处理 | 用户要求先交可用版本 → 交，但报告标 D 类未解决，并写明哪些输入会失效 |
| 方案要求的做法与项目现有约定冲突（命名、目录结构、依赖、代码风格） | 以项目现有约定为准，并在报告中列出偏离方案的每一处及理由 | 用户要求逐字照方案 → 照做，但报告首段写明由此造成的项目不一致；不得静默混用两套约定 |

## 与其他 Skill 的协作

- **前置：real-solution-plan** - 获取详细实现方案
- **前置：analyze-only** - 如果验证失败需要根因分析，调用 analyze-only
- **失败回溯：real-solution-plan** - 如果根因是方案缺陷，重新调用 real-solution-plan
- **后续：recoder** - 成功实现后记录关键决策和实现路径
- **替代：ship-it-for-real** - 如果不需要严格的方案遵循和硬编码检测，可用 ship-it-for-real

## 常见失败模式

### 反模式 1：补丁驱动开发
```
❌ 验证失败 → 加个 if 分支 → 再失败 → 再加个特殊处理 → ...
✓ 验证失败 → 根因分析 → 定位到方案/实现层 → 正确修复
```

### 反模式 2：案例硬编码
```python
❌ 
def process(text):
    if text == "测试案例的具体内容":
        return "预期结果"
    return "其他"

✓
def process(text):
    # 通用逻辑，不依赖具体案例内容
    tokens = tokenize(text)
    return analyze(tokens)
```

### 反模式 3：降低标准过关
```
❌ 用户要求准确率 90%，实现只有 70%，于是调整验收标准为 70%
✓ 承认未达标，分析根因，重新规划或优化方案
```

### 反模式 4：跳过验证
```
❌ "代码逻辑看起来没问题，应该能工作"
✓ 必须运行真实案例，看到实际输出
```

### 反模式 5：方案即兴偏离
```
❌ "我觉得用 X 库更好"（未经分析和用户确认就改变技术选型）
✓ 严格遵循方案，或发现明确问题后与用户讨论调整
```

## 质量承诺

使用此 skill 完成的实现保证：
- ✓ 严格遵循已确认方案
- ✓ 通过真实案例验证
- ✓ 无针对测试案例的硬编码
- ✓ 满足所有验收标准（或明确报告未满足项）
- ✓ 代码质量符合项目规范
- ✓ 问题修复遵循分类规则，无补丁堆砌

不保证：
- ✗ 方案本身的正确性（方案质量由 real-solution-plan 负责）
- ✗ 超出验收标准的额外功能
- ✗ 性能优化（除非验收标准明确要求）