Claude Code 项目与团队定制

先把项目事实和权限边界写清，再增加技能、代理、Hooks 和插件。扩展越多，启动上下文、权限面和故障组合也越大。

CLI 行为基于本机 2.1.209 · 文件约定等待 Anthropic 官方站恢复后再次复核

选择最小的定制层

需求	放在哪里
当前任务的一次性目标和边界	提示词或当前会话
项目结构、命令、约定和完成标准	CLAUDE.md
工具权限、Hooks、环境和团队设置	.claude/settings.json
本机对项目的私有覆盖	.claude/settings.local.json
外部实时数据和动作	MCP
可复用专业流程	Skill
独立角色和隔离上下文	Agent / subagent
工具事件前后的确定性检查	Hook
一组可安装、可更新的能力	Plugin

一次提示词能解决的问题不要急着做 Skill；一条项目规则能解决的问题不要急着做 Hook。

CLAUDE.md：保存稳定项目事实

常见位置：

• ~/.claude/CLAUDE.md：个人跨项目说明。
• 仓库根目录 CLAUDE.md 或 .claude/CLAUDE.md：团队共享规则。
• 子目录中的 CLAUDE.md：模块级更具体说明。

用 /init 生成草案后人工整理：

# CLAUDE.md

## 项目结构
- apps/web：前端入口和页面
- packages/core：共享领域逻辑
- tests：集成测试

## 常用命令
- 安装：pnpm install --frozen-lockfile
- 开发：pnpm dev
- 检查：pnpm lint && pnpm typecheck
- 测试：pnpm test
- 构建：pnpm build

## 工作约定
- 修改前阅读同目录实现、测试和最近调用方。
- 不提交 .env、密钥、日志、覆盖率或生成目录。
- Bug 修复不升级依赖，不顺手重构无关模块。
- 新功能覆盖成功、失败、空数据和权限状态。

## 完成标准
- 运行与改动直接相关的检查。
- 审查完整 diff，保留用户原有修改。
- 最终列出改动、证据、未验证项和剩余风险。

可以用 @README.md 或 @docs/architecture.md 导入已有说明。只导入每次任务都值得读取的稳定内容；大文档和临时日志会持续占用上下文。

CLAUDE.md 适合团队审查的显式规则，自动记忆适合本机积累经验。关键命令和安全边界仍应进入版本控制，而不是只依赖自动记忆。

设置文件与加载来源

文件	作用
~/.claude/settings.json	个人跨项目设置
.claude/settings.json	团队共享设置，可提交 Git
.claude/settings.local.json	当前电脑或当前项目私有覆盖，通常不提交

CLI 可用 --setting-sources user,project,local 限定加载来源，也可用 --settings SETTINGS_JSON_OR_FILE 追加一次性设置。排错时一次只改变一个来源。

提交团队设置前检查：

• 没有绝对个人路径、Key、代理凭据和账号 ID。
• Hooks 与 MCP 启动命令来源可信、可在目标平台运行。
• allow 规则足够具体，deny 规则覆盖敏感文件和危险动作。
• Windows、macOS 和 Linux 的路径与 shell 差异已处理。

权限规则

一个保守起点：

{
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(npm publish *)"
    ]
  }
}

规则设计：

1. 从真实审批记录找稳定、可重复的命令。
2. 允许项目检查，不允许任意 shell。
3. 拒绝密钥、发布、远程写入和不可逆删除。
4. 定期删除过时规则，避免“临时放宽”变成永久默认。

权限模式和 allow/deny 共同决定行为；acceptEdits 不自动允许所有 Bash，dontAsk 不自动授予未允许工具。

MCP

添加 HTTP MCP：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

添加 stdio MCP：

claude mcp add my-server -- command-that-starts-the-server

作用域：

claude mcp add --scope local my-server -- command-that-starts-the-server
claude mcp add --scope project my-server -- command-that-starts-the-server
claude mcp add --scope user my-server -- command-that-starts-the-server

• local：当前项目、当前用户，默认。
• project：写入项目 .mcp.json，适合团队共享，首次加载需要审批。
• user：当前用户所有项目。

管理和诊断：

claude mcp list
claude mcp get my-server
claude mcp login my-server
claude mcp login --no-browser my-server
claude mcp logout my-server
claude mcp reset-project-choices

--no-browser 适合 SSH 或无图形界面的 OAuth 登录，它会打印授权 URL 并等待回填 redirect URL。当前 CLI 还提供 claude mcp add-from-claude-desktop（仅 Mac 和 WSL）导入 Claude Desktop 配置，以及 claude mcp serve 启动 Claude Code MCP server；使用前分别通过对应 --help 确认导入来源和调用方。

共享 MCP 前检查服务发布者、包名、启动命令、传输、认证、工具读写能力和日志脱敏。先做无副作用查询，再授权写操作。

Skills

项目技能通常放在 .claude/skills/NAME/SKILL.md，通过对应斜杠名称调用。适合：

• 已经重复并稳定的发布检查、代码审查或数据迁移流程。
• 需要参考文件、脚本、模板和明确质量门的任务。
• 希望把复杂流程从 CLAUDE.md 中拆出，按需加载。

一个 Skill 至少写清：触发场景、输入、前提、步骤顺序、产物、验证和停止条件。不要把整本团队手册都放进每次启动的上下文。

