Skip to content

claude-global-vs-project-settings.md

Latest commit

 

History

History
248 lines (186 loc) · 9.9 KB

claude-global-vs-project-settings.md

File metadata and controls

248 lines (186 loc) · 9.9 KB

Claude Code：全局与项目级特性对比

全面比较哪些 Claude Code 特性仅支持全局（~/.claude/），哪些同时支持全局和项目级（.claude/）的配置。

← 返回 Claude Code 最佳实践 Claude

目录

  1. 概述
  2. 仅全局特性
  3. 双作用域特性
  4. 设置优先级
  5. 目录结构对比
  6. 任务系统
  7. Agent 团队
  8. 设计原则
  9. 来源

概述

Claude Code 使用作用域层次结构，其中一些特性同时存在于全局（~/.claude/）和项目（.claude/）级别，而另一些则仅支持全局配置。设计原则：个人状态或跨项目协调的内容存储在全局；团队可共享的项目配置可以存储在项目级别。

  • ~/.claude/ 是你的用户级主目录（全局，所有项目）
  • 仓库内的 .claude/ 是你的项目级主目录（限定于该项目）

仅全局特性

这些仅存在于 ~/.claude/ 下，不能限定到项目：

特性 位置 用途
任务 ~/.claude/tasks/ 跨会话和 Agent 的持久任务列表
Agent 团队 ~/.claude/teams/ 多 Agent 协调配置（实验性，2026年2月）
自动记忆 ~/.claude/projects/<hash>/memory/ Claude 每个项目的自我编写学习（个人，永不共享）
凭证与 OAuth 系统钥匙串 + ~/.claude.json API 密钥、OAuth 令牌（从不在项目文件中）
快捷键 ~/.claude/keybindings.json 自定义键盘快捷键
MCP 用户服务器 ~/.claude.json (mcpServers 键) 跨所有项目的个人 MCP 服务器
偏好设置/缓存 ~/.claude.json 主题、模型、输出样式、会话状态

双作用域特性

这些存在于两个级别，项目级优先于全局：

特性 全局 (~/.claude/) 项目 (.claude/) 优先级
CLAUDE.md ~/.claude/CLAUDE.md ./CLAUDE.md 或 .claude/CLAUDE.md 项目覆盖全局
设置 ~/.claude/settings.json .claude/settings.json + .claude/settings.local.json 项目 > 全局
规则 ~/.claude/rules/*.md .claude/rules/*.md 项目覆盖
Agent/子代理 ~/.claude/agents/*.md .claude/agents/*.md 项目覆盖
Command ~/.claude/commands/*.md .claude/commands/*.md 两者都可用
Skill ~/.claude/skills/ .claude/skills/ 两者都可用
Hooks ~/.claude/hooks/ .claude/hooks/ 两者都执行
MCP 服务器 ~/.claude.json (用户作用域) .mcp.json (项目作用域) 三层：本地 > 项目 > 用户

设置优先级

用户可写的设置按以下覆盖顺序应用（从高到低）：

优先级 位置 作用域 版本控制 用途
1 命令行标志 会话 N/A 单会话覆盖
2 .claude/settings.local.json 项目 否（被 git 忽略） 个人项目特定
3 .claude/settings.json 项目 是（已提交） 团队共享设置
4 ~/.claude/settings.local.json 用户 N/A 个人全局覆盖
5 ~/.claude/settings.json 用户 N/A 全局个人设置

策略层：managed-settings.json 是组织强制执行的，不能被本地文件覆盖。

重要：deny 规则具有最高的安全优先级，不能被低优先级的 allow/ask 规则覆盖。

目录结构对比

全局作用域 (~/.claude/)

~/.claude/
├── settings.json              # 用户级设置（所有项目）
├── settings.local.json        # 个人覆盖
├── CLAUDE.md                  # 用户记忆（所有项目）
├── agents/                    # 用户子代理（可用于所有项目）
│   └── *.md
├── rules/                     # 用户级模块化规则
│   └── *.md
├── commands/                  # 用户级命令
│   └── *.md
├── skills/                    # 用户级技能
│   └── */SKILL.md
├── tasks/                     # 仅全局：任务列表
│   └── {task-list-id}/
├── teams/                     # 仅全局：Agent 团队配置
│   └── {team-name}/
│       └── config.json
├── projects/                  # 仅全局：每项目自动记忆
│   └── {project-hash}/
│       └── memory/
│           ├── MEMORY.md
│           └── *.md
├── keybindings.json           # 仅全局：键盘快捷键
└── hooks/                     # 用户级 hooks
    ├── scripts/
    └── config/

