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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址不带 UTM直接用于配置https://taotoken.net/api操作路径很直接注册后在控制台创建 API Key然后把它写进环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量所以配置骨架长这样# ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥改完记得source ~/.zshrc让变量生效。如果你用的是 Windows PowerShell对应写法是$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你的TaoToken密钥这里有个容易踩的坑ANTHROPIC_BASE_URL末尾不要带/v1Claude 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 - 客户端状态Zustandtoken、theme - 本地状态useState - Zustand 不存接口返回数据 ## 常用命令 - npm run dev - npm run build - npm test3.2 CLAUDE.local.md个人工作空间这个文件不提交加进.gitignore。它记录个人偏好比如命名导出习惯、本地代理配置、调试技巧。Claude 会同时读两个文件冲突时 local 优先但不能破坏团队规则。# CLAUDE.local.md个人偏好勿提交 ## 个人习惯 - 默认 npmCI 环境接受 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 声明pathsClaude 只在匹配路径下应用这条规则。--- 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 QueryZustand 不存接口数据」。如果它答不上来或者答错说明文件路径不对或格式有问题。再验证 hooks故意写一个带any的 TS 文件看type-guardian是否被触发。如果 hooks 配置正确你会看到子代理介入并指出类型问题。最后验证 API 通道在 Claude Code 里随便问一句「你好」如果正常返回说明 TaoToken 的ANTHROPIC_BASE_URL和 Key 配置没问题。想单独测模型对话可以用模型对话页面直接发一条消息确认通道通畅。5. 本篇常见错排查配置过程中最容易卡住的几个点我整理成表格对照现象原因处理Claude 不读 CLAUDE.md文件不在项目根目录的 .claude/ 下确认路径是.claude/CLAUDE.mdCLAUDE.local.md 被提交了忘了加 .gitignore补上CLAUDE.local.md并git rm --cachedhooks 不触发YAML 缩进错误用 2 空格缩进别用 Tabrules 全路径生效front matter 的 paths 没写补上paths字段并确认 glob 正确请求 404BASE_URL 末尾多了 /v1改成https://taotoken.net/api401 未授权Key 没生效或拼错重新 source 环境变量检查 Key 前缀子代理不执行tools 字段没声明补上Read, Grep等必要工具排障时优先看 Claude Code 的启动日志它会打印加载了哪些配置文件。如果某个文件没出现在日志里基本就是路径或格式问题。6. 把配置沉淀成团队资产.claude/目录真正的价值不是让 Claude 变聪明而是把团队里那些「口头约定」变成可版本管理的文件。CLAUDE.md管怎么写review.md管怎么审hooks.yaml管自动拦截agents/管专项复查skills/管知识复用。这套骨架建好之后新人拉下代码就自带一套 AI 协作规范不用再靠口口相传。接入层面用 TaoToken 统一 Key 和 API 通道多个工具共用一个入口额度和管理都集中。长期跑编码任务和 Agent 的话可以看下 Coding Plan 的额度方案只是验证模型通不通模型对话页面发一条消息最快接入配置有疑问就翻接入文档字段说明都在里面。配置这东西建一次能用很久但前提是每个文件的职责边界要清晰。别把所有规则都塞进CLAUDE.md那样 Claude 读起来累你改起来也累。