--disable-slash-commands 会禁用 skills。--bare 仍可以通过明确的 /skill-name 解析技能，但不会自动发现其他项目上下文；以当前 CLI 帮助为准。

Agents 与后台任务

一次性代理定义只对同一次 CLI invocation 生效。可以先把 JSON 放进 shell 变量：

REVIEWER_AGENT='{
  "reviewer": {
    "description": "审查当前改动中的可验证 Bug 和缺失测试",
    "prompt": "只报告有文件证据的问题，按严重程度排序"
  }
'}

在同一次启动中定义并选择：

claude --agents "$REVIEWER_AGENT" --agent reviewer \
  --permission-mode plan --tools "Read,Glob,Grep,Bash" \
  --allowedTools "Read,Glob,Grep,Bash(git status *),Bash(git diff *)" \
  -- "审查当前分支，不修改文件"

后台代理：

claude --agents "$REVIEWER_AGENT" \
  --background --agent reviewer \
  --permission-mode plan --tools "Read,Glob,Grep,Bash" \
  --allowedTools "Read,Glob,Grep,Bash(git status *),Bash(git diff *)" \
  -- "审查当前分支，不修改文件"
claude agents --json

如果只运行 claude --agent reviewer，该代理必须已经通过持久化配置存在；前一个进程中的一次性 --agents 不会自动传给后一个进程。

不要混淆三层概念：--agents 为当前 invocation 提供 custom agent 定义，--agent 选择当前会话使用的 agent；--background 把一个顶层会话放到后台，claude agents 管理这类后台会话；subagent 则是在会话内部被委派的隔离上下文。当前 claude agents --help 只承诺管理 background agents，不能把它当成所有会话内 subagent 的通用列表。

代理适合隔离搜索、审查、测试分析等独立上下文。不要把多个强依赖步骤同时并行，也不要让两个代理写同一文件或分支。

Hooks

当前顶层 --help 能确认 Hooks 会被 Safe/Bare mode 影响，并能在 stream-json 中输出 Hook events，但没有列出 settings JSON 的完整事件名、输入字段和退出码协议。本版不据此编造可复制的 Hook 配置模板；精确 schema 等官方资料恢复后再补。

Hook 适合在工具或会话事件前后执行确定性动作，例如：

• 编辑后运行格式化或静态检查。
• 只有当前官方 schema 明确支持阻断时，才把敏感工具调用检查做成阻断；否则由 permissions 与外部 sandbox 承担强制边界。
• 对发布、远程写入和删除动作增加审计。
• 把验证结果写入明确的交付记录。

每个 Hook 应有超时、错误输出、失败策略和平台说明。Hook 代码与仓库脚本一样需要审查；不要在 Hook 中隐藏大范围修改或把网络失败静默吞掉。

需要观察自动化中的 Hook 生命周期时，当前 CLI 可以把事件加入 stream-json：

claude -p --no-session-persistence --verbose --output-format stream-json \
  --include-hook-events \
  --permission-mode plan --tools "Read,Glob,Grep" \
  -- "只读检查项目入口，不修改文件"

该命令会实际加载并触发已配置 Hooks，只能在预先信任的项目中运行；不要用它“试跑”来源不明的 Hook。调用方要解析事件并对 Hook 输出脱敏。Hook 造成启动失败时先用 claude --safe-mode 建立无定制基线；--bare 会跳过 Hooks，但同时改变认证和其他加载行为，不能把两种模式的结果混为一谈。

Plugins

当前 2.1.209 的 claude plugin 支持：

• 安装、卸载、启用、禁用和更新插件。
• 管理 marketplace。
• 查看插件组件清单和预计 Token 成本。
• 校验插件或 marketplace manifest。
• 对插件运行 eval。

claude plugin list
claude plugin details PLUGIN_NAME
claude plugin validate --strict PLUGIN_PATH

顶层 CLI 还支持用 --plugin-dir 加载本地目录或 zip，以及用 --plugin-url 为当前会话下载远程 zip。远程插件可能同时带入 Skills、Hooks、MCP 或 agents；只使用来源、版本和内容都已审查的固定制品，不把临时 URL 当作可信安装源。

采用前检查来源、许可证、组件清单、Token 成本、MCP/Hook 权限、更新和回滚。只有一个流程时先用 Skill；需要一组可分发能力时再用 Plugin。

团队落地顺序

1. 写准确的 CLAUDE.md 和真实验证命令。
2. 用最小 settings.json 固定权限和平台约定。
3. 只连接必要的 MCP，并做只读验证。
4. 重复流程成熟后再做 Skill。
5. 需要独立角色时定义 Agent，避免无意义并行。
6. 确定性质量门才使用 Hook。
7. 多能力分发才使用 Plugin，并记录版本与回滚。
8. 使用 --safe-mode 做无定制基线回归。

定制变更验收

• 新会话能正确读到项目命令和约束。
• allow / deny 的正反例符合预期。
• MCP 工具只显示必要账号和数据范围。
• Skill 不把无关大文档加载到所有任务。
• Agent 之间没有同文件、同分支或同外部资源写冲突。
• Hook 失败可见，不会静默放过或破坏工作区。
• Plugin 的来源、组件、成本和更新策略可审查。

官方资料

以下链接待网络恢复后重新读取：

• Memory and CLAUDE.md
• Settings
• Permissions
• MCP
• Skills
• Subagents
• Hooks
• Plugins