1. 项目概述：Shipwright，一个为AI编码智能体注入“全栈工程思维”的技能

如果你和我一样，在过去一年里深度使用过Cursor、Claude Code这类AI编程助手，你肯定经历过一个典型的“蜜月期”后的阵痛：它们写代码片段确实快，但一旦涉及到一个完整的、需要交付的项目，问题就暴露无遗。代码是有了，但架构呢？安全呢？性能呢？那个UI，是不是又回到了那个“AI味”十足的、千篇一律的紫色渐变按钮和Roboto字体？你发现自己从一个写代码的程序员，变成了一个不停给AI“擦屁股”、手动补全设计、安全、测试和部署细节的“监工”。

这正是我遇到 Shipwright 这个项目时，感到眼前一亮的原因。它不是一个新框架，也不是一个运行时工具，而是一个 AI智能体技能 。简单说，它是一套极其详尽、结构化的“思维框架”和“检查清单”，你可以把它“安装”到你的Claude Code或Cursor智能体中。一旦加载，你的AI助手就不再只是一个“代码生成器”，而是被赋予了从零到一构建、并最终交付一个具备生产级质量软件所需的 完整工程方法论 。

它的核心价值在于，将Airbnb、Stripe、Meta等顶级科技公司内部那些不成文的、需要多年经验积累的“工程标准”和“最佳实践”，编码成AI可以理解和执行的步骤。这相当于给你的AI编程伙伴配了一位拥有十年全栈经验的资深架构师作为“副驾驶”，确保产出的每一个功能、每一行代码，在诞生之初就考虑了可扩展性、安全性、可访问性和可维护性。接下来，我将结合自己的使用体验和项目源码，为你深度拆解Shipwright是如何工作的，以及如何让它真正为你所用。

2. 核心设计哲学：从“代码生成”到“产品交付”的范式转变

2.1 解决AI编码智能体的根本性缺陷

当前主流的AI编码助手，其训练数据和反馈机制决定了它们擅长的是“模式匹配”和“片段生成”。你问“用Python写一个FastAPI的CRUD端点”，它能给你一个像模像样的代码块。但问题在于， 软件工程远不止是代码片段的堆砌 。它是一系列连贯的、有上下文关联的决策过程。

Shipwright的创始人（或者说，设计者）敏锐地捕捉到了几个关键缺陷，并针对性地设计了解决方案：

1. 缺乏系统性设计 ：AI倾向于直接跳入实现细节，而跳过至关重要的“思考”阶段。比如，它不会主动问你：“这个功能的失败模式有哪些？预期的QPS是多少？数据一致性要求是强一致性还是最终一致性？” Shipwright的 BUILD模式 强制智能体先进行“Think → Architect → Plan”的顶层设计，把问题域和解决方案域梳理清楚，再开始写代码。

2. 忽视非功能性需求 ：这是新手程序员和初级AI最容易忽略的。安全性、性能、可访问性、国际化、监控，这些在项目初期看似“不重要”的东西，往往在后期带来巨大的返工成本。Shipwright的 SHIP模式 将这12个维度的生产就绪度审计，变成了一个可自动化执行的检查清单。

3. 产出“AI味”过重的平庸设计 ：尤其是在前端，如果你不给出非常具体的设计指令，AI生成的界面往往陷入一种“安全但乏味”的美学：大量使用Inter/Roboto字体、单一的Material Design风格、缺乏品牌辨识度的配色。Shipwright内置的 前端设计指南 明确反对这种“AI slop”（AI渣滓），它要求智能体做出有意的、独特的视觉选择，比如建立一套有层级的色彩系统、定义细致的组件状态（hover, active, disabled, loading），并确保明暗模式都有精心打磨的呈现。

2.2 结构化与按需加载的工程智慧

一个涵盖完整软件生命周期的指南，内容必然庞大。如果一次性将全部内容（超过1600行）塞给AI智能体，会严重占用其有限的上下文窗口，导致核心指令被稀释，响应速度变慢且可能遗漏关键信息。

Shipwright采用了一种非常巧妙的 分层加载机制 ，这体现了对AI工作方式（特别是上下文窗口管理）的深刻理解。

• 核心工作流（SKILL.md） ：这是一个始终加载的、相对精简（288行）的文件。它定义了BUILD和SHIP两大模式的核心流程和阶段跳转逻辑。可以把它看作智能体的“主程序”或“调度器”。
• 深度参考手册（references/） ：这是一系列按主题划分的Markdown文件，如 security-hardening.md 、 frontend-design.md 等。它们只在智能体执行到特定阶段时才被动态加载。例如，当进入SHIP模式的第4阶段“安全加固”时，智能体会去加载 security-hardening.md ，里面包含了具体的OWASP Top 10检查项、测试Payload示例、修复代码模式等深度内容。

