project-settings
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese/project-settings — view or change project config
/project-settings — 查看或更改项目配置
Manages (team-wide config, committed) and
(per-developer overrides, gitignored). Use this skill to inspect current
settings or change them without manually editing YAML.
project.yamlproject.local.yamlAutomation mode: Resolve ( →
→ default ). The approval gates in Phase 4 and
Phase 5 follow the pattern in . Note:
writing to is a decision (a default
category), so confirms config writes even
in mode unless the user has removed from their
always-ask list.
modes.automationproject.local.yamlproject.yamlcollaborative.claude/docs/automation-modes.mdproject.yamlschema_changesautomation_always_ask/project-settingsautonomousschema_changes管理 (团队级配置,已提交到版本控制)和 (单个开发者的覆盖配置,被 gitignore)。使用此 skill 检查当前设置或直接更改设置,无需手动编辑 YAML。
project.yamlproject.local.yaml自动化模式:解析 ( → → 默认值 )。第 4 阶段和第 5 阶段中的审批门控遵循 中的模式。注意:写入 是一项 决策(默认属于 类别),因此即使处于 模式, 也会在写入配置前请求确认,除非用户已从其 always-ask 列表中移除 。
modes.automationproject.local.yamlproject.yamlcollaborative.claude/docs/automation-modes.mdproject.yamlschema_changesautomation_always_askautonomous/project-settingsschema_changesPhase 0: Parse Arguments
阶段 0:解析参数
Determine which of the four forms the user invoked:
| Form | Mode |
|---|---|
| View-all (Phase 2) |
| View-one (Phase 3) |
| Set-yaml (Phase 4) |
| Set-local (Phase 5) |
For Set-yaml and Set-local, is a dotted YAML path (e.g.
, ) and is the new value.
<key>modes.review_modetesting.strict.logic<value>Empty-operand validation: After splitting the operand on
, if either or is empty, this is malformed — route to
Phase 6 (usage) rather than attempting the write. The rule applies in both
Set-yaml and Set-local routing: for , strip the token
first, then check the remaining operand the same way (so
and both go to Phase 6).
key=value=<key><value>--local--local/project-settings --local =foo/project-settings --local key=Anything else that doesn't match the four forms above → Phase 6 (usage).
确定用户使用的是以下四种形式中的哪一种:
| 形式 | 模式 |
|---|---|
| 查看全部(阶段 2) |
| 查看单项(阶段 3) |
| 设置 YAML(阶段 4) |
| 设置本地配置(阶段 5) |
对于设置 YAML 和设置本地配置模式, 是点分 YAML 路径(例如 、), 是新值。
<key>modes.review_modetesting.strict.logic<value>空操作数校验:按 拆分 操作数后,如果 或 为空,则格式错误——应进入阶段 6(用法),而不是尝试写入。此规则同时适用于设置 YAML 和设置本地配置模式:对于 ,先移除 标记,然后以相同方式检查剩余操作数(因此 和 都应进入阶段 6)。
=key=value<key><value>--local--local/project-settings --local =foo/project-settings --local key=任何不符合上述四种形式的内容 → 阶段 6(用法)。
Phase 1: Load Helper
阶段 1:加载 Helper
All four subcommands need . Run each helper call as its own
plain command:
yaml-helper.shbash
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" <helper call><helper call>resolve_setting modes.review_modevalidate_yaml_enum project.yamlproject.yamlproject.local.yamlis_locally_overridable01sourcecd ... &&; echo $?If is missing, this is not a Claude Code Game Studios project.
Report the error and exit.
.claude/hooks/yaml-helper.sh所有四个子命令都需要 。每次 helper 调用都应作为独立的普通命令运行:
yaml-helper.shbash
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" <helper call><helper call>resolve_setting modes.review_modevalidate_yaml_enum project.yamlproject.yamlproject.local.yamlis_locally_overridable01sourcecd ... &&; echo $?如果 不存在,则当前目录不是 Claude Code Game Studios 项目。报告该错误并退出。
.claude/hooks/yaml-helper.shPhase 1b: Reserved-setting detection
阶段 1b:检测保留设置
Some settings are fully documented and settable, and no skill
or hook reads them — setting one changes nothing. This skill must say so.
Returning an ordinary success lets a user reasonably believe the behaviour the
setting describes is now enforced — an accessibility tier being the case that
motivates this. (The key is not named here on purpose; see the note below.)
The banner exists only in
, which someone
configuring their project will never open. A setting that does nothing must never look
exactly like one that works — obligation 3.
.claude/docs/effects-map.md.claude/rules/skill-authoring.mdDerive the set; do not hardcode it (obligation 5):
bash
grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md | grep -E '^## 'Match the banner HEADING (), never the bare word "RESERVED".
's section mentions the banner in prose, to record that it
carried one and later became a live setting. A looser match re-reports a working
setting as dead — the direction that understates what the framework does, and
why the dead-settings gate asserts both directions.
> ### RESERVEDplatform.cert_tierA heading may name two keys joined by " and " — split on that separator so
both are captured, or the second one silently escapes the set. Let
be the result.
RESERVED_SETDeliberately phrased without naming those keys. The dead-settings gate asserts that a setting on the allowlist has no readers, and it counts any skill file that spells the key. Naming them here to illustrate the split would makeregister as a reader of two settings nothing reads, and the gate would fail — correctly. Spelling a dead path out while explaining why not to use it trips the same wire. Reword instead of adding an exemption: the strictness is the point, so do not re-introduce the literal names to make an example clearer./project-settings
Never refuse a write to a reserved key. Storing the value a user intends is
legitimate; storing it silently is the defect.
有些设置已有完整文档且可以设置,但没有任何 skill 或 hook 读取它们——设置这些项不会产生任何变化。此 skill 必须明确说明这一点。 返回普通的成功结果会让用户合理地以为该设置所描述的行为现已生效——无障碍等级正是促成此要求的情形。(这里故意不写出该键名;请参阅下方说明。)该横幅仅存在于 中,而配置项目的人永远不会打开它。无效的设置绝不能看起来与有效的设置完全一样——这是 义务 3 的要求。
.claude/docs/effects-map.md.claude/rules/skill-authoring.md应派生该集合,不要将其硬编码(义务 5):
bash
grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md | grep -E '^## '务必匹配横幅标题(),绝不能只匹配裸词“RESERVED”。 所在章节在正文中提到了该横幅,用于记录它曾经拥有横幅、后来成为有效设置的情况。过于宽松的匹配会再次将有效设置报告为无效设置——这种方向会低估框架实际提供的能力,而失效设置门控正是要同时断言两个方向。
> ### RESERVEDplatform.cert_tier一个标题可能会命名两个以“ and ”连接的键——应按该分隔符拆分,以同时捕获两者,否则第二个键会悄然逃出集合。令结果为 。
RESERVED_SET特意采用不包含这些键名的表述。失效设置门控会断言允许列表中的设置没有读取方,并统计任何明确拼写出该键的 skill 文件。如果在这里为说明拆分方式而命名这些键,就会被登记为两个无人读取的设置的读取方,门控也会因此失败——这是正确行为。在解释原因时写出一个无效路径,同样会触发这条规则。应当改写措辞,而不是添加例外:严格性正是目的所在,因此不要为了让示例更清晰而重新引入字面键名。/project-settings
绝不要拒绝写入保留键。存储用户想要的值是合理行为;静默存储才是缺陷。
Phase 2: View-all Mode
阶段 2:查看全部模式
(when no arguments)
-
Confirmexists. If missing, report:
project.yaml"Nofound — runproject.yamlto create one." And exit./start -
Check ifexists.
project.local.yaml -
Runand capture any errors. If
validate_yaml_enum project.yamlexists, also runproject.local.yaml. Tag each error with its source file so the user can tell them apart.validate_yaml_enum project.local.yaml -
Enumerate leaves. Read both YAML files as text. Walk through each file's structure and collect every leaf key into a deduplicated list of dotted paths. A leaf is aline whose value is non-empty (a scalar or inline-array) — NOT a parent block that introduces a nested map. Maintain insertion order per file; merge by appending leaves from
key: valuethat aren't already present fromproject.local.yaml. The resulting list is the set of leaves to display.project.yamlThen append the rigor family —,modes.rigor,modes.workflow,docs.density,qa.level,modes.story_granularity,modes.review_mode— for any of the seven the merged list does not already contain. These are normally leaves of neither file:team.sizehas a terminal default and the other six are supplied by the rigor expansion (modes.rigorandmodes.review_modemay also appear as file leaves when set locally, but must still be appended so their derived value shows). Enumerating only file leaves would hide exactly the settings a user just chose, in the one view meant to show them.team.size -
For each leaf, perform three reads and one check:
- →
resolve_setting <path>, TAB,<value>. This walks the whole chain (<source>→project.local.yaml→ legacy file →project.yamlexpansion → default), so it is the only read that can report a derived value or name what supplied it.rigor - → yaml-only value (needed only to show what a local override is shadowing)
get_yaml_key project.yaml <path> - → 0 (overridable) or 1 (locked)
is_locally_overridable <path>
Compute the source annotation from:<source><source>Annotation , yaml-only value non-emptyproject.local.yaml(LOCAL OVERRIDE — yaml has: <yamlvalue>), yaml-only value emptyproject.local.yaml(project.local.yaml)project.yaml(project.yaml)a legacy file path (e.g. )production/review-mode.txt(<path>, legacy)rigor:<level>(derived from rigor: <level>)default(default)unsetskip the leaf (don't print unset keys) Appendto the annotation when, lockedreturned 1.is_locally_overridableAppendwhen the leaf is in, reserved(Phase 1b), and print this line with the legend below the block:RESERVED_SETreserved = stored, but nothing reads it. Setting it changes no behaviour today.All four phases must carry the reserved marking — view-one, view-all, and both write paths. Marking view-one and the writes while leaving view-all — the most-used form of this skill — unmarked means a user who set a reserved key sees it listed beside working settings with an ordinaryannotation, in the view most people actually run. Guard all four: view-one and view-all are twins in exactly the way the two write paths are.(project.yaml) -
Print, grouped by top-level section (,
framework,modes, etc.) in the order leaves first appeared. The grouping is determined by the dotted path, not by which file the leaf came from — e.g.enginegroups undermodes.automationeven if onlymodes:defines it. Within each section, indent leaves by 2 spaces; nest further for sub-blocks (e.g.project.local.yaml). Example output:testing.strict.*
project.yaml: present
project.local.yaml: present
Schema validation: ok
Effective config:
framework:
version: 1.3.0 (project.yaml, locked)
modes:
review_mode: lean (project.yaml)
automation: autonomous (LOCAL OVERRIDE — yaml has: collaborative)
rigor: full (project.yaml, locked)
workflow: full (derived from rigor: full, locked)
story_granularity: fine (derived from rigor: full, locked)
docs:
density: terse (project.yaml, locked)
qa:
level: full (derived from rigor: full, locked)
engine:
name: Godot (project.yaml, locked)
version: 4.7 (project.yaml, locked)
testing:
strict:
logic: false (LOCAL OVERRIDE — yaml has: true)
integration: true (project.yaml)
locked = cannot be overridden in project.local.yaml (project-wide setting).
It does NOT mean fixed: a derived value can still be set explicitly with
/project-settings <key>=<value>, and an explicit value wins over rigor.Print that two-line legend after the config block whenever any rendered
line carries . Without it users read as "immutable" and
conclude a rigor-derived knob cannot be changed — the opposite of what
Phase 3's view-one tells them for the same knob ("an explicit value wins
over rigor"). The two views must not leave contradictory impressions of
the same knob's mutability.
lockedlockedThe line above is the precedence rule made visible: an
explicit value keeps winning over the level would
otherwise derive, so "comprehensive but compact" stays expressible.
docs.densityproject.yamlrigorIf schema errors exist, print them in this form before the effective
config block:
Schema validation: ERRORS
[project.yaml] modes.review_mode: 'chaotic' is not a valid value (expected: full|lean|solo)
[project.local.yaml] engine.name: 'Pygame' is not a valid value (expected: Godot|Unity|Unreal|Web)(无参数时)
-
确认存在。如果不存在,报告:
project.yaml“Nofound — runproject.yamlto create one.” 然后退出。/start -
检查是否存在。
project.local.yaml -
运行并捕获所有错误。如果
validate_yaml_enum project.yaml存在,也运行project.local.yaml。为每个错误标记其来源文件,以便用户区分。validate_yaml_enum project.local.yaml -
枚举叶节点。 将两个 YAML 文件作为文本读取。遍历每个文件的结构,将每个叶节点键收集到去重后的点分路径列表中。叶节点是值非空(标量或内联数组)的行,而不是引入嵌套映射的父级块。按文件维护插入顺序;合并时,追加
key: value中尚未出现在project.local.yaml中的叶节点。最终列表即待显示的叶节点集合。project.yaml然后追加 rigor 系列——、modes.rigor、modes.workflow、docs.density、qa.level、modes.story_granularity、modes.review_mode——即使用合并列表中尚未包含这七项中的任何一项,也必须追加。它们通常不是两个文件中的叶节点:team.size具有终端默认值,其他六项由 rigor 扩展提供(当在本地设置时,modes.rigor和modes.review_mode也可能作为文件叶节点出现,但仍必须追加,以显示其派生值)。如果只枚举文件叶节点,就会恰好隐藏用户刚刚选择的设置,而这个视图本应专门用于展示它们。team.size -
对每个叶节点执行三次读取和一次检查:
- →
resolve_setting <path>、TAB、<value>。这会遍历整个链条(<source>→project.local.yaml→ 旧版文件 →project.yaml扩展 → 默认值),因此这是唯一能够报告派生值或指出其来源的读取方式。rigor - → 仅 YAML 中的值(仅用于显示本地覆盖所遮蔽的值)。
get_yaml_key project.yaml <path> - → 0(允许覆盖)或 1(已锁定)。
is_locally_overridable <path>
根据计算来源标注:<source><source>标注 ,仅 YAML 的值非空project.local.yaml(LOCAL OVERRIDE — yaml has: <yamlvalue>),仅 YAML 的值为空project.local.yaml(project.local.yaml)project.yaml(project.yaml)旧版文件路径(例如 )production/review-mode.txt(<path>, legacy)rigor:<level>(derived from rigor: <level>)default(default)unset跳过该叶节点(不要打印未设置的键) 当返回 1 时,在标注后追加is_locally_overridable。, locked当叶节点位于中时(阶段 1b),追加RESERVED_SET,并在配置块下方使用以下图例:, reservedreserved = stored, but nothing reads it. Setting it changes no behaviour today.所有四个阶段都必须带有保留标记——查看单项、查看全部以及两条写入路径。 如果只标记查看单项和写入,却不标记查看全部——这个 skill 最常用的形式——用户就会看到自己设置的保留键与有效设置并列显示,并带有普通的标注。请保护全部四条路径:查看单项和查看全部在写入路径完全相同的方式上互为对应。(project.yaml) -
打印,按顶层分区(、
framework、modes等)分组,顺序采用叶节点首次出现的顺序。分组依据是点分路径,而不是叶节点来自哪个文件——例如,即使只有engine定义了project.local.yaml,它仍会归入modes.automation。在每个分区内,叶节点缩进 2 个空格;更深层级的子块继续嵌套(例如modes:)。输出示例:testing.strict.*
project.yaml: present
project.local.yaml: present
Schema validation: ok
Effective config:
framework:
version: 1.3.0 (project.yaml, locked)
modes:
review_mode: lean (project.yaml)
automation: autonomous (LOCAL OVERRIDE — yaml has: collaborative)
rigor: full (project.yaml, locked)
workflow: full (derived from rigor: full, locked)
story_granularity: fine (derived from rigor: full, locked)
docs:
density: terse (project.yaml, locked)
qa:
level: full (derived from rigor: full, locked)
engine:
name: Godot (project.yaml, locked)
version: 4.7 (project.yaml, locked)
testing:
strict:
logic: false (LOCAL OVERRIDE — yaml has: true)
integration: true (project.yaml)
locked = cannot be overridden in project.local.yaml (project-wide setting).
It does NOT mean fixed: a derived value can still be set explicitly with
/project-settings <key>=<value>, and an explicit value wins over rigor.只要任何渲染行带有 ,就在配置块后打印这两行图例。否则,用户会把 理解为“不可变”,进而认为 rigor 派生的选项无法更改——这与阶段 3 的查看单项结果恰好相反,后者会说明同一个选项可以修改(“显式值优先于 rigor”)。两个视图不得对同一选项的可修改性留下相互矛盾的印象。
lockedlocked上面的 行直观展示了优先级规则: 中的显式值继续优先于 本来会派生的级别,因此“内容全面但紧凑”仍然可以表达。
docs.densityproject.yamlrigor如果存在 schema 错误,请在有效配置块之前按以下形式打印:
Schema validation: ERRORS
[project.yaml] modes.review_mode: 'chaotic' is not a valid value (expected: full|lean|solo)
[project.local.yaml] engine.name: 'Pygame' is not a valid value (expected: Godot|Unity|Unreal|Web)Phase 3: View-one Mode
阶段 3:查看单项模式
(when single arg, no )
=If is in , print this BEFORE the value block — above,
not below. A caveat under a value reads as a footnote on a working setting:
<key>RESERVED_SETis RESERVED — nothing reads it. The value below is stored; it changes no behaviour today.<key>
Let be the argument. Perform four reads:
<key>- →
resolve_setting <key>, TAB,<value>(effective value + provenance)<source> - → yaml-only value
get_yaml_key project.yaml <key> - → local-only value (skip if file absent)
get_yaml_key project.local.yaml <key> - → 0 (overridable) or 1 (locked)
is_locally_overridable <key>
Determine the source from (same table as Phase 2 step 5)
and the Locally overridden status:
<source>- if the local-only value is non-empty
yes - otherwise
no
Print:
<key>
Effective value: <effective-value or "(not set)" if <source> is unset>
Source: <project.yaml | project.local.yaml | project.local.yaml (overrides project.yaml) | derived from rigor: <level> | default>
Locally overridden: <yes | no>
Whitelist: <"can be locally overridden" if is_locally_overridable returned 0, else "locked — project-wide">When both files set the key (the LOCAL OVERRIDE case), add two more
lines under Source:
project.yaml value: <yamlvalue>
project.local.yaml value: <localvalue>When is , add one line under Source so the user
knows the value is settable and how:
<source>rigor:<level> Set explicitly with: /project-settings <key>=<value> (an explicit value wins over rigor)When the effective value is empty (key not set anywhere), print just:
<key>
Effective value: (not set)
Locally overridden: no
Whitelist: <"can be locally overridden" | "locked — project-wide">(单个参数且不含 时)
=如果 位于 中,请在值块之前打印以下内容——必须放在上方,而不是下方。位于值下方的警告会被理解为有效设置的脚注:
<key>RESERVED_SETis RESERVED — nothing reads it. The value below is stored; it changes no behaviour today.<key>
令 为传入参数。执行四次读取:
<key>- →
resolve_setting <key>、TAB、<value>(有效值及来源)<source> - → 仅 YAML 中的值
get_yaml_key project.yaml <key> - → 仅本地文件中的值(文件不存在时跳过)
get_yaml_key project.local.yaml <key> - → 0(允许覆盖)或 1(已锁定)
is_locally_overridable <key>
根据 确定来源(与阶段 2 第 5 步的表相同),并确定本地覆盖状态:
<source>- 仅本地文件中的值非空时为
yes - 否则为
no
打印:
<key>
Effective value: <effective-value or "(not set)" if <source> is unset>
Source: <project.yaml | project.local.yaml | project.local.yaml (overrides project.yaml) | derived from rigor: <level> | default>
Locally overridden: <yes | no>
Whitelist: <"can be locally overridden" if is_locally_overridable returned 0, else "locked — project-wide">当两个文件都设置了该键(LOCAL OVERRIDE 情况)时,在 Source 下额外添加两行:
project.yaml value: <yamlvalue>
project.local.yaml value: <localvalue>当 为 时,在 Source 下添加一行,让用户知道该值可以设置以及设置方式:
<source>rigor:<level> Set explicitly with: /project-settings <key>=<value> (an explicit value wins over rigor)当有效值为空(任何位置都未设置该键)时,只打印:
<key>
Effective value: (not set)
Locally overridden: no
Whitelist: <"can be locally overridden" | "locked — project-wide">Phase 4: Set-yaml Mode
阶段 4:设置 YAML 模式
(when , no )
<key>=<value>--local- Schema validation: call . If it returns 1, the stderr line is shown to the user verbatim (
validate_enum_value <key> <value>) and the skill exits without writing. If it returns 0, the value is either valid or the key has no enum constraint — proceed.Invalid value '<value>' for '<key>'. Allowed: ...
1b. Known-key check: run, from the project root as in Phase 1,
and read its
row. If it says , proceed. If it says , nothing in Claude Code Game Studios reads
that key, so writing it changes nothing; it is most often a typo. Do not
write yet: say so, and ask with the question tool, with the options
(only when the row ends ),
, . Continue only on an explicit choice; with
, start this phase again with that key. A skipped or
empty answer cancels.
bash .claude/scripts/config-set.sh <key> <value> --dry-runknownyesnoUse <nearest> insteadnearest: <key>Write <key> anywayCancelUse <nearest> instead-
Reserved warning: ifis in
<key>(Phase 1b), print BEFORE the approval prompt:RESERVED_SET"Note:is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way."<key>Then continue to the approval gate as normal. Phase 5 carries the identical warning. Warning on one write path and not the other leaves a silent route to the same outcome, which is the whole failure this guards against. -
Shadow warning: read. If it returns a non-empty value, print BEFORE the approval prompt:
get_yaml_key project.local.yaml <key>"Note: this setting is currently locally overridden in(value:project.local.yaml). Writing to<localvalue>will not change your effective value."project.yaml -
Approval gate: ask with the question tool:
- Prompt:
Set `<key>=<value>` in `project.yaml`? - Options: /
[A] Yes, write[B] No, cancel
Whenis<key>, the same write points CLAUDE.md'sengine.nameline atENGINE-REFERENCE-IMPORT(the value's first word, lowercased), inserting it right after the marker comment's closing@docs/engine-reference/<engine>/VERSION.mdwhen there is none yet, so no session loads another engine's reference: name-->in the prompt too. The rest of an engine (its version, folders and Technology Stack) isCLAUDE.md's: say so in one line./setup-engine - Prompt:
-
Write: editin place. The edit strategy depends on what already exists in
project.yaml:project.yamlCase A — key exists: Read. Locate the lineproject.yamland the line immediately above it that introduces its parent block (e.g.<lastsegment>: <oldvalue>formodes:). Make the edit's old text include the parent block line PLUS the leaf line, so the match is unique even ifmodes.review_modeappears elsewhere. Example for<lastsegment>: <oldvalue>:modes.review_mode=fullold_string: modes: review_mode: lean new_string: modes: review_mode: fullCase B — parent block exists, leaf doesn't: Find the last line of the parent block. Append the new leaf line at the correct indentation, using the last existing leaf as theanchor.old_stringCase C — parent block doesn't exist: Append a new top-level block at end-of-file (deterministic — always end-of-file, never between blocks). Use the last non-empty line of the file as the anchor and append the new block after it.Case D — file structure is unusual (commented-out keys with the same name, ambiguous nesting, malformed YAML): STOP and ask with the question tool:"Couldn't find a clean insertion point forin<key>. Show me what to do."project.yaml -
Confirm:
Set `<key>=<value>` in `project.yaml`.Whenis<key>, the write also moves six other knobs, so print what they resolve to now — re-read each withmodes.rigorrather than reciting the expansion table, since any of them may carry an explicit value that still wins:resolve_settingSet modes.rigor=full in project.yaml. It now supplies: modes.workflow: full (derived from rigor: full) docs.density: terse (project.yaml — explicit, unchanged) qa.level: full (derived from rigor: full) modes.story_granularity: fine (derived from rigor: full) modes.review_mode: full (derived from rigor: full) team.size: studio (derived from rigor: full)
( 且不含 时)
<key>=<value>--local- Schema 校验:调用 。如果返回 1,则向用户逐字显示 stderr 行(
validate_enum_value <key> <value>),并且 skill 在不写入的情况下退出。如果返回 0,则该值有效,或者该键没有枚举约束——继续执行。Invalid value '<value>' for '<key>'. Allowed: ...
1b. 已知键检查:从项目根目录运行(与阶段 1 相同):,并读取其 行。如果显示 ,则继续。如果显示 ,说明 Claude Code Game Studios 中没有任何内容读取该键,因此写入它不会产生任何变化;这通常是拼写错误。不要立即写入:应说明这一点,并使用 question tool 询问,提供以下选项:(仅当该行以 结尾时提供)、、。只有在用户明确选择后才能继续;如果选择 ,则使用该键重新开始本阶段。跳过或提供空答案将取消操作。
bash .claude/scripts/config-set.sh <key> <value> --dry-runknownyesnoUse <nearest> insteadnearest: <key>Write <key> anywayCancelUse <nearest> instead-
保留警告:如果位于
<key>中(阶段 1b),请在审批提示之前打印:RESERVED_SET“Note:is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way.”<key>然后照常进入审批门控。阶段 5 使用完全相同的警告。如果只在一条写入路径上警告而不在另一条上警告,就会留下一个静默写入路径,而它可能产生相同结果——这正是此机制要防范的失败。 -
遮蔽警告:读取。如果返回非空值,请在审批提示之前打印:
get_yaml_key project.local.yaml <key>“Note: this setting is currently locally overridden in(value:project.local.yaml). Writing to<localvalue>will not change your effective value.”project.yaml -
审批门控:使用 question tool 询问:
- 提示:
Set `<key>=<value>` in `project.yaml`? - 选项:/
[A] Yes, write[B] No, cancel
当为<key>时,同一次写入还会将 CLAUDE.md 的engine.name行指向ENGINE-REFERENCE-IMPORT(取该值的第一个单词并转换为小写),插入到标记注释的结束符@docs/engine-reference/<engine>/VERSION.md之后;如果尚未插入该行,以确保没有会话加载其他引擎的参考文档。还要在提示中提及-->。引擎的其余部分(版本、文件夹和 Technology Stack)由CLAUDE.md负责:用一行说明这一点。/setup-engine - 提示:
-
写入:就地编辑。编辑策略取决于
project.yaml中已经存在的内容:project.yaml情况 A——键已存在:读取。定位project.yaml行,以及其正上方引入父级块的行(例如<lastsegment>: <oldvalue>对应的modes.review_mode)。编辑的 old text 必须同时包含父级块行和叶节点行,以确保匹配唯一,即使modes:出现在其他位置也不会产生歧义。<lastsegment>: <oldvalue>的示例:modes.review_mode=fullold_string: modes: review_mode: lean new_string: modes: review_mode: full情况 B——父级块存在,但叶节点不存在:找到父级块的最后一行。在正确的缩进位置追加新的叶节点行,并使用最后一个现有叶节点作为锚点。old_string情况 C——父级块不存在:在文件末尾追加一个新的顶层块(采用确定性方式——始终追加到文件末尾,绝不插入两个块之间)。使用文件的最后一个非空行作为锚点,并在其后追加新块。情况 D——文件结构异常(存在同名但已注释的键、嵌套关系有歧义或 YAML 格式错误):停止操作,并使用 question tool 询问:“Couldn't find a clean insertion point forin<key>. Show me what to do.”project.yaml -
确认:
Set `<key>=<value>` in `project.yaml`.当为<key>时,此次写入还会改变另外六个选项,因此应打印它们当前解析出的值——重新使用modes.rigor读取每一项,而不是照抄扩展表,因为其中任何一项都可能仍带有优先的显式值:resolve_settingSet modes.rigor=full in project.yaml. It now supplies: modes.workflow: full (derived from rigor: full) docs.density: terse (project.yaml — explicit, unchanged) qa.level: full (derived from rigor: full) modes.story_granularity: fine (derived from rigor: full) modes.review_mode: full (derived from rigor: full) team.size: studio (derived from rigor: full)
Phase 5: Set-local Mode
阶段 5:设置本地配置模式
(when )
--local <key>=<value>-
Whitelist check: call.
is_locally_overridable <key>- If it returns 1 (locked), print one line:
<key> cannot be locally overridden — it's a project-wide setting. Use `/project-settings <key>=<value>` (no `--local`) to change it for the whole team. - Exit without writing.
- If it returns 1 (locked), print one line:
-
Schema validation: call. If it returns 1, show the stderr message verbatim and exit without writing.
validate_enum_value <key> <value>
2a. Known-key check: as in Phase 4 step 1b, with before
: if the row says , ask before writing, offering the key
when the row names one.
--local<key>knownnonearest:2b. Reserved warning: if is in (Phase 1b), print
BEFORE the approval prompt:
<key>RESERVED_SET"Note:is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way."<key>
Identical to Phase 4 step 2, and deliberately so. Both write paths reach the
same file-of-record for a user's intent; warning on one only would leave
as the silent route.
--local-
Base check: ifdoesn't exist:
project.yaml"Cannot create—project.local.yamlis missing. Runproject.yamlto create one first." Exit. (Local overrides require a base, per spec.)/start -
Approval gate: ask with the question tool:
- Prompt:
Set `<key>=<value>` in `project.local.yaml` (your personal override, gitignored)? - Options: /
[A] Yes, write[B] No, cancel
- Prompt:
-
Write:
- If doesn't exist, create it with the new setting wrapped in its parent block(s). Minimal example for
project.local.yaml:--local modes.automation=autonomousyaml# project.local.yaml — per-developer overrides (gitignored) modes: automation: autonomous - If it exists, edit it with the same Case A/B/C strategy as Phase 4 step 5.
- If
-
Confirm:
Set `<key>=<value>` in `project.local.yaml` (your override).
( 时)
--local <key>=<value>-
白名单检查:调用。
is_locally_overridable <key>- 如果返回 1(已锁定),打印一行:
<key> cannot be locally overridden — it's a project-wide setting. Use `/project-settings <key>=<value>` (no `--local`) to change it for the whole team. - 不写入并退出。
- 如果返回 1(已锁定),打印一行:
-
Schema 校验:调用。如果返回 1,则逐字显示 stderr 消息,不写入并退出。
validate_enum_value <key> <value>
2a. 已知键检查:与阶段 4 第 1b 步相同,但在 前加上 :如果 行显示 ,则在写入前询问,并在该行提供键名时提供 键。
<key>--localknownnonearest:2b. 保留警告:如果 位于 中(阶段 1b),请在审批提示之前打印:
<key>RESERVED_SET“Note:is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way.”<key>
这与阶段 4 第 2 步完全相同,且是刻意如此。两条写入路径最终都会将用户的意图记录到同一个权威文件中;如果只警告其中一条,就会让 成为静默路径。
--local-
基础配置检查:如果不存在:
project.yaml“Cannot create—project.local.yamlis missing. Runproject.yamlto create one first.” 退出。(按照规范,本地覆盖必须以基础配置为前提。)/start -
审批门控:使用 question tool 询问:
- 提示:
Set `<key>=<value>` in `project.local.yaml` (your personal override, gitignored)? - 选项:/
[A] Yes, write[B] No, cancel
- 提示:
-
写入:
- 如果 不存在,则创建该文件,将新设置放入其父级块中。例如
project.local.yaml:--local modes.automation=autonomousyaml# project.local.yaml — per-developer overrides (gitignored) modes: automation: autonomous - 如果文件已经存在,则使用与阶段 4 第 5 步相同的情况 A/B/C 策略进行编辑。
- 如果
-
确认:
Set `<key>=<value>` in `project.local.yaml` (your override).
Phase 6: Usage
阶段 6:用法
When the argument doesn't match any of the four valid forms (or has
empty operands), print:
Usage:
/project-settings — view all effective config
/project-settings <key> — view a single setting
/project-settings <key>=<value> — change a setting (project.yaml)
/project-settings --local <key>=<value> — change a setting locally
(project.local.yaml, gitignored)
Examples:
/project-settings modes.review_mode
/project-settings modes.review_mode=full
/project-settings --local modes.automation=autonomous当参数不符合四种有效形式之一,或操作数为空时,打印:
Usage:
/project-settings — view all effective config
/project-settings <key> — view a single setting
/project-settings <key>=<value> — change a setting (project.yaml)
/project-settings --local <key>=<value> — change a setting locally
(project.local.yaml, gitignored)
Examples:
/project-settings modes.review_mode
/project-settings modes.review_mode=full
/project-settings --local modes.automation=autonomousNotes
注意事项
- All YAML writes are edits in place (existing keys and blocks) or a new
file. The skill does not depend on or any external YAML library.
yq - The whitelist is enforced in (
yaml-helper.shfunction). To extend it, edit theis_locally_overridableconstant — do not duplicate the list here._yaml_helper_locally_overridable - Derived values are not stored anywhere. ,
modes.workflow,docs.density,qa.level,modes.story_granularityandmodes.review_modehave no terminal default; when no file sets them their value comes from theteam.sizeexpansion inmodes.rigor(yaml-helper.sh). Report them via_yaml_helper_rigor_expansion— aresolve_settingread returns empty and would render them "(not set)" while every skill is in fact acting on a real value.get_yaml_key - The schema-validation enum constants are in (
yaml-helper.sh)._yaml_helper_enumsis the single-key validator for pending writes;validate_enum_valuevalidates whole files (used byvalidate_yaml_enum).session-start.sh - is gitignored. These overrides never propagate to teammates.
project.local.yaml - For which value to choose for a given game type or situation — and when to
suggest changing one — see (advisory presets
.claude/docs/settings-guidance.md- change triggers). says what each setting does; that doc says which to pick.
effects-map.md
- change triggers).
- 所有 YAML 写入都是对现有键和块的原地编辑,或者创建一个新文件。此 skill 不依赖 或任何外部 YAML 库。
yq - 白名单在 中强制执行(
yaml-helper.sh函数)。如需扩展,请编辑is_locally_overridable常量——不要在此处重复维护列表。_yaml_helper_locally_overridable - 派生值不会存储在任何位置。 、
modes.workflow、docs.density、qa.level、modes.story_granularity和modes.review_mode没有终端默认值;当没有文件设置它们时,其值来自team.size中的yaml-helper.sh扩展(modes.rigor)。应通过_yaml_helper_rigor_expansion报告这些值——使用resolve_setting读取会返回空值,并将其呈现为“(not set)”,但实际上每个 skill 都在使用一个真实值。get_yaml_key - Schema 校验的枚举常量位于 (
yaml-helper.sh)中。_yaml_helper_enums是待写入项的单键校验器;validate_enum_value用于校验整个文件(由validate_yaml_enum使用)。session-start.sh - 被 gitignore。这些覆盖配置永远不会传播给团队成员。
project.local.yaml - 关于针对特定游戏类型或场景应选择哪个值,以及何时建议更改设置,请参阅 (建议预设和变更触发条件)。
.claude/docs/settings-guidance.md说明每个设置的作用;该指导文档则说明应选择哪个值。effects-map.md