building-react-web-application

React Web 应用

设置

项目	类型	必需	适用时机	完成条件	方法
Node.js 22.12+	用户	必需	所有情况	node --version 显示 22.12 或更高版本	https://nodejs.org
常设规则	自动	必需	搭建新应用	根目录 AGENTS.md 中包含该行	将 - `<target_path>` follows building-react-web-application; load it before changing code there. 添加到根目录 AGENTS.md（若不存在则创建），并在根目录 CLAUDE.md 存在且未导入 AGENTS.md 时也添加；已包含该行的文件则跳过

工作流

1. 设置 — 按顺序处理每一条适用于请求的 设置 项：满足完成条件 → 跳过；user → 若必需，则停止并输出其方法；若可选，则不设置并继续；ask → 填写请求中已回答的内容，将其余问题合并为一条消息提问，并记录每个答案；auto 和 static → 执行。
2. 契约 — 阅读 web-app-contract.md。
3. 配方 — 匹配一条 配方 项；打开其“阅读”列中的所有文档。

• 跨越多项的请求（例如新增带表单的路由）需匹配每一项。

常用场景

意图	示例表述	阅读
设置	“设置 building-react-web-application”，“building-react-web-application 准备好了吗？”	设置 — 对每一行运行工作流步骤 1，然后报告每一行的状态
搭建脚手架	“在 apps/web 中创建一个 Vite + React 应用”，“在此处搭建脚手架”，“为应用添加 lint 和环境变量处理”	scaffolding-application.md、managing-package-installs.md、managing-environment.md、managing-linting.md
结构	“这个模块应该放在哪里？”，“两个功能都需要这个 hook”，“将这个组件移到合适的层”	managing-project-structure.md、managing-linting.md
页面 / 功能	“添加一个设置页面”，“新增订单功能”，“添加侧边栏”，“添加一个 /settings 路由”	managing-project-structure.md、creating-page.md
UI 基础组件	“向 src/ui 添加一个 Dialog”，“根据规范构建 select”	managing-project-structure.md、creating-ui-component.md、managing-styling.md
数据	“从 API 获取订单”，“为结账添加一个 mutation”，“格式化订单日期”	managing-data.md、managing-environment.md
异步 UI 状态	“显示带有加载和错误状态的订单列表”，“滚动时加载更多订单”	creating-async-component.md、managing-data.md
错误 / 反馈	“保存失败时显示 toast”，“报告崩溃”，“添加 404 页面”	managing-errors.md、managing-data.md
表单 / 多步骤	“添加个人资料表单”，“将结账设计为三步表单”	creating-form.md、managing-data.md
样式 / 主题	“应用设计令牌”，“更改品牌颜色”，“添加深色模式”，“将 Inter 用作正文字体”	managing-styling.md
身份验证	“添加登录流程”，“在 API 调用中附加令牌”，“收到 401 时登出”	setting-up-authentication.md、managing-data.md
身份验证守卫	“保护仪表板”，“登录后要求完成个人资料设置”，“添加邀请链接”，“限制只有成员才能访问团队页面”	setting-up-auth-guard.md、setting-up-authentication.md、creating-page.md