这种设计保证了智能体在大部分时间保持“轻量”和“专注”，只在需要专家级细节时才去“查阅手册”，极大地提升了效率和准确性。

实操心得 ：这种设计模式非常值得我们在构建自己的AI智能体工作流时借鉴。不要试图做一个“巨无霸”提示词，而应该构建一个“核心路由器+功能模块”的体系。核心路由器负责理解意图和调度，功能模块负责提供特定领域的深度知识。

3. 深度拆解：BUILD模式与SHIP模式的实战指南

3.1 BUILD模式：为想法注入坚固的骨架

当你对智能体说“ 我们来构建一个销售数据追踪仪表盘 ”时，Shipwright的BUILD模式会被触发。这不是简单地开始写React组件和API路由，而是一个严谨的四步流程。

第一步：思考与定义 智能体会首先引导你（或自行推理）明确项目的核心约束和需求。这包括：

• 失败模式 ：如果数据库连接失败，仪表盘该如何降级？是显示缓存数据、一个友好的错误状态，还是完全白屏？
• 约束条件 ：预期的用户并发数是多少？数据更新频率是实时、近实时还是每日批次？是否有合规性要求（如GDPR）？
• 核心需求 ：除了基本的图表展示，是否需要告警功能？数据导出？多租户支持？权限分级？

这个阶段产出的不是代码，而是一份清晰的 问题定义文档 。它确保了所有后续工作都瞄准了正确的靶心。

第二步：架构设计 基于清晰的定义，智能体开始进行技术架构设计。Shipwright的参考指南（ architecture.md ）在这里提供强大的理论支持，它引入了领域驱动设计、CQRS等现代架构思想。

• 领域建模 ：识别核心实体（如 Sale , Customer , Product ）、值对象和聚合根。明确业务边界。
• 服务边界 ：这是一个单体应用，还是需要拆分为多个微服务？如果拆分，服务间通信采用REST、gRPC还是消息队列？
• 数据模式 ：读写分离是否必要？哪些查询需要被优化？是否引入缓存层（Redis）？数据一致性模型如何？
• API策略 ：设计RESTful端点还是GraphQL？如何版本化API？认证和授权机制是什么？

这个阶段会产出 架构决策记录 和初步的 系统组件图 。

第三步：实施规划 有了架构蓝图，智能体开始将其分解为具体的、可执行的任务。这里Shipwright强调了两个关键工程实践：

• 测试驱动开发 ：为每个任务先编写测试用例。这迫使智能体（和你）先思考接口和行为，再思考实现，产出更健壮、更易测试的代码。
• YAGNI原则 ：“You Ain‘t Gonna Need It”。智能体会被要求避免过度工程化，只实现当前迭代明确需要的功能，并为未来可能的扩展点做好标记，而非立即实现。

任务会被组织成小的、原子的提交单元，便于代码审查和回滚。

第四步：匠心实现 这是写代码的阶段，但Shipwright要求以“工匠精神”而非“流水线”心态来对待。代码要整洁、自解释、符合项目约定的代码风格。智能体会利用其代码生成能力，但会确保生成的代码融入了前面三个阶段的所有设计决策。

3.2 SHIP模式：十二道金牌，护航应用上线

BUILD模式产出了一个“能用”的系统，而SHIP模式的目标是将其变成一个“敢用”的生产系统。这是一个包含12个阶段的、自动化审计与修复流程。你可以对整个项目运行完整审计，也可以针对特定方面下达指令，如“ 强化此应用的安全性 ”或“ 优化前端性能 ”。

阶段1：代码健康度

• 审计内容 ：未使用的变量/导入、过时或存在安全漏洞的依赖项、硬编码的密钥、TypeScript的 any 类型、构建过程中的警告信息。
• 智能体行动 ：自动移除死代码，使用 npm audit 或 snyk 检查并升级依赖，将密钥移至环境变量，修复类型错误，消除所有构建警告。 它不只是指出问题，而是直接修复并验证 。

阶段2：后端与可扩展性 这是最体现工程深度的阶段之一。智能体会检查：