~/.claude.json                 # 仅全局：MCP 服务器、OAuth、偏好设置、缓存

项目作用域 (.claude/)

.claude/
├── settings.json              # 团队共享设置
├── settings.local.json        # 个人项目覆盖（被 git 忽略）
├── CLAUDE.md                  # 项目记忆（./CLAUDE.md 的替代）
├── agents/                    # 项目子代理
│   └── *.md
├── rules/                     # 项目级模块化规则
│   └── *.md
├── commands/                  # 自定义斜杠命令
│   └── *.md
├── skills/                    # 自定义技能
│   └── {skill-name}/
│       ├── SKILL.md
│       └── supporting-files/
├── hooks/                     # 项目级 hooks
│   ├── scripts/
│   └── config/
└── plugins/                   # 已安装插件

.mcp.json                      # 项目级 MCP 服务器（仓库根目录）

任务系统

在 Claude Code v2.1.16（2026年1月22日）中引入，替代已弃用的 TodoWrite 系统。

存储

任务存储在本地文件系统的 ~/.claude/tasks/（不在云数据库中）。这使得任务状态可审计、可版本控制且可崩溃恢复。

工具

工具 用途
TaskCreate 创建具有 subject、description 和 activeForm 的新任务
TaskGet 通过 ID 检索特定任务的完整详情
TaskUpdate 更改状态、设置所有者、添加依赖项或删除
TaskList 列出所有任务及其当前状态

任务生命周期

pending  →  in_progress  →  completed

依赖管理

任务可以通过 addBlockedBy/addBlocks 阻塞其他任务，创建防止过早执行的依赖图。

多会话协作

CLAUDE_CODE_TASK_LIST_ID=my-project-tasks claude

所有共享相同 ID 的会话实时查看任务更新，支持并行工作流和会话恢复。

与旧 Todos 的关键区别

特性 旧 Todos 新 Tasks
作用域 单会话 跨会话、跨 Agent
依赖项 无 完整的依赖图
存储 仅内存 文件系统 (~/.claude/tasks/)
持久性 会话结束时丢失 在重启和崩溃后保留
多会话 不可能 通过 CLAUDE_CODE_TASK_LIST_ID

Agent 团队

于 2026年2月5日 作为实验性功能宣布。Agent 团队允许多个 Claude Code 会话协调共享工作。

启用

// 在 ~/.claude/settings.json 中
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

配置

团队配置位于 ~/.claude/teams/{team-name}/，支持以下模式：

模式 描述 要求
In-process（默认） 所有队友在你的终端内运行 无
Split panes 每个队友获得自己的窗格 tmux 或 iTerm2（非 VS Code 终端）

设计原则

仅全局与双作用域的分割遵循一个清晰的模式：

类别 作用域 原理
协调状态（任务、团队） 仅全局 需要超越任何单个项目的持久性
安全状态（凭证、OAuth） 仅全局 防止意外提交到版本控制
个人学习（自动记忆） 仅全局 用户特定，不可团队共享
输入偏好（快捷键） 仅全局 用户的肌肉记忆，不是项目特定的
配置（设置、规则、Agent） 两个级别 团队需要共享项目特定的行为
工作流定义（命令、技能） 两个级别 可以是个人或团队共享的

自动记忆（~/.claude/projects/<hash>/memory/）是一个值得注意的混合体：它是关于特定项目的，但存储在全局，因为它代表个人学习而不是可团队共享的配置。

来源
⚡