update-claude-code-schema
Skill8 starsChanged 5 months agoMITView on GitHub
同步 Code Manager 的 Claude Code settings schema。当需要拉取 SchemaStore 最新定义、跟进 hooks/env/worktree/permissionRule 等新字段、排查 Rust 配置校验(`validate_settings_document` / `config::tests`)变红,或复盘 schema 变化对前端编辑器/表单/类型契约的影响时使用;凡改动 `src/schemas/claude-settings.schema.json` 都走本技能。
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- release-new-versionSkill
- upgrade-dependenciesSkill
The file
Files
Update Claude Code Schema
为 Code Manager 同步 Claude Code settings 的 SchemaStore 定义。事实源永远是当前下载的完整 https://www.schemastore.org/claude-code-settings.json:整体替换本地文件,再证明语义等同。字段级拼补会漏掉上游的“删除字段”变更、让本地 schema 越积越脏——只做整体替换。
1. 前置检查
读 CLAUDE.md 与 .claude/rules/config-system.md。git status --short 看工作区,只叠加本任务改动,不回退别人或上一条工作线的改动。确认 curl、jq、node、pnpm、cargo 可用。
2. 下载官方 schema 到临时文件
curl -fsSL https://www.schemastore.org/claude-code-settings.json \
-o /private/tmp/claude-code-settings.latest.json- 下载到临时文件,是为后续语义比对留一份未经格式化的原始字节基线——直接覆盖本地文件会丢掉对照基线。
- sandbox 会挡掉这条 curl(读
/etc证书或写/private/tmp被拒,报curl: (77)或 operation not permitted)。提权重跑同一条命令,不要改命令绕过。
3. 整体替换 + 单文件格式化
cp /private/tmp/claude-code-settings.latest.json src/schemas/claude-settings.schema.json
pnpm exec biome format --write src/schemas/claude-settings.schema.json只格式化这一个文件:pnpm check / make fmt 会顺手改写无关文件,污染本次改动的 blast radius。
4. 语义比对
先验 JSON 完整,再证明本地与下载文件深度排序后字节相同——格式差异(缩进、键顺序)允许,内容漂移不允许:
jq empty src/schemas/claude-settings.schema.json
node -e '
const fs = require("fs");
const sort = v =>
Array.isArray(v) ? v.map(sort)
: v && typeof v === "object"
? Object.fromEntries(
Object.entries(v)
.sort(([a],[b]) => a.localeCompare(b))
.map(([k,x]) => [k, sort(x)])
)
: v;
const local = sort(JSON.parse(fs.readFileSync("src/schemas/claude-settings.schema.json","utf8")));
const upstream = sort(JSON.parse(fs.readFileSync("/private/tmp/claude-code-settings.latest.json","utf8")));
if (JSON.stringify(local) !== JSON.stringify(upstream)) {
console.error("schema differs semantically");
process.exit(1);
}
console.log("schema matches SchemaStore semantically");
'完成标准:打印 schema matches SchemaStore semantically。 失败说明 biome format 改写了内容而非仅格式——回查 biome 配置或 schema 中的特殊字符(unicode escape、JSON pointer)。
5. 审查关键变化
深度排序比对只证明“和上游一致”,不告诉你“上游改了什么”。用 git show HEAD 取旧版、和下载文件对比顶层 properties 键,抓出增删:
diff <(git show HEAD:src/schemas/claude-settings.schema.json | jq -r '.properties|keys[]' | sort) \
<(jq -r '.properties|keys[]' /private/tmp/claude-code-settings.latest.json | sort)再按下列高频位置扫嵌套结构——这是历史踩过的点,不是穷举,以实际 diff 为准:
env:从宽泛 pattern 收紧成显式 properties,或新增大量环境变量枚举。hooks:新事件类型、新字段(如continueOnBlock、argsexec form)、嵌套结构调整。worktree:新字段或 enum 值。permissionRule正则:是否影响Read(*)、Skill(*)、mcp__*等通配规则的合法性。- 标量字段的 enum 收紧/放宽:如顶层
effortLevel去掉max。step 5 的.properties|keys[]顶层键 diff 只能发现键增删,抓不到枚举收紧;这类变化会让前端表单选项与 Rustvalidate_settings_document校验失配,必须单独核对。 - 区分同名概念的两套枚举:
env.CLAUDE_CODE_EFFORT_LEVEL(env 键)与顶层effortLevel是不同字段、不同枚举、不同约束,收紧一个不影响另一个;排查前后端影响时不要混用。
审查只为把高风险变化告诉用户,确认是否需要后续动作(编辑器 UI、Rust 校验、表单字段、类型同步)。除非用户明确要求,本任务范围只到 schema 文件。
6. 验证
| 改动范围 | 命令 |
| JSON 完整性 | jq empty src/schemas/claude-settings.schema.json |
| Rust 配置校验 | cd src-tauri && cargo test config::tests |
| 格式 | make fmt-check |
| Diff whitespace | git diff --check |
- 测试过滤是子串匹配:
cargo test validate_settings_document只命中validate_settings_document_*这几个单测(均在config::tests内),并非"0 个用例"。验证以更全的cargo test config::tests为准,二者不矛盾。 validate_settings_document()的性质:未知顶层键放行,已知字段的嵌套结构严格校验。推论:上游删除顶层字段 → 老配置作为未知键仍通过,Rust 一般不炸;上游改已知字段的嵌套结构 → Rust 可能挂,需更新断言或修校验代码。- 前端门禁:Stop 钩子会通用地提示
make lint/build/test-frontend;schema-only 改动由上表覆盖,无需前端构建。
没有本次会话的新鲜命令输出,不声称通过。
7. 收口输出
## Schema 同步结果
下载源:https://www.schemastore.org/claude-code-settings.json
下载时间:<UTC 时间>
语义比对:<pass/fail>
JSON 完整性:<pass/fail>
Rust 配置校验(config::tests):<pass/fail,附关键输出>
格式与 diff 检查:<pass/fail>
关键 schema 变化:
- 顶层字段:<新增 / 移除条目>
- hooks:<新字段 / 新事件 / 结构调整>
- env / worktree / permissionRule:<具体点>
需要人工后续(不在本任务范围):
- <编辑器 UI / 表单字段 / 前端类型是否需要同步>
- <Rust 校验是否需要补断言>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

