前端项目 .claude/ 目录结构示例：CLAUDE.md、hooks.yaml 与 agents 配置骨架

1. 前端项目里 .claude/ 到底该放什么

如果你正在用 Claude Code 写 React + TypeScript 项目，大概率会遇到一个尴尬：每次开新会话，它都要重新问一遍技术栈、目录约定、状态管理选型，甚至把 TanStack Query 的数据塞进 Zustand。.claude/目录就是解决这个问题的——它是项目级的 AI 行为配置中心，把「团队规范」「个人偏好」「自动守门」「专家分工」「可复用知识」拆成不同文件，让 Claude 每次进项目就像老员工回工位，不用重新入职。

这篇给你一份可以直接复制的.claude/目录树和配置骨架，覆盖CLAUDE.md、CLAUDE.local.md、hooks.yaml、agents/、skills/、rules/的职责划分。同时说明怎么用 TaoToken 统一 Key 和 API 通道，让 Claude Code、Cursor、Cline 这些工具走同一个入口，最后用一次本地校验动作确认配置真的生效。适合已经在用 Claude Code 做前端、但配置还散落在聊天记录里的同学。

2. 先接上 TaoToken：统一 Key 与 API 通道

在写配置文件之前，先把「AI 工具怎么连」这件事定下来。Claude Code 默认走 Anthropic 官方通道，但很多团队希望多个工具（Claude Code、Cursor、Cline、Continue）共用一套 Key 和额度，这时候用 TaoToken 做统一入口会省事很多。

TaoToken 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

API 基础地址（不带 UTM，直接用于配置）：https://taotoken.net/api

操作路径很直接：注册后在控制台创建 API Key，然后把它写进环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量，所以配置骨架长这样：

# ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的TaoToken密钥"

改完记得source ~/.zshrc让变量生效。如果你用的是 Windows PowerShell，对应写法是：

$env:ANTHROPIC_BASE_URL = "https://taotoken.net/api" $env:ANTHROPIC_AUTH_TOKEN = "sk-你的TaoToken密钥"

这里有个容易踩的坑：ANTHROPIC_BASE_URL末尾不要带/v1，Claude Code 会自己拼路径。我试过手动加/v1，结果请求 404，排查了十几分钟才发现是路径重复。

Key 管理页面在控制台的 API Keys 区域，建议给不同工具建不同的 Key，方便按工具看用量。接入文档里有各客户端的详细配置说明，遇到不确定的字段直接对照文档改。

注意：环境变量里的 Key 不要提交到 Git。如果你把配置写进项目里的.env，务必确认.env已经在.gitignore中。

3. 可复制的 .claude/ 目录树与配置骨架

下面这份目录树是前端项目（React 18 + TypeScript + Vite）的落地版本，可以直接照着建：

.claude/ ├── CLAUDE.md # 团队级行为总纲，提交到 Git ├── CLAUDE.local.md # 个人偏好，不提交 ├── review.md # 代码审查标准 ├── hooks.yaml # 自动化守门员 ├── rules/ # 分路径生效的规则体系 │ ├── security.md │ ├── coding-style.md │ ├──># 项目：前端管理台 ## 技术栈 - React 18 + TypeScript - Vite 构建 - TanStack Query（服务端状态） - Zustand（客户端状态） - 原生 CSS（组件级） ## 目录结构 src/ ├── components/ │ ├── ui/ # 基础 UI，无业务 │ └── features/ # 业务功能组件 ├── pages/ ├── hooks/ ├── stores/ ├── api/ └── types/ ## 组件规范 - 函数组件 + Hooks - Props 接口命名：XxxProps - 组件默认导出，Props 类型单独导出 - 每个组件对应一个 CSS 文件 - 路径别名使用 @/ ## 状态管理 - 服务端状态：TanStack Query - 客户端状态：Zustand（token、theme） - 本地状态：useState - Zustand 不存接口返回数据 ## 常用命令 - npm run dev - npm run build - npm test

3.2 CLAUDE.local.md：个人工作空间

这个文件不提交，加进.gitignore。它记录个人偏好，比如命名导出习惯、本地代理配置、调试技巧。Claude 会同时读两个文件，冲突时 local 优先，但不能破坏团队规则。