• API设计 ：端点命名是否遵循RESTful约定？是否使用了正确的HTTP状态码？请求/响应体格式是否一致？
• 数据库 ：是否为高频查询字段添加了索引？N+1查询问题是否存在？连接池配置是否合理？
• 缓存策略 ：哪些数据适合缓存？缓存失效策略是什么？是否考虑了缓存穿透、击穿、雪崩？
• 后台任务 ：耗时操作是否已异步化（如使用Celery、Sidekiq、BullMQ）？任务是否具有幂等性？
• 弹性模式 ：是否实现了断路器（Circuit Breaker）以防止级联失败？服务降级和限流策略是否就位？

阶段3：测试完备性

• 审计内容 ：单元测试覆盖率、集成测试（包括API、数据库）、端到端测试（如使用Cypress、Playwright）、边界条件测试、压力测试、契约测试（如Pact）、视觉回归测试（如Percy）。
• 智能体行动 ：补充缺失的测试用例，特别是针对业务核心逻辑的负面测试和边界测试。确保测试不是“为了覆盖而覆盖”，而是真正验证了行为。

阶段4：安全加固 智能体加载 security-hardening.md ，进行深度安全扫描：

• 注入攻击 ：检查所有用户输入点，确保使用参数化查询（防SQL注入），对输出进行编码或使用安全库（防XSS）。
• 身份与访问控制 ：验证认证流程（如OAuth 2.0, JWT），检查是否存在不安全的直接对象引用漏洞，确保每个API端点都有正确的权限校验。
• 其他漏洞 ：检查CSRF令牌、SSRF防护、安全HTTP头（如CSP, HSTS）、敏感信息是否在日志中泄露。
• 供应链安全 ：检查依赖项是否有已知漏洞，锁定依赖版本。

阶段5：前端设计抛光 智能体加载 frontend-design.md ，按照一套高标准来审查UI：

• 视觉一致性 ：检查色彩系统是否在亮/暗模式下都协调且有足够的对比度。字体层级（h1-h6, body）是否清晰。
• 组件状态 ：每个交互式组件（按钮、输入框）是否都有定义良好的默认、悬停、激活、禁用、加载状态。
• 动效 ：转场动画是否流畅、有意义，而非滥用。
• 反AI模式 ：明确要求避免使用过于泛滥的“安全”字体组合和配色，鼓励建立有品牌特色的设计系统。

阶段6：移动端响应式

• 审计内容 ：在从320px（小手机）到1920px（大桌面）的9个标准断点上，布局是否正常？触摸目标是否不小于44x44px？导航栏在小屏幕上是否会合理折叠？图片是否使用了 srcset 进行响应式加载？

阶段7：可访问性

• 审计内容 ：是否使用语义化HTML标签？是否可以通过键盘完全操作？屏幕阅读器能否正确朗读？颜色对比度是否符合WCAG 2.1 AA标准？是否为所有图标和图片提供了 alt 文本？

阶段8：性能优化

• 审计内容 ：JavaScript/CSS包体积是否过大？核心Web指标（LCP-最大内容绘制, INP-交互下次绘制, CLS-累积布局偏移）是否达标？运行时是否有不必要的重渲染？服务器接口延迟是否在目标范围内（如P95 < 200ms）？

阶段9：CI/CD流水线

• 审计内容 ：是否配置了自动化构建、测试、部署流水线（如GitHub Actions, GitLab CI）？是否有分阶段环境（staging, production）？是否支持金丝雀发布？Docker镜像是否优化过？部署后是否有冒烟测试？

阶段10：可观测性

• 审计内容 ：日志是否是结构化的（JSON格式）？是否有错误监控和告警（如Sentry, Datadog）？是否实现了分布式追踪？是否定义了服务等级目标和服务等级协议？是否有健康检查端点？

阶段11：世界级标准

• 审计内容 ：代码是否为国际化做好准备（字符串外部化）？是否考虑了搜索引擎优化和生成式引擎优化？是否集成了基础数据分析？是否有关闭故障功能的开关？是否有错误边界？是否考虑了混沌工程测试？

阶段12：文档

• 审计内容 ：项目README是否清晰？是否有架构决策记录？API是否有文档（如Swagger/OpenAPI）？运维手册是否齐全？技术债务是否有记录？

这12个阶段构成了一个极其严苛但又无比实用的生产就绪度清单。智能体像一个不知疲倦的、经验丰富的DevOps工程师，逐项检查、修复、验证，最终交付一个让你能安心睡个好觉的系统。

4. 实战部署：将Shipwright集成到你的工作流

4.1 安装与配置

安装过程非常简单，本质上就是将Shipwright的技能文件克隆到AI智能体能够读取的特定目录。

对于Claude Code（全局安装，对所有项目生效）：

# 在终端中执行
git clone https://github.com/saadjangda/shipwright.git ~/.claude/skills/shipwright

