Communitygithub.com

TheDecipherist/claude-code-mastery-project-starter-kit

选择Web应用的渲染方式和是否使用框架,前置决策。Claude默认使用客户端渲染和手写原生HTML/JS,但这对于内容网站和多页面应用通常是错误的起点。在开始或搭建网站、应用时使用,决定页面渲染方式(SSR、SSG、CSR),或即将手动构建路由和状态管理时使用。涵盖默认使用服务端渲染HTML以实现首屏加载和SEO,在存在多个页面时选用框架,以及避免对单页面过度设计。

claude-code-mastery-project-starter-kit 是什么?

该技能帮助开发者在使用AI编码助手(如Claude Code)时,在项目初期正确选择Web应用的技术架构和渲染策略。Claude等AI工具倾向于默认采用客户端渲染和纯手动HTML/JS,但这对于大多数真实网站并非最佳实践。该技能提供了三层决策指南:一是默认使用服务端渲染(SSR/SSG)以确保首屏加载速度和SEO友好性;二是在项目包含多个页面时,推荐采用Next.js、Astro、SvelteKit等现代框架,以获得开箱即用的路由、数据加载和代码分割能力;三是根据项目实际规模选择最轻量的方案——单页登录页无需重型框架,但多页内容网站也不应手写。技能面向Claude Code、Cursor等AI编程工具,集成后能自动触发架构建议。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit/tree/HEAD/.claude/skills/web-architecture

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Web 架构:预先选择渲染策略

Claude 默认倾向于两种通常错误的做法:在浏览器中渲染所有内容,以及使用原生 HTML/JS 手动构建多页面应用。这两者都应是预先审慎做出的选择,而对于大多数真实网站,更好的答案是服务端渲染 HTML 和框架。即使用户没有明确要求,也应主动提出这些建议,就像在生产环境前主动提出使用 WAF 一样。

默认使用服务端渲染 HTML,而非客户端渲染

对于任何关注内容、SEO 或首屏加载的场景,内容必须存在于初始 HTML 响应中,而不是由客户端 JavaScript 在之后绘制。客户端渲染(一个空白外壳,在浏览器中获取并渲染内容)意味着在包加载并运行之前屏幕是空白的,LCP 缓慢,并且许多爬虫和 LLM 检索器从未看到内容,因为它们无法可靠地执行 JavaScript。请改用服务端渲染:

  • SSG(静态生成): 在构建时渲染,从 CDN 提供静态文件。最快、最便宜、缓存性最强。适用于不随请求变化的内容的默认选择:营销页面、文档、博客、列表页面和分类页面(可重新构建)。
  • SSR(服务端渲染): 在服务端按请求渲染。适用于无法在构建时生成的动态、个性化或需要身份验证的内容。
  • CSR / 岛屿架构: 仅在浏览器中渲染真正需要交互的部分,或用于登录后且 SEO 无关的应用式界面(如仪表盘)。采用岛屿架构(Astro),页面以静态 HTML 形式交付,仅交互式组件进行水合。

你可以按页面选择,混合使用:同一站点中,可以有静态营销页面(SSG)、个性化账户页面(SSR)和交互式小部件(岛屿架构)。

多个页面意味着选用框架

如果项目包含多个页面、共享布局、路由或真实数据获取,使用原生 JS 手动构建将是一个维护和性能陷阱,而且除非另有指示,这是 Claude 的默认行为。请选用框架(Next.js、Astro、SvelteKit、Nuxt、Remix)。它们提供开箱即用的路由、SSR 和 SSG、代码分割、数据加载和图像优化,并且更重要的是,它们在服务端渲染的初始 HTML 之上提供 SPA 风格的客户端导航,因此你能获得流畅的多页应用体验,而无需交付一个破坏首屏加载和 SEO 的纯客户端 SPA。

请注意区别:纯客户端渲染的 SPA 是内容网站应避免的。进行 SSR/SSG 并支持客户端导航的框架既能提供应用体验,又能将内容保留在 HTML 中。

但要根据项目匹配合适的工具

不要过度纠正。单个静态页面、登录页或小型可嵌入小部件不需要 Next.js,纯 HTML 和 CSS 是正确的、更轻量的选择,而在此处使用重型框架则是另一种错误。失败可能出现在两个方向:常见的是选择不足(全原生、在浏览器中渲染),但对琐碎页面过度设计也是真实存在的。决策标准是:有多少页面、内容是否需要可爬取且快速、交互性如何,然后选择满足这些要求的最轻量方案。


此技能会持续成长。当实际架构决策有稳定且可辩护的答案时,可以添加一条规则。

相关技能