前端项目 CLAUDE.md 模板

适用场景

用 React、Next.js App Router 或 Astro 写站点，希望 Claude 一上来就知道：用哪个包管理器、组件放哪里、什么时候才能加 "use client"、改完 UI 怎么自检。

前端项目最容易踩的坑不在语法，而在「看起来对、实际一用就坏」：布局在窄屏崩掉、拼音输入时回车误提交、样式写死了色值。模板把这几类问题都写成了可检查的规则。

模板

保存为 CLAUDE.md，把【】和技术栈按实际情况改掉：

# 【项目名】（前端）

技术栈：【Next.js 15 App Router | Astro 5 + MDX】、TypeScript、【Tailwind | CSS Modules】，包管理器 【pnpm】。

## 常用命令
- 开发服务器：`pnpm dev`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`
- 单个测试：`pnpm test 【文件路径】`（优先单文件，不要每次全量）
- 构建：`pnpm build`（提交前必须通过）

## 组件与目录
- 页面：`src/app/`（Next）或 `src/pages/`（Astro）。
- 可复用组件：`src/components/`，一个组件一个目录，样式与测试放在同目录。
- 数据请求只放在 `src/lib/api/`，组件里不直接写 `fetch`。
- 颜色、间距等设计令牌在 `src/styles/tokens.css`，组件里不写死色值。

## 编码约定
- 只用函数组件与 Hooks；Props 用 `type` 声明，命名为 `组件名Props`。
- 【Next】默认写服务端组件；只有需要交互或浏览器 API 时才加 `"use client"`，并在汇报里说明原因。
- 【Astro】能用纯 `.astro` 就不要引入前端框架岛；确需交互再选 `client:visible` 等指令。
- 禁止 `any`；确实无法避免时用 `unknown` 加类型收窄。
- 不新增依赖，需要时先说明理由并等待确认。

## 交互与可访问性
- 可点击元素用 `button` 或 `a`，不要给 `div` 绑 onClick。
- 图片必须写 `alt`，表单控件必须有关联的 label。
- 支持 Enter 发送的输入框，必须判断输入法组合状态（`event.nativeEvent.isComposing`），避免拼音选词时误提交。

## 验证
- 改完 UI 必须在浏览器里看一遍或截图，类型检查通过不代表界面正确。
- 涉及布局的改动，检查 375px 和 1280px 两个宽度，不允许出现横向滚动条。
- 汇报时说明：跑了哪些命令、看了哪些页面、哪些没验证。

## 禁区
- 不手改 `src/generated/`、lockfile。
- 不提交 `.env*`；环境变量只通过 `import.meta.env` 或 `process.env` 读取，并在 `.env.example` 登记变量名。

怎么用 / 怎么改

• 只保留你真正使用的框架那一行，删掉带【Next】或【Astro】标记的另一半。技术栈写错比不写更糟糕。
• 如果规则越来越多，按文件类型拆到 .claude/rules/ 下。例如新建 .claude/rules/components.md，开头写 YAML 前置信息：

---
paths:
  - "src/components/**/*.{ts,tsx}"
---

之后只有 Claude 读写匹配文件时，这份规则才会加载，根目录文件可以保持精简。paths 是规则文件里 Claude Code 唯一识别的字段。

• 设计稿相关的约束（间距刻度、字号表）更适合放进单独的文档，再用 @docs/design-tokens.md 引用，或者做成 Skill 按需调用。
• 如果项目用 monorepo，在各子包目录放自己的 CLAUDE.md，子目录文件在 Claude 触碰该目录时才加载。

常见问题或注意事项

• Claude 总是跳过自检。 「改完必须看浏览器」属于建议性规则。想让它形成闭环，在提示词里要求「截图并对比，列出差异再修复」，或者接入能截图的浏览器工具。
• 规则很多但效果一般。 先检查文件是否超过 200 行；再检查有没有互相矛盾的条目，比如一处要求默认服务端组件，另一处又写「交互组件随便加 use client」。
• 想强制格式化。 格式化不要靠 CLAUDE.md 提醒，用 PostToolUse hook 在每次编辑后自动执行，见本站「编辑后自动格式化」模板。
• 模板里的命令是示例。 换成你的包管理器和脚本名，并真的运行一遍确认能跑通，再让团队其他人使用。