安装后，你打开任何项目，Claude Code智能体都已具备Shipwright的能力。

对于Claude Code（项目级安装，仅对当前项目生效）：

# 在你的项目根目录下执行
git clone https://github.com/saadjangda/shipwright.git .claude/skills/shipwright

对于Cursor：

# 在你的项目根目录下执行
git clone https://github.com/saadjangda/shipwright.git .cursor/skills/shipwright

注意事项 ：确保你的Claude Code或Cursor版本是最新的，以支持技能（Skills）功能。安装后，可能需要重启一下IDE或智能体会话，技能才会被正确加载。

4.2 与智能体对话：触发技能

安装完成后，你无需记忆任何特殊命令。技能的触发完全基于自然语言对话的意图识别。

• 启动新项目 ： “我们来构建一个个人博客系统，支持Markdown和标签分类。” → 智能体会自动进入 BUILD模式 ，开始与你探讨需求、设计架构。
• 审计现有项目 ： “帮我检查一下这个Express API项目，看它是否达到上线标准。” → 智能体会启动 SHIP模式 ，运行完整的12阶段审计。
• 针对性改进 ： “我觉得这个页面的性能有点慢，优化一下。” → 智能体会直接跳转到SHIP模式的**第8阶段（性能）**进行专项审计和修复。
• 设计评审 ： “这个UI太单调了，按照现代设计规范美化一下，特别是暗黑模式。” → 智能体会跳转到**第5阶段（前端设计）**和第6阶段（移动端），并加载 frontend-design.md 进行深度优化。

4.3 实战案例：用Shipwright构建一个链接短链服务

让我们通过一个具体例子，看看Shipwright如何引导智能体工作。

1. 触发BUILD模式 我对Cursor里的智能体说：“用Node.js和Fastify构建一个简单的链接短链服务，需要生成短码、存储原始URL、重定向，并记录访问次数。”

智能体没有立刻开始写代码，而是进入了Shipwright的BUILD流程：

• 思考 ：它反问了我几个问题：“短码生成算法需要抗碰撞吗？（我答：需要，用nanoid）”“数据持久化用内存、文件还是数据库？（我答：SQLite，简单）”“需要用户认证吗？（我答：不需要，公开服务）”“预计QPS？（我答：很低，个人项目）”
• 架构 ：基于我的回答，它给出了一个简单的领域模型（ ShortLink 聚合根，包含 originalUrl , shortCode , visitCount 属性），设计了 POST /shorten 和 GET /:code 两个核心API，并决定使用SQLite + Prisma ORM。
• 规划 ：它将任务分解为：①初始化项目与依赖；②设置Prisma和数据库模型；③实现短码生成与存储逻辑；④实现创建短链端点；⑤实现重定向与计数端点；⑥为每个功能编写单元测试。
• 实现 ：然后，它才开始按照TDD的方式，一个任务接一个任务地生成代码。每完成一个任务，都会运行相关的测试。

2. 触发SHIP模式 基础功能完成后，我说：“现在，让它变得生产就绪。”

智能体切换到SHIP模式，开始了马拉松式的审计：

• 阶段1 ：它删除了一个未使用的 console.log ，并更新了 package.json 里一个包的补丁版本。
• 阶段2 ：它检查了API端点，建议为 GET /:code 添加速率限制（即使我说QPS低），并为我添加了 @fastify/rate-limit 插件。它检查了Prisma连接池的默认配置，确认为单机低负载应用是合适的。
• 阶段3 ：它补充了几个边界测试，比如传入超长URL、重复短码冲突的处理。
• 阶段4 ：这是重点。它发现重定向是 302 Found ，提示可能存在URL劫持风险，建议对用户生成的短链使用 301 Moved Permanently ，对管理功能保持 302 。它检查了输入，确保Prisma的查询已参数化，防住了SQL注入。它提醒我需要在生产环境将 DATABASE_URL 等密钥移至环境变量。
• 阶段5/6/7 ：由于是纯API服务，这些阶段被跳过或标记为不适用。
• 阶段8 ：它建议我考虑对 GET /:code 这个最频繁的读操作添加一层内存缓存（如Node-cache），并给出了示例代码。
• 阶段9 ：它为我生成了一个基本的GitHub Actions工作流文件，包含安装依赖、运行测试、构建的步骤。
• 阶段10 ：它建议集成像Pino这样的结构化日志库，并为服务添加一个 GET /health 健康检查端点。
• 阶段11/12 ：它生成了一个清晰的README，说明了如何安装、运行、测试和部署。

整个过程，我就像一个项目负责人，而智能体则是一个执行力超强、考虑周全的技术负责人，把我能想到和想不到的细节都处理了。

