promote-claude-settings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

promote-claude-settings

推广Claude设置

Interactively promote entries from

.claude/settings.local.json

(project) to

~/.claude/settings.json

(global).

交互式地将

.claude/settings.local.json

（项目级）中的配置项推广到

~/.claude/settings.json

（全局级）。

Workflow

工作流程

1. Read both files

1. 读取两个文件

Read
```
.claude/settings.local.json
```
from the current project root
Read
```
~/.claude/settings.json
```
If local file is missing or empty (
```
{}
```
), tell the user and stop

从当前项目根目录读取
```
.claude/settings.local.json
```
读取
```
~/.claude/settings.json
```
如果本地文件缺失或为空（
```
{}
```
），告知用户并终止操作

2. Diff

2. 差异对比

Compare every top-level key in local against global. For array values (e.g.

permissions.allow

), compare per-element, not the whole array.

Classify each entry:

Status	Meaning
New	Not in global — can be added
Exists	Already identical in global — skip
Conflict	Present in global with a different value

Present the full diff summary to the user before asking anything.

对比本地配置与全局配置中的每一个顶级键。对于数组类型的值（例如

permissions.allow

），逐个元素进行对比，而非对比整个数组。

将每个配置项分类：

状态	含义
新增	全局配置中不存在 — 可添加
已存在	与全局配置完全一致 — 跳过
冲突	全局配置中存在但值不同

在询问用户之前，向其展示完整的差异汇总。

3. Interactive confirm (per item)

3. 交互式确认（逐项）

Walk through every non-"Exists" entry and ask:

New → "Add to global? (Y/N)"
Conflict → show both values, ask "Use local / Keep global / Skip"

Use the question tool for each prompt.

遍历所有非“已存在”的配置项并询问：

新增 → “添加到全局？(是/否)”
冲突 → 展示双方的值，询问“使用本地配置 / 保留全局配置 / 跳过”

每个提示都使用提问工具。

3a. Scope generalization (local → global)

3a. 范围泛化（本地→全局）

Local settings are often written with project-specific context. Before promoting any entry to global, evaluate whether it contains narrowing signals that won't make sense outside this project. If so, suggest a broader version.

Common narrowing signals:

Relative paths (
```
./mvnw
```
,
```
./gradlew
```
,
```
./scripts/foo
```
)
Absolute paths (
```
/Users/matt/project-x/...
```
)
Project-specific directory or file names
Overly specific subcommand locks that only apply to one project's workflow

Examples:

Local value	Why it's too narrow	Suggested generalization
`Bash(./mvnw test:*)`	Relative path + subcommand lock	`Bash(mvnw)`
`Bash(./gradlew build:*)`	Relative path	`Bash(gradlew)`
`Bash(npx vitest:*)`	Already generic	Keep as-is
Hook command: `cd ./api && lint`	Relative path	Evaluate if hook makes sense globally
Env: `PROJECT_ROOT=/Users/matt/foo`	Absolute path	Likely should not be promoted

For each entry being promoted:

Detect whether the value contains project-specific narrowing
Suggest a broader alternative with a brief rationale (or recommend skipping promotion if it doesn't make sense globally)
Ask the user: "Original:
```
X
```
→ Suggested:
```
Y
```
— Use suggested version / Keep original / Custom?"
Use whichever version the user picks

If the value is already generic, skip this step for that entry.

本地配置通常带有项目特定的上下文信息。在将任何配置项推广到全局之前，需评估其是否包含仅适用于当前项目的限定性信息。如果有，建议使用更通用的版本。

常见的限定性信号：

相对路径（
```
./mvnw
```
、
```
./gradlew
```
、
```
./scripts/foo
```
）
绝对路径（
```
/Users/matt/project-x/...
```
）
项目特定的目录或文件名
仅适用于单个项目工作流的过于具体的子命令锁定

示例：

本地值	为何过于限定	建议的泛化版本
`Bash(./mvnw test:*)`	相对路径+子命令锁定	`Bash(mvnw)`
`Bash(./gradlew build:*)`	相对路径	`Bash(gradlew)`
`Bash(npx vitest:*)`	已具备通用性	保持原样
钩子命令： `cd ./api && lint`	相对路径	评估该钩子是否适用于全局
环境变量： `PROJECT_ROOT=/Users/matt/foo`	绝对路径	建议不推广

对于每个待推广的配置项：

检测该值是否包含项目特定的限定性信息
建议一个更通用的替代版本并附上简要理由（如果该配置项不适用于全局，则建议跳过推广）
询问用户：“原始值：
```
X
```
→ 建议值：
```
Y
```
— 使用建议版本 / 保留原始值 / 自定义？”
使用用户选择的版本

如果该值已具备通用性，则跳过此步骤。

4. Write to global

4. 写入全局配置

Apply confirmed changes to

~/.claude/settings.json

with the Edit tool. If the file does not exist, create it.

使用编辑工具将确认的修改应用到

~/.claude/settings.json

。如果该文件不存在，则创建它。

5. Cleanup confirm

5. 清理确认

If removing promoted entries would leave

settings.local.json

{}

, explain that the file is now effectively empty (

{}

) and ask whether to delete it entirely or keep the empty file. If the user chooses to keep it, leave the file as-is (do not remove entries).

If removing promoted entries would still leave other entries in the file, ask whether to remove the promoted entries.

如果移除已推广的配置项后，settings.local.json将变为

{}

，需向用户说明该文件实际上已为空，并询问是完全删除该文件还是保留空文件。如果用户选择保留，则保持文件原样（不删除任何配置项）。

如果移除已推广的配置项后，文件中仍有其他配置项，则询问用户是否移除已推广的配置项。

Edge cases

边缘情况

```
~/.claude/settings.json
```
missing → create with confirmed entries
JSON parse error → report and stop; do not attempt repair
Do NOT touch
```
.claude/settings.json
```
(project shared settings)

```
~/.claude/settings.json
```
缺失 → 使用确认的配置项创建该文件
JSON解析错误 → 报告错误并终止操作；不尝试修复
请勿修改
```
.claude/settings.json
```
（项目共享配置）