Shipwright：让AI编码助手具备全栈工程思维，从代码生成到软件交付

1. 项目概述一个为AI编码智能体设计的“全栈工程师”技能如果你用过Claude Code或者Cursor这类AI编码助手大概率有过这样的体验让它写个函数、修个bug它干得又快又好但一旦你让它“从零开始设计一个完整的Web应用”或者“把这个项目优化到能上线的程度”结果往往就一言难尽了。它可能会给你生成一堆看起来能跑、但架构混乱、毫无安全考虑、UI千篇一律、完全无法应对真实流量的代码。本质上大多数AI编码智能体只是一个“高级代码补全工具”它缺乏一个优秀工程师所具备的系统性工程思维和全生命周期项目经验。这正是Shipwright要解决的问题。它不是一个独立的工具而是一个“技能包”Skill你可以把它安装到Claude Code或Cursor中。安装后你的AI助手就仿佛被注入了一位拥有顶尖公司如Airbnb, Stripe, Meta工程实践经验的“虚拟资深工程师”的灵魂。这个灵魂的核心是一套结构化的、可执行的方法论覆盖了从萌生想法到代码上线、再到稳定运行的完整软件生命周期。简单来说Shipwright让AI编码智能体从一个“代码打字员”升级为一个懂得设计、构建、测试、打磨、交付全流程的“Shipwright”造船匠。它回答的核心问题是如果我们要让AI真正独立负责一个项目它需要知道哪些人类工程师才知道的“隐形知识”Shipwright将这些知识编码成了一份详尽的、可操作的检查清单和工作流。2. 核心设计理念与工作模式解析2.1 核心理念从“生成代码”到“交付软件”大多数AI编码工具的失败在于混淆了“写代码”和“做软件”这两个概念。写代码是解决一个局部、具体的技术问题而做软件是一个系统工程涉及需求分析、架构设计、代码实现、质量保障、安全加固、性能优化、部署运维等一系列环环相扣的环节。Shipwright的设计理念基于一个明确的认知AI智能体需要被赋予“上下文”和“约束”。没有上下文它不知道目标是什么没有约束它不知道“好”的标准是什么。因此Shipwright提供了两大核心模式为智能体构建了完整的上下文和明确的约束标准。2.2 双模式工作流详解Shipwright主要包含两种工作模式分别对应项目生命周期的不同阶段。BUILD模式为“从零到一”而生当你对智能体说“我们来构建一个销售数据追踪仪表盘”时BUILD模式会自动激活。它的核心是“设计先行”强制智能体在动手写第一行代码之前必须进行深度思考。其流程是一个严谨的瀑布式与敏捷结合的混合模型思考Think分析潜在的失败模式、系统约束如预算、时间、团队技能和核心需求。这一步是为了避免“手里有锤子看什么都是钉子”的AI惯性思维。架构Architect进行领域建模识别核心实体、聚合根、值对象、划定服务边界是否采用微服务模块如何划分、设计数据模式数据库选型、表结构和API策略RESTful, GraphQL, RPC。规划Plan将大目标拆解为具体、可执行的任务。这里强制引入测试驱动开发TDD理念要求先写测试用例再实现功能。同时遵循“你不需要它YAGNI”原则避免过度设计并提倡小步快跑、频繁提交。实现Implement在以上规划的严格框架下进行编码。Shipwright在这里特别强调“工艺”明确反对“AI式敷衍”AI Slop要求代码必须具备可读性、可维护性和一致性。这个流程确保了最终产出的不是一个“能跑就行”的玩具而是一个结构清晰、意图明确、便于后续迭代的软件基石。SHIP模式为“从一到一百”而战当你的项目初具雏形对智能体说“让这个项目达到生产就绪状态”时SHIP模式便会启动。这是一个极其详尽的12阶段生产就绪度审计流程。它不仅仅是一份检查清单更是一个“发现问题-立即修复-验证修复”的自动化工作流。这12个阶段覆盖了软件交付的每一个层面我将其归纳为四大维度代码与架构健康度阶段1-2清理死代码、管理依赖、优化数据库查询、设计缓存策略、确保数据一致性。这是软件的内在质量。质量与安全保障阶段3-4建立从单元测试到端到端测试的全方位测试网进行系统性的安全加固从常见的注入攻击、跨站脚本XSS到密钥管理、供应链安全无一遗漏。用户体验与可达性阶段5-7这是Shipwright颇具特色的部分。它要求前端设计必须有“抛光”感反对使用AI生成的那种千篇一律的Inter/Roboto字体搭配紫色渐变的界面。它要求提供精心调校的浅色/深色模式、完整的响应式布局从320px手机到1920px桌面共9个断点、以及严格的WCAG 2.1 AA级无障碍访问支持如足够的色彩对比度、完整的键盘导航、屏幕阅读器友好。运维与业务就绪度阶段8-12关注性能指标如Core Web Vitals、建立CI/CD流水线、搭建可观测性体系日志、监控、追踪、并考虑国际化i18n、搜索引擎优化SEO、甚至是为AI时代准备的“生成式引擎优化GEO”、功能开关、法律合规等业务级需求。关键在于智能体在审计每个条目时如果发现问题会直接生成代码或配置来修复它并运行测试来确认修复有效然后才进入下一个条目。这模拟了一个资深工程师在代码评审和预发布检查中所做的工作。3. 技术实现与集成实操3.1 安装与集成让智能体“获得技能”Shipwright的安装过程非常简单本质上是将一套Markdown文档放到AI智能体能读取的特定技能目录下。以下是以Claude Code全局安装为例的详细步骤和原理说明# 1. 克隆Shipwright仓库到本地 git clone https://github.com/saadjangda/shipwright.git ~/.claude/skills/shipwright # 2. 进入Claude Code技能目录通常位于用户主目录下 cd ~/.claude/skills # 3. 确认shipwright技能文件夹已存在 ls -la # 你应该能看到一个名为 shipwright 的文件夹操作原理解析与注意事项~/.claude/skills/是Claude Code客户端查找和加载自定义技能的默认路径。将技能放在这里意味着你打开任何项目Claude Code都能调用Shipwright的能力。如果你只想在当前项目中使用则克隆到项目根目录的.claude/skills/shipwright路径下。这常用于项目特定的技能配置。对于Cursor用户路径变更为.cursor/skills/shipwright。其原理完全相同。安装后通常需要重启你的Claude Code或Cursor客户端以确保它能重新扫描并加载新的技能目录。3.2 底层架构分层加载与上下文管理这是Shipwright设计中最精妙的部分之一直接关系到使用效率和智能体的表现。一个常见的误区是把所有的知识都塞给AI它就能做得更好。实际上过长的上下文Context会稀释核心指令的权重导致AI“忘记”关键目标或产生混乱。Shipwright采用了一种“按需加载”的分层架构shipwright/ ├── SKILL.md # 核心工作流文件始终加载 └── references/ # 深度参考库按需加载 ├── architecture.md ├── frontend-design.md ├── security-hardening.md ├── mobile-responsive.md ├── seo-geo.md └── production-readiness.md工作流程解析触发与核心加载当你发出“make this production ready”指令时智能体首先加载SKILL.md这个288行的核心文件。这个文件包含了12个阶段的宏观工作流和每个阶段的高层检查项。按需深度加载当智能体执行到某个具体阶段例如“阶段4安全加固”时它发现需要更详细的知识比如具体的SQL注入测试载荷、XSS攻击向量示例。此时它会动态地去加载references/security-hardening.md这个深度参考文件。执行与上下文保持智能体利用深度参考文件中的具体知识来生成代码、执行修复和验证。完成后它可能不再需要该文件的全部细节上下文管理的压力得以释放。这种设计保证了智能体在绝大多数时间其工作记忆上下文窗口中保持的是轻量的、目标导向的工作流而非沉重的、数千行的参考手册从而显著提升了任务的完成质量和效率。3.3 交互模式自然语言驱动的开发安装完成后你无需记忆任何复杂命令。整个交互完全基于自然语言智能体会根据你的意图自动切换模式或跳转到特定阶段。例如场景一启动新项目你“我们需要一个个人博客系统支持Markdown写作和标签分类。”智能体识别到“构建”意图自动进入BUILD模式。它会开始与你对话澄清需求“需要评论功能吗需要SEO优化吗”然后输出设计思路、架构图和技术选型建议最后开始按TDD模式编写代码。场景二优化现有项目你“这个后台管理页面的表格在手机上显示错乱了。”智能体识别到具体问题可能直接跳转到SHIP模式的第6阶段移动端适配检查视口设置、CSS媒体查询并给出修复方案。场景三发布前审计你“功能都完成了下周能上线吗”你“Is this ready to ship?”智能体识别到“发布就绪”意图启动完整的SHIP模式12阶段审计并生成一份详细的审计报告列出所有发现的问题、已修复项和剩余风险。这种交互模式极大地降低了使用门槛让开发者可以像与一位经验丰富的同事结对编程一样专注于业务逻辑和产品决策而将工程细节和最佳实践的执行交给被Shipwright赋能后的智能体。4. 深度功能拆解与最佳实践4.1 对抗“AI式敷衍”前端设计的“反套路”AI生成前端界面有一个通病美学上的同质化与细节上的粗糙。Shipwright的“前端设计”阶段阶段5明确宣战。它不仅仅是一套规范更是一套审美和工艺标准。具体实践与要求字体禁令明确反对在标题中使用过于常见的“AI安全字体”如Inter或Roboto鼓励探索更具品牌个性的字体组合例如搭配一个衬线字体和一个无衬线字体。色彩系统要求建立有层级的、可访问的色彩系统而不是随机生成渐变色。例如定义primary-50到primary-900的一系列色阶并确保文本与背景的对比度至少达到WCAG AA标准4.5:1。状态完整性组件必须设计并实现所有状态默认、悬停、聚焦、激活、禁用、加载、错误。AI常常会忽略“禁用”或“加载”状态。动效原则使用缓动函数如cubic-bezier(0.4, 0, 0.2, 1)让动画更自然规定持续时间如200-300ms禁止滥用浮夸的动画。实操示例当你要求智能体“优化这个按钮的样式”时一个未受训的AI可能只是改个颜色。而搭载了Shipwright的AI会做以下事情检查按钮的颜色对比度是否达标。确保按钮有足够的内部填充padding和触摸目标大小≥44x44px。为按钮添加上面提到的所有交互状态的样式。可能建议将按钮的边框半径与项目中的全局设计令牌如--radius-md关联。检查按钮的文案是否清晰、行动指向明确。4.2 超越基础安全主动式安全加固安全检查不是运行一个npm audit就结束了。Shipwright的阶段4提供了一套主动的、深入的加固方案。深度安全清单节选身份验证与授权强制使用bcrypt成本因子≥12或Argon2id进行密码哈希。实施基于角色的访问控制RBAC并对所有API端点进行授权检查。注入防御SQL注入强制使用参数化查询或ORM并提供具体的恶意输入样例如 OR 11来测试现有代码。XSS对所有用户输入进行转义。如果必须使用dangerouslySetInnerHTMLReact或v-htmlVue必须配合DOMPurify这样的库进行净化。这是一个硬性规定。敏感信息管理禁止在代码中硬编码密钥。强制要求从环境变量或密钥管理服务如AWS Secrets Manager读取并在CI/CD流水线中配置秘密扫描。安全头文件检查并配置HTTP安全头如Content-Security-PolicyCSP、X-Frame-Options、Strict-Transport-SecurityHSTS等。实操心得在这个阶段智能体不仅仅是添加依赖。它会修改你的代码。例如它发现你有一段拼接SQL字符串的代码它会直接将其重写为使用预处理语句Prepared Statement的版本并运行相关测试以确保功能不变且漏洞被堵上。4.3 生产就绪的度量可观测性与可靠性阶段10可观测性和阶段11世界级标准将项目从“可以运行”提升到“可以放心运维”。可观测性三板斧结构化日志要求将console.log替换为使用JSON格式的结构化日志库如Winston, Pino确保每条日志包含timestamp,level,service,requestId等字段便于后续聚合和查询。错误监控集成引导你集成Sentry、Rollbar或DataDog等错误监控服务。它会帮你配置全局错误边界React或全局异常处理器后端确保未捕获的错误能被上报。健康检查端点要求创建/health或/ready端点该端点不仅返回200状态码还应检查数据库连接、缓存连接、第三方API可达性等核心依赖的健康状态。可靠性工程实践SLO与错误预算引导你为关键服务定义服务等级目标SLO例如“API请求的99.9%延迟低于200ms”。基于此计算错误预算并设置警报。混沌工程预备虽然不要求在生产环境运行混沌实验但会检查代码是否具备弹性。例如数据库连接失败时是否有重试和回退机制第三方API超时是否会影响核心流程它会建议引入断路器模式如使用opossum库来防止级联故障。5. 常见问题与实战排坑指南在实际使用Shipwright与AI智能体协作的过程中你可能会遇到一些典型问题。以下是我在多次实践中总结的经验和解决方案。5.1 智能体“不理解”或“不执行”技能指令问题现象安装了Shipwright但当你发出“让它生产就绪”的指令时AI似乎无视了技能还是按照它原有的简单方式回应。排查步骤与解决确认安装路径这是最常见的问题。首先检查技能文件夹是否准确克隆到了正确的路径下~/.claude/skills/或./.claude/skills/。路径错误或文件夹名称不对都会导致加载失败。重启AI客户端Claude Code或Cursor可能在安装时已经启动需要完全退出并重新启动以重新加载技能目录。检查技能加载在一些Claude Code版本中你可以在设置中查看已加载的技能列表。确认shipwright出现在列表中。使用明确的触发短语尝试使用README中提到的标准触发句如“Make this production ready”或“Lets build a dashboard for tracking sales”。这些短语在SKILL.md中被设计为明确的触发器。提供更多上下文如果项目非常新或非常复杂AI可能无法确定范围。尝试更详细的指令如“请按照Shipwright的SHIP模式对当前这个Express.js后端API进行第一阶段代码健康度和第四阶段安全的审计”。5.2 SHIP模式审计耗时过长或上下文溢出问题现象运行完整12阶段审计时AI回复速度极慢或者在中途开始“胡言乱语”忘记之前审计的内容。原因分析这是AI模型的上下文窗口限制导致的。即使Shipwright采用了分层加载一个大型项目的完整审计仍然会产生非常长的对话历史。优化策略分阶段审计不要一次性要求“全部审计”。可以分多次进行“请先执行SHIP模式的前三个阶段代码健康度、后端、测试”。完成并应用更改后再进行下一批。聚焦具体问题如果你只关心某个方面直接跳转到对应阶段。例如“请针对当前项目执行SHIP模式的第5阶段前端设计抛光重点检查颜色对比度和响应式布局。”项目阶段性使用在项目早期代码量少时就引入Shipwright的BUILD模式进行设计并在开发过程中定期运行部分SHIP审计如每次提交前跑一下测试和安全检查将工作负载平摊而不是堆积到最后。5.3 AI生成的修复方案与现有技术栈冲突问题现象Shipwright指导AI给出了一个修复方案比如建议使用Prisma作为ORM但你现有的项目使用的是Sequelize。处理原则记住Shipwright提供的是标准和最佳实践而不是不可更改的圣旨。AI智能体是你的助手你才是项目的决策者。正确操作方式理解意图AI建议Prisma是因为它在类型安全、开发体验上可能更符合现代标准。你需要理解这个建议背后的意图是“改善数据库操作的类型安全和开发效率”。给出明确约束在指令中提前或事后补充你的技术栈约束。例如“请按照Shipwright的安全标准加固项目但注意我们使用Sequelize作为ORM请生成适用于Sequelize的参数化查询示例。”审查与调整将AI生成的方案视为一个“提案”。仔细审查其代码理解其原理然后将其适配到你现有的技术栈中。这个过程本身也是极好的学习机会。5.4 对“AI式敷衍”的判定过于主观问题现象在“前端设计抛光”阶段你个人觉得AI生成的界面虽然用了常见字体但看起来也不错不确定是否要强制更改。实战心得Shipwright的“反AI敷衍”规则是一种强制的审美训练目的是打破AI的惰性。在实际操作中你可以将其视为一个起点而非终点。如果项目是内部工具或MVP或许可以接受更高效、更通用的组件库如Ant Design, Chakra UI带来的“标准化”外观。此时你可以指示AI“接受当前组件库的默认样式但请确保满足Shipwright中关于颜色对比度、触摸目标和无障碍访问的所有具体可量化标准。”如果项目是面向用户的核心产品那么坚持Shipwright的“反套路”要求是值得的。它迫使你和AI去思考品牌独特性这会在长期建立产品辨识度。你可以要求AI“遵循‘反AI敷衍’原则但我们的品牌色是蓝色系请基于此重新设计一个独特的配色方案和字体组合。”6. 进阶应用与场景扩展Shipwright的价值不仅限于指导单个项目的开发。当你深入理解其方法论后可以将其思想应用到更广泛的团队和工程实践中。6.1 作为团队的新人入职培训指南对于刚加入团队的新工程师尤其是毕业生Shipwright的12阶段审计清单是一份绝佳的“生产就绪软件检查清单”。它可以系统性地教会新人一个功能在“开发完成”和“可以上线”之间还有哪些鸿沟需要填补。团队可以将这份清单内化作为代码评审Code Review和上线清单Launch Checklist的重要依据。6.2 作为遗留系统重构的路线图面对一个庞大的、文档缺失的遗留系统如何开始重构你可以利用Shipwright的SHIP模式对其进行一次“体检”。让AI或手动按照每个阶段进行检查并生成报告。这份报告会清晰地揭示出系统在安全、性能、可观测性、测试覆盖等方面的具体债务。这为制定重构优先级和规划提供了数据驱动的依据。例如如果阶段4安全发现大量高危漏洞那么安全重构就应该是第一优先级。6.3 定制化你自己的“领域技能”Shipwright的架构是开放的。你可以以它为蓝本创建适合自己公司或特定技术栈的定制技能。场景你的公司全部使用Go语言和Kubernetes。操作Fork Shipwright仓库修改其中的参考文件。例如在references/security-hardening.md中将Node.js相关的安全示例如helmet库替换为Go相关的如secure中间件。在CI/CD阶段将示例从GitHub Actions改为GitLab CI或Argo CD。这样你就拥有了一个高度定制化的、更高效的内部AI工程技能。6.4 与现有开发流程的结合将Shipwright集成到你的CI/CD流水线中作为一个“AI评审员”环节。例如可以在提交流水线中设置一个Job调用Claude Code的API对变更的代码运行Shipwright某几个阶段的快速检查如代码风格、安全反模式、测试覆盖率变化并将评论自动提交到Pull Request中。这为代码质量保障增加了一层智能化的、基于最佳实践的自动化检查。经过多个项目的实践我个人最大的体会是Shipwright最大的价值不在于它替你写了多少代码而在于它强制引入了一种严谨的、全周期的工程化思考框架。它像一位不知疲倦的、知识渊博的结对编程伙伴时刻在你耳边提醒那些容易被忽略的“细节”——而这些细节往往正是区分一个业余项目与一个专业产品的关键。它可能无法完全替代资深架构师的深度决策但它无疑能将每个开发者包括AI辅助下的开发者向“工匠”的方向推进一大步。开始使用时你可能会觉得它有些“啰嗦”或“死板”但一旦适应了这种节奏你会发现项目的底线质量得到了前所未有的保障。