5. 进阶技巧与避坑指南

5.1 如何最大化Shipwright的价值

1. 明确你的“标准” ：Shipwright是高度“固执己见”的。它的标准可能非常严格（比如前端设计）。在开始一个项目前，你可以快速浏览一下其 references/ 目录下的文件，了解它的“口味”。如果你所在团队有特殊规范（比如必须使用某个内部UI库），你可能需要在项目初期通过对话明确告诉智能体：“在我们的项目中，前端组件请使用公司内部的 XDesign 库，配色遵循品牌指南XXX。” 智能体会记住这个上下文，并在后续设计中遵循。

2. 分阶段使用，不要一次性跑完SHIP ：对于大型项目，一次性运行完整的12阶段审计可能会非常耗时，并且产生大量变更。更佳实践是：

   • 在开发每个核心功能模块后 ，运行相关的阶段。例如，写完用户认证模块后，立即运行**阶段4（安全）**进行审计。
   • 在提测前 ，运行阶段1-3（代码健康、后端、测试）和阶段8（性能）。
   • 在上线前 ，再完整地跑一遍所有阶段，作为最终守门员。

3. 将Shipwright作为学习工具 ：即使你不完全采纳它的所有建议，它生成的审计报告和修复代码也是一个绝佳的学习材料。你可以看到一个经验丰富的工程师会关注哪些点，以及如何用代码解决这些问题。这对于提升个人和团队的工程能力非常有帮助。

5.2 常见问题与排查

1. 智能体没有触发Shipwright技能？

   • 检查安装路径 ：确保克隆到的目录完全正确（ ~/.claude/skills/ 或项目内的 .claude/skills/ / .cursor/skills/ ）。
   • 检查技能加载 ：在Claude Code中，你可以尝试输入“ /skills ”命令（如果支持）来查看已加载的技能列表。在Cursor中，可能需要查看设置中关于技能路径的配置。
   • 重启会话 ：关闭并重新打开与智能体的聊天窗口或IDE。

2. 智能体给出的建议过于激进或不适合我的项目？

   • Shipwright的默认配置是针对一个理想的、绿色的生产项目。对于遗留系统或特定场景（如内部工具、概念验证），你可以 直接与智能体沟通，调整标准 。例如：“这是一个内部管理后台，用户不超过10人，请跳过性能压测和复杂的弹性模式检查，重点关注代码质量和安全基线。” 智能体能够理解并调整其审计的严格程度。

3. 生成的代码或修改与我的代码风格不符？

   • 这是AI辅助编程的普遍问题。你需要在项目初期就建立清晰的代码风格约定（如使用Prettier、ESLint配置文件）。你可以在触发BUILD模式前就对智能体说：“本项目使用ESLint Airbnb规则和Prettier进行代码格式化，请确保所有生成的代码符合此规范。” 智能体在修改代码时会尽量遵循现有风格，但复杂重构后手动运行一下格式化工具仍是好习惯。

4. 如何处理智能体无法自动修复的问题？

   • Shipwright并非万能。对于一些深层次的架构问题或需要业务决策的改动（例如，将单体拆分为微服务），智能体可能只会给出 建议和警告 ，而无法自动实施。这时，就需要你作为人类工程师介入，做出决策，然后可以指示智能体：“根据我们刚才讨论的方案A，开始重构用户服务模块。”

5.3 与其他工具链的整合思考

Shipwright是一个方法论和检查清单的载体，它可以与你现有的工具链完美结合：

• 与Linter/Formatter集成 ：Shipwright的“代码健康度”阶段可以调用你项目中的ESLint、Prettier、RuboCop等工具。
• 与测试框架集成 ：它的测试审计会依赖于你的Jest、PyTest、RSpec等测试套件。
• 与CI/CD管道集成 ：你可以将“运行Shipwright SHIP模式审计”作为CI管道中的一个特定阶段（例如，在合并请求时），让智能体自动审查代码并生成报告，但 不建议 在CI中自动应用所有修复，因为这可能引入不可控的变更。更好的做法是将其作为门禁，要求开发者根据报告手动或半自动地修复问题。

我个人在实际使用中最大的体会是，Shipwright并没有取代我作为工程师的思考和决策，而是将我从不厌其烦的、重复性的细节检查中解放出来，让我能更专注于真正的业务逻辑和创新。它像是一个永不疲倦的、知识渊博的结对编程伙伴，时刻提醒我那些容易在 deadline 压力下被忽略的“小事”，而这些“小事”，往往决定了软件最终的品质和寿命。