企业官网建设流程全解析

1. 为什么团队用 Claude Code 总会「各写各的」

一个人用 Claude Code，配置随便放都行。三个人以上协作，问题立刻暴露：新同事 clone 完仓库，Claude 不知道项目用 pnpm 还是 npm，不知道测试命令是pnpm test还是vitest run，不知道.env绝对不能碰。每个人本地调出来的行为都不一样，代码 review 时才发现 AI 生成的风格南辕北辙。

.claude/文件夹就是解决这件事的地方。它把「这个项目默认怎么运转」从口头约定变成可提交 Git 的配置文件，让团队里每个人的 Claude Code 加载同一套规则、同一套权限边界、同一套可复用工作流。这篇聚焦团队协作场景，拆开.claude/目录下的CLAUDE.md、settings.json、rules/、skills/、agents/骨架，并演示怎么通过 TaoToken 统一 Key 和 API 通道接入，让全组走同一条链路。

适合谁看：正在把 Claude Code 从个人玩具推向团队工具的开发者、需要给新人一套开箱即用配置的 Tech Lead、以及被「配置怎么没生效」折磨过的人。读完你能拿到可直接复制的settings.json与config.toml片段，以及验证配置生效的具体动作。

先说一个前提：Claude Code 迭代很快，字段名和语法以官方文档为准，这里讲的是骨架和落地思路。真正稳定的东西是分层逻辑——什么该放哪一层，什么该提交 Git，什么只能留本机。

2. TaoToken 前置：统一 Key 与 API 通道

团队协作里最烦的一件事是 Key 管理。每个人自己申请、自己配环境变量，出了问题不知道是谁的额度、走的哪条链路。TaoToken 的价值在于给团队一个统一的 API 入口，Key 集中管理，模型通道统一，新人入职只要拿到一个 Key 就能跑起来。

TaoToken 是一个大模型 API 聚合服务，兼容 Anthropic 与 OpenAI 风格的接口，Claude Code 这类工具可以直接把 base URL 指过来。对团队来说，它解决三件事：一是 Key 不用每人一份散落各处，二是模型调用走统一通道便于排查，三是切换模型或调整额度时改一处即可。

接入前你需要准备：

• 一个 TaoToken 账号，登录后在控制台创建 API Key
• 团队约定的模型名（比如 Claude 系列的具体型号）
• 把 Key 通过环境变量注入，不要硬编码进settings.json提交到 Git

获取 Key 的入口在控制台的 API Keys 页面，创建后复制保存，页面关掉就不再完整显示。这一步建议由团队管理员统一做，然后把 Key 通过内部密码管理工具分发，而不是丢在群里。

注意：settings.json会提交到 Git，任何写进这个文件的 Key 都等于公开。Key 一律走环境变量，配置文件里只引用变量名。

TaoToken 的 API 地址是https://taotoken.net/api，官网在https://taotoken.net/。下面所有配置都基于这个入口。

3. 可复制配置：settings.json 与 config.toml

3.1 目录骨架先摆清楚

团队仓库里，.claude/的结构建议长这样：

your-repo/ ├── CLAUDE.md # 团队共享，项目级指令 ├── CLAUDE.local.md # 本地有效，gitignored ├── .mcp.json # 团队共享，MCP 配置 └── .claude/ ├── settings.json # 团队共享，权限与行为 ├── settings.local.json # 本地有效，gitignored ├── rules/ # 团队共享，按主题拆分的规范 ├── skills/ # 团队共享，可复用工作流 └── agents/ # 团队共享，子代理

判断标准很简单：影响全组行为的提交 Git，只影响你本机的进.gitignore。settings.local.json默认被忽略，用来做个人实验或临时放宽权限，不会污染团队配置。

3.2 settings.json：权限边界写死在客户端

settings.json是把「能做什么」从提示词期望升级为客户端强制规则的地方。建议加上$schema，编辑器会给补全和校验，权限规则写错比代码写错更难察觉。

