.claude/目录结构示例（前端）

claude/├── CLAUDE.md# Claude 行为总纲（项目级）├── review.md# 代码审查标准├── hooks.yaml# Hooks 配置（守门员）│├── code-reviewer.md# 代码审查子代理│├── type-guardian.md# 类型安全子代理│└── component-architect.md # 组件设计子代理。

web行路人

359人浏览 · 2026-05-09 17:07:20

web行路人 · 2026-05-09 17:07:20 发布

.claude/
├── CLAUDE.md # Claude 行为总纲（项目级）

├── CLAUDE.local.md # 本地级个人工作空间
├── review.md # 代码审查标准
├── hooks.yaml # Hooks 配置（守门员）

├──rules/ Claude 的“法律体系”
├── agents/
│ ├── code-reviewer.md # 代码审查子代理
│ ├── type-guardian.md # 类型安全子代理
│ └── component-architect.md # 组件设计子代理
└── skills/
└── react-best-practices.md # 可选：技能库

一、各文件职责总览

文件 / 目录	作用
`CLAUDE.md vs` CLAUDE.local.md	Claude 的“入职手册”
`review.md`	Claude 的“评审标准”
`hooks.yaml`	自动化守门员
`agents/`	各领域专家
`skills/`	可复用的知识片段
rules/	拆分和组织项目指令

二、`CLAUDE.md vs` CLAUDE.local.md`（`Claude 的“入职手册”`）`

CLAUDE.md：团队级、提交到 Git CLAUDE.local.md：个人级、不提交（加入 .gitignore） Claude Code 同时读取两者，但 local优先级更高

1、CLAUDE.md:Claude 行为总纲（项目级）

# 项目：xxxx

## 技术栈
- React 18 + TypeScript
- Vite 构建
- TanStack Query（数据获取）
- Zustand（状态管理）
- 原生 CSS（组件级 CSS）

## 目录结构
src/
├── components/
│   ├── ui/        # 基础 UI（无业务）
│   └── features/  # 业务功能组件
├── pages/         # 页面
├── hooks/         # 自定义 Hooks
├── stores/        # Zustand stores
├── api/           # API 调用
└── types/         # 类型定义

## 组件规范
- 函数组件 + Hooks
- Props 接口命名：`XxxProps`
- 组件默认导出组件本身，Props 类型单独导出
- 组件样式：每个组件对应一个 CSS 文件
  （如 `Button.tsx` + `Button.css`）
- 路径别名：使用 `@/` 代替相对路径
  （如 `@/components/ui/Button`）

## 状态管理
- 服务端状态：TanStack Query
- 客户端状态：Zustand（如 token、theme）
- 本地状态：useState
- Zustand 不存接口返回数据

## 常用命令
- `npm run dev` - 开发服务器
- `npm run build` - 构建
- `npm test` - 测试

让 Claude：

不乱换技术栈
不写反模式
生成风格高度一致的 React + TS 代码

2、CLAUDE.local.md:个人工作空间用于记载个人工作笔记，不提交到 Git，适合内容包括本地环境配置、个人调试技巧、当前工作备注，敏感信息（测试账号等）

# CLAUDE.local.md（个人开发偏好）

> ⚠️ 本文件为**个人本地配置**，**请勿提交到 Git**
> 已建议在 `.gitignore` 中加入：
> ```
> CLAUDE.local.md
> ```

---

## 1. 个人开发习惯

- 默认使用 `npm`，但在 CI 环境中接受 `pnpm`
- 个人更偏好 **命名导出** 用于：
  - hooks
  - utils
  - api 函数
- 组件仍遵循团队规范（默认导出）

---

## 2. 本地环境差异

### 接口代理（Vite）

本地开发使用 Vite 代理：
Claude 在生成本地相关代码时可参考该配置。

---

## 3. 个人命令别名（非团队强制）
Claude 在交互中可以识别并使用这些别名。

---

## 4. 个人审查关注点（补充 review.md）

在执行 `/review` 时，我会额外关注：

- 是否存在未处理的 `undefined` / `null`
- 是否遗漏 `key` 导致 React warning
- 是否存在不必要的 `useEffect`
- 是否有可提取的重复逻辑

---

## 5. 个人调试习惯

- 允许在开发环境中使用：
- 提交前必须移除或通过 `PreCommit` Hook 自动清理

---

## 6. 与 CLAUDE.md 的关系