# CLAUDE.local.md（个人偏好，勿提交） ## 个人习惯 - 默认 npm，CI 环境接受 pnpm - hooks / utils / api 函数偏好命名导出 - 组件仍遵循团队默认导出规范 ## 本地环境 - Vite 代理指向本地后端 8080 ## 审查补充关注点 - 未处理的 undefined / null - 遗漏 key 导致的 React warning - 不必要的 useEffect

记得在.gitignore里加一行CLAUDE.local.md，这是最容易忘的一步。

3.3 hooks.yaml：自动化守门员

hooks 是 Claude 执行动作前后的拦截器，配置在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 和格式化；commit 前强制类型检查，不过就拦下；改vite.config必须你点头；TS 文件改完自动交给type-guardian复查。这套下来，低级错误基本进不了仓库。

3.4 rules/：分路径生效的规则体系

rules/的价值在于「每条规则只管一件事，只在它该管的地方生效」。每个文件头部用 YAML front matter 声明paths，Claude 只在匹配路径下应用这条规则。

--- name: api-rules description: API 调用规范 paths: - "src/api/**/*.ts" --- # API 开发规范 - 所有接口使用 RESTful 风格 - 响应体必须包含 code、message、data 字段 - queryKey 必须语义清晰且稳定

security.md管 XSS、CSRF、敏感信息，coding-style.md管命名和导入顺序，data-layer.md管 Query 和 Store 的边界。这样拆的好处是，改一条规则不会牵动全局，也不会让 Claude 在无关文件上浪费注意力。

3.5 agents/：各领域专家子代理

子代理是独立进程，能读文件、能执行命令，适合做专项检查。骨架：

--- name: type-guardian description: 专注 TypeScript 类型安全审查 tools: Read, Grep model: haiku --- 检查 TypeScript 代码中的类型问题： - 是否存在 any - 是否滥用类型断言 - 是否缺少 null / undefined 处理 输出要简短精准，只关注类型问题。

code-reviewer管整体审查，component-architect管组件拆分合理性。子代理用haiku这类轻量模型跑专项检查，成本低、速度快。

3.6 skills/：可复用知识片段

Skill 比CLAUDE.md聚焦，比子代理轻量，类似内部 Copilot Prompt。骨架：

--- name:>请读取 .claude/CLAUDE.md 和 .claude/rules/data-layer.md， 告诉我这个项目里服务端状态应该用什么管理，Zustand 能不能存接口数据。

如果配置生效，Claude 会回答「服务端状态用 TanStack Query，Zustand 不存接口数据」。如果它答不上来或者答错，说明文件路径不对或格式有问题。

再验证 hooks：故意写一个带any的 TS 文件，看type-guardian是否被触发。如果 hooks 配置正确，你会看到子代理介入并指出类型问题。

最后验证 API 通道：在 Claude Code 里随便问一句「你好」，如果正常返回，说明 TaoToken 的ANTHROPIC_BASE_URL和 Key 配置没问题。想单独测模型对话，可以用模型对话页面直接发一条消息确认通道通畅。

5. 本篇常见错排查

配置过程中最容易卡住的几个点，我整理成表格对照：

排障时优先看 Claude Code 的启动日志，它会打印加载了哪些配置文件。如果某个文件没出现在日志里，基本就是路径或格式问题。

6. 把配置沉淀成团队资产

.claude/目录真正的价值不是让 Claude 变聪明，而是把团队里那些「口头约定」变成可版本管理的文件。CLAUDE.md管怎么写，review.md管怎么审，hooks.yaml管自动拦截，agents/管专项复查，skills/管知识复用。这套骨架建好之后，新人拉下代码就自带一套 AI 协作规范，不用再靠口口相传。

接入层面，用 TaoToken 统一 Key 和 API 通道，多个工具共用一个入口，额度和管理都集中。长期跑编码任务和 Agent 的话，可以看下 Coding Plan 的额度方案；只是验证模型通不通，模型对话页面发一条消息最快；接入配置有疑问就翻接入文档，字段说明都在里面。

配置这东西，建一次能用很久，但前提是每个文件的职责边界要清晰。别把所有规则都塞进CLAUDE.md，那样 Claude 读起来累，你改起来也累。