{ "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [ "Bash(pnpm *)", "Bash(git status)", "Bash(git diff *)", "Read", "Edit", "Write", "Grep", "Glob" ], "deny": [ "Bash(rm -rf *)", "Bash(curl *)", "Bash(wget *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)" ] }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "${TAOTOKEN_API_KEY}" } }

这里有两个关键点。第一，env段把 base URL 指向 TaoToken，ANTHROPIC_AUTH_TOKEN引用环境变量${TAOTOKEN_API_KEY}，实际值由每个成员在 shell 里 export，不进仓库。第二，deny里同时挡掉curl和wget，因为只挡curl的话wget照样能发网络请求。

权限规则的匹配顺序是deny > ask > allow，第一个匹配的规则生效。空格很重要：Bash(ls *)匹配ls -la但不匹配lsof，而Bash(ls*)两个都匹配，因为前者有空格强制了词边界。

3.3 config.toml：把通道配置固化下来

如果你用支持 TOML 配置的客户端或自建脚本调用，config.toml可以这样写：

[api] base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" timeout_seconds = 120 [model] default = "claude-sonnet" fallback = "claude-haiku" [team] project = "your-repo" shared_rules = ".claude/rules"

api_key_env指向环境变量名而不是值，这样配置文件可以安全提交。default和fallback让团队默认走性价比更高的模型，复杂任务再手动切。

3.4 CLAUDE.md：控制在 200 行以内

CLAUDE.md每次会话开始自动注入，承载编码规范、工作流、架构边界。一个被反复验证的经验值：控制在 200 行以内。文件过长，有效信息被稀释，遵循度明显下降。

# 项目说明 ## 常用命令 pnpm dev # 启动开发 pnpm test # 跑测试 pnpm lint # lint/format pnpm build # 构建 ## 关键结构 - 后端：src/server/ - 前端：src/web/ - 通用：src/shared/ ## 约定 - 改动要补测试（明确说明可以不补的除外） - 错误处理走 src/shared/logger，禁止随手 console.log - 优先修补，不要动不动大重构 ## 容易踩的坑 - 严格类型检查默认开启 - 本地测试依赖 Redis（见 docs/dev.md）

长文档用@导入，最大支持 5 层深度：

项目概览见 @README.md，可用命令见 @package.json # 额外指令 - @docs/git-instructions.md - @~/.claude/my-project-instructions.md

IMPORTANT:、YOU MUST:、NEVER:这类关键词 Claude 会格外关注，但要克制使用，全是重点等于没有重点。

3.5 rules/：按路径触发，减少噪音

CLAUDE.md开始变成团队 wiki 时，把内容迁到.claude/rules/。一个主题一份 markdown，递归发现，多人维护互不干扰。带pathsfrontmatter 的规则只在处理匹配路径的文件时触发：

--- paths: - "src/server/api/**/*.ts" --- # API 约定 - 所有 handler 必须做输入校验 - 对外错误返回统一结构 { data, error } - 禁止把内部堆栈直接返回给客户端

这样 API 约定只在src/server/api/**生效，前端组件规范只在src/components/**生效，无关噪音大幅减少。

3.6 skills/：把重复工作流变成一条命令

CLAUDE.md和rules解决「Claude 一直知道什么」，skills解决「Claude 能快速干什么」。创建一个含SKILL.md的目录，就能用/<skill-name>调用。

--- name: review-pr description: 审查当前分支相对 main 的改动，输出按文件分组的可执行建议 disable-model-invocation: true allowed-tools: Bash(git diff *), Bash(git status), Read, Grep, Glob context: fork --- ## 变更文件 !`git diff --name-only main...HEAD` ## 详细 diff !`git diff main...HEAD` 请按文件输出： - 潜在 bug / 边界条件 - 安全风险 - 测试缺口 - 可维护性建议（只提必要的）

!反引号是动态上下文注入，Claude Code 会先执行这条 shell 命令，把输出插进 prompt 再交给 Claude。context: fork让技能在隔离子代理里跑，不污染主上下文。disable-model-invocation: true阻止 Claude 自动触发，带副作用的操作建议开启。

3.7 agents/：重活丢进隔离窗口

任务复杂到需要大量检索时，主对话上下文很容易被塞满。子代理跑在独立上下文里，结果摘要回传主线程。

--- name: code-reviewer description: 专职代码审查员，适合合并前、自测失败、或重构后稳定性检查 tools: Read, Glob, Grep model: sonnet --- 你是资深 code reviewer，重点看： - 逻辑正确性和边界 - 可读性、命名、复杂度 - 并发、权限、注入、资源泄露等风险点 输出要具体到文件和行范围，给出可以直接动手改的建议。

子代理的真正价值不是并行性，而是上下文隔离。每个子代理有独立上下文窗口，主线程只收到摘要，不收到中间的检索噪音，这能有效防止长会话中的上下文腐烂。

4. 验证请求：确认配置真的生效

配置写完不算完，得验证。团队协作里最常见的抱怨就是「我配了但没生效」，下面这套动作能快速定位。

第一步，确认环境变量注入成功。在终端执行：

echo $TAOTOKEN_API_KEY | head -c 8

应该输出 Key 的前 8 位。如果为空，说明 shell 没加载，检查.zshrc或.bashrc。

第二步，确认 Claude Code 读到了项目配置。在项目根目录启动会话，输入/memory，看CLAUDE.md是否被加载进来。如果没出现，检查文件位置是不是在启动目录或其父目录。

第三步，确认权限规则生效。输入/permissions，查看当前生效的权限和来源。如果项目级deny了某个工具，用户级的allow不会覆盖它，因为deny > allow。

第四步，发一个真实请求验证通道。让 Claude 跑一条允许的命令：

git status

应该正常执行。再让它尝试一条被 deny 的命令：

curl https://example.com

应该被拦截。如果没被拦截，说明settings.json没被加载，或者规则写错了。

第五步，验证模型通道。让 Claude 回答一个简单问题，观察是否正常返回。如果报鉴权错误，检查ANTHROPIC_BASE_URL是否指向https://taotoken.net/api，以及 Key 是否有效。需要单独测试模型对话时，可以直接用模型对话页面发一条消息确认通道通畅。

实测下来，这五步走完，90% 的「配置没生效」问题都能定位到具体哪一层。

5. 本篇常见错排查

错误一：CLAUDE.md 过长导致选择性遵循。写了 300 多行，Claude 开始漏掉部分规则。原因是 LLM 性能随上下文填充下降，系统提示本身已占不少指令，再堆几百行有效信息被稀释。解决：拆到rules/，核心指令控制在 200 行以内。

错误二：把强制规则放在 CLAUDE.md 里。写了「绝对不要执行 rm -rf」，长会话中还是执行了。原因是CLAUDE.md是建议层不是执行层，上下文压缩可能丢失指令。解决：强制规则放settings.json的deny加PreToolUsehook。

错误三：Read/Edit 的 deny 不阻止 Bash。deny了Read(./.env)，但 Claude 用cat .env照样读到。原因是 Read/Edit deny 只约束内置文件工具，不约束 Bash 子进程。解决：启用 sandbox 做 OS 级别路径隔离，或者干脆 deny 掉cat这类命令。

错误四：Bash 权限规则被绕过。Bash(curl http://github.com/ *)看似限制了 curl，但curl -X GET http://github.com/...这类参数变体绕得过去。原因是 Bash 规则是简单前缀匹配。解决：用 deny 阻止整个命令，改用域名级白名单，或用PreToolUsehook 做更精确验证。

错误五：路径前缀搞混。Read(/Users/alice/file)不生效。原因是/path是项目根目录相对路径，不是绝对路径。记住四种前缀：//是文件系统绝对路径，~是家目录，/是项目根，./是当前目录。要表示绝对路径必须用//Users/alice/file。

错误六：设置放错作用域。「我的配置不生效」往往是放在了低优先级作用域。如果项目级 deny 了某工具，用户级 allow 不会生效。解决：理解五层优先级，用/permissions查看来源。

错误七：monorepo 中其他团队的 CLAUDE.md 干扰。大型 monorepo 里别的目录的CLAUDE.md被意外加载。解决：用claudeMdExcludes排除：

{ "claudeMdExcludes": [ "**/other-team/CLAUDE.md", "/home/user/monorepo/other-team/.claude/rules/**" ] }

错误八：所有任务都用最贵的模型。费用居高不下。解决：默认用 Sonnet，仅在复杂架构设计、跨文件重构、难调 bug 时切更强模型，子代理可以单独指定模型。

6. 团队落地：从配置到习惯

配置只是起点，真正让团队跑顺的是习惯。几条经验：新仓库初始化时，把.claude/骨架和CLAUDE.md模板一起提交，新人 clone 完直接能用；settings.local.json加进.gitignore，让每个人有实验空间；Key 走环境变量，管理员统一在控制台管理，需要轮换时改一处。

长期做编码和 Agent 任务的团队，可以考虑用 Coding Plan 把额度、模型、通道统一管起来，避免每人各自为战。接入文档里有完整的字段说明和示例，遇到配置字段不确定时以官方文档为准。

最后一句实在话：.claude/的价值不在于配置多花哨，而在于把「我以为你知道」变成「文件里写着」。团队协作里，能提交 Git 的约定，永远比口头约定可靠。