- `CLAUDE.md`：团队规范（主导）
- `CLAUDE.local.md`：个人偏好（补充）

> 当两者冲突时，以 `CLAUDE.local.md` 为准，但不得破坏团队规则或降低代码质量。

---

## 7. 示例：Claude 如何结合两者工作

### 团队规则（CLAUDE.md）
- 使用 `@/` 路径别名
- 组件默认导出

### 个人偏好（CLAUDE.local.md）
- hooks / utils 使用命名导出

### Claude 生成结果示例
---

## 8. 推荐 .gitignore 配置
---

记得把 CLAUDE.local.md 加入 .gitignore！

三、`review.md（`Claude 的“评审标准”`）`

# review.md — Claude 代码审查规范

> 本文件用于指导 Claude Code 在执行 `/review` 时的审查标准  
> 适用于 MR / PR / 单次代码变更

---

## 1. 审查目标

Claude 在审查代码时应重点关注：

1. 是否违反 `CLAUDE.md`
2. TypeScript 类型是否安全
3. 状态分层（Query / Zustand / useState）是否正确
4. 组件拆分是否合理
5. 样式是否符合组件级 CSS 规范
6. 是否有性能、可维护性或可读性问题

---

## 2. 强制审查规则（必须执行）

### 2.1 TypeScript

✅ 必须检查：
- 是否存在 `any`
- 是否遗漏 `null / undefined`
- Props / State / 返回值是否有明确类型
- 是否滥用类型断言

❌ 不允许通过：
- 用 `any` 绕过类型检查
- 隐式 `any`

---

### 2.2 React 组件

✅ 必须检查：
- 是否为函数组件
- Props 接口是否命名为 `XxxProps`
- 组件是否默认导出，类型是否单独导出
- 是否避免不必要的 `useState / useEffect`
- 是否拆分 `ui / features`

❌ 不允许通过：
- 页面直接写 API 请求
- 单个组件超过 200 行且不拆分

---

### 2.3 TanStack Query

✅ 必须检查：
- 是否使用 `useQuery / useMutation`
- `queryKey` 是否稳定、语义清晰
- 是否避免 `useEffect + fetch`

❌ 不允许通过：
- 用 Zustand 存接口数据
- 页面直接 `fetch / axios`

---

### 2.4 Zustand

✅ 必须检查：
- 是否只存客户端状态（如 token、theme）
- 是否与 Query 职责分离

❌ 不允许通过：
- 在 store 中写请求逻辑
- 存服务端数据

---

### 2.5 样式规范

✅ 必须检查：
- 是否使用组件级 CSS（如 `Button.css`）
- 是否正确引入：

四、hooks.yaml（守门员配置）

hooks:
  PostEdit:
    - run: pnpm lint --fix
    - run: pnpm prettier --write {{filePaths}}

  PreCommit:
    - run: pnpm type-check
      exitOnError: true

  PreToolUse:
    - tool: Bash
      command: rm
      action: deny
    - tool: Write
      pattern: "**/vite.config.*"
      action: ask

  PostEdit:
    - agent: type-guardian
      files: "src/**/*.ts{,x}"

效果：

Claude 写完代码 → 自动 lint / format
commit 前 → 强制类型检查
改 vite.config→ 必须你同意
TS 文件 → 自动交给 type-guardian复查

五、rules/(Claude 的“法律体系”)

.claude/rules/是 Claude 的“法律体系”
•每一条规则只管一件事
•只在它该管的地方生效
•让 Claude 越用越像“你团队的高级工程师”

文件配置示例
一个典型的 .claude/rules/目录结构如下：

.claude/
├── rules/
│ ├── security.md # 安全规范（XSS、CSRF、鉴权）
│ ├── coding-style.md # 编码风格 / 命名 / 结构
│ ├── data-layer.md # TanStack Query + Zustand 使用规范
│ ├── component-rules.md # 组件设计规则（ui / features）
│ ├── api-rules.md # API 调用规范
│ ├── testing.md # 测试规范（vitest / rtl）
│ └── git-workflow.md # Git / Commit / PR 规范

各规则文件职责说明

