ship-ready Skill 技能

ship-ready - 让 AI 写出的代码配得上「企业级」三个字的硬核技能

技能简介

ship-ready 是面向 Claude Code、OpenAI Codex、GitHub Copilot（CLI 与 VS Code）、Gemini CLI / Antigravity、Cursor 等所有主流 AI 编程智能体的「代码升级」技能。它把 AI 生成、遗留或原型代码，打磨成陌生人能读懂、能信任、能修改、能运维的真正生产级代码，并用「证据」而非形容词来证明。技能内置 8 阶段流水线（基线 → 锁行为 → 评估 → 重构 → 优化 → 证明 → 交接 → 报告），每一阶段都有强制 exit gate，任何 P0 缺陷未关闭都会让 verdict 自动输出 NOT_READY，避免「我跑过了」式的自欺欺人。在盲测评测中，启用 ship-ready 的智能体通过率从 0.46 跃升到 0.90。

核心能力

1. 基线建立（Phase 0）：自动识别技术栈、按 churn × size 排序热点，输出 .quality/baseline.json，让后续所有改动都有量化对照。
2. 行为锁定（Phase 1）：对未测试代码编写 characterization tests，并演示「注入缺陷 → 测试必须失败」的活体验证，杜绝「重构通过但行为已变」的隐性回归。
3. 真伪可证的安全评估（Phase 2）：依据 OWASP 2025、CWE Top 25 2025 与 AI 特有陷阱（幻觉包、授权缺失、沉默 fallback、同义反复测试）逐项输出可证伪发现，含严重度、置信度、文件:行号。
4. 低复杂度重构（Phase 3）：降低圈复杂度（不是搬运），逐项落地，确保每步后测试仍绿，diff 在范围内可审查。
5. 基于测量的优化（Phase 4）：MEASURE → IDENTIFY → FIX → VERIFY → GUARD 五步循环，性能需超过噪声且 oracle 测试证明输出未变，否则 revert。
6. 抗 AI 缺陷清单：内置 verify_package.sh 在安装前检查 PyPI/npm/crates.io/Go proxy，从根上拦截「幻觉包」风险。
7. 五种 Always-on Guardrails：通过 installer 写入 CLAUDE.md / AGENTS.md / GEMINI.md / copilot-instructions.md，让「快速清理、跳过测试」等偷工指令也走完整门禁。
8. 机器可读 verdict：v2.4 起 verdict.py 计算而非声明 READY / READY_WITH_CONDITIONS / NOT_READY，并强制覆盖到最终报告，杜绝「形容词绿」。

安装配置

# 方式 1：skills.sh 一键安装（Claude Code / Codex / Copilot / Cursor / Gemini 等）
npx skills add notaaaronfr/ship-ready

# 方式 2：Claude Code 插件市场（含 session-start guardrails hook）
/plugin marketplace add notaaaronfr/ship-ready
/plugin install ship-ready@ship-ready

# 方式 3：完整安装器（macOS / Linux，bash + git；Windows 用 WSL 或 Git Bash）
git clone https://github.com/notaaaronfr/ship-ready.git && cd ship-ready
./install.sh --all                       # 所有受支持智能体，仅当前用户
./install.sh --target claude,codex       # 仅选定的智能体
./install.sh --all --scope project       # 团队级，安装到 ~/code/xxx

• 方式 1 / 方式 2 仅安装技能；方式 3 还会把五条 guardrails 写入每个智能体的指令文件（Claude Code 走 hook 也可加载）。
• 用户级安装使用符号链接，git pull 即更新；项目级安装复制目录并随仓库提交。
• 升级 v1.0：重新运行 ./install.sh --all 即可，会清理旧路径下重复副本。

使用步骤

1. 安装 skill：运行 npx skills add notaaaronfr/ship-ready，让智能体在合适的请求下加载该技能。
2. 发起请求：在 Claude Code 输入 /ship-ready src/；在 Codex 输入 $ship-ready；或直接说「make this enterprise grade」。
3. 选择模式：small / urgent 改动走 quick mode（分钟级，仅核心门禁）；大改动走 full mode（完整 8 阶段流水线）。
4. 查看 gate 证据：智能体会把质量门输出写入 .quality/gate.json、报告写入 .quality/report.json、verdict 写入 .quality/verdict.txt。
5. 应用 Always-on Guardrails：用方式 3 的 --scope project 安装，把五条铁律同步给团队所有智能体。
6. 验证 ship-ready 自身：跑 evals/run.sh 复现 README 中的盲测评分。

适用场景

1. AI 写的 demo 想上线：用 ship-ready 把 hallucinated 包、SQL 注入、money 用 float 等典型 AI 缺陷一次性清理干净。
2. 遗留老系统接管：先建立基线，再用 characterization tests 锁住既有行为，避免「改完客户说不对了」。
3. 发布前的最后一道关：把 ship-ready 接进 CI，对每次 MR 自动跑 quality_gate.sh，verdict 不通过即禁止合并。
4. 审计 / 合规需要证据：每个发现都是 falsifiable claim + 严重度 + 文件行号 + 测试，OWASP / CWE 标准直接对照。
5. 跨智能体统一质量标准：同一份 skill 同时装到 Claude Code / Codex / Copilot / Gemini，避免「换工具就降质」。
6. 教学新工程师：guardrails 把「先验证包存在、再装」等隐性规则显式化，加速 onboarding。

适用人群

• 用 AI 编程智能体交付生产代码的全栈 / 后端工程师
• 负责代码评审与质量门禁的 Tech Lead、架构师
• 关注 OWASP / CWE / SLSA / OpenSSF Scorecard 的安全与合规团队
• 评估「AI 生成代码到底能不能用」的 CTO / 工程总监
• 维护 monorepo、需要在多种智能体间保持一致规范的平台团队

工作原理

ship-ready 由三部分组成：(1) 纯 Markdown 的 SKILL.md + references + templates，让智能体在请求匹配描述时加载工作流；(2) 可读的 shell / Python 脚本（quality_gate.sh、hotspots.sh、verify_package.sh、verdict.py），所有门禁的真相都来自命令输出而非 LLM 自述；(3) install.sh 多智能体安装器，把技能复制或符号链接到各家指令路径，并在 AGENTS.md / CLAUDE.md / GEMINI.md 内插入标记块写入五条 guardrails。整套机制无 MCP server、无遥测、无凭证，不上传你的代码。verdict 由 verdict.py 根据 gate.json + report.json 机械计算并写入 .quality/verdict.txt，从 v2.4 起智能体必须照抄该 verdict，禁止自行升级标签。

官方链接

• 仓库：https://github.com/notaaaronfr/ship-ready
• 安装包索引：https://skills.sh
• 评测方法：仓库内 evals/README.md（含 fixture、scenarios、trigger queries、runner、answer key）