文件	作用	生效路径
`security.md`	XSS / CSRF / token / 敏感信息	`src/*/.tsx?`, `src/api/**`
`coding-style.md`	命名 / 导入 / 注释 / 顺序	`src/*/.tsx?`
`data-layer.md`	Query / Store 边界	`src/stores/`, `src/api/`
`component-rules.md`	ui / features 拆分	`src/components/**`
`api-rules.md`	接口封装 / queryKey	`src/api/**`
`testing.md`	测试结构 / mock	`src/*/.test.tsx?`
`git-workflow.md`	commit / branch / pr	`.git/**`

示例：api-rules.md可配置为仅在操作后端文件时触发：

---
paths:
  - "src/api/**/*.ts"
  - "src/controllers/**/*.ts"
---
# API 开发规范
- 所有接口使用 RESTful 风格
- 响应体必须包含 code、message、data 字段

示例：security.md: 安全规范

---
name: security-rules
description: 前端安全规范（XSS、CSRF、鉴权、敏感信息处理）
paths:
  - "src/**/*.tsx"
  - "src/**/*.ts"
  - "src/api/**/*"
---

# 前端安全规范（Claude 必须遵守）

> 本规则仅在涉及前端代码或 API 调用时生效

---

## 1. XSS 防护

### ✅ 允许的做法
- 使用 React 默认的 `{}` 插值（自动转义）
- 使用 `dangerouslySetInnerHTML` 时，必须先 sanitize

示例：coding-style.md：编码风格

---
name: coding-style
description: React + TypeScript 编码风格与结构规范
paths:
  - "src/**/*.ts"
  - "src/**/*.tsx"
---

# 编码风格规范（Coding Style）

> 本规则用于约束代码风格、命名、结构  
> 与 `CLAUDE.md` 保持一致，但更细致、可自动检查

---

## 1. 命名规范

### 1.1 文件命名
- 组件文件：`PascalCase.tsx`
- 工具 / hook / store：`camelCase.ts`

### 1.2 变量 / 函数
- 变量、函数：`camelCase`
- 常量：`UPPER_CASE`
- 组件名：`PascalCase`
### 1.3 Props 类型
- 必须命名为 `XxxProps`
---

## 2. TypeScript 风格

- ❌ 禁止使用 `any`
- ✅ 优先使用 `interface`
- ✅ 公共类型放入 `src/types/`
---

## 3. React 组件风格

### 3.1 基本结构
- 函数组件 + hooks
- 默认导出组件，Props 类型单独导出
### 3.2 组件内部顺序
---

## 4. 样式规范

- 每个组件对应一个 CSS 文件
- 使用组件级 CSS Modules 或普通 CSS
- ❌ 禁止大量内联 style
- ✅ 可提取通用 class

---

## 5. 状态与数据流风格

### 5.1 状态分层
- 服务端状态 → TanStack Query
- 客户端状态 → Zustand
- 局部状态 → useState

### 5.2 禁止反模式
---

## 6. 导入顺序（推荐）

Claude 生成代码时请保持以下顺序：
---

## 7. 注释风格

- 公共函数 / hook 必须有 JSDoc
- 复杂逻辑需注释“为什么”，而不是“做了什么”
---

## 8. Claude 行为约束

Claude 在生成代码时必须：

- ✅ 遵守上述命名规则
- ✅ 自动按目录放置文件
- ✅ 不生成 `any`
- ✅ 不混用默认导出 / 命名导出
- ✅ 不写无意义注释（如 `// set loading`）

---

## 9. 与 review.md 的配合

在 `/review` 时，Claude 应重点检查：

- 命名是否统一
- 是否违反导入顺序
- 是否存在 `any`
- 是否混用状态来源
- 是否风格混乱

---

✅ 本规则文件特点：
- **只管“怎么写得好看、好维护”**
- **不干涉架构 / 安全 / 业务逻辑**
- 与 `security.md`、`CLAUDE.md` 正交互补

---

六、agents/子代理示例

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 代码审查。检查 TypeScript、React、性能、可读性。
tools: Read, Glob, Grep
model: sonnet
---
你是一名资深前端 reviewer。

请重点检查：
1. TypeScript 类型安全
2. React 组件拆分合理性
3. TanStack Query / Zustand 使用是否正确
4. 是否有性能隐患
5. 命名与结构是否清晰

输出格式：
- ✅ 优点
- ⚠️ 问题（严重 / 一般）
- 💡 改进建议（附代码）

.claude/agents/type-guardian.md

---
name: type-guardian
description: 专注 TypeScript 类型安全审查。
tools: Read, Grep
model: haiku
---
你的任务是检查 TypeScript 代码中的类型问题：

- 是否存在 any
- 是否滥用类型断言
- 是否缺少 null / undefined 处理
- 是否可进一步收窄类型

输出要简短、精准，只关注类型问题。

.claude/agents/component-architect.md

---
name: component-architect
description: 审查 React 组件结构与职责划分。
tools: Read, Glob
---
请检查组件是否满足：

- 单一职责
- ui / features 拆分正确
- Props 接口清晰
- 是否应拆分为更小组件
- 是否不应使用 state / effect

输出建议性重构方案。

七、skills/（可复用的知识片段）

Skill = 一段可复用的“专家知识”

可以被 Claude 在生成 / 审查代码时自动或手动调用

可以理解为：

比 CLAUDE.md更聚焦
比 SubAgent 更轻量
类似「内部 Copilot Prompt」

Skill 文件示例（组件设计）

.claude/skills/component-design.md

---
name: component-design
description: React 组件设计最佳实践（函数组件 + Props + CSS）
model: inherit
---

你是一名 React 组件设计专家。

请遵循以下规则：

1. 使用函数组件 + hooks
2. Props 接口命名为 `XxxProps`
3. 组件默认导出组件本身，Props 类型单独导出
4. 每个组件对应一个 CSS 文件：
5. 禁止在组件中写 API 请求
6. 禁止业务逻辑混入 ui 组件

生成组件时，请输出：
- 组件代码
- 对应的 CSS 文件
- Props 类型

使用实例：

/code 使用 component-design 规范，创建一个 Button 组件

.claude/skills/data-layer.md

---
name: data-layer
description: React 数据层规范（TanStack Query + Zustand）
---

你负责设计 React 数据层。

规则：

1. 服务端数据：TanStack Query
2. 客户端状态：Zustand（token / theme）
3. Zustand 不存接口数据
4. 页面不直接写 fetch / axios
5. API 请求统一放在 `src/api/`

生成代码时请同时输出：
- api 请求函数
- query / mutation hook
- 正确使用方式示例

使用示例:

/code 使用 data-layer skill，创建用户详情接口

Claude 会输出：

api/user.ts
useUserQuery
页面调用示例

八、Skill vs SubAgent vs CLAUDE.md

能力	CLAUDE.md	Skill	SubAgent
作用范围	全局	局部	独立进程
是否执行命令	❌	❌	✅
是否可复用	✅	✅	✅
适合场景	行为规范	专家知识	复杂任务

✅ 最佳实践：

CLAUDE.md：告诉 Claude「怎么写」
skill：教 Claude「某一方面怎么写得更好」
subagent：让 Claude「去专门找问题」

九、CLAUDE.md与 Hooks / Agents 的关系

CLAUDE.md → 告诉 Claude「怎么写」
review.md → 告诉 Claude「怎么审」
hooks.yaml → 自动执行规则
agents/ → 分工更细的专家

协作流程图（文字版）

你发出指令
↓
CLAUDE.md 决定行为
↓
Claude 写代码
↓
hooks.yaml 拦截
↓
agent 复查（可选）
↓
代码进入 repo

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

DeepSeek 工具调用超时治理：何时重试、何时熔断？

DeepSeek技术社区

OpenAI兼容网关接入DeepSeek：字段映射与错误码对齐的工程实践

DeepSeek技术社区

投机解码上线前必问：你的延迟账本从首token还是整句开始算？

DeepSeek技术社区

所有评论(0)

查看更多评论

web行路人

@qishuixian

已为社区贡献2条内容

.claude/目录结构示例（前端）

web行路人

一、各文件职责总览

二、CLAUDE.md vs CLAUDE.local.md（Claude 的“入职手册”）

三、review.md（Claude 的“评审标准”）

四、hooks.yaml（守门员配置）

五、rules/(Claude 的“法律体系”​)

六、agents/子代理示例

七、skills/（ 可复用的知识片段）

八、Skill vs SubAgent vs CLAUDE.md

九、CLAUDE.md与 Hooks / Agents 的关系

所有评论(0)

温馨提示：您尚未绑定手机号

web行路人

二、`CLAUDE.md vs` CLAUDE.local.md`（`Claude 的“入职手册”`）`

三、`review.md（`Claude 的“评审标准”`）`

五、rules/(Claude 的“法律体系”)

七、skills/（可复用的知识片段）